Package org.apache.sis.coverage

Class Category

java.lang.Object

org.apache.sis.coverage.Category

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

ConvertedCategory

public class Category
extends Object
implements Serializable

Describes a sub-range of sample values in a sample dimension. A category maps a range of values to an observation, which may be either qualitative or quantitative:

• Examples of qualitative observations: a sample dimension may have one Category instance specifying that sample value 0 stands for water, another Category instance specifying that sample value 1 stands for forest, etc.
• Example of quantitative observation: another sample dimension may have a Category instance specifying that sample values in the range [0…100] stands for elevation data. Those sample values are related to measurements in the real world (altitudes in metres) through a transfer function, foe example altitude = (sample value)×100 - 25.

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. There is usually at most one quantitative category per sample dimension, but Apache SIS accepts an arbitrary number of them.

All categories must have a human readable name. In addition, quantitative categories may define a conversion from sample values s to real values x. This conversion 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 conversions are expressed with a MathTransform1D object.

All Category objects are immutable and thread-safe.

Since:

1.0

Version:

1.1

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
(package private) static final Comparator<Category>	COMPARATOR	Compares Category objects according their NumberRange.getMinDouble(boolean) value.
(package private) final Category	converse	The category that describes values after transfer function has been applied, or if this category is already converted then the original category.
(package private) final org.opengis.util.InternationalString	name	The category name.
(package private) final NumberRange<?>	range	The [minimum … maximum] range of values in this category (never null).
private static final long	serialVersionUID	Serial number for inter-operability with different versions.
(package private) final org.opengis.referencing.operation.MathTransform1D	toConverse	The conversion from sample values to real values (or conversely), never null even for qualitative categories.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Category(CharSequence name, NumberRange<?> samples, org.opengis.referencing.operation.MathTransform1D toUnits, javax.measure.Unit<?> units, DoubleToIntFunction toNaN)	Constructs a qualitative or quantitative category.
protected	Category(Category copy)	Creates a copy of the given category.
(package private)	Category(Category copy, Category caller)	Creates a copy of the given category except for the converse and toConverse fields.
(package private)	Category(Category original, org.opengis.referencing.operation.MathTransform1D toSamples, boolean isQuantitative, javax.measure.Unit<?> units)	Creates a category storing the inverse of the "sample to real values" transfer function.

Method Summary

Modifier and Type	Method	Description
(package private) static int	compare(double v1, double v2)	Compares two double values.
(package private) Category	converted()	The category that describes values after transfer function has been applied.
boolean	equals(Object object)	Compares the specified object with this category for equality.
Category	forConvertedValues(boolean converted)	Returns a category that describes measurement values or packed values, depending if converted is true or false respectively.
Optional<MeasurementRange<?>>	getMeasurementRange()	Returns the range of values after conversions by the transfer function.
org.opengis.util.InternationalString	getName()	Returns the category name.
(package private) final Object	getRangeLabel()	Returns an object to format for representing the range of values for display purpose only.
NumberRange<?>	getSampleRange()	Returns the range of values occurring in this category.
Optional<org.opengis.referencing.operation.MathTransform1D>	getTransferFunction()	Returns the transfer function from sample values to real values in units of measurement.
int	hashCode()	Returns a hash value for this category.
(package private) static org.opengis.referencing.operation.MathTransform1D	identity()	Returns the identity transform.
(package private) final boolean	isConvertedQualitative()	Returns true if this category is a qualitative category that has been converted to "real values".
boolean	isQuantitative()	Returns true if this category is quantitative.
String	toString()	Returns a string representation of this category for debugging purpose.

Methods inherited from class java.lang.Object

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

Field Details

serialVersionUID

private static final long serialVersionUID

Serial number for inter-operability with different versions.

See Also:

• Constant Field Values

COMPARATOR

static final Comparator<Category> COMPARATOR

Compares Category objects according their NumberRange.getMinDouble(boolean) value.

