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 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 amount 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
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

  Modifier and Type
  Method
  Description
  `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.
  `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()`
  Returns `true` if this category is quantitative.
  `String`
  `toString()`
  Returns a string representation of this category for debugging purpose.

  ### Methods inherited from class Object

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

- ## 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

    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), 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 can not be used.

- ## Method Details

  - ### getName

    public InternationalString getName()
    Returns the category name.
    Returns:
      the category name.

  - ### 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 can not 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()`

  - ### 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()`

  - ### 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)`

  - ### 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 equals 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.