[Top] [Prev]
8.11 Chunked Raster Images
The GR interface also supports chunking in a manner similar to that of the SD interface. There is one restriction on a raster image: it must be created with MFGR_INTERLACE_PIXEL (or 0) in the call to GRcreate. We refer the reader to Section 3.11 of Chapter 3, Scientific Data Sets (SD API), and to Chapter 14, HDF Performance Issues, for discussions of chunking concepts and performance related topics. The GR interface provides three routines, GRsetchunk, GRsetchunkcache, and GRgetchunkinfo, to create and maintain chunked raster images. The GR interface does not have special write/read routines similar to SDwritechunk/SDreadchunk; chunked raster images are written and read by GRwriteimage and GRreadimage.
8.11.1 Difference between a Chunked Raster Image and a Chunked SDS
Chunks of scientific datasets (SDSs) have the same dimensionality as the SDS itself and the chunks can divide the SDS along any dimension. While raster images under the GR interface are actually 3-dimensional arrays, 2 dimensions define the image while the third dimension (the stack of 2-dimensional image planes) provides the composite definition of the color at each pixel of the 2-dimensional image. Chunking can be applied only across the 2-dimensions of the image; chunking cannot divide the array across the third dimension. In other words, all of the elements of the raster image that define a single pixel must remain together in the same chunk.
FIGURE 8b 
Chunks in a GR raster image dataset
8.11.2 Making a Raster Image a Chunked Raster Image: GRsetchunk
GRsetchunk makes the raster image, identified by the parameter ri_id, a chunked raster image according to the provided chunking and compression information. The syntax of GRsetchunk is as follows:
C: status = GRsetchunk(ri_id, c_def, flags);
FORTRAN: status = mgschnk(ri_id, dim_length, comp_type, comp_prm)
The parameters c_def and flags in C or the parameters comp_type and comp_prm in FORTRAN-77 provide the chunking and compression information and are discussed below.
In C:
The parameter c_def is a union of type HDF_CHUNK_DEF, which is defined as follows:
typedef union hdf_chunk_def_u
{
int32 chunk_lengths[2]; /* chunk lengths along each dim */
struct
{
int32 chunk_lengths[2];
int32 comp_type; /* compression type */
struct comp_info cinfo;
} comp;
struct
{
/* is not used in GR interface */
} nbit;
} HDF_CHUNK_DEF
Valid values of the parameter flags are HDF_CHUNK for chunked and uncompressed data and (HDF_CHUNK | HDF_COMP) for chunked and compressed data. Data can be compressed using run-length encoding (RLE), Skipping Huffman, or GZIP compression algorithms.
If the parameter flags has a value of HDF_CHUNK, the chunk dimensions must be specified in the field c_def.chunk_lengths[]. If the parameter flags has a value of (HDF_CHUNK | HDF_COMP), the chunk dimensions must be specified in the field c_def.comp.chunk_lengths[] and the compression type in the field c_def.comp.comp_type. Valid values of compression type values are:
-
COMP_CODE_NONE (or 0) for uncompressed data
-
COMP_CODE_RLE (or 1) for data compressed using the RLE compression algorithm
-
COMP_CODE_SKPHUFF (or 3) for data compressed using the Skipping Huffman compression algorithm
-
COMP_CODE_DEFLATE (or 4) for data compressed using the GZIP compression algorithm
If using Skipping Huffman compression, the skipping size is specified in the field c_def.comp.cinfo.skphuff.skp_size. If using GZIP compression, the deflate level is specified in the field c_def.comp.cinfo.deflate.level. Valid deflate level values are integers from 1 to 9 inclusive. Refer to the discussion of SDsetcompress routine in Section 3.5.2 on page 45 for the definition of the structure comp_info.
In FORTRAN-77:
Chunk dimensions are specified in the array dim_length and the compression type in the parameter comp_type. Valid compression types and their values are defined in the "hdf.inc"file and are listed below:
-
COMP_CODE_NONE (or 0) for uncompressed data
-
COMP_CODE_RLE (or 1) for data compressed using the RLE compression algorithm
-
COMP_CODE_SKPHUFF (or 3) for data compressed using the Skipping Huffman compression algorithm
-
COMP_CODE_DEFLATE (or 4) for data compressed using the GZIP compression algorithm
The parameter comp_prm specifies the compression parameters for the Skipping Huffman and GZIP compression methods. It contains only one element which is set to the skipping size for Skipping Huffman compression or the deflate level for GZIP compression.
GRsetchunk returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise. The GRsetchunk parameters are discussed further in Table 8L on page 284.
8.11.3 Obtaining Information about a Chunked Raster Image: GRgetchunkinfo
GRgetchunkinfo is used to determine whether a raster image is chunked and how chunking is defined. The syntax of the GRgetchunkinfo routine is as follows:
C: status = GRgetchunkinfo(ri_id, &c_def, &flag);
FORTRAN: status = mggichnk(ri_id, dim_length, flag)
GRgetchunkinfo retrieves chunking information about the raster image into the parameters c_def and flag in C and into the parameters dim_length and flag in FORTRAN-77. Note that only chunk dimensions are retrieved; compression information is not available.
The value returned in the parameter flag indicates whether the raster image is not chunked, chunked, or chunked and compressed. HDF_NONE (or -1) indicates that the raster image is not chunked. HDF_CHUNK (or 0) indicates that the raster image is chunked and not compressed. (HDF_CHUNK | HDF_COMP) (or 1) indicates that raster image is chunked and compressed with one of the allowed compression methods: RLE, Skipping Huffman, or GZIP.
In C, if the raster image is chunked and not compressed, GRgetchunkinfo fills the array chunk_lengths in the union c_def with the values of the corresponding chunk dimensions. If the raster image is chunked and compressed, GRgetchunkinfo fills the array chunk_lengths in the structure comp of the union c_def with the values of the corresponding chunk dimensions. Refer to Section 8.11.2 on page 282 on GRsetchunk for specific information on the union HDF_CHUNK_DEF. In C, if the chunk length for each dimension is not needed, NULL can be passed in as the value of the parameter c_def.
In FORTRAN-77, chunk dimensions are retrieved into the array dim_length.
GRgetchunkinfo returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise. The GRgetchunkinfo parameters are discussed further in Table 8L.
8.11.4 Setting the Maximum Number of Chunks in the Cache: GRsetchunkcache
GRsetchunkcache sets the maximum number of chunks to be cached for chunked raster image. GRsetchunkcache has similar behavior to SDsetchunkcache. Refer to Section 3.11.2 on page 106 for specific information. The syntax of GRsetchunkcache is as follows:
C: status = GRsetchunkcache(ri_id, maxcache, flags);
FORTRAN: status = mgscchnk(ri_id, maxcache, flags)
The maximum number of chunks is specified by the parameter maxcache. Currently, the only valid value of the parameter flags is 0.
If GRsetchunkcache is not called, the maximum number of chunks in the cache is set to the number of chunks along the fastest-changing dimension. Since GRsetchunkcache is similar to the routine SDsetchunkcache, refer to Section 3.11.2 on page 106 for more detailed discussion of the routine's behavior.
GRsetchunkcache returns the value of the parameter maxcache if successful and FAIL (or -1) otherwise. The GRsetchunkcache parameters are discussed further in Table 8L.
TABLE 8L - GRsetchunk, GRgetchunkinfo, and GRsetchunkcache Parameter Lists
[Top] [Prev]
hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 05/19/99, NCSA HDF
Development Group.