name

final org.opengis.util.InternationalString name

The category name.

See Also:

• getName()

range

final NumberRange<?> range

The [minimum … maximum] range of values in this category (never null). Notes:

• The minimum and maximum values may be one of the NaN values (see below).
• The value type may be different than Double (typically Integer).
• The bounds may be exclusive instead of inclusive.
• The range may be an instance of MeasurementRange if the toConverse is identity and the units of measurement are known.

The range may be NaN if this category is a qualitative category converted to real values. Those categories are characterized by two apparently contradictory properties, and are implemented using Float.NaN values:

• This category is member of a SampleDimension having an identity transfer function.
• The transfer function of this category is absent (because this category is qualitative).

See Also:

• getSampleRange()

toConverse

final org.opengis.referencing.operation.MathTransform1D toConverse

The conversion from sample values to real values (or conversely), never null even for qualitative categories. In the case of qualitative categories, this transfer function shall map to NaN values or conversely. In the case of sample values that are already in the units of measurement, this transfer function shall be the identity function.

See Also:

• getTransferFunction()

converse

final Category converse

The category that describes values after transfer function has been applied, or if this category is already converted then the original category. Never null, but may be this if the transfer function is the identity function.

This field establishes a bidirectional navigation between sample values and real values. This is in contrast with methods named converted(), which establish a unidirectional navigation from sample values to real values.

See Also:

• converted()
• CategoryList.converse
• SampleDimension.converse

Constructor Details

Category

protected Category(Category copy)

Creates a copy of the given category. This constructor is provided for subclasses wanting to extent an existing category with custom information.

Parameters:

copy - the category to copy.

Category

Category(Category copy,
 Category caller)

Creates a copy of the given category except for the converse and toConverse fields. This constructor serves two purposes:

• If caller is null, then toConverse is is set to identity. This is used only if a user specify a ConvertedCategory to SampleDimension constructor. Such converted category can only come from another SampleDimension and may have inconsistent information for the new sample dimension that the user is creating.
• If caller is non-null, then toConverse is set to the same transform than copy and converse is set to caller. This is used only as a complement for the copy constructor.

Parameters:

copy - the category to copy.

caller - the converse, or null for this.

Category

protected Category(CharSequence name,
 NumberRange<?> samples,
 org.opengis.referencing.operation.MathTransform1D toUnits,
 javax.measure.Unit<?> units,
 DoubleToIntFunction toNaN)

Constructs a qualitative or quantitative category. This constructor is accessible for sub-classing. For other usages, SampleDimension.Builder should be used instead.

Parameters:

name - the category name (mandatory).

samples - the minimum and maximum sample values (mandatory).

toUnits - the conversion from sample values to real values (possibly identity), or null for constructing a qualitative category. Mandatory if units is non-null.

units - the units of measurement, or null if not applicable. This is the target units after conversion by toUnits.

toNaN - mapping from sample values to ordinal values to be supplied to MathFunctions.toNanFloat(int). That mapping is used only if toUnits is null and samples are not NaN values. That mapping is responsible to ensure that there is no ordinal value collision between different categories in the same SampleDimension. The input is a real number in the samples range and the output shall be a unique value between -2097152 and 2097151 inclusive.

Throws:

IllegalSampleDimensionException - if the samples range of values is empty or the transfer function cannot be used.

Category

Category(Category original,
 org.opengis.referencing.operation.MathTransform1D toSamples,
 boolean isQuantitative,
 javax.measure.Unit<?> units)
  throws org.opengis.referencing.operation.TransformException

Creates a category storing the inverse of the "sample to real values" transfer function. The toConverse of this category will convert real value in specified units to the sample (packed) value. This constructor is reserved to ConvertedCategory usage only.

Parameters:

original - the category storing the conversion from sample to real value.

toSamples - the "real to sample values" conversion, as the inverse of original.toConverse. For qualitative category, this function is a constant mapping NaN to the original sample value.

