GridSampleDimension (Geotools modules 21.0 API)

Object
- GridSampleDimension

All Implemented Interfaces:

Serializable, SampleDimension
```
public class GridSampleDimension
extends Object
implements SampleDimension, Serializable
```
Describes the data values for a coverage as a list of categories. For a grid coverage a sample dimension is a band. Sample values in a band may be organized in categories. This GridSampleDimension implementation is capable to differenciate qualitative and quantitative categories. For example an image of sea surface temperature (SST) could very well defines the following categories:
```
   [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] defines a quantitative category, while all others categories are qualitative.
While this class can be used with arbitrary coverage, the primary target for this implementation is grid coverage storing their sample values as integers. This explain the "Grid" prefix in the class name.
Since:

2.1

Author:

Martin Desruisseaux (IRD)

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type Field and Description

static Logger LOGGER
The logger for grid sample dimensions.

Fields
Modifier and Type	Field and Description
`static Logger`	`LOGGER` The logger for grid sample dimensions.

Constructor Summary

Constructors
Modifier	Constructor and Description
	`GridSampleDimension(CharSequence description)` Constructs a sample dimension with specified name and no category.
	`GridSampleDimension(CharSequence description, Category[] categories, Unit<?> units)` Constructs a sample dimension with an arbitrary set of categories, which may be both quantitative and qualitative.
	`GridSampleDimension(CharSequence description, CharSequence[] categoriesNames)` Constructs a sample dimension with a set of qualitative categories only.
	`GridSampleDimension(CharSequence description, CharSequence[] names, Color[] colors)` Constructs a sample dimension with a set of qualitative categories and colors.
	`GridSampleDimension(CharSequence description, SampleDimensionType type, ColorInterpretation color, Color[] palette, CharSequence[] categories, double[] nodata, double minimum, double maximum, double scale, double offset, Unit<?> unit)` Constructs a sample dimension with the specified properties.
`protected`	`GridSampleDimension(GridSampleDimension other)` Constructs a new sample dimension with the same categories and units than the specified sample dimension.
	`GridSampleDimension(String description, Category[] categories, double scale, double offset)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`equals(Object object)` Compares the specified object with this sample dimension for equality.
`List<Category>`	`getCategories()` Returns all categories in this sample dimension.
`Category`	`getCategory(double sample)` Returns the category for the specified sample value.
`InternationalString[]`	`getCategoryNames()` Returns a sequence of category names for the values contained in this sample dimension.
`ColorInterpretation`	`getColorInterpretation()` Returns the color interpretation of the sample dimension.
`ColorModel`	`getColorModel()` Returns a color model for this sample dimension.
`ColorModel`	`getColorModel(int visibleBand, int numBands)` Returns a color model for this sample dimension.
`ColorModel`	`getColorModel(int visibleBand, int numBands, int type)` Returns a color model for this sample dimension.
`InternationalString`	`getDescription()` Gets the sample dimension title or description.
`String`	`getLabel(double value, Locale locale)` Returns a string representation of a sample value.
`double`	`getMaximumValue()` Returns the maximum value occurring in this sample dimension (inclusive).
`double`	`getMinimumValue()` Returns the minimum value occurring in this sample dimension (inclusive).
`double[]`	`getNoDataValues()` Returns the values to indicate "no data" for this sample dimension.
`double`	`getOffset()` Returns the value to add to grid values for this sample dimension.
`int[][]`	`getPalette()` Deprecated. No replacement.
`PaletteInterpretation`	`getPaletteInterpretation()` Indicates the type of color palette entry for sample dimensions which have a palette.
`NumberRange<? extends Number>`	`getRange()` Returns the range of values in this sample dimension.
`SampleDimensionType`	`getSampleDimensionType()` Returns a code value indicating grid value data type.
`double`	`getScale()` Returns the value which is multiplied to grid values for this sample dimension.
`Unit<?>`	`getUnits()` Returns the unit information 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 GridSampleDimension`	`wrap(SampleDimension sd)` Wraps the specified OpenGIS's sample dimension into a Geotools's implementation of `GridSampleDimension`.

Methods inherited from class Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - LOGGER
```
public static final Logger LOGGER
```
    The logger for grid sample dimensions.
- Constructor Detail
  - GridSampleDimension
```
public GridSampleDimension(CharSequence description)
```
    Constructs a sample dimension with specified name and no category.
    
    Parameters:
    
    description - The sample dimension title or description, or null if none. This is the value to be returned by getDescription().
    
    Since:
    
    2.3
  - GridSampleDimension
```
public GridSampleDimension(CharSequence description,
                           CharSequence[] categoriesNames)
