Fifteen minutes Guide

JAI-EXT Maven artifacts can be found at the following link inside the GeoSolutions Maven repository.

For using the JAI-EXT artifacts directly into another project the user must follow a few simple steps:

• Add the GeoSolutions Maven repository to the pom.xml file:

  <repositories>
    <repository>
      <id>geosolutions</id>
      <name>GeoSolutions Repository</name>
      <url>http://maven.geo-solutions.it</url>
    </repository>
  </repositories>

• Then add the Jai-Ext dependency required to the pom.xml. For example for the rescale operation:

<dependencies>
     <dependency>
        <groupId>it.geosolutions.jaiext.rescale</groupId>
       <artifactId>jt-rescale</artifactId>
       <version>${project.version}</version>
     </dependency>
</dependencies>

• Build your project
• Example of use of the operation.

// Image to elaborate
RenderedImage source;
// Selection of the Image bounds
int minx = source.getMinX(); // Minimum X value of the image
int miny = source.getMinY(); // Minimum Y value of the image
int width = source.getWidth(); // Image Width
int height= source.getHeight(); // Image Height

Definition of the scale and offset factors for all the bands. If we have more than one band, the first value is used also for the other bands.

double[] scales = new double[]{2.0d};
double[] offsets= new double[]{1.0d};

Definition of the ROI on which calculating the result. In this case we use a ROI which is an half of the source image.

ROI roi= new ROIShape(new Rectangle(minx, miny, width, (int)(height/2)));

Definition of a Range of No Data. The Range class is contained in the package it.geosolutions.jaiext.range. It defines a range of values which are No Data and must not be calculated. For example we can set a single no data as 0. Supposing the image is Byte. If the image belongs to another datatype, the nodata for the range must have the same datatype, otherwise an exception is thrown. The following range will contain a single value. The maxIncluded and minIncluded parameters indicates if the Range bounds must be included or not.

byte value= 0;
boolean minIncluded = true;
boolean maxIncluded = true;

A Range object is created with the associated factory.

Range nodata = RangeFactory.create(value, minIncluded, value, maxIncluded);

If possible, the user can choose if the ROI check is made with the help of a RasterAccessor or in the default way. The RasterAccessor in some cases is more precise but requires to use more memory. In our case we will use the default behaviour.

boolean useRoiAccessor = false;

Definition of a value to set when a source image pixel is a nodata and then it is not calculated.

double destNoData = 0.0d;

RenderingHints used for setting other optional parameters to use by the Rescale operation, like the TileCache. In this case no optional parameter is set.

RenderingHints hints = null;

Note that the final image is a RenderedOp, an implementation of the RenderedImage interface with other additional methods.

RenderedOp rescaled = RescaleDescriptor.create(source, scales, offsets, roi,
                noDataRange, useRoiAccessor, destNoData, hints);

The final image is not already calculated; this happens because the JAI API returns the tiles to be rendered only when they are requested and not before, with a functionality similar to the lazy initialization. For forcing the computation of the image tiles the user can call the following methods:

// For calculating all the tiles
Raster[] data = rescaled.getTiles();
// For calculating a single tile
// x = tile X coordinate;
// y = tile Y coordinate;
Raster tile = rescaled.getTile(x, y);

These methods will process the image tiles and return them inside a Raster object, which can be directly accessed with the getSample() and getPixel() methods.

// x = pixel X coordinate;
// y = pixel Y coordinate;
// b = band index;
int singleSample = tile.getSample(x,y,b);
int[] singlePixel = tile.getPixel(x,y, new int[0]);