isQuantitative - true if we are construction a quantitative category, or false for qualitative.

units - the units of measurement, or null if not applicable. This is the source units before conversion by toSamples.

Throws:

org.opengis.referencing.operation.TransformException

Method Details

compare

static int compare(double v1,
 double v2)

Compares two double values. This method is similar to Double.compare(double,double) except that it also orders NaN values from raw bit patterns. Reminder: NaN values are sorted last.

getName

public org.opengis.util.InternationalString getName()

Returns the category name.

Returns:

the category name.

converted

Category converted()

The category that describes values after transfer function has been applied. If the values are already converted (eventually to NaN values), returns this. This method differs from converse field in being unidirectional: navigate from sample to converted values but never backward.

See Also:

• forConvertedValues(boolean)

isConvertedQualitative

final boolean isConvertedQualitative()

Returns true if this category is a qualitative category that has been converted to "real values". In such case, the real values are Float.isNaN() numbers. If false, then this category is either a quantitative category or a qualitative category that has not been converted to "real values".

isQuantitative

public boolean isQuantitative()

Returns true if this category is quantitative. A quantitative category has a transfer function mapping sample values to values in some units of measurement. By contrast, a qualitative category maps sample values to a label, for example “2 = forest”. That later mapping cannot be represented by a transfer function.

Returns:

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

getSampleRange

public NumberRange<?> getSampleRange()

Returns the range of values occurring in this category. The range delimits sample values that can be converted into real values using the transfer function. If that function is identity, then the sample values are already real values and the range may be an instance of MeasurementRange (i.e. a number range with units of measurement).

This method never returns null, but may return an unbounded range or a range containing a singleton Double.NaN value. The NaN values happen if this range is derived from a "no data" value converted to "real value" by the transfer function.

Returns:

the range of sample values in this category.

See Also:

• SampleDimension.getSampleRange()

getMeasurementRange

public Optional<MeasurementRange<?>> getMeasurementRange()

Returns the range of values after conversions by the transfer function. This range is absent if there is no transfer function, i.e. if this category is qualitative.

Returns:

the range of values after conversion by the transfer function.

See Also:

• SampleDimension.getMeasurementRange()

getRangeLabel

final Object getRangeLabel()

Returns an object to format for representing the range of values for display purpose only. It may be either the NumberRange, a single Number or a String with a text like "NaN #0".

getTransferFunction

public Optional<org.opengis.referencing.operation.MathTransform1D> getTransferFunction()

Returns the transfer function from sample values to real values in units of measurement. The function is absent if this category is not a quantitative category.

Returns:

the transfer function from sample values to real values.

See Also:

• SampleDimension.getTransferFunction()

forConvertedValues

public Category forConvertedValues(boolean converted)

Returns a category that describes measurement values or packed values, depending if converted is true or false respectively. Notes:

• The converted values of a qualitative category is a NaN value.
• The converted values of a quantitative category are real values. Those values are computed by the transfer function. That function may be identity, in which case this method returns this.

Parameters:

converted - true for a category describing values in units of measurement, or false for a category describing packed values (usually as integers).

Returns:

a category describing converted or packed values, depending on converted argument value. May be this but never null.

Since:

1.1

See Also:

• getMeasurementRange()
• SampleDimension.forConvertedValues(boolean)

identity

static org.opengis.referencing.operation.MathTransform1D identity()

Returns the identity transform. This is the value returned by ConvertedCategory.getTransferFunction().

hashCode

public int hashCode()

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

Overrides:

hashCode in class Object

equals

public boolean equals(Object object)

Compares the specified object with this category for equality.

Overrides:

equals in class Object

Parameters:

object - the object to compare with.

Returns:

true if the given object is equal to this category.

toString

public String toString()

Returns a string representation of this category for debugging purpose. This string representation may change in any future SIS version.

Overrides:

toString in class Object

Returns:

a string representation of this category for debugging purpose.