Package org.apache.sis.coverage
Class Category
- Object
-
- Category
-
- All Implemented Interfaces:
Serializable
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 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 × s
More general equation are allowed. For example, SeaWiFS images use a logarithmic transform. General conversions are expressed with aMathTransform1D
object.All
Category
objects are immutable and thread-safe.- Since:
- 1.0
- See Also:
- Serialized Form
Defined in the
sis-feature
module
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
Category(CharSequence name, NumberRange<?> samples, MathTransform1D toUnits, Unit<?> units, DoubleToIntFunction toNaN)
Constructs a qualitative or quantitative category.protected
Category(Category copy)
Creates a copy of the given category.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
equals(Object object)
Compares the specified object with this category for equality.Optional<MeasurementRange<?>>
getMeasurementRange()
Returns the range of values after conversions by the transfer function.InternationalString
getName()
Returns the category name.NumberRange<?>
getSampleRange()
Returns the range of values occurring in this category.Optional<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.boolean
isQuantitative()
Returnstrue
if this category is quantitative.String
toString()
Returns a string representation of this category for debugging purpose.
-
-
-
Constructor Detail
-
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
protected Category(CharSequence name, NumberRange<?> samples, MathTransform1D toUnits, 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.
-
-
Method Detail
-
getName
public InternationalString getName()
Returns the category name.- Returns:
- the category name.
-
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 can not be represented by a transfer function.- Returns:
true
if this category is quantitative, orfalse
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 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:
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()
-
getTransferFunction
public Optional<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()
-
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
public boolean equals(Object object)
Compares the specified object with this category for equality.
-
-