```
    Constructs a sample dimension with a set of qualitative categories only. This constructor expects only a sequence of category names for the values contained in a sample dimension. This allows for names to be assigned to numerical values. The first entry in the sequence relates to a cell value of zero. For example: [0]="Background", [1]="Water", [2]="Forest", [3]="Urban". The created sample dimension will have no unit and a default set of colors.
    
    Parameters:
    
    description - The sample dimension title or description, or null for the default (the name of what looks like the "main" category). This is the value to be returned by getDescription().
    
    categoriesNames - Sequence of category names for the values contained in a sample dimension, as String or InternationalString objects.
    
    Since:
    
    2.3
  - GridSampleDimension
```
public GridSampleDimension(CharSequence description,
                           CharSequence[] names,
                           Color[] colors)
```
    Constructs a sample dimension with a set of qualitative categories and colors. This constructor expects a sequence of category names for the values contained in a sample dimension. This allows for names to be assigned to numerical values. The first entry in the sequence relates to a cell value of zero. For example: [0]="Background", [1]="Water", [2]="Forest", [3]="Urban". The created sample dimension will have no unit and a default set of colors.
    
    Parameters:
    
    description - The sample dimension title or description, or null for the default (the name of what looks like the "main" category). This is the value to be returned by getDescription().
    
    names - Sequence of category names for the values contained in a sample dimension, as String or InternationalString objects.
    
    colors - Color to assign to each category. This array must have the same length than names.
    
    Since:
    
    2.3
  - GridSampleDimension
```
public GridSampleDimension(CharSequence description,
                           SampleDimensionType type,
                           ColorInterpretation color,
                           Color[] palette,
                           CharSequence[] categories,
                           double[] nodata,
                           double minimum,
                           double maximum,
                           double scale,
                           double offset,
                           Unit<?> unit)
```
    Constructs a sample dimension with the specified properties. For convenience, any argument which is not a double primitive can be null, and any char sequence can be either a String or InternationalString object.
    This constructor allows the construction of a GridSampleDimension without explicit construction of Category objects. An heuristic approach is used for dispatching the informations into a set of Category objects. However, this constructor still less general and provides less fine-grain control than the constructor expecting an array of Category objects.
    
    Parameters:
    
    description - The sample dimension title or description, or null for the default (the name of what looks like the "main" category). This is the value to be returned by getDescription().
    
    type - The grid value data type (which indicate the number of bits for the data type), or null for computing it automatically from the range [minimum..maximum]. This is the value to be returned by getSampleDimensionType().
    
    color - The color interpretation, or null for a default value (usually PALETTE_INDEX). This is the value to be returned by getColorInterpretation().
    
    palette - The color palette associated with the sample dimension, or null for a default color palette (usually grayscale). If categories is non-null, then both arrays usually have the same length. However, this constructor is tolerant on this array length. This is the value to be returned (indirectly) by getColorModel().
    
    categories - A sequence of category names for the values contained in the sample dimension, or null if none. This is the values to be returned by getCategoryNames().
    
    nodata - the values to indicate "no data", or null if none. This is the values to be returned by getNoDataValues().
    
    minimum - The lower value, inclusive. The [minimum..maximum] range may or may not includes the nodata values; the range will be adjusted as needed. If categories was non-null, then minimum is usually 0. This is the value to be returned by getMinimumValue().
    
    maximum - The upper value, inclusive as well. The [minimum..maximum] range may or may not includes the nodata values; the range will be adjusted as needed. If categories was non-null, then maximum is usually equals to categories.length-1. This is the value to be returned by getMaximumValue().
    
    scale - The value which is multiplied to grid values, or 1 if none. This is the value to be returned by getScale().
    
    offset - The value to add to grid values, or 0 if none. This is the value to be returned by getOffset().
    
    unit - The unit information for this sample dimension, or null if none. This is the value to be returned by getUnits().
    
    Throws:
    
    IllegalArgumentException - if the range [minimum..maximum] is not valid.
  - GridSampleDimension
```
public GridSampleDimension(CharSequence description,
                           Category[] categories,
                           Unit<?> units)
                    throws IllegalArgumentException
