Package org.apache.sis.coverage

## Class SampleDimension

- Object
- - SampleDimension

- All Implemented Interfaces:
    `Serializable`

      public class SampleDimension
      extends Object
      implements Serializable

  Describes the data values in a coverage (the range). For a raster, a sample dimension is a band. A sample dimension can reserve some values for qualitative information like “this is a forest” and some other values for quantitative information like a temperature measurements.
  Example: an image of sea surface temperature (SST) could define the following categories:

  Example of categories in a sample dimension
  Values range | Meaning
  --- | ---
  [0] | No data
  [1] | Cloud
  [2] | Land
  [10…210] | Temperature to be converted into Celsius degrees through a linear equation

  In this example, sample values in range [10…210] define a quantitative category, while all others categories are qualitative.
  Relationship with metadata
  This class provides the same information than ISO 19115 `org​.opengis​.metadata​.content​.SampleDimension`, but organized in a different way. The use of the same name may seem a risk, but those two types are typically not used in same time.
  Since:
    1.0
  See Also:
    Serialized Form

  Defined in the `sis-feature` module

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `SampleDimension.Builder` | A mutable builder for creating an immutable `SampleDimension`.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SampleDimension​(GenericName name, Number background, Collection<? extends Category> categories)` | Creates a sample dimension with the specified name and categories.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `equals​(Object object)` | Compares the specified object with this sample dimension for equality.
    `SampleDimension` | `forConvertedValues​(boolean converted)` | Returns a sample dimension that describes real values or sample values, depending if `converted` is `true` or `false` respectively.
    `Optional<Number>` | `getBackground()` | Returns the background value.
    `List<Category>` | `getCategories()` | Returns all categories in this sample dimension.
    `Optional<MeasurementRange<?>>` | `getMeasurementRange()` | Returns the range of values after conversions by the transfer function.
    `GenericName` | `getName()` | Returns an identification for this sample dimension.
    `Set<Number>` | `getNoDataValues()` | Returns the values to indicate "no data" for this sample dimension.
    `Optional<NumberRange<?>>` | `getSampleRange()` | Returns the range of values occurring in this sample dimension.
    `Optional<MathTransform1D>` | `getTransferFunction()` | Returns the transfer function from sample values to real values.
    `Optional<TransferFunction>` | `getTransferFunctionFormula()` | Returns the scale factor and offset of the transfer function.
    `Optional<Unit<?>>` | `getUnits()` | Returns the units of measurement for this sample dimension.
    `int` | `hashCode()` | Returns a hash value for this sample dimension.
    `String` | `toString()` | Returns a string representation of this sample dimension.
    `static String` | `toString​(Locale locale, SampleDimension... dimensions)` | Returns a string representation of the given sample dimensions.

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### SampleDimension

          public SampleDimension​(GenericName name,
                                 Number background,
                                 Collection<? extends Category> categories)

      Creates a sample dimension with the specified name and categories. The sample dimension name is used as a way to perform a band select by using human comprehensible descriptions instead of numbers. The background value is used for filling empty space in map reprojections. The background value (if specified) should be the value of a qualitative category present in the `categories` collection, but this is not mandatory.

      Note that `SampleDimension​.Builder` provides a more convenient way to create sample dimensions.

      Parameters:
        `name` - an identification for the sample dimension.
        `background` - the background value, or `null` if none.
        `categories` - the list of categories. May be empty if none.

  - ### Method Detail

    - #### getName

          public GenericName getName()

      Returns an identification for this sample dimension. This is typically used as a way to perform a band select by using human comprehensible descriptions instead of just numbers. Web Coverage Service (WCS) can use this name in order to perform band sub-setting as directed from a user request.
      Returns:
        an identification of this sample dimension.
      See Also:
        `RangeDimension​.getSequenceIdentifier()`

    - #### getCategories

          public List<Category> getCategories()

      Returns all categories in this sample dimension. Note that a `Category` object may apply to an arbitrary range of sample values. Consequently, the first element in this collection may not be directly related to the sample value `0`.
      Returns:
        the list of categories in this sample dimension, or an empty list if none.

    - #### getBackground

          public Optional<Number> getBackground()

      Returns the background value. If this sample dimensions has quantitative categories, then the background value should be one of the value returned by `getNoDataValues()`. However this is not mandatory.
      Returns:
        the background value, typically (but not necessarily) one of `getNoDataValues()`.

    - #### getNoDataValues

          public Set<Number> getNoDataValues()

      Returns the values to indicate "no data" for this sample dimension. If the sample dimension describes converted values, then the "no data values" are NaN values.
      Returns:
        the values to indicate no data values for this sample dimension, or an empty set if none.
      Throws:
        `IllegalStateException` - if this method can not expand the range of no data values, for example because some ranges contain an infinite amount of values.

    - #### getSampleRange

          public Optional<NumberRange<?>> getSampleRange()

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

    - #### 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.
      Returns:
        the range of values after conversion by the transfer function.
      See Also:
        `getUnits()`

    - #### getTransferFunction

          public Optional<MathTransform1D> getTransferFunction()

      Returns the transfer function from sample values to real values. This method returns a transform expecting sample values as input and computing real values as output. The output units of measurement is given by `getUnits()`.

      This transform takes care of converting all "no data values" into `NaN` values. The `transferFunction.inverse()` transform is capable to differentiate those `NaN` values and get back the original sample value.

      Returns:
        the transfer function from sample to real values. May be absent if this sample dimension does not define any transform (which is not the same that defining an identity transform).

    - #### getTransferFunctionFormula

          public Optional<TransferFunction> getTransferFunctionFormula()

      Returns the scale factor and offset of the transfer function. The formula returned by this method does not take "no data values" in account. For a more generic transfer function, see `getTransferFunction()`.
      Returns:
        a description of the part of the transfer function working on real numbers.
      Throws:
        `IllegalStateException` - if the transfer function can not be simplified in a form representable by `TransferFunction`.

    - #### getUnits

          public Optional<Unit<?>> getUnits()

      Returns the units of measurement for this sample dimension. This unit applies to values obtained after the transfer function. May be absent if not applicable.
      Returns:
        the units of measurement.
      Throws:
        `IllegalStateException` - if this sample dimension use different units.
      See Also:
        `getMeasurementRange()`

    - #### forConvertedValues

          public SampleDimension forConvertedValues​(boolean converted)

      Returns a sample dimension that describes real values or sample values, depending if `converted` is `true` or `false` respectively. If there is no transfer function, then this method returns `this`.
      Parameters:
        `converted` - `true` for a sample dimension describing converted values, or `false` for a sample dimension describing packed values.
      Returns:
        a sample dimension describing converted or packed values, depending on `converted` argument value. May be `this` but never `null`.
      See Also:
        `GridCoverage​.forConvertedValues(boolean)`

    - #### hashCode

          public int hashCode()

      Returns a hash value for this sample dimension.
      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals​(Object object)

      Compares the specified object with this sample dimension for equality.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `object` - the object to compare with.
      Returns:
        `true` if the given object is equals to this sample dimension.

    - #### toString

          public String toString()

      Returns a string representation of this sample dimension. This string is for debugging purpose only and may change in future version.
      Overrides:
        `toString` in class `Object`
      Returns:
        a string representation of this sample dimension for debugging purpose.

    - #### toString

          @Debug
          public static String toString​(Locale locale,
                                        SampleDimension... dimensions)

      Returns a string representation of the given sample dimensions. This string is for debugging purpose only and may change in future version.
      Parameters:
        `locale` - the locale to use for formatting texts.
        `dimensions` - the sample dimensions to format.
      Returns:
        a string representation of the given sample dimensions for debugging purpose.