org.geotools.cv
Class Category

java.lang.Object
  org.geotools.cv.Category

All Implemented Interfaces:

java.io.Serializable

Deprecated. Replaced by Category in the org.geotools.coverage package.

public class Category

extends java.lang.Object

implements java.io.Serializable

A category delimited by a range of sample values. A categogy may be either qualitative or quantitative. For exemple, a classified image may have a qualitative category defining sample value 0 as water. An other qualitative category may defines sample value 1 as forest, etc. An other image may define elevation data as sample values in the range [0..100]. The later is a quantitative category, because sample values are related to some measurement in the real world. For example, elevation data may be related to an altitude in metres through the following linear relation: altitude = sample value×100. Some image mixes both qualitative and quantitative categories. For example, images of Sea Surface Temperature (SST) may have a quantitative category for temperature with values ranging from ?2 to 35?C, and three qualitative categories for cloud, land and ice.

All categories must have a human readable name. In addition, quantitative categories may define a transformation between sample values s and geophysics values x. This transformation is usually (but not always) a linear equation of the form:

x = offset + scale×s

More general equation are allowed. For example, SeaWiFS images use a logarithmic transform. General transformations are expressed with a MathTransform1D object. In the special case where the transformation is a linear one (as in the formula above), then a Category object may be understood as the interval between two breakpoints in the JAI's piecewise operation.

All Category objects are immutable and thread-safe.

Version:

$Id: Category.java 17672 2006-01-19 00:25:55Z desruisseaux $

Author:

Martin Desruisseaux

See Also:

SampleDimension, PiecewiseDescriptor, Serialized Form

Field Summary

static Category	FALSE Deprecated. A default category for the boolean "false" value.
static Category	NODATA Deprecated. A default category for "no data" values.
static Category	TRUE Deprecated. A default category for the boolean "true" value.

Constructor Summary

Category(java.lang.String name, java.awt.Color[] colors, int lower, int upper, double scale, double offset)
Deprecated. Construct a quantitative category for sample values ranging from lower inclusive to upper exclusive.

Category(java.lang.String name, java.awt.Color[] colors, NumberRange sampleValueRange, double scale, double offset)
Deprecated. Construct a quantitative category for sample values in the specified range.

Category(java.lang.String name, java.awt.Color[] colors, NumberRange sampleValueRange, MathTransform1D sampleToGeophysics)
Deprecated. Construct a qualitative or quantitative category for samples in the specified range.

Category(java.lang.String name, java.awt.Color[] colors, NumberRange sampleValueRange, NumberRange geophysicsValueRange)
Deprecated. Construct a quantitative category mapping samples to geophysics values in the specified range.

Category(java.lang.String name, java.awt.Color color, double sample)
Deprecated. Construct a qualitative category for sample value sample.

Category(java.lang.String name, java.awt.Color color, int sample)
Deprecated. Construct a qualitative category for sample value sample.

Category(java.lang.String name, java.awt.Color color, NumberRange sampleValueRange)
Deprecated. Construct a quantitative category for samples in the specified range.

Method Summary

boolean	equals(java.lang.Object object) Deprecated. Compares the specified object with this category for equality.
Category	geophysics(boolean geo) Deprecated. If true, returns the geophysics companion of this category.
java.awt.Color[]	getColors() Deprecated. Returns the set of colors for this category.
java.lang.String	getName(java.util.Locale locale) Deprecated. Returns the category name localized in the specified locale.
NumberRange	getRange() Deprecated. Returns the range of sample values occurring in this category.
MathTransform1D	getSampleToGeophysics() Deprecated. Returns a transform from sample values to geophysics values.
int	hashCode() Deprecated. Returns a hash value for this category.
boolean	isQuantitative() Deprecated. Returns true if this category is quantitative.
Category	recolor(java.awt.Color[] colors) Deprecated. Returns a category for the same range of sample values but a different color palette.
Category	rescale(MathTransform1D sampleToGeophysics) Deprecated. Changes the mapping from sample to geophysics values.
java.lang.String	toString() Deprecated. Returns a string representation of this category.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NODATA

public static final Category NODATA

Deprecated.

A default category for "no data" values. This default qualitative category use sample value 0, which is mapped to geophysics value Float.NaN for those who work with floating point images. The rendering color default to a fully transparent color and the name is "no data" localized to the requested locale.

FALSE

public static final Category FALSE

Deprecated.

A default category for the boolean "false" value. This default identity category uses sample value 0, the color black and the name "false" localized to the specified locale.

TRUE

public static final Category TRUE

Deprecated.

