THe GR Images (GR) API provides the data interface, data model, and a collection of calable software (C or FORTRAN) to work with raster images in HDF format. The GR interface is very similar to the SD interface, and also allows for working with multiple files. As will be demonstrated in further sections, all callable FORTRAN (C) routines/programs used to work with images in the GR interface begin with the "mg" ("GR") prefix. Each GR data set (image) must contain the following:
Similar to the SD API, the GR interface provides software that allows for data compression, data chunking, the use of external files, the modification of existing files, and the writing and reading of both entire or partial GR images or data along with associated palettes. As a teaching tool, this tutorial will mainly focus upon the writing and reading of full images. For a complete listing of all operations permitted in the GR API, please see the HDF 4.1r3 Users Guide.
The Image array is a 2-D array of pixels that represent the image data itself. In addition, each raster imager/image array has an associated index and reference number that, respectively, locates the position of the data set in the HDF file and a reference number assigned by the calling interface.
Along with the reference number, a raster image indentifier is also generated by the callable GR API routines when opening new or existing data. This identifier uniquely indentifies a raster image within a file.
The name is a case-sensitive character string chosen by the creator of the image array when written in the GR interface.
Each pixel (element) in an array consists of a number of color component values such as Red-Green-Blue (RGB). These are called pixel components and can be represented by methods such as lookup tables. The data type and the number of components in each pixel comprise the pixel type.
Dimensions are used, upon data set creation, to specify the shape of the image array for raster images.
These are components not required for GR data sets, but which may be included by the creator of the image. The two types of optional components allowed in the GR interface are palettes and attributes.. The attributes contain information about the files and images themselves. The listings are similar to the attributes for the SD API. Please see Section 11 - Attributes and Metadata for a complete overview.
Palettes are used to define the color values for the pixels in each array. The GR API (in addition to the Palette API) provides routines that permit the reading and writing of palette data within the GR interface. This is discussed in more detail in upcoming sections.