org.jaitools.media.jai.classifiedstats
Class ClassifiedStatsDescriptor

java.lang.Object
  javax.media.jai.OperationDescriptorImpl
      org.jaitools.media.jai.classifiedstats.ClassifiedStatsDescriptor

All Implemented Interfaces:

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

public class ClassifiedStatsDescriptor
extends javax.media.jai.OperationDescriptorImpl

Calculates a number of classified summary statistics, for the whole data image. Optionally, an ROI can be provided to constrain which areas of the data image will be sampled for calculation of statistics.

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 CLASSIFIED_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.

Note that the source name for this operator are "dataImage"

The range of data image values that contribute to the analysis can be constrained in two ways: with the "ranges" parameter and the "noDataRanges" parameter. Each of these parameters take a Collection of Range objects.

The "ranges" parameter allows you to define values to include or exclude from the calculations, the choice being specified by the associated "rangesType" parameter. If "rangesType" is Range.Type#INCLUDE you can also request that statistics be calculated separately for each range of values by setting the "rangeLocalStats" parameter to Boolean.TRUE.

The "noDataRanges" parameter allows you to define values to treat as NODATA. As well as being excluded from calculations of statistics, the frequency of NODATA values is tracked by the operator and can be retrieved from the results.

The "classifiers" parameter allows you to define the classifiers used on stats computation. As an instance, suppose you have classifiers like [age, job]. Where age has byte values like [18,19,20,...,80] job has byte values like [0,1,2,3,4,5,6,...,20] // 0: employer, 1: consultant, ..., 20: professional dancer Statistic computations made on pixels which belong to the same age value and job value will be grouped together. So you will potentially have in output statistics for the group of pixels related to the set of pixels classifier belonging: age = 18 & job = 0 age = 18 & job = 1 age = 18 & job = 2 .... age = 19 & job = 0 age = 19 & job = 1 age = 19 & job = 2 ... A MultiKey object will be used to represent these tuples of key. Only the tuples found during the computation will be reported as output results. As an instance, in case there isn't any pixel belonging to age = 70 & job = 20 (professional dancer), the output won't contain a <80,20> tuple.

The optional "noDataClassifiers" parameter allows you to define a specific value to treat as NODATA for each classifier image. When specifying the noDataClassifierRanges array entries, make sure to use the same order you have used to specify the "classifiers" parameter. The first no data in the array will be used for the first classifier, the second no data in the array will be used for the second classifier, and so on... use Double.NaN in case you won't (or you don't know) specify a noData for a specific entry. Note that although classifier are always of integer types, we use double to allow specifying NaN as "unknown/unspecified" element.

Optionally, you can also specify "pivotClassifiers" (when more then one is needed). Pivots are classifiers which should be used to form different groups containing the same common classifiers and only a distinct (pivot) classifier. As an instance, suppose you have classifiers like [age, job, sex] and classifiers like [country, district, town]. Then you would like to do 3 classified stats like this:
- country, age, job, sex
- district, age, job, sex
- town, age, job, sex
You can specify a "pivotClassifiers" parameter with [country, district, town] and the standard "classifiers" parameter with [age, job, sex]. Optionally you can also specify noData for pivot classifiers (make sure to respect the proper order: first NoData of the array refers to the first pivot classifier, second NoData of the array refers to the second pivot classifier,...)

The "noDataPivotClassifiers" parameter allows you to define a specific value to treat as NODATA for each pivot classifier image. The same remarks made on "noDataClassifiers" apply to this paramter.

Example of use...

 RenderedImage myData = ...
 RenderedImage myClassifierImage0 = ...
 RenderedImage myClassifierImage1 = ...
 RenderedImage myClassifierImage2 = ...
 RenderedImage pivotClassifierImage0 = ...
 RenderedImage pivotClassifierImage1 = ...
 

 ParameterBlockJAI pb = new ParameterBlockJAI("ClassifiedStats");
 pb.setSource("dataImage", myData);

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

 pb.setParameter("stats", stats);
 pb.setParameter("classifiers", new RenderedImage[]{myClassifierImage0, myClassifierImage1, myClassifierImage2});
 pb.setParameter("pivotClassifiers", new RenderedImage[]{pivotClassifierImage0, pivotClassifierImage1});
 pb.setParameter("noDataClassifiers", new Double[] {0d, -1d, -9999d});
   pb.setParameter("noDataPivotClassifiers", new Double[] {-32768d, Double.NaN});
 RenderedOp op = JAI.create("ClassifiedStats", pb);

 ClassifiedStats stats = (ClassifiedStats) op.getProperty(ClassifiedStatsDescriptor.CLASSIFIED_STATS_PROPERTY);

 // print results to console
 Map> results = stats.results().get(0);
 Set multik = results.keySet();
 Iterator it = multik.iterator();
 while (it.hasNext()) {
      MultiKey key = it.next(); 
      List rs = results.get(key);
      for (Result r: rs){
              System.out.println(r.toString());
      }
 }
 

