Writing data to an image array involves the following steps:
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.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.SUCCEED (or 0) or FAIL (or -1). The parameters for GRwriteimage are described in Table 8C.
TABLE 8C - GRwriteimage Parameter List
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
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.DFNT_CHAR8, and interlace mode of MFGR_INTERLACE_PIXEL.
8.6.2 Compressing Raster Images: GRsetcompress
(Note: The GRsetcompress routine does not work in the current release.)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
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
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:
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.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.SUCCEED (or 0) or FAIL (or -1). The parameters of GRsetexternalfile are further defined in Table 8E.
TABLE 8E - GRsetexternalfile Parameter List
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.