A default category for the boolean "true" value. This default identity category uses sample value 1, the color white and the name "true" localized to the specified locale.

Constructor Detail

Category

public Category(java.lang.String name,
                java.awt.Color color,
                int sample)

Deprecated.

Construct a qualitative category for sample value sample.

Parameters:

name - The category name.

color - The category color, or null for a default color.

sample - The sample value as an integer, usually in the range 0 to 255.

Category

public Category(java.lang.String name,
                java.awt.Color color,
                double sample)

Deprecated.

Construct a qualitative category for sample value sample.

Parameters:

name - The category name.

color - The category color, or null for a default color.

sample - The sample value as a double. May be one of NaN values.

Category

public Category(java.lang.String name,
                java.awt.Color color,
                NumberRange sampleValueRange)
         throws java.lang.IllegalArgumentException

Deprecated.

Construct a quantitative category for samples in the specified range.

Parameters:

name - The category name.

color - The category color, or null for a default color.

sampleValueRange - The range of sample values for this category. Element class is usually Integer, but Float and Double are accepted as well.

Category

public Category(java.lang.String name,
                java.awt.Color[] colors,
                int lower,
                int upper,
                double scale,
                double offset)
         throws java.lang.IllegalArgumentException

Deprecated.

Construct a quantitative category for sample values ranging from lower inclusive to upper exclusive. Sample values are converted into geophysics values using the following linear equation: x = offset + scale×s

Parameters:

name - The category name.

colors - A set of colors for this category. This array may have any length; colors will be interpolated as needed. An array of length 1 means that an uniform color should be used for all sample values. An array of length 0 or a null array means that some default colors should be used (usually a gradient from opaque black to opaque white).

lower - The lower sample value, inclusive.

upper - The upper sample value, exclusive.

scale - The scale value which is multiplied to sample values for this category.

offset - The offset value to add to sample values for this category.

Throws:

java.lang.IllegalArgumentException - if lower is not smaller than upper.

java.lang.IllegalArgumentException - if scale or offset are not real numbers.

Category

public Category(java.lang.String name,
                java.awt.Color[] colors,
                NumberRange sampleValueRange,
                double scale,
                double offset)
         throws java.lang.IllegalArgumentException

Deprecated.

Construct a quantitative category for sample values in the specified range. Sample values are converted into geophysics values using the following linear equation: x = offset + scale×s

Parameters:

name - The category name.

colors - A set of colors for this category. This array may have any length; colors will be interpolated as needed. An array of length 1 means that an uniform color should be used for all sample values. An array of length 0 or a null array means that some default colors should be used (usually a gradient from opaque black to opaque white).

sampleValueRange - The range of sample values for this category. Element class is usually Integer, but Float and Double are accepted as well.

scale - The scale value which is multiplied to sample values for this category.

offset - The offset value to add to sample values for this category.

Throws:

java.lang.IllegalArgumentException - if lower is not smaller than upper.

java.lang.IllegalArgumentException - if scale or offset are not real numbers.

Category

public Category(java.lang.String name,
                java.awt.Color[] colors,
                NumberRange sampleValueRange,
                NumberRange geophysicsValueRange)
         throws java.lang.IllegalArgumentException

Deprecated.

Construct a quantitative category mapping samples to geophysics values in the specified range. Sample values in the sampleValueRange will be mapped to geophysics values in the geophysicsValueRange through a linear equation of the form: x = offset + scale×s scale and offset coefficients are computed from the ranges supplied in arguments.

Parameters:

name - The category name.

colors - A set of colors for this category. This array may have any length; colors will be interpolated as needed. An array of length 1 means that an uniform color should be used for all sample values. An array of length 0 or a null array means that some default colors should be used (usually a gradient from opaque black to opaque white).

sampleValueRange - The range of sample values for this category. Element class is usually Integer, but Float and Double are accepted as well.

geophysicsValueRange - The range of geophysics values for this category. Element class is usually Float or Double.

Throws:

java.lang.ClassCastException - if the range element class is not a Number subclass.

java.lang.IllegalArgumentException - if the range is invalid.

Category

public Category(java.lang.String name,
                java.awt.Color[] colors,
                NumberRange sampleValueRange,
                MathTransform1D sampleToGeophysics)
         throws java.lang.IllegalArgumentException

Deprecated.

Construct a qualitative or quantitative category for samples in the specified range. Sample values (usually integers) will be converted into geophysics values (usually floating-point) through the sampleToGeophysics transform.

Parameters:

name - The category name.

