org.geotools.coverage
Class GridSampleDimension

java.lang.Object
  org.geotools.coverage.GridSampleDimension

All Implemented Interfaces:

org.opengis.coverage.SampleDimension, java.io.Serializable

public class GridSampleDimension

extends java.lang.Object

implements org.opengis.coverage.SampleDimension, java.io.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 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 defines a quantitative category, while all others categories are qualitative. The difference between those two kinds of category is that the Category.getSampleToGeophysics() method returns a non-null transform if and only if the category is quantitative.

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 "" prefix in the class name.

Since:

2.1

Version:

$Id: GridSampleDimension.java 17672 2006-01-19 00:25:55Z desruisseaux $

Author:

Martin Desruisseaux

See Also:

Serialized Form

Constructor Summary

	GridSampleDimension() Constructs a sample dimension with no category.
	GridSampleDimension(Category[] categories, javax.units.Unit units) Constructs a sample dimension with an arbitrary set of categories, which may be both quantitative and qualitative.
	GridSampleDimension(java.lang.CharSequence[] names) Constructs a sample dimension with a set of qualitative categories only.
	GridSampleDimension(java.lang.CharSequence[] names, java.awt.Color[] colors) Constructs a sample dimension with a set of qualitative categories and colors.
	GridSampleDimension(java.lang.CharSequence description, org.opengis.coverage.SampleDimensionType type, org.opengis.coverage.ColorInterpretation color, java.awt.Color[] palette, java.lang.CharSequence[] categories, double[] nodata, double minimum, double maximum, double scale, double offset, javax.units.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.

Method Summary

boolean	equals(java.lang.Object object) Compares the specified object with this sample dimension for equality.
GridSampleDimension	geophysics(boolean geo) If , returns the geophysics companion of this sample dimension.
Category	getBackground() Returns a default category to use for background.
java.util.List	getCategories() Returns all categories in this sample dimension.
Category	getCategory(double sample) Returns the category for the specified sample value.
org.opengis.util.InternationalString[]	getCategoryNames() Returns a sequence of category names for the values contained in this sample dimension.
java.lang.String[]	getCategoryNames(java.util.Locale locale) Deprecated. Use getCategoryNames() instead.
org.opengis.coverage.ColorInterpretation	getColorInterpretation() Returns the color interpretation of the sample dimension.
java.awt.image.ColorModel	getColorModel() Returns a color model for this sample dimension.
java.awt.image.ColorModel	getColorModel(int visibleBand, int numBands) Returns a color model for this sample dimension.
java.awt.image.ColorModel	getColorModel(int visibleBand, int numBands, int type) Returns a color model for this sample dimension.
org.opengis.util.InternationalString	getDescription() Get the sample dimension title or description.
java.lang.String	getDescription(java.util.Locale locale) Deprecated. Use getDescription() instead.
java.lang.String	getLabel(double value, java.util.Locale locale) Returns a string representation of a sample value.
double	getMaximumValue() Returns the maximum value occurring in this sample dimension.
java.lang.String[]	getMetaDataNames() The list of metadata keywords for a sample dimension.
java.lang.String	getMetadataValue(java.lang.String name) Retrieve the metadata value for a given metadata name.
double	getMinimumValue() Returns the minimum value occurring in this sample dimension.
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() Color palette associated with the sample dimension.
org.opengis.coverage.PaletteInterpretation	getPaletteInterpretation() Indicates the type of color palette entry for sample dimensions which have a palette.
NumberRange	getRange() Returns the range of values in this sample dimension.
org.opengis.coverage.SampleDimensionType	getSampleDimensionType() Returns a code value indicating grid value data type.
org.opengis.referencing.operation.MathTransform1D	getSampleToGeophysics() Returns a transform from sample values to geophysics values.
double	getScale() Returns the value which is multiplied to grid values for this sample dimension.
javax.units.Unit	getUnits() Returns the unit information for this sample dimension.
int	hashCode() Returns a hash value for this sample dimension.
GridSampleDimension	rescale(double scale, double offset) Returns a sample dimension using new scale and offset coefficients.
java.lang.String	toString() Returns a string representation of this sample dimension.
static GridSampleDimension	wrap(org.opengis.coverage.SampleDimension sd) Wrap the specified OpenGIS's sample dimension into a Geotools's implementation of .

Methods inherited from class java.lang.Object

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

Constructor Detail

GridSampleDimension

public GridSampleDimension()

Constructs a sample dimension with no category.

GridSampleDimension

public GridSampleDimension(java.lang.CharSequence[] names)

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:

names - Sequence of category names for the values contained in a sample dimension, as String or InternationalString objects.

GridSampleDimension

public GridSampleDimension(java.lang.CharSequence[] names,
                           java.awt.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:

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 .

GridSampleDimension

public GridSampleDimension(java.lang.CharSequence description,
                           org.opengis.coverage.SampleDimensionType type,
                           org.opengis.coverage.ColorInterpretation color,
                           java.awt.Color[] palette,
                           java.lang.CharSequence[] categories,
                           double[] nodata,
                           double minimum,
                           double maximum,
                           double scale,
                           double offset,
                           javax.units.Unit unit)

Constructs a sample dimension with the specified properties. For convenience, any argument which is not a primitive can be , and any char sequence can be either a String or InternationalString object. This constructor allows the construction of a 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 if none. 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 for computing it automatically from the range . This is the value to be returned by getSampleDimensionType().

color - The color interpretation, or 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 for a default color palette (usually grayscale). If 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 if none. This is the values to be returned by getCategoryNames().

nodata - the values to indicate "no data", or if none. This is the values to be returned by getNoDataValues().

minimum - The lower value, inclusive. The range may or may not includes the values; the range will be adjusted as needed. If was non-null, then is usually 0. This is the value to be returned by getMinimumValue().

maximum - The upper value, inclusive as well. The range may or may not includes the values; the range will be adjusted as needed. If was non-null, then is usually equals to . 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 if none. This is the value to be returned by getUnits().

Throws:

java.lang.IllegalArgumentException - if the range is not valid.

GridSampleDimension

public GridSampleDimension(Category[] categories,
                           javax.units.Unit units)
                    throws java.lang.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. Quantitative categories can map sample values to geophysics values using arbitrary relation (not necessarly linear).

Parameters:

categories - The list of categories.

units - The unit information for this sample dimension. May be if no category has units. This unit apply to values obtained after the sampleToGeophysics transformation.

Throws:

java.lang.IllegalArgumentException - if contains incompatible categories. If may be the case for example if two or more categories have overlapping ranges of sample values.

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 .

Method Detail

wrap

public static GridSampleDimension wrap(org.opengis.coverage.SampleDimension sd)

Wrap the specified OpenGIS's sample dimension into a Geotools's implementation of .

Parameters:

sd - The sample dimension to wrap into a Geotools implementation.

getSampleDimensionType

public org.opengis.coverage.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 org.opengis.coverage.SampleDimension

Returns:

a code value indicating grid value data type.

getDescription

public org.opengis.util.InternationalString getDescription()

Get the sample dimension title or description. This string may be if no description is present.

Specified by:

getDescription in interface org.opengis.coverage.SampleDimension

getDescription

public java.lang.String getDescription(java.util.Locale locale)

Deprecated. Use getDescription() instead.

getCategoryNames

public org.opengis.util.InternationalString[] getCategoryNames()
                                                        throws java.lang.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 org.opengis.coverage.SampleDimension

Returns:

The sequence of category names for the values contained in this sample dimension, or if there is no category in this sample dimension.

Throws:

java.lang.IllegalStateException - if a sequence can't be mapped because some category use negative or non-integer sample values.

See Also:

getCategories(), getCategory(double)

getCategoryNames

public final java.lang.String[] getCategoryNames(java.util.Locale locale)
                                          throws java.lang.IllegalStateException

Deprecated. Use getCategoryNames() instead.

Returns a sequence of category names for the values contained in this sample dimension.

Throws:

java.lang.IllegalStateException

getCategories

public java.util.List 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 .

Returns:

The list of categories in this sample dimension, or 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 .

Parameters:

sample - The value (can be one of values).

Returns:

The category for the supplied value, or if none.

See Also:

getCategories(), getCategoryNames()

getBackground

public Category getBackground()

Returns a default category to use for background. A background category is used when an image is resampled (for example reprojected in an other coordinate system) and the resampled image do not fit in a rectangular area. It can also be used in various situation where a raisonable "no data" category is needed. The default implementation try to returns one of the no data values. If no suitable category is found, then a default one is returned.

Returns:

A category to use as background for the "Resample" operation. Never .

getNoDataValues

public double[] getNoDataValues()
                         throws java.lang.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. The rules are:

• If getSampleToGeophysics() returns , then returns as well. This means that this sample dimension contains no category or contains only qualitative categories (e.g. a band from a classified image).
• If getSampleToGeophysics() returns an identity transform, then returns . This means that sample value in this sample dimension are already expressed in geophysics values and that all "no data" values (if any) have already been converted into values.
• Otherwise, if there is at least one quantitative category, returns the sample values of all non-quantitative categories. For example if "Temperature" is a quantitative category and "Land" and "Cloud" are two qualitative categories, then sample values for "Land" and "Cloud" will be considered as "no data" values. "No data" values that are already will be ignored.

Together with getOffset() and getScale(), this method provides a limited way to transform sample values into geophysics values. However, the recommended way is to use the sampleToGeophysics transform instead, which is more general and take care of converting automatically "no data" values into .

Specified by:

getNoDataValues in interface org.opengis.coverage.SampleDimension

Returns:

The values to indicate no data values for this sample dimension, or if not applicable.

Throws:

java.lang.IllegalStateException - if some qualitative categories use a range of non-integer values.

See Also:

getSampleToGeophysics()

getMinimumValue

public double getMinimumValue()

Returns the minimum value occurring in this sample dimension. 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 org.opengis.coverage.SampleDimension

See Also:

getRange()

getMaximumValue

public double getMaximumValue()

Returns the maximum value occurring in this sample dimension. 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 org.opengis.coverage.SampleDimension

See Also:

getRange()

getRange

public NumberRange getRange()

Returns the range of values in this sample dimension. This is the union of the range of values of every categories, excluding 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 if this sample dimension has no quantitative category.

See Also:

Category.getRange(), getMinimumValue(), getMaximumValue()

To Do:

We should do a better job in when selecting the appropriate data type. TypeMap.getSampleDimensionType(Range) may be of some help.

getLabel

public java.lang.String getLabel(double value,
                                 java.util.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 maps a qualitative category, then the category name is returned as of Category.getName().
• Otherwise, if maps a quantitative category, then the value is transformed into a geophysics value as with the sampleToGeophysics transform, the result is formatted as a number and the unit symbol is appened.

Parameters:

value - The sample value (can be one of values).

locale - Locale to use for formatting, or for the default locale.

Returns:

A string representation of the geophysics value, or if there is none.

To Do:

What should we do when the value can't be formatted? returns if there is no category or if an exception is thrown, but returns "Untitled" if the value is an unknow NaN, and try to format the number anyway in other cases.

getUnits

public javax.units.Unit getUnits()

Returns the unit information for this sample dimension. May returns if this dimension has no units. This unit apply to values obtained after the sampleToGeophysics transformation.

Specified by:

getUnits in interface org.opengis.coverage.SampleDimension

See Also:

getSampleToGeophysics()

getOffset

public double getOffset()
                 throws java.lang.IllegalStateException

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. However, the recommended way is to use the sampleToGeophysics transform instead, which is more general and take care of converting automatically "no data" values into .

Specified by:

getOffset in interface org.opengis.coverage.SampleDimension

Returns:

The offset to add to grid values.

Throws:

java.lang.IllegalStateException - if the transform from sample to geophysics values is not a linear relation.

See Also:

getSampleToGeophysics(), rescale(double, double)

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. However, the recommended way is to use the sampleToGeophysics transform instead, which is more general and take care of converting automatically "no data" values into .

Specified by:

getScale in interface org.opengis.coverage.SampleDimension

Returns:

The scale to multiply to grid value.

Throws:

java.lang.IllegalStateException - if the transform from sample to geophysics values is not a linear relation.

See Also:

getSampleToGeophysics(), rescale(double, double)

getSampleToGeophysics

public org.opengis.referencing.operation.MathTransform1D getSampleToGeophysics()

Returns a transform from sample values to geophysics values. If this sample dimension has no category, then this method returns . If all sample values are already geophysics values (including for "no data" values), then this method returns an identity transform. Otherwise, this method returns a transform expecting sample values as input and computing geophysics value as output. This transform will take care of converting all "no data values" into values. The sampleToGeophysics.inverse() transform is capable to differenciate values to get back the original sample value.

Specified by:

getSampleToGeophysics in interface org.opengis.coverage.SampleDimension

Returns:

The transform from sample to geophysics values, or if this sample dimension do not defines any transform (which is not the same that defining an identity transform).

See Also:

getScale(), getOffset(), getNoDataValues(), rescale(double, double)

geophysics

public GridSampleDimension geophysics(boolean geo)

If , returns the geophysics companion of this sample dimension. By definition, a geophysics sample dimension is a sample dimension with a range of sample values transformed in such a way that the sampleToGeophysics transform is always the identity transform, or if no such transform existed in the first place. In other words, the range of sample values in all category maps directly the "real world" values without the need for any transformation.

objects live by pair: a geophysics one (used for computation) and a non-geophysics one (used for packing data, usually as integers). The argument specifies which object from the pair is wanted, regardless if this method is invoked on the geophysics or non-geophysics instance of the pair. In other words, the result of depends only on the value in the last call ().

Parameters:

geo - to get a sample dimension with an identity transform and a range of sample values matching the geophysics values, or to get back the original sample dimension.

Returns:

The sample dimension. Never , but may be .

See Also:

Category.geophysics(boolean), GridCoverage2D.geophysics(boolean)

getPalette

public int[][] getPalette()

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, will be returned.

Specified by:

getPalette in interface org.opengis.coverage.SampleDimension

Returns:

The color palette associated with the sample dimension.

See Also:

getPaletteInterpretation(), getColorInterpretation(), IndexColorModel

getPaletteInterpretation

public org.opengis.coverage.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 org.opengis.coverage.SampleDimension

Returns:

The type of color palette entry for sample dimensions which have a palette.

getColorInterpretation

public org.opengis.coverage.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 org.opengis.coverage.SampleDimension

getColorModel

public java.awt.image.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(). The returned color model will typically use data type DataBuffer.TYPE_FLOAT if this instance is "geophysics", or an integer data type otherwise.

Note that GridCoverage2D.getSampleDimension(int) returns special implementations of . In this particular case, the color model created by this 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 if this sample dimension has no category.

getColorModel

public java.awt.image.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(). The returned color model will typically use data type DataBuffer.TYPE_FLOAT if this instance is "geophysics", or an integer data type otherwise.

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 and ignore the others, but the existence of all 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 if this sample dimension has no category.

To Do:

This method may be deprecated in a future version. It it strange to use only one object for creating a multi-bands color model. Logically, we would expect as many s as bands.

getColorModel

public java.awt.image.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 and ignore the others, but the existence of all 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 if this sample dimension has no category.

To Do:

This method may be deprecated in a future version. It it strange to use only one object for creating a multi-bands color model. Logically, we would expect as many s as bands.

rescale

public GridSampleDimension rescale(double scale,
                                   double offset)

Returns a sample dimension using new scale and offset coefficients. Other properties like the sample value range, no data values and colors are unchanged.

Parameters:

scale - The value which is multiplied to grid values for the new sample dimension.

offset - The value to add to grid values for the new sample dimension.

See Also:

getScale(), getOffset(), Category.rescale(org.opengis.referencing.operation.MathTransform1D)

getMetaDataNames

public java.lang.String[] getMetaDataNames()

The list of metadata keywords for a sample dimension. If no metadata is available, the sequence will be empty.

Specified by:

getMetaDataNames in interface org.opengis.coverage.SampleDimension

Returns:

The list of metadata keywords for a sample dimension.

See Also:

getMetadataValue(java.lang.String), PropertySource.getPropertyNames()

getMetadataValue

public java.lang.String getMetadataValue(java.lang.String name)
                                  throws org.opengis.coverage.MetadataNameNotFoundException

Retrieve the metadata value for a given metadata name.

Specified by:

getMetadataValue in interface org.opengis.coverage.SampleDimension

Parameters:

name - Metadata keyword for which to retrieve metadata.

Returns:

The metadata value for a given metadata name.

Throws:

org.opengis.coverage.MetadataNameNotFoundException - if there is no value for the specified metadata name.

See Also:

getMetaDataNames(), PropertySource.getProperty(java.lang.String)

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(java.lang.Object object)

Compares the specified object with this sample dimension for equality.

toString

public java.lang.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.