Class SampleDimension

java.lang.Object
org.apache.sis.coverage.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 at the same time.

Definition of missing data

An important aspect of sample dimensions is the background value. It defines how to initialize an empty image or canvas with respect to the sample definition. It can be thought as the value for "lack of data" (fill value, no-data, missing value) category when the missing value cannot be categorized more precisely (cloud, instrument error, etc).
Since:
1.0
Version:
1.2
See Also:
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serial number for inter-operability with different versions.
      See Also:
    • name

      private final org.opengis.util.GenericName name
      Identification for this sample dimension. 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.
      See Also:
    • background

      private final Number background
      The background value, or null if unspecified. Should be a sample value of a qualitative category in the categories list, but this is not mandatory.
      See Also:
    • categories

      private final CategoryList categories
      The list of categories making this sample dimension. May be empty but shall never be null.
    • transferFunction

      private final org.opengis.referencing.operation.MathTransform1D transferFunction
      The transform from samples to real values. May be null if this sample dimension does not define any transform (which is not the same than defining an identity transform).
      See Also:
    • converse

      private final SampleDimension converse
      The SampleDimension that describes values after transfer function has been applied, or if this SampleDimension is already converted then the original sample dimension. May be null if this sample dimension has no transfer function, or 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:
  • Constructor Details

    • SampleDimension

      private SampleDimension(SampleDimension original, Category bc)
      Creates a new sample dimension for values that are already converted to real values. This transfer function is set to identity, which implies that this constructor should be invoked only for sample dimensions having at least one quantitative category.
      Parameters:
      original - the original sample dimension for packed values.
      bc - category of the background value in original sample dimension, or null.
    • SampleDimension

      public SampleDimension(org.opengis.util.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.
      Throws:
      IllegalSampleDimensionException - if two or more categories have overlapping sample value range.
  • Method Details

    • converted

      private SampleDimension converted()
      Returns the sample dimension that describes real values. This method establishes a unidirectional navigation from sample values to real values. This is in contrast to converse, which establish a bidirectional navigation.
      See Also:
    • getName

      public org.opengis.util.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. This is the value used for filling empty spaces (e.g. in image corners) after a resampling operation. 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 cannot expand the range of no data values, for example because some ranges contain an infinite amount of values.
      See Also:
    • compare

      private static int compare(Number n1, Number n2)
      Compares as 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.
    • 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:
    • getTransferFunction

      public Optional<org.opengis.referencing.operation.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 cannot be simplified in a form representable by TransferFunction.
    • getUnits

      public Optional<javax.measure.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:
    • allowsNaN

      public boolean allowsNaN()
      Returns true if some sample values can be NaN values. It may be the case for converted values, but not necessarily (because a coverage does not necessarily allow missing values). If true, then the NaN values should be listed by getNoDataValues().
      Returns:
      whether some values in this sample dimension can be NaN.
      Since:
      1.1
      See Also:
    • 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:
    • 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 equal 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.