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