ChangeMatrix Operation

The ChangeMatrix operation is a new operation that takes in input two images, one called Reference image and the other called Source image, and counts, for each couple of source-reference pixels, how many times this couple is present. The pixel values are called classes, and the ChangeMatrix is used for storing informations about the possible changes of them.

It is important to note that the source and reference images must have the same data type, the same dimensions, and must contain only integral data.

WORKFLOW:

• creation of the descriptor and the RenderedImageFactory associated to the ChangeMatrix operation;
• testing of all the classes.

The classes composing this module are:

• ChangeMatrix : this class is the place where the information about the class variations are stored.
• ChangeMatrixOpImage : this class executes the "ChangeMatrix" operation.
• ChangeMatrixDescriptor : this class defines the parameters for the "ChangeMatrix" operation.
• ChangeMatrixRIF : this class is a RenderedImageFactory called by JAI for returning a new instance of the ChangeMatrixOpImage.

The ChangeMatrix is a container which stores the information about how many class pairs are founded between the two images. Not all the class pairs must be recorded, but only the ones defined by the user. Optionally the user can also define a ROI on which the calculations are performed. The ChangeMatrix must be set as a parameter for the ChangeMatrixOpImage class for having the desired calculations.

A simple pseudo-code for better understanding how the ChangeMatrix is calculated:

// s[x][y] = pixel value of the source.
// r[x][y] = pixel value of the reference.
// cm = changeMatrix object.
// insideROI = boolean indicating that the pixel is contained in the optional ROI object(if provided).
// srcHeight,srcWidth = source image tiles number, height, width.

// Calculation of the ChangeMatrix
for(int y = 0; y<srcHeight;y++){
    for(int x = 0; x<srcWidth;x++){
        if(insideROI){
            // Selection of the input class values 
            // and update of the counter associated 
            // to this couple.
            cm.registerPair(s[x][y],r[x][y]);
        }                                
    }
}

The calculations on the ChangeMatrix are executed inside the ChangeMatrixOpImage class. This class takes in input the two images, the ChangeMatrix object, an optional ROI if needed, and an integer value called PixelMultiplier used for processing the pixels of the two images. The ChangeMatrixOpImage executes two different operations:

• calculates the ChangeMatrix by setting each couple of pixels from the source and reference images.
• processes the input images and return a result image where each pixel is a combination of the source and reference images, so that for 2 pixel with the same source and same reference pixel value (source and reference could be different), the result pixel will be the same.

The operation on the pixel values can be resumed with this simple pseudo-code:

// s[x][y] = pixel value of the source.
// r[x][y] = pixel value of the reference.
// d[x][y] = pixel value of the result image.
// pixelMultiplier = constant value used for processing pixels.
// insideROI = boolean indicating that the pixel is contained in the optional ROI object(if provided).
// srcHeight,srcWidth = source image tiles number, height, width.

// Pixel Processing
for(int y = 0; y<srcHeight;y++){
    for(int x = 0; x<srcWidth;x++){
        if(insideROI){
            // Processing
            d[x][y] = r[x][y] + pixelMultiplier * s[x][y];
        }                                
    }
}

With this operation it is simple to find the reference class from each pixel by simply calculating the module of the pixel with the multiplier, and the source class by subtracting the reference value from the pixel value and then dividing for the multiplier. It is worth to point out that this algorithm could change the data type of the output image, because the final result could be bigger than the maximum value allowed for the input image data type.

The ChangeMatrixDescriptor class defines the input parameters of the ChangeMatrix operation used by JAI for register the operation.

The ChangeMatrixRIF class is a RenderedImageFactory associated to the ChangeMatrix operation. This class is called when the JAI.create() method is called with the argument string "ChangeMatrix" and a parameterBlock object containing all the parameters associated with the operation. The ChangeMatrixRIF takes the parameterBlock, unpacks the parameters and passes them to a new instance of the "ChangeMatrixOpImage".

For evaluating the functionalities of the ChangeMatrix operation these test-classes are used:

• ChangeMatrixTest
• SpeedChangeMatrixTest

The first class contains multiple tests for checking if the ChangeMatrixOpImage class throws an exception when the input parameters are not correctly set. Also various tests ensure that both the changematrix calculation and the pixel processing are done in a right way. Some tests are executed with a ROI object. The tests are made for all the allowed data types both in input and output(if the data type is changed).

The second class contains a single test which executes the ChangeMatrix operation on the same image multiple times, and after each calculation flushes the tile cache from the destination image tiles, so that the calculation must be restarted. At the end of all the cycles, the mean calculation time is returned. Not all the cycle are taken into account, in fact the first N (where N can be defined by the user or left by default to 20) cycles are not considered due to the Java HotSpot compilation. The result is printed to the screen.

Maven dependency associated with this module:

<dependency>
    <groupId>it.geosolutions-jai-ext</groupId>
    <artifactId>change-matrix</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>