Package org.apache.sis.coverage
Class Category
java.lang.Object
org.apache.sis.coverage.Category
- All Implemented Interfaces:
Serializable
- Direct Known Subclasses:
ConvertedCategory
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 value0
stands for water, anotherCategory
instance specifying that sample value1
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.
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 × sMore 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:
-
Field Summary
FieldsModifier and TypeFieldDescription(package private) static final Comparator
<Category> ComparesCategory
objects according theirNumberRange.getMinDouble(boolean)
value.(package private) final Category
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
The category name.(package private) final NumberRange
<?> The [minimum … maximum] range of values in this category (nevernull
).private static final long
Serial number for inter-operability with different versions.(package private) final org.opengis.referencing.operation.MathTransform1D
The conversion from sample values to real values (or conversely), nevernull
even for qualitative categories. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
Category
(CharSequence name, NumberRange<?> samples, org.opengis.referencing.operation.MathTransform1D toUnits, javax.measure.Unit<?> units, DoubleToIntFunction toNaN) Constructs a qualitative or quantitative category.protected
Creates a copy of the given category.(package private)
Creates a copy of the given category except for theconverse
andtoConverse
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 TypeMethodDescription(package private) static int
compare
(double v1, double v2) Compares twodouble
values.(package private) Category
The category that describes values after transfer function has been applied.boolean
Compares the specified object with this category for equality.forConvertedValues
(boolean converted) Returns a category that describes measurement values or packed values, depending ifconverted
istrue
orfalse
respectively.Returns the range of values after conversions by the transfer function.org.opengis.util.InternationalString
getName()
Returns the category name.(package private) final Object
Returns an object to format for representing the range of values for display purpose only.NumberRange
<?> Returns the range of values occurring in this category.Optional
<org.opengis.referencing.operation.MathTransform1D> 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
Returnstrue
if this category is a qualitative category that has been converted to "real values".boolean
Returnstrue
if this category is quantitative.toString()
Returns a string representation of this category for debugging purpose.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
COMPARATOR
ComparesCategory
objects according theirNumberRange.getMinDouble(boolean)
value. -
name
final org.opengis.util.InternationalString nameThe category name.- See Also:
-
range
The [minimum … maximum] range of values in this category (nevernull
). Notes:- The minimum and maximum values may be one of the NaN values (see below).
- The value type may be different than
Double
(typicallyInteger
). - The bounds may be exclusive instead of inclusive.
- The range may be an instance of
MeasurementRange
if thetoConverse
is identity and the units of measurement are known.
NaN
if this category is a qualitative category converted to real values. Those categories are characterized by two apparently contradictory properties, and are implemented usingFloat.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:
-
toConverse
final org.opengis.referencing.operation.MathTransform1D toConverseThe conversion from sample values to real values (or conversely), nevernull
even for qualitative categories. In the case of qualitative categories, this transfer function shall map toNaN
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:
-
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 bethis
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:
-
-
Constructor Details
-
Category
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
Creates a copy of the given category except for theconverse
andtoConverse
fields. This constructor serves two purposes:- If
caller
is null, thentoConverse
is is set to identity. This is used only if a user specify aConvertedCategory
toSampleDimension
constructor. Such converted category can only come from anotherSampleDimension
and may have inconsistent information for the new sample dimension that the user is creating. - If
caller
is non-null, thentoConverse
is set to the same transform thancopy
andconverse
is set tocaller
. This is used only as a complement for the copy constructor.
- Parameters:
copy
- the category to copy.caller
- the converse, ornull
forthis
.
- If
-
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), ornull
for constructing a qualitative category. Mandatory ifunits
is non-null.units
- the units of measurement, ornull
if not applicable. This is the target units after conversion bytoUnits
.toNaN
- mapping from sample values to ordinal values to be supplied toMathFunctions.toNanFloat(int)
. That mapping is used only iftoUnits
isnull
andsamples
are not NaN values. That mapping is responsible to ensure that there is no ordinal value collision between different categories in the sameSampleDimension
. The input is a real number in thesamples
range and the output shall be a unique value between -2097152 and 2097151 inclusive.- Throws:
IllegalSampleDimensionException
- if thesamples
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. ThetoConverse
of this category will convert real value in specifiedunits
to the sample (packed) value. This constructor is reserved toConvertedCategory
usage only.- Parameters:
original
- the category storing the conversion from sample to real value.toSamples
- the "real to sample values" conversion, as the inverse oforiginal.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, orfalse
for qualitative.units
- the units of measurement, ornull
if not applicable. This is the source units before conversion bytoSamples
.- Throws:
org.opengis.referencing.operation.TransformException
-
-
Method Details
-
compare
static int compare(double v1, double v2) Compares twodouble
values. This method is similar toDouble.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), returnsthis
. This method differs fromconverse
field in being unidirectional: navigate from sample to converted values but never backward.- See Also:
-
isConvertedQualitative
final boolean isConvertedQualitative()Returnstrue
if this category is a qualitative category that has been converted to "real values". In such case, the real values areFloat.isNaN()
numbers. Iffalse
, then this category is either a quantitative category or a qualitative category that has not been converted to "real values". -
isQuantitative
public boolean isQuantitative()Returnstrue
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, orfalse
if this category is qualitative.
-
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 ofMeasurementRange
(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 singletonDouble.NaN
value. TheNaN
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:
-
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:
-
getRangeLabel
Returns an object to format for representing the range of values for display purpose only. It may be either theNumberRange
, a singleNumber
or aString
with a text like "NaN #0". -
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:
-
forConvertedValues
Returns a category that describes measurement values or packed values, depending ifconverted
istrue
orfalse
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, orfalse
for a category describing packed values (usually as integers).- Returns:
- a category describing converted or packed values, depending on
converted
argument value. May bethis
but nevernull
. - Since:
- 1.1
- See Also:
-
identity
static org.opengis.referencing.operation.MathTransform1D identity()Returns the identity transform. This is the value returned byConvertedCategory.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. -
equals
Compares the specified object with this category for equality. -
toString
Returns a string representation of this category for debugging purpose. This string representation may change in any future SIS version.
-