org.geotoolkit.coverage.io
Class GridCoverageStoreParam

Object
  GridCoverageStoreParam

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

GridCoverageReadParam, GridCoverageWriteParam

public abstract class GridCoverageStoreParam
extends Object
implements Serializable

Base class for GridCoverageReadParam and GridCoverageWriteParam. This class defines which part of the source (a stream when reading, or a coverage when writing) shall be transfered to the destination (a coverage when reading, or a stream when writing).

Note: This class is conceptually equivalent to the IIOParam class provided in the standard Java library. The main difference is that GridCoverageStoreParam works with geodetic coordinates while IIOParam works with pixel coordinates.

Since:

3.14 (derived from 3.09)

Version:

3.15

Author:

Johann Sorel (Geomatys), Martin Desruisseaux (Geomatys)

See Also:

IIOParam, Serialized Form

Module:

coverage/geotk-coverageio (download)

View source code for this class

Constructor Summary

protected	GridCoverageStoreParam() Creates a new GridCoverageStoreParam instance.
protected	GridCoverageStoreParam(GridCoverageStoreParam param) Creates a new GridCoverageStoreParam instance initialized to the same values than the given parameters.

Method Summary

void	clear() Resets all parameters to their null value.
CoordinateReferenceSystem	getCoordinateReferenceSystem() Returns the CRS of the envelope and resolution parameters, or null if unspecified.
Envelope	getEnvelope() Returns the maximal extent of the region to read from the source, or null if unspecified.
double[]	getResolution() Returns the resolution to read from the source, or null if unspecified.
int[]	getSourceBands() Returns the set of source bands to read, or null for all of them.
void	setCoordinateReferenceSystem(CoordinateReferenceSystem crs) Sets the CRS of the envelope and resolution parameters.
void	setEnvelope(Envelope envelope) Sets the maximal extent of the region to read from the source.
void	setEnvelope(Rectangle2D bounds, CoordinateReferenceSystem crs) Sets the maximal extent of the region to read from the source.
void	setResolution(double... resolution) Sets the resolution to read from the source.
void	setSourceBands(int... bands) Sets the indices of the source bands to read.
String	toString() Returns a string representation of this object for debugging purpose.

Methods inherited from class Object

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

Constructor Detail

GridCoverageStoreParam

protected GridCoverageStoreParam()

Creates a new GridCoverageStoreParam instance. All properties are initialized to null. Callers must invoke setter methods in order to provide information about the way to decode or encode the stream.

GridCoverageStoreParam

protected GridCoverageStoreParam(GridCoverageStoreParam param)

Creates a new GridCoverageStoreParam instance initialized to the same values than the given parameters.

Parameters:

param - The parameters to copy, or null if none.

Since:

3.15

Method Detail

clear

public void clear()

Resets all parameters to their null value.

getCoordinateReferenceSystem

public CoordinateReferenceSystem getCoordinateReferenceSystem()

Returns the CRS of the envelope and resolution parameters, or null if unspecified.

Returns:

The CRS of the envelope and resolution parameters, or null.

setCoordinateReferenceSystem

public void setCoordinateReferenceSystem(CoordinateReferenceSystem crs)
                                  throws MismatchedReferenceSystemException,
                                         MismatchedDimensionException

Sets the CRS of the envelope and resolution parameters. If the envelope parameter is already defined with a different CRS, then this method throws a MismatchedReferenceSystemException.

Parameters:

crs - The new CRS for the envelope and resolution parameters.

Throws:

MismatchedReferenceSystemException - If the envelope parameter is already defined with a different CRS.

MismatchedDimensionException - If the resolution parameter is already defined with a different dimension.

getEnvelope

public Envelope getEnvelope()

Returns the maximal extent of the region to read from the source, or null if unspecified. If the envelope CRS is not equals to the native CRS of the grid coverage to be read or written, then the envelope will be transformed to the later CRS at reading or writing time.

Returns:

The region to read from the stream, or null if unspecified.

See Also:

IIOParam.getSourceRegion()

setEnvelope

public void setEnvelope(Envelope envelope)
                 throws IllegalArgumentException

Sets the maximal extent of the region to read from the source. The actual envelope of the destination (the coverage returned by GridCoverageReader, or the coverage in the file written by GridCoverageWriter) may be smaller if the coverage available in the source does not fill completely the given envelope.

