[Top] [Prev] [Next] [Bottom]

8.5 Creating and Writing General Raster Images

This section describes the routines needed to create and write simple general raster data sets. A "simple" general raster data set is defined here as one with no attributes.

Creating a general raster data set and writing data to it are separate operations in the GR programming model. Once an array is defined it is ready to store data. No definitions are retained about the size, contents or number of components of a general raster data set from one data set to the next or from one file to the next.

8.5.1 Creating General Raster Images: GRcreate

Creating a simple general raster data set requires the following steps:

1. Open a file and initialize the GR interface.
2. Define the characteristics of the general raster data set.
3. Perform optional operations on the data set.
4. Terminate access to the data set.
5. Terminate access to the GR interface and close the file.
To create the data set, the calling program must contain the following sequence of function calls:

C:		file_id = Hopen(filename, access_mode, number_of_desc);
		gr_id = GRstart(file_id);
		ri_id = GRcreate(gr_id, name, ncomp, number_type, il, 	
			dim_sizes);
		<Optional operations>
		status = GRendaccess(ri_id);
		status = GRend(gr_id);
		status = Hclose(file_id);

FORTRAN:	file_id = hopen(filename, access_mode, number_of_desc)
		gr_id = mgstart(filename, access_mode)
		ri_id = mgcreat(gr_id, name, ncomp, number_type, il, 	
			dim_sizes);
		<Optional operations>
		status = mgendac(ri_id)
		status = mgend(gr_id)
		status = hclose(file_id)

GRcreate defines a new general raster data set using the arguments name, ncomp, number_type, il and dim_sizes. Once a data set is created, you cannot change its name, data type, dimension or number of components. GRcreate does not actually perform the write; this occurs only when GRendaccess is called.

The maximum length of a data set name is defined by MAX_GR_NAME and the maximum number of components of an image array is defined by MAX_VAR_DIMS. Both are defined in the "hlimits.h" header file.

When creating a general raster data set, it is necessary to specify the data type of the image array data. The "hntdefs.h" header file contains definitions of all valid data types, which are described in Chapter 2, titled HDF Fundamentals. The GR interface supports all regular HDF data types. However, it does not include the support for "n-bit" integers which is included in the SD interface.

TABLE 8C GRcreate Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

GRcreate

(mgcreat)

gr_id

int32

integer

General raster data set identifier.

name

char *

character* (*)

Name of the image.

ncomp

int32

integer

Number of components in each element of the data set.

data_type

int32

integer

Data type of the data set.

interlace_mode

int32

integer

Interlace mode to be used when writing to the data set

dim_sizes

int32 [2]

integer (2)

Array defining the size of both dimensions.

8.5.2 Setting the Interlace Mode

During the process of reading a palette or an image, the interlace mode can be set to either MFGR_INTERLACE_PIXEL, MFGR_INTERLACE_LINE or MFGR_INTERLACE_COMPONENT. These definitions respectively correspond to pixel interlacing, line interlacing and component interlacing. The first two interlacing modes are illustrated for the instance of 24-bit pixel representation in Figure 7c of Chapter 7, titled 24-bit Raster Images (DF24 API). Component interlacing, as the name implies, describes interlacing raster data by color component.

EXAMPLE 1. Creating and Accessing a General Raster Data Set

In these examples an empty array is created, or one that has been defined but not yet initialized with data.

C:

#include "hdf.h"
#include "mfgr.h"

#define X_LENGTH 5
#define Y_LENGTH 10

main( ) 
{

	int32 gr_id, ri_id, file_id, status;
	int32 dimsizes[2], ncomp, il;

	/* Create and open the file. */
	file_id = Hopen("Example1.hdf", DFACC_CREATE, 0);

	/* Initiate the GR interface. */
	gr_id = GRstart(file_id);

	/* Define the number of components and dimensions of the image. */
	ncomp = 2;
	il = MFGR_INTERLACE_PIXEL;
	dimsizes[0] = X_LENGTH;
	dimsizes[1] = Y_LENGTH;

	/* Create the image array. */
	ri_id = GRcreate(gr_id, "Image_array_1", ncomp, DFNT_INT16, il, 
					dimsizes);

	/* Terminate access to the image array. */
	status = GRendaccess(gr_id);

	/* Terminate access to the GR interface and close the file */
	status = GRend(ri_id);

	/* Close the file. */
	status = Hclose(file_id);

}

