org.geotoolkit.image.io
Class SpatialImageReadParam

Object
  IIOParam
      ImageReadParam
          SpatialImageReadParam

All Implemented Interfaces:

Localized, WarningProducer

public class SpatialImageReadParam
extends ImageReadParam
implements WarningProducer

Default parameters for SpatialImageReader. This class extends the standard ImageReadParam class with the following additional capabilities:

• Specify the plane to read in datasets having more than 2 dimensions, as for example in NetCDF files.

• Specify the name of a color palette. This is useful when reading an image from a file that doesn't contain such information, for example ASCII grid.

• For images having more than one band where the bands are not color components, specify which band to use with the Index Color Model. For example an image may contain Sea Surface Temperature (SST) measurements in the first band, and an estimation of the measurement errors in the second band. Users may want to read both bands for computation purpose, while applying a color palette using only the values in the first band.

Handling more than two dimensions
Some file formats like NetCDF can store dataset having more than two dimensions. Geotk handles the supplemental dimensions with the following policies by default:

1. The two first dimensions - typically named (x, y) - are assigned to the (columns, rows) pixel indices.

2. An additional dimension can optionally be assigned to band indices. This is typically the altitude (z) in a dataset having the (x, y, z, t) dimensions, but can be customized. The actual dimension assigned to band indices is returned by DimensionIdentification.findDimensionIndex(Iterable). See MultidimensionalImageStore for more information.

3. An additional dimension can optionally be assigned to image index. This is typically the time (t) in a dataset having the (x, y, z, t) dimensions, but can be customized. See MultidimensionalImageStore for more information.

4. Only one slice of every supplemental dimensions can be read. By default the data at index 0 are loaded, but different indices can be selected (see DimensionSlice). The actual index used is the value returned by getSliceIndex(Object[]).

Since:

3.05 (derived from 2.4)

Version:

3.20

Author:

Martin Desruisseaux (Geomatys)

Module:

coverage/geotk-coverageio (download)

View source code for this class

Field Summary

static String	DEFAULT_PALETTE_NAME The name of the default color palette to apply when none was explicitly specified.
protected ImageReader	reader The image reader for which this SpatialImageReadParam instance has been created, or null if unknown.

Fields inherited from class ImageReadParam

canSetSourceRenderSize, destination, destinationBands, minProgressivePass, numProgressivePasses, sourceRenderSize

Fields inherited from class IIOParam

controller, defaultController, destinationOffset, destinationType, sourceBands, sourceRegion, sourceXSubsampling, sourceYSubsampling, subsamplingXOffset, subsamplingYOffset

Fields inherited from interface WarningProducer

LOGGER

Constructor Summary

SpatialImageReadParam(ImageReader reader)
Creates a new, initially empty, set of parameters.

Method Summary

DimensionSlice	getDimensionSlice(Object... dimensionIds) Returns the dimension slice identified by at least one of the given identifiers.
Set<DimensionSlice>	getDimensionSlices() Returns all DimensionSlice instances known to this parameters block.
Locale	getLocale() Returns the locale used for formatting error messages, or null if none.
PaletteFactory	getPaletteFactory() Returns the palette factory to use for creating a color model from the palette name.
String	getPaletteName() Returns the name of the color palette to apply when creating an index color model.
List<SampleDomain>	getSampleDomains() Returns the range of valid values together with the fill values, or null if unspecified.
int	getSliceIndex(Object... dimensionIds) Returns the index of the slice in the dimension identified by at least one of the given identifiers.
int	getVisibleBand() Returns the band to display in the target image.
boolean	hasDimensionSlices() Returns true if the parameters contain at least one DimensionSlice.
boolean	isSampleConversionAllowed(SampleConversionType type) Returns true if the given kind of sample conversions is allowed.
DimensionSlice	newDimensionSlice() Creates a new handler for selecting a slice of the (x, y) plane to read.
void	setPaletteFactory(PaletteFactory factory) Sets the palette factory to use for creating a color model from the palette name.
void	setPaletteName(String palette) Sets the color palette as one of the available names provided by the default palette factory.
void	setSampleConversionAllowed(SampleConversionType type, boolean allowed) Sets whatever the given kind of sample conversions is allowed.
void	setSampleDomains(List<SampleDomain> domains) Sets the range of valid values and fill values to use for creating a color model.
void	setVisibleBand(int visibleBand) Sets the band to make visible in the destination image.
String	toString() Returns a string representation of this block of parameters.
boolean	warningOccurred(LogRecord record) Invoked when a warning occurred.

Methods inherited from class ImageReadParam

canSetSourceRenderSize, getDestination, getDestinationBands, getSourceMaxProgressivePass, getSourceMinProgressivePass, getSourceNumProgressivePasses, getSourceRenderSize, setDestination, setDestinationBands, setDestinationType, setSourceProgressivePasses, setSourceRenderSize

Methods inherited from class IIOParam