```
    Constructs a sample dimension with an arbitrary set of categories, which may be both quantitative and qualitative. It is possible to specify more than one quantitative categories, providing that their sample value ranges do not overlap.
    
    Parameters:
    
    description - The sample dimension title or description, or null for the default (the name of what looks like the "main" category). This is the value to be returned by getDescription().
    
    categories - The list of categories.
    
    units - The unit information for this sample dimension. May be null if no category has units.
    
    Throws:
    
    IllegalArgumentException - if categories contains incompatible categories. If may be the case for example if two or more categories have overlapping ranges of sample values.
    
    Since:
    
    2.3
  - GridSampleDimension
```
protected GridSampleDimension(GridSampleDimension other)
```
    Constructs a new sample dimension with the same categories and units than the specified sample dimension.
    
    Parameters:
    
    other - The other sample dimension, or null.
  - GridSampleDimension
```
public GridSampleDimension(String description,
                           Category[] categories,
                           double scale,
                           double offset)
```
- Method Detail
  - wrap
```
public static GridSampleDimension wrap(SampleDimension sd)
```
    Wraps the specified OpenGIS's sample dimension into a Geotools's implementation of GridSampleDimension.
    
    Parameters:
    
    sd - The sample dimension to wrap into a Geotools implementation.
    
    Returns:
    
    The given sample dimension as a GridSampleDimension instance.
  - getSampleDimensionType
```
public SampleDimensionType getSampleDimensionType()
```
    Returns a code value indicating grid value data type. This will also indicate the number of bits for the data type.
    
    Specified by:
    
    getSampleDimensionType in interface SampleDimension
    
    Returns:
    
    A code value indicating grid value data type.
  - getDescription
```
public InternationalString getDescription()
```
    Gets the sample dimension title or description. This string may be null if no description is present.
    
    Specified by:
    
    getDescription in interface SampleDimension
    
    Returns:
    
    The title or description of this sample dimension.
  - getCategoryNames
```
public InternationalString[] getCategoryNames()
                                       throws IllegalStateException
```
    Returns a sequence of category names for the values contained in this sample dimension. This allows for names to be assigned to numerical values. The first entry in the sequence relates to a cell value of zero. For example:
    [0] Background [1] Water [2] Forest [3] Urban
    Specified by:
    
    getCategoryNames in interface SampleDimension
    
    Returns:
    
    The sequence of category names for the values contained in this sample dimension, or null if there is no category in this sample dimension.
    
    Throws:
    
    IllegalStateException - if a sequence can't be mapped because some category use negative or non-integer sample values.
    
    See Also:
    
    getCategories(), getCategory(double)
  - 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 null if none.
    
    See Also:
    
    getCategoryNames(), getCategory(double)
  - getCategory
```
public Category getCategory(double sample)
```
    Returns the category for the specified sample value. If this method can't maps a category to the specified value, then it returns null.
    
    Parameters:
    
    sample - The value (can be one of NaN values).
    
    Returns:
    
    The category for the supplied value, or null if none.
    
    See Also:
    
    getCategories(), getCategoryNames()
  - getNoDataValues
```
public double[] getNoDataValues()
                         throws IllegalStateException
