C: file_id = Hopen(filename, access_mode, number_of_desc); gr_id = GRstart(file_id); ri_id = GRselect(gr_id, gr_index); status = GRreadimage(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 = mgselct(gr_id, GRs_index) status = mgrdimg(ri_id, start, stride, edge, data) status = mgendac(gr_id) status = mgend(ri_id) status = hclose(file_id)
GRreadimage can be used to read either an entire image or a subset of the image. The ri_id argument is the raster image identifier returned by GRselect. As with GRwriteimage, the arguments start, stride, and edge respectively describe the starting location for the read operation, the number of locations the current image array location will be moved forward after each read, and the length of each dimension to be read. If the image array is smaller than the data argument array, the amount of data read will be limited to the maximum size of the image array.
8.6.1 Reading General Raster Images from an External File
Image data is read from an external or compressed file in the same way that it is read from a primary file. 8.6.2 Setting the Interlace Mode for a Palette or Image Read
There are two GR routines that deal with setting the interlace in raster image data sets: GRreqlutil and GRreqimageil. Refer to Section 8.5.2 on page 205 for a description of the GR interlace modes.
The GRreqlutil routine sets the interlace mode for the next palette read. It can be called at anytime before the read operation and takes two parameters, ri_id and interlace_mode. The ri_id parameter is the image array identifier returned by the GRselect routine and the interlace_mode is the interlace mode that will be in effect for the next image or palette read operation.
TABLE 8E GRreadimage, GRreqlutil and GRreqimageil Parameter List
C:
#include "hdf.h" #define X_LENGTH 15 #define Y_LENGTH 10 main( ) { int32 gr_id, ri_id, file_id, status; int32 start[2], edges[2], dims[2], nattrs; int16 image_data[Y_LENGTH][X_LENGTH][2]; /* Open the file. */ file_id = Hopen("Example2.hdf", DFACC_RDONLY, 0); /* Open the file and initiate the GR interface. */ gr_id = GRstart(file_id); /* Select the first (and in this case, only) data set in the file. */ ri_id = GRselect(gr_id, 0); /* Define the location, pattern, and size of the data to read. */ dims[0] = X_LENGTH; dims[1] = Y_LENGTH; start[0] = start[1] = 0; edges[0] = dims[0]; edges[1] = dims[1]; /* Read the data in the image array. */ status = GRreadimage(ri_id, start, NULL, edges, (VOIDP)image_data); /* Terminate access to the image array */ status = GRendaccess(ri_id); /* Terminate access to the GR interface. */ status = GRend(gr_id); /* Close the file. */ status = Hclose(file_id); }
PROGRAM READ ARRAY integer*4 gr_id, ri_id, file_id, status integer start(2), edge(2), stride(2) integer hopen, hclose, mgstart, mgselct, mgrdimg integer mgendac, mgend C DFACC_RDONLY is defined in hdf.h. MAX_NC_NAME and MAX_VAR_DIMS C are defined in netcdf.h. integer*4 DFACC_RDONLY, MAX_NC_NAME, MAX_VAR_DIMS integer*4 X_LENGTH, Y_LENGTH parameter (DFACC_RDONLY = 1, MAX_NC_NAME = 256, + MAX_VAR_DIMS = 32, X_LENGTH = 15, + Y_LENGTH = 10) integer*2 array_data(2, X_LENGTH, Y_LENGTH) integer dims(MAX_VAR_DIMS) C Open the file. file_id = hopen(`Example2.hdf', DFACC_RDONLY, 0) C Initiate the GR interface. gr_id = mgstart(file_id) C Select the first (and in this case, only) data set in the file. ri_id = mgselct(gr_id, 0) C Define the location, pattern, and size of the data to read C from the data set. dims(1) = X_LENGTH dims(2) = Y_LENGTH start(1) = 0 start(2) = 0 stride(1) = 1 stride(2) = 1 edge(1) = dims(1) edge(2) = dims(2) C Read the array data set. status = mgrdimg(ri_id, start, stride, edge, array_data) C Terminate access to the image array. status = mgendac(ri_id) C Terminate access to the GR interface and the file. status = mgend(gr_id) C Close the file. status = hclose(file_id) end
EXAMPLE 4. Reading a Subset of an Image Array
The following examples show how the start and edges arguments of the GRreadimage function can be initialized so that a subset of the data set can be read.
#include "hdf.h" #define X_LENGTH 15 #define Y_LENGTH 10 main( ) { int32 gr_id, ri_id, file_id; int32 start[2], edges[2]; int16 all_image[2][Y_LENGTH][X_LENGTH]; int16 subset_image[2][7][3], status; /* Open the file. */ file_id = Hopen("Example2.hdf", DFACC_RDONLY, 0); /* Open the file for read-only access. */ gr_id = GRstart(file_id); /* Select the first data set. */ ri_id = GRselect(gr_id, 0); /* First, read the entire data set. */ start[0] = start[1] = 0; edges[0] = X_LENGTH; edges[1] = Y_LENGTH; status = GRreadimage(ri_id, start, NULL, edges, (VOIDP)all_image); /* Read a subset of the data set. */ start[0] = 1; start[1] = 1; edges[0] = 3; edges[1] = 7; status = GRreadimage(ri_id, start, NULL, edges, (VOIDP)subset_image); /* 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); }
PROGRAM READ SUBSET integer*4 gr_id, ri_id, file_id integer start(2), edges(2), stride(2), status integer mgstart, mgselct, mgrdimg, mgendac, mgend integer hopen, hclose C DFACC_RDONLY is defined in hdf.h. integer*4 DFACC_RDONLY integer*4 X_LENGTH, Y_LENGTH parameter (DFACC_RDONLY = 1, X_LENGTH = 15, Y_LENGTH = 10) integer*2 all_image(2, X_LENGTH, Y_LENGTH) integer*2 subset_image(2, 3, 7) C Open the file. file_id = hopen(`Example2.hdf', DFACC_RDONLY, 0) C Initialize the GR interface. gr_id = mgstart(file_id) C Select the first data set. ri_id = mgselct(gr_id, 0) C Read the entire data set. start(1) = 0 start(2) = 0 edges(1) = X_LENGTH edges(2) = Y_LENGTH stride(1) = 1 stride(2) = 1 status = mgrdimg(ri_id, start, stride, edges, all_image) C Read a subset from the middle of the data set. start(1) = 1 start(2) = 1 edges(1) = 3 edges(2) = 7 status = mgrdimg(ri_id, start, stride, edges, subset_image) C Terminate access to the array. status = mgendac(ri_id) C Terminate access to the GR interface and the file. status = mgend(gr_id) C Close the file. file_id = hclose(file_id) end
EXAMPLE 5. Sampling Image Data
These examples illustrate how samples of data set elements can be read by using the stride argument of the GRreadimage function. Here we read every fourth row and every other column.
#include "hdf.h" #include "mfgr.h" #define X_LENGTH 10 #define Y_LENGTH 20 main( ) { int32 gr_id, ri_id, file_id, start[2], edges[2], ncomp, il; int32 stride[2], dims[2]; int16 all_image[Y_LENGTH][X_LENGTH][2], sample_image[5][5][2], status; intn i, j; /* Open the file. */ file_id = Hopen("Example5.hdf", DFACC_CREATE, 0); /* Open the file. */ gr_id = GRstart(file_id); /* Define the number of components and dimensions of the image. */ ncomp = 2; dims[0] = X_LENGTH; dims[1] = Y_LENGTH; il = MFGR_INTERLACE_PIXEL; /* Create the array. */ ri_id = GRcreate(gr_id, "Image_array_5", ncomp, DFNT_INT16, il, dims); /* Compute and store the data values. */ for (j = 0; j < Y_LENGTH; j++) { for (i = 0; i < X_LENGTH; i++) { all_image[j][i][0] = i + j * 10; all_image[j][i][1] = i + j * 10; } } /* Define the start and edge parameters. */ start[0] = start[1] = 0; edges[0] = X_LENGTH; edges[1] = Y_LENGTH; /* Write the buffered data in all_image to the array. */ status = GRwriteimage(ri_id, start, NULL, edges, (VOIDP)all_image); /* Close the GR interface and the file, then re-open both and select the first and only data set in the file. */ status = GRendaccess(ri_id); status = GRend(gr_id); status = Hclose(file_id); file_id = Hopen("Example5.hdf", DFACC_RDONLY, 0); gr_id = GRstart(file_id); ri_id = GRselect(gr_id, 0); /* Read the data into sample_image, skipping every fourth \ row and every other column. */ start[0] = start[1] = 0; edges[0] = 5; edges[1] = 5; stride[0] = 2; stride[1] = 4; status = GRreadimage(ri_id, start, stride, edges, (VOIDP)sample_image); /* Terminate access to the array */ status = GRendaccess(ri_id); /* Terminate access to the GR interface the file */ status = GRend(gr_id); /* Close the file */ status = Hclose(file_id); }
PROGRAM READ STRIDES integer*4 gr_id, ri_id, file_id, ncomp, il integer*4 start(2), edges(2), stride(2), dims(2) integer i, j, status integer mgstart, mgcreat, mgwrimg, mgendac integer mgselct, mgend, hopen, hclose C DFACC_CREATE and DFNT_INT16 are defined in hdf.h. integer*4 DFACC_CREATE, DFACC_RDONLY, DFNT_INT16 integer*4 X_LENGTH, Y_LENGTH parameter (DFACC_CREATE = 4, DFACC_RDONLY = 1, DFNT_INT16 = 22, + X_LENGTH = 10, Y_LENGTH = 20) integer*2 all_image(2, X_LENGTH, Y_LENGTH) C Create the file. file_id = hopen(`Example5.hdf', DFACC_CREATE, 0) C Create the file. gr_id = mgstart(file_id) C Define the number of components and dimensions of the image. ncomp = 2 dims(1) = X_LENGTH dims(2) = Y_LENGTH C Create the array. ri_id = mgcreat(gr_id, `Image_array_5', ncomp, DFNT_INT16, il, + dims) C Compute and store the data values. do 20 j = 1, Y_LENGTH do 10 i = 1, X_LENGTH all_image(1, i, j) = i + j * 10 all_image(2, i, j) = i + j * 10 10 continue 20 continue C Set up the start and edge parameters to write the buffered C data to the entire array. start(1) = 0 start(2) = 0 edges(1) = X_LENGTH edges(2) = Y_LENGTH stride(1) = 1 stride(2) = 1 C Write the buffered data in all_image to the data set array. status = mgwrimg(ri_id, start, stride, edges, all_image) C Close the GR interface and the file, then re-open both and C select the first and only data set in the file. status = mgendac(ri_id) status = mgend(gr_id) status = hclose(file_id) file_id = hopen(`Example5.hdf', DFACC_RDONLY, 0) gr_id = mgstart(file_id) ri_id = mgselct(gr_id, 0) C Read the data into sample_image, skipping every fourth row C and every other column. edges(1) = 5 edges(2) = 5 stride(1) = 4 stride(2) = 2 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