activateController, getController, getDefaultController, getDestinationOffset, getDestinationType, getSourceBands, getSourceRegion, getSourceXSubsampling, getSourceYSubsampling, getSubsamplingXOffset, getSubsamplingYOffset, hasController, setController, setDestinationOffset, setSourceBands, setSourceRegion, setSourceSubsampling

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_PALETTE_NAME

public static final String DEFAULT_PALETTE_NAME

The name of the default color palette to apply when none was explicitly specified. The default palette is "grayscale".

See Also:

getPaletteName(), setPaletteName(String), Constant Field Values

reader

protected final ImageReader reader

The image reader for which this SpatialImageReadParam instance has been created, or null if unknown.

Since:

3.15

Constructor Detail

SpatialImageReadParam

public SpatialImageReadParam(ImageReader reader)

Creates a new, initially empty, set of parameters.

Parameters:

reader - The reader for which this parameter block is created, or null.

Method Detail

hasDimensionSlices

public boolean hasDimensionSlices()

Returns true if the parameters contain at least one DimensionSlice. Invoking this method is equivalent to testing !getDimensionSlices().isEmpty().

Returns:

If the parameters contain at least one dimension slice.

Since:

3.21

newDimensionSlice

public DimensionSlice newDimensionSlice()

Creates a new handler for selecting a slice of the (x, y) plane to read. This is relevant only for n-dimensional dataset where n>2. The caller should invoke one or many addDimensionId(...) methods for specifying the dimension, and invoke DimensionSlice.setSliceIndex(int) for specifying the index of the slice point (WMS 2.0 terminology).

A new handler can be created for each supplemental dimension above the two (x, y) dimensions and the bands handled by Java2D. If no slice is specified for a supplemental dimension, then the default is the slice at index 0.

Returns:

A new handler for specifying the index of the slice to read in a supplemental dimension.

Since:

3.08

getDimensionSlices

public Set<DimensionSlice> getDimensionSlices()

Returns all DimensionSlice instances known to this parameters block. They are the instances created by newDimensionSlice() and for which at least one identifier has been added.

The returned collection is live: if new dimension slices are created, they will appear dynamically in the returned set.

Returns:

The dimensions registered in this parameters, or an empty set if none.

Since:

3.08

getDimensionSlice

public DimensionSlice getDimensionSlice(Object... dimensionIds)

Returns the dimension slice identified by at least one of the given identifiers. This is relevant mostly for n-dimensional dataset where n>2. The dimension can be identified by a zero-based index as an Integer, a dimension name as a String, or an axis direction as an AxisDirection. More than one identifier can be specified in order to increase the chance to get the index, for example:

DimensionSlice slice = getDimensionSlice("time", AxisDirection.FUTURE);

If different slices are found for the given identifiers, then a warning is emitted and this method returns the first slice matching the given identifiers. If no slice is found, null is returned.

Parameters:

dimensionIds - Integer, String or AxisDirection that identify the dimension for which the slice is desired.

Returns:

The first slice found for the given dimension identifiers, or null if none.

Since:

3.08

getSliceIndex

public int getSliceIndex(Object... dimensionIds)

Returns the index of the slice in the dimension identified by at least one of the given identifiers. This method is equivalent to the code below, except that a warning is emitted only if index values are ambiguous:

DimensionSlice slice = getDimensionSlice(dimensionIds);
return (slice != null) ? slice.getSliceIndex() : 0;

This method is relevant mostly for n-dimensional dataset where n>2. The dimension can be identified by a zero-based index as an Integer, a dimension name as a String, or an axis direction as an AxisDirection. More than one identifier can be specified in order to increase the chance to get the index, for example:

int index = getSliceIndex("time", AxisDirection.FUTURE);

If different indices are found for the given identifiers, then a warning is emitted and this method returns the index for the first slice matching the given identifiers. If no index is found, 0 (which is the default index value) is returned.

Parameters:

dimensionIds - Integer, String or AxisDirection that identify the dimension for which the index is desired.

Returns:

The index set in the first slice found for the given dimension identifiers, or 0 if none.

Since:

3.08

See Also:

DimensionSlice.getSliceIndex()

getVisibleBand

public int getVisibleBand()

Returns the band to display in the target image. In theory, images backed by index color model should have only one band. But sometime we want to load additional bands as numerical data, in order to perform computations. In such case, we need to specify which band in the destination image will be used as an index for displaying the colors. The default value is 0.

Returns:

The band to display in the target image.

setVisibleBand

public void setVisibleBand(int visibleBand)
                    throws IllegalArgumentException

Sets the band to make visible in the destination image.

Parameters:

visibleBand - The band to make visible.

Throws:

IllegalArgumentException - if the specified band index is invalid.

getPaletteName

public String getPaletteName()

Returns the name of the color palette to apply when creating an index color model. This is the name specified by the last call to setPaletteName(String).

For a table of available palette names in the default Geotk installation, see the PaletteFactory class javadoc.

Returns:

The name of the color palette to apply, or null if none.

See Also:

SpatialImageReader.hasColors(int)

setPaletteName

public void setPaletteName(String palette)

Sets the color palette as one of the available names provided by the default palette factory. This name will be given by the SpatialImageReader default implementation to the default palette factory for creating a image type specifier.

Note: This method is useful with image formats that don't store any color information in the file. If the image format provides its own color palette (as in PNG of JPEG formats), then the palette name given to this method may be ignored. The SpatialImageReader.hasColors(int) method can be invoked in order to check if the image file provides its own color palette.

For a table of available palette names in the default Geotk installation, see the PaletteFactory class javadoc.

Parameters:

palette - The name of the color palette to apply.

See Also:

SpatialImageReader.hasColors(int), PaletteFactory.getAvailableNames()

getPaletteFactory

public PaletteFactory getPaletteFactory()

Returns the palette factory to use for creating a color model from the palette name. This method is invoked by the SpatialImageReader.getImageType method after it has determined the range of sample values from the image metadata. The returned factory may be used in various way, but the following pseudo-code can be considered typical:

public ImageTypeSpecifier getImageType(int imageIndex, ImageReadParam param, ...) {
    SpatialMetadata md = getImageMetadata(imageIndex);
    // ... process metadata
    return param.getPaletteFactory().getPalette(param.getPaletteName(),
            lower, upper, size, numBands, visibleBand);
}

Returns:

The palette factory that the SpatialImageReader.getImageType method shall use for creating a color model from the palette name, or null for the default factory.

Since:

3.11

setPaletteFactory

public void setPaletteFactory(PaletteFactory factory)

Sets the palette factory to use for creating a color model from the palette name.

Parameters:

factory - The new factory, or null for the default factory.

Since:

3.11

getSampleDomains

public List<SampleDomain> getSampleDomains()

Returns the range of valid values together with the fill values, or null if unspecified. If non-null, then SpatialImageReader will use this information for creating the image color model as documented in the getPaletteFactory() method.

This property is typically null, either because the color model is specified by the image format, or because the range of valid values is extracted from the image metadata.

If non-null, then the size of this list shall be equals to the number of source bands. The SampleDomain at index i is for the band at index sourceBands[i] in the stream.

Returns:

The range of valid values and the fill values for each band to be read, or null if unspecified.

Since:

3.12

setSampleDomains

public void setSampleDomains(List<SampleDomain> domains)

Sets the range of valid values and fill values to use for creating a color model. It is typically not necessary to set this property, since those information are extracted from the image metadata by default. However it may be useful to set the range and the fill values explicitly if the image to be read is known to have missing or incomplete metadata. This is the case for example of NetCDF files not conform to the CF conventions.

If this method is invoked with a non-null value, then the size of the given list shall be equals to the number of source bands. The SampleDomain at index i is for the band at index sourceBands[i] in the stream. The range and fill values in the given SampleDomains while have precedence over any value declared in the image metadata.

Parameters:

domains - The range of valid values and the fill values for each band to be read, or null for letting the reader infers them from the image metadata.

Since:

3.12

isSampleConversionAllowed

public boolean isSampleConversionAllowed(SampleConversionType type)

Returns true if the given kind of sample conversions is allowed. By default, newly constructed SpatialImageReadParam instances return false for any given type (i.e. SpatialImageReader will make its best effort for storing the sample values with no change). However more efficient storage can be achieved if some changes are allowed on the sample values. See setSampleConversionAllowed for examples.

Parameters:

type - The kind of conversion.

Returns:

Whatever the given kind of conversion is allowed.

Since:

3.11

setSampleConversionAllowed

public void setSampleConversionAllowed(SampleConversionType type,
                                       boolean allowed)

Sets whatever the given kind of sample conversions is allowed. By default, the false value is assigned to all conversion types (i.e. SpatialImageReader will make its best effort for storing the sample values with no change). However more efficient storage can be achieved if some changes are allowed on the sample values, for example adding an offset to signed integers in order to ensure that all values are positive.

Parameters:

type - The kind of conversion.

allowed - Whatever the given kind of conversion is allowed.

Since:

3.11

getLocale

public Locale getLocale()

Returns the locale used for formatting error messages, or null if none. The default implementation returns the locale used by the ImageReader given at construction time, or null if none.

Specified by:

getLocale in interface Localized

Returns:

The locale, or null if not explicitly defined.

warningOccurred

public boolean warningOccurred(LogRecord record)

Invoked when a warning occurred. The default implementation forwards the warning to the image reader given at construction time if possible, or logs the warning otherwise.

Specified by:

warningOccurred in interface WarningProducer

Parameters:

record - The warning that occurred.

Returns:

true if the message has been sent to at least one warning listener, or false if it has been sent to the logging system as a fallback.

Since:

3.08

toString

public String toString()

Returns a string representation of this block of parameters. The default implementation formats the source region, subsampling values, source bands, destination offset and the color palette on a single line, completed by the list of dimension slices (if any) on the next lines.

Overrides:

toString in class Object