[Top] [Prev] [Next]

8.6 Writing Raster Images

A raster image can be written partially or entirely. Partial writing includes writing to a contiguous region of the image and writing to selected locations in the image according to patterns defined by the user. This section describes the routine GRwriteimage and how it can write data to part of an image or to an entire image. The section also illustrates the concepts of compressing raster images and the use of external files to store image data.

8.6.1 Writing Raster Images: GRwriteimage

GRwriteimage is used to either completely or partially fill an image array.

Writing data to an image array involves the following steps:

  1. Open a file and initialize the GR interface.
  2. Select an existing raster image or create a new one.
  3. Write data to the image array.
  4. Terminate access to the raster image.
  5. Terminate access to the GR interface and close the file.

The calling program must contain the following sequence of calls:

C:		file_id = Hopen(filename, access_mode, num_dds_block);
		gr_id = GRstart(file_id);
		ri_id = GRselect(gr_id, ri_index);
	OR	ri_id = GRcreate(gr_id, name, n_comps, number_type, interlace_mode, dim_sizes);	
		status = GRwriteimage(ri_id, start, stride, edges, data);
		status = GRendaccess(gr_id);
		status = GRend(ri_id);
		status = Hclose(file_id);
FORTRAN:	file_id = hopen(filename, access_mode, num_dds_block)
		gr_id = mgstart(file_id)
		ri_id = mgselct(gr_id, ri_index);
	OR	ri_id = mgcreat(gr_id, name, n_comps, number_type, interlace_mode, dim_sizes);
		status = mgwrimg(ri_id, start, stride, edges, data)
	OR	status = mgwrcmg(ri_id, start, stride, edges, data) 
		status = mgendac(ri_id)
		status = mgend(gr_id)
		status = hclose(file_id)
As with SD arrays, whole raster images, subsamples, and slabs can be written. The data to be written is defined by the values of the parameters start, stride, and edges, which correspond to the coordinate location of the data origin, number of values to be skipped along each dimension during write operation, and number of elements to be written along each dimension.

The array start specifies the starting location of the data to be written. Valid values of each element in the array start are 0 to the size of the corresponding raster image dimension - 1. The first element of the array start specifies an offset from the beginning of the array data along the fastest-changing dimension, which is the second dimension in C and the first dimension in FORTRAN-77. The second element of the array start specifies an offset from the beginning of the array data along the second fastest-changing dimension, which is the first dimension in C and the second dimension in FORTRAN-77. For example, if the first value of the array start is 2 and the second value is 3, the starting location of the data to be written is at the fourth row and third column in C, and at the third row and fourth column in FORTRAN-77. Note that the correspondence between elements in the array start and the raster image dimensions in the GR interface is different from that in the SD interface. See Section 3.6 on page 55 on SDreaddata for an example of this.

The array stride specifies the writing pattern along each dimension. For example, if one of the elements of the array stride is 1, then every element along the corresponding dimension of the array data will be written. If one of the elements of the stride array is 2, then every other element along the corresponding dimension of the array data will be written, and so on. The correspondence between elements of the array stride and the dimensions of the array data is the same as described above for the array start.

Note that the FORTRAN-77 version of GRwriteimage has two routines; mgwrimg writes buffered numeric data and mgwcimg writes buffered character data.

GRwriteimage returns either SUCCEED (or 0) or FAIL (or -1). The parameters for GRwriteimage are described in Table 8C.

TABLE 8C - GRwriteimage Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
GRwriteimage

[intn]

(mgwrimg/
mgwcimg)
ri_id
int32
integer
Raster image identifier returned by GRcreate

start
int32 [2]
integer (2)
Array containing the x,y-coordinate location where 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

edges
int32 [2]
integer (2)
Array containing the number of data elements that will be written along each dimension

data
VOIDP
<valid numeric data type>(*)/
character(*)
Buffer for the image data to be written

EXAMPLE 1. Creating and Writing a Raster Image

This example illustrates the use of the routines Hopen/hopen, GRstart/mgstart, GRcreate/mgcreat, GRwriteimage/mgwrimg, GRendaccess/mgendac, GRend/mgend, and Hclose/hclose to create an HDF file and store a raster image in it.

In this example, the program creates the HDF file called "General_RImages.hdf" and a raster image in the file. The image created is of size 5x10 and named "Image Array 1", and has data of the int16 data type, 2 components, and interlace mode MFGR_INTERLACE_PIXEL. Then the program writes the image data, terminates access to the image and the GR interface, and closes the file.

C version



FORTRAN-77 version

EXAMPLE 2. Modifying an Existing Raster Image

This example illustrates the use of the routines GRselect/mgselct to obtain an existing raster image and GRwrite/mgwrimg to modify image data.

In this example, the program selects the only raster image in the file "General_RImages.hdf" created and written in Example 1, and modifies image data. The program also creates another raster image that is named "Image Array 2" and has 3 components with dimension size of 4x6, data type of DFNT_CHAR8, and interlace mode of MFGR_INTERLACE_PIXEL.

C version

FORTRAN-77 version

8.6.2 Compressing Raster Images: GRsetcompress

(Note: The GRsetcompress routine does not work in the current release.)

Images can be compressed using the routine GRsetcompress. GRsetcompress compresses the image data at the time it is called and supports all standard HDF compression algorithms. The syntax of the routine GRsetcompress is as follows:

C:		status = GRsetcompress(ri_id, comp_type, c_info);
FORTRAN:	status = mgscompress(ri_id, comp_type, comp_prm)
The compression method is specified by the parameter comp_type. Valid values of the parameter comp_type are:

COMP_CODE_NONE (or 0) for no compression
COMP_CODE_RLE (or 1) for RLE run-length encoding
COMP_CODE_SKPHUFF (or 3) for Skipping Huffman compression
COMP_CODE_DEFLATE (or 4) for GZIP compression
The compression parameters are specified by the parameter c_info in C and the parameter comp_prm in FORTRAN-77. The parameter c_info has type comp_info and contains algorithm-specific information for the library compression routines. The type comp_info is described in the header file "hcomp.h" and in the Reference Manual page for SDsetcompress. Compression parameters are only needed when Skipping Huffman or GZIP compression methods are applied.

The skipping size for the Skipping Huffman algorithm is specified in the field c_info.skphuff.skp_size in C and in the parameter comp_prm(1) in FORTRAN-77.

The deflate level for the GZIP algorithm is specified in the field c_info.deflate.level in C and in the parameter comp_prm(1) in FORTRAN-77.

GRsetcompress returns either SUCCEED (or 0) or FAIL (or -1). The GRsetcompress parameters are further described in Table 8D.

TABLE 8D - GRsetcompress Parameter List

Routine Name

[Return Type]
(FORTRAN-77)

Parameter
Parameter Type
Description
C
FORTRAN-77
GRsetcompress

[intn]
(mgscompress)

ri_id
int32
integer
Raster image identifier

comp_type
int32
integer
Compression method

c_info
comp_info*
N/A
Pointer to compression information structure

comp_prm
N/A
integer
Compression parameters array

8.6.3 External File Operations Using the GR Interface

An external image array is one that is stored in a file that is not the file containing the metadata for the image. The HDF file containing the metadata is known as the primary HDF file; the file containing the external image array is known as an external file. The concept of externally stored data is described in Chapter 3, Scientific Data Sets (SD API). The GR interface supports the same external file functionality as the SD interface.

8.6.3.1 Creating a Raster Image in an External File: GRsetexternalfile

Creating an image with the data stored in an external file involves the same general steps as with the SD interface:

  1. Create the image array.
  2. Specify that an external data file is to be used.
  3. Write data to the image array.
  4. Terminate access to the image.

To create a data set containing image array stored in an external file, the calling program must make the following calls.

C:		ri_id = GRcreate(gr_id, name, n_comps, data_type, interlace_mode, dim_sizes);
		status = GRsetexternalfile(ri_id, filename, offset);
		status = GRwriteimage(ri_id, start, stride, edges, image_data);
		status = GRendaccess(ri_id);
FORTRAN:	ri_id = mgcreat(gr_id, name, n_comps, data_type, interlace_mode, dim_sizes)
		status = mgsxfil(ri_id, filename, offset)
		status = mgwrimg(ri_id, start, stride, edges, image_data)
		status = mgendac(ri_id)
GRsetexternalfile marks the image identified by the parameter ri_id as one whose data is to be written to an external file. The parameter filename is the name of the external file, and the parameter offset specifies the number of bytes from the beginning of the external file to the location where the first byte of data will be written.

GRsetexternalfile can only be called once per data set. If a file with the same name as filename exists in the current directory, HDF will use it as the external file. If the file does not exist, HDF will create one. Once the name of the external file is specified, it is impossible to change it without breaking the association between the raster image and its data.

Use caution when writing to existing files because the routine GRwriteimage begins its write at the specified offset without checking whether existing data is being overwritten. When different data sets have arrays being stored the same external file, the calling program is responsible for avoiding any overlap between them.

GRsetexternalfile returns either SUCCEED (or 0) or FAIL (or -1). The parameters of GRsetexternalfile are further defined in Table 8E.

TABLE 8E - GRsetexternalfile Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
GRsetexternalfile

[intn]

(mgsxfil)
ri_id
int32
integer
Raster image identifier

filename
char *
character*(*)
Name of the external file

offset
int32
integer
Offset in bytes from the beginning of the external file to the image data

8.6.3.2 Moving Raster Images to an External File

Images can be moved from the primary HDF file to an external file. To do so requires the following steps:

  1. Select the image.
  2. Specify the external data file.
  3. Terminate access to the image.

The calling program must make the following calls:

C:		ri_id = GRselect(gr_id, ri_index);
		status = GRsetexternalfile(ri_id, filename, offset);
		status = GRendaccess(ri_id);
FORTRAN:	ri_id = mgselct(gr_id, ri_index);
		status = mgsxfil(ri_id, filename, offset)
		status = mgendac(ri_id);
When GRsetexternalfile is used in conjunction with GRselect, it will immediately write the existing data to the external file; any data in the external file that occupies the space reserved for the external array will be overwritten as a result of this operation. A data set can only be moved to an external file once.

During the operation, the data is written to the external file as a contiguous stream regardless of how it is stored in the primary file. Because data is moved "as is," any unwritten locations in the data set are preserved in the external file. Subsequent read and write operations performed on the data set will access the external file.



[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 07/21/98, NCSA HDF Development Group.