The ClassifiedStats object returned by the getProperty method above allows you to examine results by image band, classifier key, pivot, statistic, range. As output, you will get the List of results where the i-th element is related to the classified stats computed on top of the i-th pivot element

 List>> results = stats.results();
 Map> pivot0Results = results.get(0);
 Map> pivot1Results = results.get(1);
 Map> pivot2Results = results.get(2);
 

Parameters

Name	Type	Description	Default value
classifiers	RenderedImage[]	classifier images to be used in computations	NO DEFAULT although this parameter is mandatory
pivotClassifiers	RenderedImage[]	optional pivot classifier images to be used in computations. Elements of this array are used to form group with the standard classifiers. As an instance, suppose the classifiers are [classifier1, classifier2] and the pivot classifiers are [pivot1, pivot2], then the stats will be computed on classifiers [pivot1, classifier1, classifier2] and [pivot2, classifier1, classifier2].	null
stats	Statistic[]	Statistics to calculate	NO DEFAULT
bands	Integer[]	Image bands to sample	{0}
roi	ROI	An optional ROI to constrain sampling	null
ranges	Collection<Range>	Ranges of values to include or exclude	null (include all data values)
rangesType	Range.Type	How to treat values supplied via the "ranges" parameter	Range.Type.INCLUDE
rangeLocalStats	Boolean	If Ranges are supplied via the "ranges" parameter, whether to calculate statistics for each of them separately	Boolean.FALSE
noDataRanges	Collection<Range>	Ranges of values to treat specifically as NODATA	null (no NODATA values defined)
noDataClassifiers	Double[]	NoData specific for image classifiers. The order of the noData elements of the array shall respect the order of the elements within the image classifiers array. NoData are specified as Double although they refer to classifiers images which are of integer types. Using a Double allows to specifiy NaN in case some specific noData entries aren't unavailable for some classifier images. As an instance [-9999, Double.NaN, -32768, 0, Double.NaN] in case there isn't any noData for classifierImage 1 and 4 (starting from index 0).	null (no NODATA values defined)
noDataPivotClassifiers	Double[]	NoData specific for pivot image classifiers. The order of the noData elements of the array shall respect the order of the elements within the pivot image classifiers array. NoData are specified as Double although they refer to pivot classifiers images which are of integer types. Using a Double allows to specifiy NaN in case some specific noData entries aren't unavailable for some pivot classifier images. As an instance [-9999, Double.NaN, -32768, 0, Double.NaN] in case there isn't any noData for pivotClassifierImage 1 and 4 (starting from index 0).	null (no NODATA values defined)

Since:

1.2

Author:

Daniele Romagnoli, GeoSolutions S.A.S.

See Also:

Result, Statistic, StreamingSampleStats, ClassifiedStats, Serialized Form

Field Summary

static String

CLASSIFIED_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

ClassifiedStatsDescriptor()
Constructor.

Method Summary

boolean

validateArguments(String modeName, ParameterBlock pb, StringBuffer msg) Validates supplied parameters.

Methods inherited from class javax.media.jai.OperationDescriptorImpl

arePropertiesSupported, 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

CLASSIFIED_STATS_PROPERTY

public static final String CLASSIFIED_STATS_PROPERTY

Property name used to retrieve the results

See Also:

Constant Field Values

Constructor Detail

ClassifiedStatsDescriptor

public ClassifiedStatsDescriptor()

Constructor.

Method Detail

validateArguments

public boolean validateArguments(String modeName,
                                 ParameterBlock pb,
                                 StringBuffer msg)

Validates supplied parameters.

Specified by:

validateArguments in interface javax.media.jai.OperationDescriptor

Overrides:

validateArguments in class javax.media.jai.OperationDescriptorImpl

Parameters:

modeName - the rendering mode

pb - the parameter block

msg - a StringBuffer to receive error messages

Returns:

true if parameters are valid; false otherwise