```
    Returns the values to indicate "no data" for this sample dimension. The default implementation deduces the "no data" values from the list of categories supplied at construction time.
    
    Specified by:
    
    getNoDataValues in interface SampleDimension
    
    Returns:
    
    The values to indicate no data values for this sample dimension, or null if not applicable.
    
    Throws:
    
    IllegalStateException - if some qualitative categories use a range of non-integer values.
    
    See Also:
    
    SampleDimension.getMinimumValue(), SampleDimension.getMaximumValue()
  - getMinimumValue
```
public double getMinimumValue()
```
    Returns the minimum value occurring in this sample dimension (inclusive). The default implementation fetch this value from the categories supplied at construction time. If the minimum value can't be computed, then this method returns Double.NEGATIVE_INFINITY.
    
    Specified by:
    
    getMinimumValue in interface SampleDimension
    
    Returns:
    
    The minimum value occurring in the sample dimension.
    
    See Also:
    
    getRange()
  - getMaximumValue
```
public double getMaximumValue()
```
    Returns the maximum value occurring in this sample dimension (inclusive). The default implementation fetch this value from the categories supplied at construction time. If the maximum value can't be computed, then this method returns Double.POSITIVE_INFINITY.
    
    Specified by:
    
    getMaximumValue in interface SampleDimension
    
    Returns:
    
    The maximum value occurring in the sample dimension.
    
    See Also:
    
    getRange()
  - getRange
```
public NumberRange<? extends Number> getRange()
```
    Returns the range of values in this sample dimension. This is the union of the range of values of every categories, excluding NaN values. A NumberRange object gives more informations than getMinimumValue() and getMaximumValue() methods since it contains also the data type (integer, float, etc.) and inclusion/exclusion informations.
    
    Returns:
    
    The range of values. May be null if this sample dimension has no quantitative category.
    
    See Also:
    
    Category.getRange(), getMinimumValue(), getMaximumValue()
  - getLabel
```
public String getLabel(double value,
                       Locale locale)
```
    Returns a string representation of a sample value. This method try to returns a representation of the geophysics value; the transformation is automatically applied when necessary. More specifically:
    - If value maps a qualitative category, then the category name is returned as of Category.getName().
    - Otherwise, if value maps a quantitative category, then the value is formatted as a number and the unit symbol is appened.
    Parameters:
    
    value - The sample value (can be one of NaN values).
    
    locale - Locale to use for formatting, or null for the default locale.
    
    Returns:
    
    A string representation of the geophysics value, or null if there is none.
  - getUnits
```
public Unit<?> getUnits()
```
    Returns the unit information for this sample dimension. May returns null if this dimension has no units.
    
    Specified by:
    
    getUnits in interface SampleDimension
    
    Returns:
    
    The unit information for this sample dimension.
  - getOffset
```
public double getOffset()
```
    Returns the value to add to grid values for this sample dimension. This attribute is typically used when the sample dimension represents elevation data. The transformation equation is:
    offset + scale*sample
    Together with getScale() and getNoDataValues(), this method provides a limited way to transform sample values into geophysics values.
    Specified by:
    
    getOffset in interface SampleDimension
    
    Returns:
    
    The offset to add to grid values.
    
    See Also:
    
    SampleDimension.getScale()
  - getScale
```
public double getScale()
```
    Returns the value which is multiplied to grid values for this sample dimension. This attribute is typically used when the sample dimension represents elevation data. The transformation equation is:
    offset + scale*sample
    Together with getOffset() and getNoDataValues(), this method provides a limited way to transform sample values into geophysics values.
    Specified by:
    
    getScale in interface SampleDimension
    
    Returns:
    
    The scale to multiply to grid value.
    
    See Also:
    
    SampleDimension.getOffset()
  - getPalette
```
public int[][] getPalette()
```
    Deprecated. No replacement.
    
    Color palette associated with the sample dimension. A color palette can have any number of colors. See palette interpretation for meaning of the palette entries. If the grid coverage has no color palette, null will be returned.
    
    Specified by:
    
    getPalette in interface SampleDimension
    
    Returns:
    
    The color palette associated with the sample dimension.
    
    See Also:
    
    getPaletteInterpretation(), getColorInterpretation(), IndexColorModel
  - getPaletteInterpretation
```
public PaletteInterpretation getPaletteInterpretation()
```
    Indicates the type of color palette entry for sample dimensions which have a palette. If a sample dimension has a palette, the color interpretation must be GRAY_INDEX or PALETTE_INDEX. A palette entry type can be Gray, RGB, CMYK or HLS.
    
    Specified by:
    
    getPaletteInterpretation in interface SampleDimension
    
    Returns:
    
    The type of color palette entry for sample dimensions which have a palette.
  - getColorInterpretation
```
public ColorInterpretation getColorInterpretation()
```
    Returns the color interpretation of the sample dimension. A sample dimension can be an index into a color palette or be a color model component. If the sample dimension is not assigned a color interpretation the value is ColorInterpretation.UNDEFINED.
    
    Specified by:
    
    getColorInterpretation in interface SampleDimension
    
    Returns:
    
    The color interpretation of the sample dimension.
  - getColorModel
```
public ColorModel getColorModel()
```
    Returns a color model for this sample dimension. The default implementation create a color model with 1 band using each category's colors as returned by Category.getColors().
    Note that GridCoverage2D.getSampleDimension(int) returns special implementations of GridSampleDimension. In this particular case, the color model created by this getColorModel() method will have the same number of bands than the grid coverage's RenderedImage.
    
    Returns:
    
    The requested color model, suitable for RenderedImage objects with values in the getRange() range. May be null if this sample dimension has no category.
  - getColorModel
```
public ColorModel getColorModel(int visibleBand,
                                int numBands)
