jaitools.media.jai.zonalstats
Class ZonalStatsDescriptor

java.lang.Object
  javax.media.jai.OperationDescriptorImpl
      jaitools.media.jai.zonalstats.ZonalStatsDescriptor

All Implemented Interfaces:

java.io.Serializable, javax.media.jai.OperationDescriptor, javax.media.jai.RegistryElementDescriptor

public class ZonalStatsDescriptor
extends javax.media.jai.OperationDescriptorImpl

Calculates a range of summary statistics, optionally for zones defined in a zone image, for values in a data image. The operator can be used without a zone image, in which case it will treat all data image pixels as being in the same zone (labeled zone 0).

Optionally, an ROI can be provided to define which pixels in the data image will contribute to the zonal statistics.

Note that the source names for this operator are "dataImage" and "zoneImage" rather than the more typical JAI names "source0", "source1".

If a zone image is provided it must be of integral data type. By default, an identity mapping is used between zone and data images, ie. zone image pixel at x, y is mapped to the data image pixel at x, y. Any data image pixels that do not have a corresponding zone image pixel are ignored, thus the zone image bounds can be a subset of the data image bounds.

The user can also provide an AffineTransform to map data image positions to zone image positions. For example, multiple data image pixels could be mapped to a single zone image pixel.

The range of data image values that contribute to the analysis can be constrained by supplying a List of Range objects, each of which defines a range of data values to exclude.

Use of this operator is similar to the standard JAI statistics operators such as javax.media.jai.operator.HistogramDescriptor where the source image is simply passed through to the destination image and the results of the operation are retrieved as a property. For this operator the property name can be reliably referred to via the ZONAL_STATS_PROPERTY constant.

The operator uses the StreamingSampleStats class for its calculations, allowing it to handle very large images for statistics other than Statistic.MEDIAN, for which the Statistic.APPROX_MEDIAN alternative is provided.

Example of use...

 RenderedImage myData = ...
 RenderedImage myZones = ...

 ParameterBlockJAI pb = new ParameterBlockJAI("ZonalStats");
 pb.setSource("dataImage", myData);
 pb.setSource("zoneImage", myZones);

 Statistic[] stats = {
     Statistic.MIN,
     Statistic.MAX,
     Statistic.MEAN,
     Statistic.APPROX_MEDIAN,
     Statistic.SDEV
 };

 pb.setParameter("stats", stats);
 RenderedOp op = JAI.create("ZonalStats", pb);
 
 ZonalStats stats = (ZonalStats) op.getProperty(ZonalStatsDescriptor.ZONAL_STATS_PROPERTY);

 // print results to console
 for (Result r : stats.results()) {
     System.out.println(r);
 }
 

The ZonalStats object returned by the getProperty method above allows you to examine results by image band, zone and statistic as shown here...

 ZonalStats stats = (ZonalStats) op.getProperty(ZonalStatsDescriptor.ZONAL_STATS_PROPERTY);

 // print all results for band 0
 for (Result r : stats.band(0).results()) {
     System.out.println(r);
 }

 // print all result for band 2, zone 5
 for (Result r : stats.band(2).zone(5).results()) {
     System.out.println(r);
 }

 // print MEAN values for all zones in band 0
 for (Result r : stats.band(0).statistics(Statistic.MEAN).results()) {
     System.out.println(r);
 }
 

Using the operator to calculate statistics for an area within the data image...

 RenderedImage myData = ...
 Rectangle areaBounds = ...
 ROI roi = new ROIShape(areaBounds);

 ParameterBlockJAI pb = new ParameterBlockJAI("ZonalStats");
 pb.setSource("dataImage", myData);
 pb.setParameter("roi", roi);

 pb.setParameter("stats", someStats);
 RenderedOp op = JAI.create("ZonalStats", pb);

 ZonalStats stats = (ZonalStats) op.getProperty(ZonalStatsDescriptor.ZONAL_STATS_PROPERTY);

 // print results to console
 for (Result r : stats.results()) {
     System.out.println(r);
 }

 

Using an AffineTransform to map data image position to zone image position...

 ParameterBlockJAI pb = new ParameterBlockJAI("ZonalStats");
 pb.setSource("dataImage", myDataImage);
 pb.setSource("zoneImage", myZoneImage);
 pb.setParameter("stats", someStats);

 AffineTransform tr = new AffineTransform( ... );
 pb.setParameter("zoneTransform", tr);
 

Asking for statistics on multiple bands.

By default the stats are calculated on a single default 0 index band. It is possible also to request calculations on multiple bands, by passing the band indexes as a parameter.

 ParameterBlockJAI pb = new ParameterBlockJAI("ZonalStats");
 pb.setSource("dataImage", myDataImage);
 pb.setSource("zoneImage", myZoneImage);
 pb.setParameter("stats", someStats);

 // ask for stats on band 0 and 2 of the image
 pb.setParameter("bands", new Integer[]{0, 2});
 RenderedOp op = JAI.create("ZonalStats", pb);

 // get the results
 ZonalStats> stats = (ZonalStats) op.getProperty(ZonalStatsDescriptor.ZONAL_STATS_PROPERTY);

 // results by band
 List resultsBand0 = stats.band(0).results;
 List resultsBand2 = stats.band(2).results;
 

