Class GridSampleDimension
- 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. ThisGridSampleDimension
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
[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
-
-
Constructor Summary
Constructors Modifier Constructor Description GridSampleDimension(CharSequence description)
Constructs a sample dimension with specified name and no category.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, CharSequence[] categories, double[] nodata, double minimum, double maximum, double scale, double offset, Unit<?> unit)
Constructs a sample dimension with the specified properties.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.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(String description, Category[] categories, double scale, double offset)
protected
GridSampleDimension(GridSampleDimension other)
Constructs a new sample dimension with the same categories and units than the specified sample dimension.
-
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.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.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 ofGridSampleDimension
.
-
-
-
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, ornull
if none. This is the value to be returned bygetDescription()
.- 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, ornull
for the default (the name of what looks like the "main" category). This is the value to be returned bygetDescription()
.categoriesNames
- Sequence of category names for the values contained in a sample dimension, asString
orInternationalString
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, ornull
for the default (the name of what looks like the "main" category). This is the value to be returned bygetDescription()
.names
- Sequence of category names for the values contained in a sample dimension, asString
orInternationalString
objects.colors
- Color to assign to each category. This array must have the same length thannames
.- 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 adouble
primitive can benull
, and any char sequence can be either aString
orInternationalString
object.This constructor allows the construction of a
GridSampleDimension
without explicit construction ofCategory
objects. An heuristic approach is used for dispatching the informations into a set ofCategory
objects. However, this constructor still less general and provides less fine-grain control than the constructor expecting an array ofCategory
objects.- Parameters:
description
- The sample dimension title or description, ornull
for the default (the name of what looks like the "main" category). This is the value to be returned bygetDescription()
.type
- The grid value data type (which indicate the number of bits for the data type), ornull
for computing it automatically from the range[minimum..maximum]
. This is the value to be returned bygetSampleDimensionType()
.palette
- The color palette associated with the sample dimension, ornull
for a default color palette (usually grayscale). Ifcategories
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) bygetColorModel()
.categories
- A sequence of category names for the values contained in the sample dimension, ornull
if none. This is the values to be returned bygetCategoryNames()
.nodata
- the values to indicate "no data", ornull
if none. This is the values to be returned bygetNoDataValues()
.minimum
- The lower value, inclusive. The[minimum..maximum]
range may or may not includes thenodata
values; the range will be adjusted as needed. Ifcategories
was non-null, thenminimum
is usually 0. This is the value to be returned bygetMinimumValue()
.maximum
- The upper value, inclusive as well. The[minimum..maximum]
range may or may not includes thenodata
values; the range will be adjusted as needed. Ifcategories
was non-null, thenmaximum
is usually equals tocategories.length-1
. This is the value to be returned bygetMaximumValue()
.scale
- The value which is multiplied to grid values, or 1 if none. This is the value to be returned bygetScale()
.offset
- The value to add to grid values, or 0 if none. This is the value to be returned bygetOffset()
.unit
- The unit information for this sample dimension, ornull
if none. This is the value to be returned bygetUnits()
.- Throws:
IllegalArgumentException
- if the range[minimum..maximum]
is not valid.
-
GridSampleDimension
public GridSampleDimension(CharSequence description, SampleDimensionType type, 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 adouble
primitive can benull
, and any char sequence can be either aString
orInternationalString
object.This constructor allows the construction of a
GridSampleDimension
without explicit construction ofCategory
objects. An heuristic approach is used for dispatching the informations into a set ofCategory
objects. However, this constructor still less general and provides less fine-grain control than the constructor expecting an array ofCategory
objects.- Parameters:
description
- The sample dimension title or description, ornull
for the default (the name of what looks like the "main" category). This is the value to be returned bygetDescription()
.type
- The grid value data type (which indicate the number of bits for the data type), ornull
for computing it automatically from the range[minimum..maximum]
. This is the value to be returned bygetSampleDimensionType()
.categories
- A sequence of category names for the values contained in the sample dimension, ornull
if none. This is the values to be returned bygetCategoryNames()
.nodata
- the values to indicate "no data", ornull
if none. This is the values to be returned bygetNoDataValues()
.minimum
- The lower value, inclusive. The[minimum..maximum]
range may or may not includes thenodata
values; the range will be adjusted as needed. Ifcategories
was non-null, thenminimum
is usually 0. This is the value to be returned bygetMinimumValue()
.maximum
- The upper value, inclusive as well. The[minimum..maximum]
range may or may not includes thenodata
values; the range will be adjusted as needed. Ifcategories
was non-null, thenmaximum
is usually equals tocategories.length-1
. This is the value to be returned bygetMaximumValue()
.scale
- The value which is multiplied to grid values, or 1 if none. This is the value to be returned bygetScale()
.offset
- The value to add to grid values, or 0 if none. This is the value to be returned bygetOffset()
.unit
- The unit information for this sample dimension, ornull
if none. This is the value to be returned bygetUnits()
.- 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, ornull
for the default (the name of what looks like the "main" category). This is the value to be returned bygetDescription()
.categories
- The list of categories.units
- The unit information for this sample dimension. May benull
if no category has units.- Throws:
IllegalArgumentException
- ifcategories
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, ornull
.
-
-
Method Detail
-
wrap
public static GridSampleDimension wrap(SampleDimension sd)
Wraps the specified OpenGIS's sample dimension into a Geotools's implementation ofGridSampleDimension
.- 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 interfaceSampleDimension
- Returns:
- A code value indicating grid value data type.
-
getDescription
public InternationalString getDescription()
Gets the sample dimension title or description. This string may benull
if no description is present.- Specified by:
getDescription
in interfaceSampleDimension
- 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 interfaceSampleDimension
- 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 aCategory
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 value0
.- 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 returnsnull
.- Parameters:
sample
- The value (can be one ofNaN
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 interfaceSampleDimension
- 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 returnsDouble.NEGATIVE_INFINITY
.- Specified by:
getMinimumValue
in interfaceSampleDimension
- 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 returnsDouble.POSITIVE_INFINITY
.- Specified by:
getMaximumValue
in interfaceSampleDimension
- 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, excludingNaN
values. ANumberRange
object gives more informations thangetMinimumValue()
andgetMaximumValue()
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 ofCategory.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 ofNaN
values).locale
- Locale to use for formatting, ornull
for the default locale.- Returns:
- A string representation of the geophysics value, or
null
if there is none.
- If
-
getUnits
public Unit<?> getUnits()
Returns the unit information for this sample dimension. May returnsnull
if this dimension has no units.- Specified by:
getUnits
in interfaceSampleDimension
- 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
getScale()
andgetNoDataValues()
, this method provides a limited way to transform sample values into geophysics values.- Specified by:
getOffset
in interfaceSampleDimension
- 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
getOffset()
andgetNoDataValues()
, this method provides a limited way to transform sample values into geophysics values.- Specified by:
getScale
in interfaceSampleDimension
- Returns:
- The scale to multiply to grid value.
- See Also:
SampleDimension.getOffset()
-
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 isColorInterpretation.UNDEFINED
.
-
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 byCategory.getColors()
.Note that
GridCoverage2D.getSampleDimension(int)
returns special implementations ofGridSampleDimension
. In this particular case, the color model created by thisgetColorModel()
method will have the same number of bands than the grid coverage'sRenderedImage
.- Returns:
- The requested color model, suitable for
RenderedImage
objects with values in the
range. May begetRange()
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 byCategory.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 thevisibleBand
and ignore the others, but the existence of allnumBands
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
range. May begetRange()
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 byCategory.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 thevisibleBand
and ignore the others, but the existence of allnumBands
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
range. May begetRange()
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.
-
equals
public boolean equals(Object object)
Compares the specified object with this sample dimension for equality.
-
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.
-
-