```
    Returns a color model for this sample dimension. The default implementation create the color model using each category's colors as returned by Category.getColors().
    
    Parameters:
    
    visibleBand - The band to be made visible (usually 0). All other bands, if any will be ignored.
    
    numBands - The number of bands for the color model (usually 1). The returned color model will renderer only the visibleBand and ignore the others, but the existence of all numBands will be at least tolerated. Supplemental bands, even invisible, are useful for processing with Java Advanced Imaging.
    
    Returns:
    
    The requested color model, suitable for RenderedImage objects with values in the getRange() range. May be null if this sample dimension has no category.
  - getColorModel
```
public ColorModel getColorModel(int visibleBand,
                                int numBands,
                                int type)
```
    Returns a color model for this sample dimension. The default implementation create the color model using each category's colors as returned by Category.getColors().
    
    Parameters:
    
    visibleBand - The band to be made visible (usually 0). All other bands, if any will be ignored.
    
    numBands - The number of bands for the color model (usually 1). The returned color model will renderer only the visibleBand and ignore the others, but the existence of all numBands will be at least tolerated. Supplemental bands, even invisible, are useful for processing with Java Advanced Imaging.
    
    type - The data type that has to be used for the sample model.
    
    Returns:
    
    The requested color model, suitable for RenderedImage objects with values in the getRange() range. May be null if this sample dimension has no category.
  - hashCode
```
public int hashCode()
```
    Returns a hash value for this sample dimension. This value need 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 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. The default implementation format the sample value range, then the list of categories. A "*" mark is put in front of what seems the "main" category.
    
    Overrides:
    
    toString in class Object

Class GridSampleDimension

Field Summary

Constructor Summary

Method Summary

Methods inherited from class Object

Field Detail

LOGGER

Constructor Detail

GridSampleDimension

GridSampleDimension

GridSampleDimension

GridSampleDimension

GridSampleDimension

GridSampleDimension

GridSampleDimension

Method Detail

wrap

getSampleDimensionType

getDescription

getCategoryNames

getCategories

getCategory

getNoDataValues

getMinimumValue

getMaximumValue

getRange

getLabel

getUnits

getOffset

getScale

getPalette

getPaletteInterpretation

getColorInterpretation

getColorModel

getColorModel

getColorModel

hashCode

equals

toString