| java.lang.Object org.geotools.coverage.GridSampleDimension
All known Subclasses: org.geotools.coverage.grid.Grid2DSampleDimension,
GridSampleDimension | public class GridSampleDimension implements SampleDimension,Serializable(Code) | | Describes the data values for a coverage as a list of
. 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. 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
,
the primary target for this implementation is
storing their sample values as integers. This explain the "
Grid " prefix
in the class name.
since: 2.1 version: $Id: GridSampleDimension.java 23398 2006-12-12 05:57:00Z desruisseaux $ author: Martin Desruisseaux |
Field Summary | |
final CategoryList | categories The category list for this sample dimension, or
null if this sample
dimension has no category. |
Constructor Summary | |
public | GridSampleDimension() Constructs a sample dimension with no description and no category. | public | GridSampleDimension(CharSequence description) Constructs a sample dimension with specified name and no category.
Parameters: description - The sample dimension title or description, or null ifnone. | 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. | public | GridSampleDimension(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. | public | GridSampleDimension(CharSequence description, CharSequence[] names, Color[] colors) Constructs a sample dimension with a set of qualitative categories and
colors. | public | GridSampleDimension(CharSequence[] names, Color[] colors) Constructs a sample dimension with a set of qualitative categories and
colors. | 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. | public | GridSampleDimension(CharSequence description, Category[] categories, Unit units) Constructs a sample dimension with an arbitrary set of categories, which
may be both quantitative and qualitative. | public | GridSampleDimension(Category[] categories, Unit units) Constructs a sample dimension with an arbitrary set of categories, which
may be both quantitative and qualitative. | protected | GridSampleDimension(GridSampleDimension other) Constructs a new sample dimension with the same categories and
units than the specified sample dimension. |
Method Summary | |
public boolean | equals(Object object) Compares the specified object with this sample dimension for equality. | public GridSampleDimension | geophysics(boolean geo) If
true , returns the geophysics companion of this sample dimension. | public Category | getBackground() Returns a default category to use for background. | public List | getCategories() Returns all categories in this sample dimension. | public Category | getCategory(double sample) Returns the category for the specified sample value. | public InternationalString[] | getCategoryNames() Returns a sequence of category names for the values contained in this sample dimension.
This allows for names to be assigned to numerical values. | 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. | public ColorModel | getColorModel() Returns a color model for this sample dimension. | public ColorModel | getColorModel(int visibleBand, int numBands) Returns a color model for this sample dimension. | public ColorModel | getColorModel(int visibleBand, int numBands, int type) Returns a color model for this sample dimension. | public InternationalString | getDescription() Get the sample dimension title or description. | public String | getLabel(double value, Locale locale) Returns a string representation of a sample value. | 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. | public String[] | getMetaDataNames() The list of metadata keywords for a sample dimension. | public String | getMetadataValue(String name) Retrieve the metadata value for a given metadata name.
Parameters: name - Metadata keyword for which to retrieve metadata. | 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. | public double[] | getNoDataValues() Returns the values to indicate "no data" for this sample dimension. | 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. | public int[][] | getPalette() Color palette associated with the sample dimension. | public PaletteInterpretation | getPaletteInterpretation() Indicates the type of color palette entry for sample dimensions which have a
palette. | public NumberRange | getRange() Returns the range of values in this sample dimension. | public SampleDimensionType | getSampleDimensionType() Returns a code value indicating grid value data type. | public MathTransform1D | getSampleToGeophysics() Returns a transform from sample values to geophysics values. | 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. | public Unit | getUnits() Returns the unit information for this sample dimension. | public int | hashCode() Returns a hash value for this sample dimension. | public GridSampleDimension | rescale(double scale, double offset) Returns a sample dimension using new
GridSampleDimension.getScale scale and
GridSampleDimension.getOffset offset coefficients. | public String | toString() Returns a string representation of this sample dimension.
This string is for debugging purpose only and may change
in future version. | public static GridSampleDimension | wrap(SampleDimension sd) Wrap the specified OpenGIS's sample dimension into a Geotools's
implementation of
GridSampleDimension . |
categories | final CategoryList categories(Code) | | The category list for this sample dimension, or
null if this sample
dimension has no category. This field is read by
SampleTranscoder only.
|
GridSampleDimension | public GridSampleDimension(CharSequence description)(Code) | | Constructs a sample dimension with specified name and no category.
Parameters: description - The sample dimension title or description, or null ifnone. This is the value to be returned by GridSampleDimension.getDescription. since: 2.3 |
GridSampleDimension | public GridSampleDimension(CharSequence description, CharSequence[] categoriesNames)(Code) | | 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 bereturned by GridSampleDimension.getDescription. Parameters: categoriesNames - Sequence of category names for the values contained in asample dimension, as String orInternationalString objects. since: 2.3 |
GridSampleDimension | public GridSampleDimension(CharSequence[] categoriesNames)(Code) | | 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: categoriesNames - Sequence of category names for the values contained in asample dimension, as String orInternationalString objects.GridSampleDimension.GridSampleDimension(CharSequence,CharSequence[]) |
GridSampleDimension | public GridSampleDimension(CharSequence description, CharSequence[] names, Color[] colors)(Code) | | 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 bereturned by GridSampleDimension.getDescription. Parameters: names - Sequence of category names for the values contained in asample dimension, as String orInternationalString objects. Parameters: colors - Color to assign to each category. This array must have thesame length than names . since: 2.3 |
GridSampleDimension | public GridSampleDimension(CharSequence[] names, Color[] colors)(Code) | | 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 asample dimension, as String orInternationalString objects. Parameters: colors - Color to assign to each category. This array must have thesame length than names .GridSampleDimension.GridSampleDimension(CharSequence,CharSequence[],Color[]) |
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)(Code) | | Constructs a sample dimension with the specified properties. For
convenience, any argument which is not a
double primitive can be
null , and any
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 bereturned by GridSampleDimension.getDescription. Parameters: type - The grid value data type (which indicate the number of bitsfor the data type), or null for computing itautomatically from the range [minimum..maximum] . Thisis the value to be returned by GridSampleDimension.getSampleDimensionType. Parameters: color - The color interpretation, or null for a default value(usuallyColorInterpretation.PALETTE_INDEX PALETTE_INDEX).This is the value to be returned byGridSampleDimension.getColorInterpretation. Parameters: 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 usuallyhave the same length. However, this constructor is tolerant onthis array length. This is the value to be returned(indirectly) by GridSampleDimension.getColorModel. Parameters: categories - A sequence of category names for the values contained in thesample dimension, or null if none. This is the valuesto be returned by GridSampleDimension.getCategoryNames. Parameters: nodata - the values to indicate "no data", or null if none.This is the values to be returned by GridSampleDimension.getNoDataValues. Parameters: minimum - The lower value, inclusive. The [minimum..maximum] range may or may not includes the nodata values; therange will be adjusted as needed. If categories wasnon-null, then minimum is usually 0. This is the valueto be returned by GridSampleDimension.getMinimumValue. Parameters: 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 isusually equals to categories.length-1 . This is thevalue to be returned by GridSampleDimension.getMaximumValue. Parameters: scale - The value which is multiplied to grid values, or 1 if none.This is the value to be returned by GridSampleDimension.getScale. Parameters: offset - The value to add to grid values, or 0 if none. This is thevalue to be returned by GridSampleDimension.getOffset. Parameters: unit - The unit information for this sample dimension, or null if none. This is the value to be returned byGridSampleDimension.getUnits. throws: IllegalArgumentException - if the range [minimum..maximum] is not valid. |
GridSampleDimension | public GridSampleDimension(CharSequence description, Category[] categories, Unit units) throws IllegalArgumentException(Code) | | 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: 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 bereturned by GridSampleDimension.getDescription. Parameters: categories - The list of categories. Parameters: units - The unit information for this sample dimension. May be null if no category has units. This unit apply tovalues obtained after theGridSampleDimension.getSampleToGeophysics sampleToGeophysicstransformation. throws: IllegalArgumentException - if categories contains incompatible categories. Ifmay be the case for example if two or more categories haveoverlapping ranges of sample values. since: 2.3 |
GridSampleDimension | public GridSampleDimension(Category[] categories, Unit units) throws IllegalArgumentException(Code) | | 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. Parameters: units - The unit information for this sample dimension. May be null if no category has units. This unit apply tovalues obtained after theGridSampleDimension.getSampleToGeophysics sampleToGeophysicstransformation. throws: IllegalArgumentException - if categories contains incompatible categories. Ifmay be the case for example if two or more categories haveoverlapping ranges of sample values.GridSampleDimension.GridSampleDimension(CharSequence,Category[],Unit) |
GridSampleDimension | protected GridSampleDimension(GridSampleDimension other)(Code) | | Constructs a new sample dimension with the same categories and
units than the specified sample dimension.
Parameters: other - The other sample dimension, or null . |
equals | public boolean equals(Object object)(Code) | | Compares the specified object with this sample dimension for equality.
|
geophysics | public GridSampleDimension geophysics(boolean geo)(Code) | | If
true , returns the geophysics companion of this sample dimension. By
definition, a geophysics sample dimension is a sample dimension with a
transformed in such a way that the
GridSampleDimension.getSampleToGeophysics sampleToGeophysics transform is always the identity
transform, or
null 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.
GridSampleDimension objects live by pair: a geophysics one
(used for computation) and a non-geophysics one (used for packing data, usually
as integers). The
geo 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
geophysics(b1).geophysics(b2).geophysics(b3) depends only on the value in the last call (
b3 ).
Parameters: geo - true to get a sample dimension with an identity and a matching the geophysics values, or false to get back theoriginal sample dimension. The sample dimension. Never null , but may be this . See Also: Category.geophysics See Also: org.geotools.coverage.grid.GridCoverage2D.geophysics |
getBackground | public Category getBackground()(Code) | | 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
. If no suitable category is found,
then a
one is returned.
A category to use as background for the "Resample" operation. Never null . |
getCategories | public List getCategories()(Code) | | 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 .
The list of categories in this sample dimension, or null if none. See Also: GridSampleDimension.getCategoryNames See Also: GridSampleDimension.getCategory |
getCategoryNames | public InternationalString[] getCategoryNames() throws IllegalStateException(Code) | | 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
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 usenegative or non-integer sample values. See Also: GridSampleDimension.getCategories See Also: GridSampleDimension.getCategory |
getColorInterpretation | public ColorInterpretation getColorInterpretation()(Code) | | 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 .
|
getColorModel | public ColorModel getColorModel()(Code) | | 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
GridSampleDimension instance is "geophysics", or an integer data type otherwise.
Note that
org.geotools.coverage.grid.GridCoverage2D.getSampleDimension 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 .
The requested color model, suitable for RenderedImage objects with valuesin the GridSampleDimension.getRange range. May be null if thissample dimension has no category. |
getColorModel | public ColorModel getColorModel(int visibleBand, int numBands)(Code) | | 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
GridSampleDimension instance is "geophysics", or an integer data type otherwise.
Parameters: visibleBand - The band to be made visible (usually 0). All other bands, if anywill be ignored. Parameters: numBands - The number of bands for the color model (usually 1). The returned colormodel will renderer only the visibleBand and ignore the others, butthe existence of all numBands will be at least tolerated. Supplementalbands, even invisible, are useful for processing with Java Advanced Imaging. The requested color model, suitable for RenderedImage objects with valuesin the GridSampleDimension.getRange range. May be null if thissample dimension has no category. SampleDimension SampleDimension |
getColorModel | public ColorModel getColorModel(int visibleBand, int numBands, int type)(Code) | | 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 anywill be ignored. Parameters: numBands - The number of bands for the color model (usually 1). The returned colormodel will renderer only the visibleBand and ignore the others, butthe existence of all numBands will be at least tolerated. Supplementalbands, even invisible, are useful for processing with Java Advanced Imaging. Parameters: type - The data type that has to be used for the sample model The requested color model, suitable for RenderedImage objects with valuesin the GridSampleDimension.getRange range. May be null if thissample dimension has no category. SampleDimension SampleDimension |
getDescription | public InternationalString getDescription()(Code) | | Get the sample dimension title or description.
This string may be
null if no description is present.
|
getLabel | public String getLabel(double value, Locale locale)(Code) | | 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
transformed into a geophysics value as with the
GridSampleDimension.getSampleToGeophysics()sampleToGeophysics transform, the result is formatted as a number and the unit
symbol is appened.
Parameters: value - The sample value (can be one of NaN values). Parameters: locale - Locale to use for formatting, or null for the default locale. A string representation of the geophysics value, or null if there isnone. GridSampleDimension null CategoryList |
getMaximumValue | public double getMaximumValue()(Code) | | 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 .
See Also: GridSampleDimension.getRange |
getMetaDataNames | public String[] getMetaDataNames()(Code) | | The list of metadata keywords for a sample dimension.
If no metadata is available, the sequence will be empty.
The list of metadata keywords for a sample dimension. See Also: GridSampleDimension.getMetadataValue See Also: javax.media.jai.PropertySource.getPropertyNames |
getMetadataValue | public String getMetadataValue(String name) throws MetadataNameNotFoundException(Code) | | Retrieve the metadata value for a given metadata name.
Parameters: name - Metadata keyword for which to retrieve metadata. The metadata value for a given metadata name. throws: MetadataNameNotFoundException - if there is no value for the specified metadata name. See Also: GridSampleDimension.getMetaDataNames See Also: javax.media.jai.PropertySource.getProperty |
getMinimumValue | public double getMinimumValue()(Code) | | 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 .
See Also: GridSampleDimension.getRange |
getNoDataValues | public double[] getNoDataValues() throws IllegalStateException(Code) | | 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
GridSampleDimension.getSampleToGeophysics returns
null , then
getNoDataValues() returns
null 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
GridSampleDimension.getSampleToGeophysics returns an identity transform,
then
getNoDataValues() returns
null .
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
NaN 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
NaN will be ignored.
Together with
GridSampleDimension.getOffset() and
GridSampleDimension.getScale() , this method provides a limited
way to transform sample values into geophysics values. However, the recommended way is to
use the
GridSampleDimension.getSampleToGeophysics sampleToGeophysics transform instead, which is more
general and take care of converting automatically "no data" values into
NaN .
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 ofnon-integer values. See Also: GridSampleDimension.getSampleToGeophysics |
getPaletteInterpretation | public PaletteInterpretation getPaletteInterpretation()(Code) | | 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
ColorInterpretation.GRAY_INDEX GRAY_INDEX or
ColorInterpretation.PALETTE_INDEX PALETTE_INDEX .
A palette entry type can be Gray, RGB, CMYK or HLS.
The type of color palette entry for sample dimensions which have a palette. |
getSampleDimensionType | public SampleDimensionType getSampleDimensionType()(Code) | | Returns a code value indicating grid value data type.
This will also indicate the number of bits for the data type.
a code value indicating grid value data type. |
getSampleToGeophysics | public MathTransform1D getSampleToGeophysics()(Code) | | Returns a transform from sample values to geophysics values. If this sample dimension
has no category, then this method returns
null . If all sample values are
already geophysics values (including
NaN 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 "
" into
NaN values.
The sampleToGeophysics.
transform is capable to differenciate
NaN values to get back the original
sample value.
The transform from sample to geophysics values, or null if thissample dimension do not defines any transform (which is not the same thatdefining an identity transform). See Also: GridSampleDimension.getScale See Also: GridSampleDimension.getOffset See Also: GridSampleDimension.getNoDataValues See Also: GridSampleDimension.rescale |
hashCode | public int hashCode()(Code) | | Returns a hash value for this sample dimension.
This value need not remain consistent between
different implementations of the same class.
|
toString | public String toString()(Code) | | 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.
|
wrap | public static GridSampleDimension wrap(SampleDimension sd)(Code) | | Wrap the specified OpenGIS's sample dimension into a Geotools's
implementation of
GridSampleDimension .
Parameters: sd - The sample dimension to wrap into a Geotools implementation. |
|
|