FORTRAN:

	 PROGRAM CREATE IMAGE ARRAY

      integer*4 gr_id, ri_id, file_id, dimsizes(2), ncomp, il
      integer mgstart, mgcreat, mgendac, mgend, hopen, hclose
      integer*4 X_LENGTH, Y_LENGTH, status
      parameter (X_LENGTH = 5, Y_LENGTH = 10,
     +           MFGR_INTERLACE_PIXEL = 0)
C     DFACC_CREATE and DFNT_INT16 are defined in hdf.h.
      integer*4 DFACC_CREATE, DFNT_INT16
      parameter (DFACC_CREATE = 4, DFNT_INT16 = 22)

C     Create and open the file.
      file_id = hopen("Example1.hdf", DFACC_CREATE, 0)

C     Initiate the GR interface.
      gr_id = mgstart(file_id)

C     Define the number of components and dimensions of the image 
C     array.
      ncomp = 2
      il = MFGR_INTERLACE_PIXEL
      dimsizes(1) = Y_LENGTH
      dimsizes(2) = X_LENGTH

C     Create the image array.
      ri_id = mgcreat(gr_id, `Ex_array_1', ncomp, DFNT_INT16, il, 
     +                dimsizes)

C     Terminate access to the image array.
      status = mgendac(ri_id)

C     Terminate access to the GR interface and close the file.
      status = mgend(gr_id)

C     Close the file.
      status = hclose(file_id)
      end

8.5.3 Writing General Raster Images: GRwriteimage

GRwriteimage is the routine used to either completely or partially fill an n-component image array. It can also skip a specified number of image array elements between write operations along each dimension.

Writing data to an image array involves the following steps:

1. Open a file and initialize the GR interface.
2. Select or create a data set.
3. Write data to the image array.
4. Terminate access to the data set.
5. Terminate access to the file and close the file.
The calling program must contain the following sequence of calls:

C:		file_id = Hopen(filename, access_mode, number_of_desc);
		gr_id = GRstart(file_id);
		ri_id = GRcreate(gr_id, name, ncomp, number_type, il, 	
			dim_sizes);	
		status = GRwriteimage(ri_id, start, stride, edge, data);
		status = GRendaccess(gr_id);
		status = GRend(ri_id);
		status = Hclose(file_id);

FORTRAN:	file_id = hopen(filename, access_mode, number_of_desc)
		gr_id = mgstart(file_id)
		ri_id = mgcreat(gr_id, name, ncomp, number_type, il, 	
			dim_sizes);
		status = mgwrimg(ri_id, start, stride, edge, data)
		status = mgendac(ri_id)
		status = mgend(gr_id)
		status = hclose(file_id)

As with SD arrays, subsets of general raster images can be written. (In n-dimensional SD arrays these two-dimensional subsets are referred to as "slabs".) A subset is specified by giving an array consisting of the coordinate location of the origin vertex and an array consisting of lengths of each of the two dimensions.

GRwriteimage takes five arguments: ri_id, start, stride, edge, and data. The ri_id argument is the raster image id returned by GRcreate or GRselect. The arguments start, stride, and edge respectively describe the initial location in the image for the write operation, the number of locations the current array location will be moved forward after each write, and the length of each dimension of the subset to be written. If the image array is smaller than the data argument array, the amount of data written will be truncated to the size of the image array. These concepts are explained further in Chapter 3, titled Scientific Data Sets (SD API).

There are two Fortran-77 versions of this routine: mgwrimg and mgwcimg. The mgwrimg routine writes buffered numeric data and the mgwcimg routine writes buffered character data.

The parameters for GRwriteimage are described in the following table. Note that, because there are two Fortran-77 versions of GRwriteimage, there are correspondingly two entries in the "Data Type" field of the data parameter.

TABLE 8D GRwriteimage Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

GRwriteimage

(mgwrimg/

mgwcimg)

ri_id

int32

integer

Image array identifier returned by GRcreate.

start

int32 [2]

integer (2)

Array containing the x,y-coordinate location the write will start for each dimension.

stride

int32 [2]

integer (2)

Array containing the number of data locations the current location is to be moved forward before the next write.

edge

int32 [2]

integer (2)

Array containing the number of data elements that will be written along each dimension.

data

VOIDP

<valid numeric data type>

Buffer array containing the data to be written.

EXAMPLE 2. Creating and Writing an Image

These examples use GRcreate and GRwriteimage under the C interface and mgcreat and mgwrimg under the Fortran-77 interface.

C:

#include "hdf.h"
#include "mfgr.h"

#define X_LENGTH 15
#define Y_LENGTH 10

main( ) 
{
	int32 gr_id, ri_id, file_id, status;
	int32 dims[2], start[2], edges[2], ncomp, il;
	int16 image_data[Y_LENGTH][X_LENGTH][2], i, j;

	/* Create and open the file. */
	file_id = Hopen("Example2.hdf", DFACC_CREATE, 0);

	/* Initiate the GR interface. */
	gr_id = GRstart(file_id);

	/* Define the number of components and dimensions of the image. */
	ncomp = 2;
	il = MFGR_INTERLACE_PIXEL;
	dims[0] = X_LENGTH;
	dims[1] = Y_LENGTH;

	/* Create the array. */
	ri_id = GRcreate(gr_id, "Ex_array_2", ncomp, DFNT_INT16, il, dims);

	/* Fill the stored-data array with values. */
	for (j = 0; j < Y_LENGTH; j++) {
		for (i = 0; i < X_LENGTH; i++) {
			image_data[j][i][0] = (i + j) + 1;
			image_data[j][i][1] = (i + j) + 1;
		}
    }

	/* Define the location, pattern, and size of the data set */
	for (i = 0; i < 2; i++) {
		start[i] = 0;
		edges[i] = dims[i];
	}

	/* Write the stored data to the image array. */
	status = GRwriteimage(ri_id, start, NULL, edges, (VOIDP)image_data);

	/* Terminate access to the array. */
	status = GRendaccess(ri_id);

	/* Terminate access to the GR interface. */
	status = GRend(gr_id);

	/* Close the file. */
	status = Hclose(file_id);

}


FORTRAN:

	 PROGRAM WRITE ARRAY

      integer*4 ri_id, gr_id, file_id, ncomp, il
      integer dims(2), start(2), edges(2), stride(2)
      integer i, j, status
      integer mgstart, mgcreat, mgwrimg, mgendac, mgend
      integer hopen, hclose
      integer*4 DFACC_CREATE, DFNT_INT16
      integer*4 X_LENGTH, Y_LENGTH
      parameter (DFACC_CREATE = 4, DFNT_INT16 = 22, X_LENGTH = 15,
     +           Y_LENGTH = 10, MFGR_INTERLACE_PIXEL = 0)
      integer*2 image_data(2, X_LENGTH, Y_LENGTH)

C     Create and open the file.
      file_id = hopen(`Example2.hdf', DFACC_CREATE, 0)

C     Initiate the GR interface.
      gr_id = mgstart(file_id)

C     Define the number of components and dimensions of the image.
      ncomp = 2
      il = MFGR_INTERLACE_PIXEL
      dims(1) = X_LENGTH
      dims(2) = Y_LENGTH

C     Create the data set.
      ri_id = mgcreat(gr_id, `Ex_array_2', ncomp, DFNT_INT16, il, dims)

C     Fill the stored-data array with values.
      do 20 j = 1, Y_LENGTH
         do 10 i = 1, X_LENGTH
            image_data(1, i, j) = i + j - 1
            image_data(2, i, j) = i + j - 1
10         continue
20    continue

C     Define the location, pattern, and size of the data set
C     that will be written to.
      start(1) = 0
      start(2) = 0
      edges(1) = X_LENGTH
      edges(2) = Y_LENGTH
      stride(1) = 1
      stride(2) = 1

C     Write the stored data to the image array.
      status = mgwrimg(ri_id, start, stride, edges, image_data)

C     Terminate access to the array.
      status = mgendac(ri_id)

C     Terminate access to the GR interface.
      status = mgend(gr_id)

C     Close the file.
      status = hclose(file_id)

      end



[Top] [Prev] [Next] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.