colors - A set of colors for this category. This array may have any length; colors will be interpolated as needed. An array of length 1 means that an uniform color should be used for all sample values. An array of length 0 or a null array means that some default colors should be used (usually a gradient from opaque black to opaque white).

sampleValueRange - The range of sample values for this category. Element class is usually Integer, but Float and Double are accepted as well.

sampleToGeophysics - A transform from sample values to geophysics values, or null if this category is not a quantitative one.

Throws:

java.lang.ClassCastException - if the range element class is not a Number subclass.

java.lang.IllegalArgumentException - if the range is invalid.

Method Detail

getName

public java.lang.String getName(java.util.Locale locale)

Deprecated.

Returns the category name localized in the specified locale. If no name is available for the specified locale, then an arbitrary locale may be used. The default implementation returns the name argument specified at construction time.

Parameters:

locale - The desired locale, or null for the default locale.

Returns:

The category name, localized if possible.

getColors

public java.awt.Color[] getColors()

Deprecated.

Returns the set of colors for this category. Change to the returned array will not affect this category.

See Also:

SampleDimension.getColorModel()

getRange

public NumberRange getRange()

Deprecated.

Returns the range of sample values occurring in this category. Sample values can be transformed into geophysics values using the getSampleToGeophysics() transform.

Returns:

The range of sample values.

See Also:

NumberRange.getMinimum(boolean), NumberRange.getMaximum(boolean), SampleDimension.getMinimumValue(), SampleDimension.getMaximumValue()

getSampleToGeophysics

public MathTransform1D getSampleToGeophysics()

Deprecated.

Returns a transform from sample values to geophysics values. If this category is not a quantitative one, then this method returns null.

isQuantitative

public boolean isQuantitative()

Deprecated.

Returns true if this category is quantitative. A quantitative category has a non-null sampleToGeophysics transform.

Returns:

true if this category is quantitative, or false if this category is qualitative.

recolor

public Category recolor(java.awt.Color[] colors)

Deprecated.

Returns a category for the same range of sample values but a different color palette.

Parameters:

colors - A set of colors for the new category. This array may have any length; colors will be interpolated as needed. An array of length 1 means that an uniform color should be used for all sample values. An array of length 0 or a null array means that some default colors should be used (usually a gradient from opaque black to opaque white).

Returns:

A category with the new color palette, or this if the new colors are identical to the current ones.

rescale

public Category rescale(MathTransform1D sampleToGeophysics)

Deprecated.

Changes the mapping from sample to geophysics values. This method returns a category with a "sample to geophysics" transformation set to the specified one. Other properties like the sample value range and the colors are unchanged.

Note about geophysics categories: The above rules are straightforward when applied on non-geophysics category, but this method can be invoked on geophysics category (as returned by geophysics(true)) as well. Since geophysics categories are already the result of some "sample to geophysics" transformation, invoking this method on those is equivalent to concatenate this "sample to geophysics" transform with the specified one.

Parameters:

sampleToGeophysics - The new sample to geophysics transform.

Returns:

A category using the specified transform.

See Also:

getSampleToGeophysics(), SampleDimension.rescale(double, double)

geophysics

public Category geophysics(boolean geo)

Deprecated.

If true, returns the geophysics companion of this category. By definition, a geophysics category is a category with a range of sample values transformed in such a way that the sampleToGeophysics transform is always the identity transform, or null if no such transform existed in the first place. In other words, the range of sample values in a geophysics category maps directly the "real world" values without the need for any transformation.

Category objects live by pair: a geophysics one (used for computation) and a non-geophysics one (used for packing data, usually as integers). The geo argument specifies which object from the pair is wanted, regardless if this method is invoked on the geophysics or non-geophysics instance of the pair. In other words, the result of geophysics(b1).geophysics(b2).geophysics(b3) depends only on the value in the last call (b3).

Newly constructed categories are non-geophysics (i.e. a sample to geophysics transform must be applied in order to gets geophysics values).

Parameters:

geo - true to get a category with an identity transform and a range of sample values matching the geophysics values, or false to get back the original category (the one constructed with new Category(...)).

Returns:

The category. Never null, but may be this.

See Also:

SampleDimension.geophysics(boolean), GridCoverage.geophysics(boolean)

hashCode

public int hashCode()

Deprecated.

Returns a hash value for this category. This value need not remain consistent between different implementations of the same class.

equals

public boolean equals(java.lang.Object object)

Deprecated.

Compares the specified object with this category for equality.

toString

public java.lang.String toString()

Deprecated.

Returns a string representation of this category. The returned string is implementation dependent. It is usually provided for debugging purposes.