Excluding data values from the analysis with the "exclude" parameter:

 ParameterBlockJAI pb = new ParameterBlockJAI("ZonalStats");
 ...

 // exclude values between -5 and 5 inclusive
 List<Range<Double>> excludeList = CollectionFactory.newList();
 excludeList.add(Range.create(-5, true, 5, true));
 pb.setParameter("exclude", excludeList);

 // after we run the operator and get the results we can examine
 // how many sample values were included in the calculation
 List results = zonalStats.results();
 for (Result r : results) {
     int numUsed = r.getNumAccepted();
     int numExcluded = r.getNumOffered() - numUsed;
     ...
 }
 

Parameters

Name	Type	Default value
stats	Statistic[]	NO DEFAULT
bands	Integer[]	{0}
roi	ROI	null
zoneTransform	AffineTransform	null (identity transform)
exclude	List<Range>	null (include all data values)

Since:

1.0

Version:

$Id: ZonalStatsDescriptor.java 1100 2010-02-10 07:28:08Z michael.bedward $

Author:

Michael Bedward, Andrea Antonello

See Also:

Result, Statistic, StreamingSampleStats, ZonalStats, Serialized Form

Field Summary

static java.lang.String

ZONAL_STATS_PROPERTY Property name used to retrieve the results

Fields inherited from class javax.media.jai.OperationDescriptorImpl

resources, sourceNames, supportedModes

Fields inherited from interface javax.media.jai.OperationDescriptor

NO_PARAMETER_DEFAULT

Constructor Summary

ZonalStatsDescriptor()
Constructor.

Method Summary

boolean	arePropertiesSupported() Returns true to indicate that properties are supported
static java.awt.image.RenderedImage	create(java.awt.image.RenderedImage dataImage, java.awt.image.RenderedImage zoneImage, Statistic[] stats, java.lang.Integer[] bands, javax.media.jai.ROI roi, java.awt.geom.AffineTransform zoneTransform, java.util.List<Range<java.lang.Double>> exclude, java.awt.RenderingHints hints) Convenience method which constructs a ParameterBlockJAI and invokes JAI.create("ZonalStats", params)
boolean	validateArguments(java.lang.String modeName, java.awt.image.renderable.ParameterBlock pb, java.lang.StringBuffer msg) Checks parameters for the following: Number of sources is 1 or 2 Data image bands are valid Zone image, if provided, is an integral data type Zone image, if provided, overlaps the data image, taking into account any AffineTransform

Methods inherited from class javax.media.jai.OperationDescriptorImpl

getDefaultSourceClass, getDestClass, getDestClass, getInvalidRegion, getName, getNumParameters, getNumSources, getParamClasses, getParamDefaults, getParamDefaultValue, getParameterListDescriptor, getParamMaxValue, getParamMinValue, getParamNames, getPropertyGenerators, getPropertyGenerators, getRenderableDestClass, getRenderableSourceClasses, getResourceBundle, getResources, getSourceClasses, getSourceClasses, getSourceNames, getSupportedModes, isImmediate, isModeSupported, isRenderableSupported, isRenderedSupported, makeDefaultSourceClassList, validateArguments, validateParameters, validateParameters, validateRenderableArguments, validateRenderableSources, validateSources, validateSources

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ZONAL_STATS_PROPERTY

public static java.lang.String ZONAL_STATS_PROPERTY

Property name used to retrieve the results

Constructor Detail

ZonalStatsDescriptor

public ZonalStatsDescriptor()

Constructor.

Method Detail

create

public static java.awt.image.RenderedImage create(java.awt.image.RenderedImage dataImage,
                                                  java.awt.image.RenderedImage zoneImage,
                                                  Statistic[] stats,
                                                  java.lang.Integer[] bands,
                                                  javax.media.jai.ROI roi,
                                                  java.awt.geom.AffineTransform zoneTransform,
                                                  java.util.List<Range<java.lang.Double>> exclude,
                                                  java.awt.RenderingHints hints)

Convenience method which constructs a ParameterBlockJAI and invokes JAI.create("ZonalStats", params)

Parameters:

dataImage - the data image

zoneImage - the zone image which must be of integral data type

stats - an array specifying the statistics required

bands - the array of bands of the data image to process (default single band == 0)

roi - optional roi (default is null) used to mask data values

zoneTransform - (default is null) an AffineTransform used to convert dataImage pixel coords to zoneImage pixel coords

exclude - a List of Ranges defining dataImage values to exclude from the analysis (may be empty or null)

hints - an optional RenderingHints object

Returns:

a RenderedImage with a band for each requested statistic

arePropertiesSupported

public boolean arePropertiesSupported()

Returns true to indicate that properties are supported

Specified by:

arePropertiesSupported in interface javax.media.jai.RegistryElementDescriptor

Overrides:

arePropertiesSupported in class javax.media.jai.OperationDescriptorImpl

validateArguments

public boolean validateArguments(java.lang.String modeName,
                                 java.awt.image.renderable.ParameterBlock pb,
                                 java.lang.StringBuffer msg)

Checks parameters for the following:

• Number of sources is 1 or 2
• Data image bands are valid
• Zone image, if provided, is an integral data type
• Zone image, if provided, overlaps the data image, taking into account any AffineTransform

Specified by:

validateArguments in interface javax.media.jai.OperationDescriptor

Overrides:

validateArguments in class javax.media.jai.OperationDescriptorImpl