Image and ImGearPage

One of the primary entities in the ImageGear for Java toolkit is page and its implementation as the ImGearPage Class.

ImGearPage Class consists of three main parts: image data, metadata, and region of interest.

Image data (or simply, image) is available for manipulations through the getDIB method, which returns an object of type ImGearDIB. Color space, channels, width, and height are major attributes which define image structure.

ImageGear for Java considers an image as a collection of channels, each of which gives some single piece of information about the pixels in a whole image. Channels are defined as an array of depths for each channel. Depth specifies the quantity of different values for a particular channel. This data is constant for the page until image processing functions are applied. It may be accessed through the ImGearDIB.getChannelDepths method.

The ImGearColorSpace class (returned by the ImGearDIB.getColorSpace method) defines the semantics of the information stored in all channels (i.e., whether the second channel is the green component of RGB color, magenta of CMYK, or alpha value of a grayscale image). This information may be formed from ImGearColorSpaceIDs Enumeration flags and placed into a constructor of ImGearPage class via an ImGearColorSpace object.

Pixels in ImGearDIB class may be accessed as both individual pixels or groups of pixels. getPixelCopy method and updateColumnFrom method are examples of such members. An important note is that the routines to get pixels return copies of the data stored in an image as an object of the ImGearPixel class or the ImGearPixelArray class. None of these members allows direct access to the pixel store.

To gain direct access to image data, the getImage method or getRaster method of the ImGearDIB class should be used. This is an efficient way to implement image processing routines, since all changes made to the objects (returned by these functions) will be reflected in the image. Users of the getImage method or getRaster method should completely understand the structure of the internal pixel store to avoid producing ill-formed images.

The following example creates an RGB image and then swaps the red and blue channel values for diagonal pixels.

Example	Copy Code
// Creates page with RGB colorspace and 8 bits channels. ImGearPage igPage = new ImGearRasterPage(pageSize, pageSize, new ImGearColorSpace(ImGearColorSpaceIDs.RGB), new int[] { 8, 8, 8 }, true); // Iterates all rows in created page. for (int row = 0; row < igPage.getDIB().getHeight(); ++row) { // Obtains reference to raster store. ImGearArrayRef igArrayRef = igPage.getDIB().GetRaster(row); // Casts content to byte[] since all channels are 8 bit. byte[] raster = igArrayRef.Content.getBytes(); // Offset of diagonal pixel in raster. int pixelOffset = igArrayRef.Offset + row * igPage.getDIB().getChannelCount(); // Swaps red & blue. byte red = raster[pixelOffset + redChannel]; raster[pixelOffset + redChannel] = raster[pixelOffset + blueChannel]; raster[pixelOffset + blueChannel] = red; }

Example

Copy Code

// Creates page with RGB colorspace and 8 bits channels. 
ImGearPage igPage = new ImGearRasterPage(pageSize, pageSize,
    new ImGearColorSpace(ImGearColorSpaceIDs.RGB),
    new int[] { 8, 8, 8 },
    true);

// Iterates all rows in created page. 
for (int row = 0; row < igPage.getDIB().getHeight(); ++row)
{
    // Obtains reference to raster store. 
    ImGearArrayRef igArrayRef = igPage.getDIB().GetRaster(row);
    // Casts content to byte[] since all channels are 8 bit. 
    byte[] raster = igArrayRef.Content.getBytes();
    // Offset of diagonal pixel in raster. 
    int pixelOffset = igArrayRef.Offset + row * igPage.getDIB().getChannelCount();
    // Swaps red & blue. 
    byte red = raster[pixelOffset + redChannel];
    raster[pixelOffset + redChannel] = raster[pixelOffset + blueChannel];
    raster[pixelOffset + blueChannel] = red;
}

Metadata is non-image data, often available in some complex formats like TIFF or PNG. It may have complexity and is completely dependent on the nature of the file format. To provide a way of manipulating such data, ImageGear for Java offers a set of classes composed from ImGearMetadataNode Class, ImGearMetadataNodeList Class and ImGearMetadataTree Class and their descendants. For a particular ImGearPage instance, metadata may be accessed through the getMetadata method.

Region of interest (ImGearROI Class) represents a free-shape image area (rectangular, non-rectangluar, or entire space) and specifies a meaningful part of an image. For example, a region of interest may be established to define an area where some image processing functions should be applied.