The envelope can be specified in any Coordinate Reference System, unless the CRS has been restricted by a call to the setCoordinateReferenceSystem method. The envelope CRS is honored as below:

• At reading time: GridCoverageReader may return a coverage in that CRS if it can do that cheaply (for example if the backing store already contains the same coverage in different CRS), or return the coverage in its native CRS otherwise, at implementation choice. Callers should check the CRS of the returned coverage.

• At writing time: GridCoverageWriter will reproject the coverage to that CRS, if needed. If the file format does not support that CRS, then an exception will be thrown.

If the envelope is set to null, then GridCoverageStore will read the full coverage extent in its native CRS.

Parameters:

envelope - The region to read from the source, or null.

Throws:

MismatchedReferenceSystemException - If the given CRS is not equal (ignoring metadata) to the CRS defined by the last call to setCoordinateReferenceSystem.

MismatchedDimensionException - If the dimension of the given envelope is not equal to the resolution dimension.

IllegalArgumentException - If the given envelope is illegal for an other reason.

See Also:

IIOParam.setSourceRegion(Rectangle)

setEnvelope

public void setEnvelope(Rectangle2D bounds,
                        CoordinateReferenceSystem crs)
                 throws MismatchedReferenceSystemException,
                        MismatchedDimensionException

Sets the maximal extent of the region to read from the source. This convenience method performs the same work than setEnvelope(Envelope), except that the envelope is created from the given rectangle and two-dimensional coordinate reference system.

Parameters:

bounds - The region to read from the source, or null.

crs - The two-dimensional coordinate reference system of the region.

Throws:

MismatchedReferenceSystemException - If the given CRS is not equal (ignoring metadata) to the CRS defined by the last call to setCoordinateReferenceSystem.

MismatchedDimensionException - If dimension of the current resolution is different than 2.

Since:

3.10

See Also:

IIOParam.setSourceRegion(Rectangle)

getResolution

public double[] getResolution()

Returns the resolution to read from the source, or null if unspecified. The resolution shall be specified in the same Coordinate Reference System than the envelope CRS. This implies that the length of the returned array must match the envelope dimension.

Returns:

The resolution to read from the stream, or null if unspecified.

See Also:

IIOParam.getSourceXSubsampling(), IIOParam.getSourceYSubsampling()

setResolution

public void setResolution(double... resolution)
                   throws MismatchedDimensionException

Sets the resolution to read from the source. The resolution shall be specified in the same Coordinate Reference System than the envelope CRS.

The resolution is honored as below:

• At reading time: If the given resolution does not match a resolution that GridCoverageReader can read, then GridCoverageReader while use the largest resolution values which are equal or smaller (finer) than the given arguments. If no available resolutions are equal or finer than the given ones, then GridCoverageReader will use the finest resolution available.

• At writing time: GridCoverageWriter will resample the coverage to that resolution, if needed. If the file format does not support that resolution, then an exception will be thrown.

If the dimension is set to null, then GridCoverageStore will read the coverage with the best resolution available.

Parameters:

resolution - The new resolution to read from the source, or null.

Throws:

MismatchedDimensionException - If the dimension of the given resolution is not equal to the envelope dimension.

See Also:

IIOParam.setSourceSubsampling(int, int, int, int)

getSourceBands

public int[] getSourceBands()

Returns the set of source bands to read, or null for all of them.

Returns:

The set of source bands to read, or null for all of them.

Since:

3.10

See Also:

IIOParam.getSourceBands()

setSourceBands

public void setSourceBands(int... bands)
                    throws IllegalArgumentException

Sets the indices of the source bands to read. A null value indicates that all source bands will be read.

At the time of reading or writing, an IllegalArgumentException will be thrown by the reader or writer if a value larger than the largest available source band index has been specified or if the number of source bands and destination bands to be used differ.

Parameters:

bands - The source bands to read, or null.

Throws:

IllegalArgumentException - If the given array is empty, or if it contains duplicated or negative values.

Since:

3.10

See Also:

IIOParam.setSourceBands(int[])

toString

public String toString()

Returns a string representation of this object for debugging purpose. The content of the returned string may change in any future version.

Overrides:

toString in class Object