org.geotoolkit.coverage
Class AbstractCoverage

Object
  PropertySourceImpl
      AbstractCoverage

All Implemented Interfaces:

Serializable, PropertySource, Localized, Coverage

Direct Known Subclasses:

AbstractGridCoverage, CoverageStack, SpatioTemporalCoverage3D, TransformedCoverage

public abstract class AbstractCoverage
extends PropertySourceImpl
implements Coverage, Localized

Base class of all coverage type. The essential property of coverage is to be able to generate a value for any point within its domain. How coverage is represented internally is not a concern. For example consider the following different internal representations of coverage:

• A coverage may be represented by a set of polygons which exhaustively tile a plane (that is each point on the plane falls in precisely one polygon). The value returned by the coverage for a point is the value of an attribute of the polygon that contains the point.
• A coverage may be represented by a grid of values. The value returned by the coverage for a point is that of the grid value whose location is nearest the point.
• Coverage may be represented by a mathematical function. The value returned by the coverage for a point is just the return value of the function when supplied the coordinates of the point as arguments.
• Coverage may be represented by combination of these. For example, coverage may be represented by a combination of mathematical functions valid over a set of polynomials.

Since:

1.2

Version:

3.00

Author:

Martin Desruisseaux (IRD)

See Also:

Serialized Form

Module:

coverage/geotk-coverage (download)

View source code for this class

Nested Class Summary

protected class

AbstractCoverage.Renderable A view of a coverage as a renderable image.

Field Summary

protected CoordinateReferenceSystem

crs The coordinate reference system, or null if there is none.

Fields inherited from class PropertySourceImpl

cachedPropertyNames, properties, propertySources

Constructor Summary

protected	AbstractCoverage(CharSequence name, CoordinateReferenceSystem crs, PropertySource propertySource, Map<?,?> properties) Constructs a coverage using the specified coordinate reference system.
protected	AbstractCoverage(CharSequence name, Coverage coverage) Constructs a new coverage with the same parameters than the specified coverage.

Method Summary

boolean	dispose(boolean force) Provides a hint that a coverage will no longer be accessed from a reference in user space.
boolean[]	evaluate(DirectPosition coord, boolean[] dest) Returns a sequence of boolean values for a given point in the coverage.
byte[]	evaluate(DirectPosition coord, byte[] dest) Returns a sequence of byte values for a given point in the coverage.
Set<Record>	evaluate(DirectPosition p, Collection<String> list) Returns a set of records of feature attribute values for the specified direct position.
double[]	evaluate(DirectPosition coord, double[] dest) Returns a sequence of double values for a given point in the coverage.
float[]	evaluate(DirectPosition coord, float[] dest) Returns a sequence of float values for a given point in the coverage.
int[]	evaluate(DirectPosition coord, int[] dest) Returns a sequence of integer values for a given point in the coverage.
Set<? extends DomainObject<?>>	evaluateInverse(Record v) Returns a set of domain objects for the specified record of feature attribute values.
GeometryValuePair	find(DirectPosition p) Returns the nearest geometry-value pair from the specified direct position.
List<? extends GeometryValuePair>	find(DirectPosition p, int limit) Returns the sequence of geometry-value pairs that include the domain objects nearest to the direct position and their distances from the direction position.
CommonPointRule	getCommonPointRule() Identifies the procedure to be used for evaluating the coverage at a position that falls either on a boundary between geometric objects or within the boundaries of two or more overlapping geometric objects.
CoordinateReferenceSystem	getCoordinateReferenceSystem() Returns the coordinate reference system to which the objects in its domain are referenced.
int	getDimension() Returns the dimension of this coverage.
Set<? extends DomainObject<?>>	getDomainElements() Returns the set of domain objects in the domain.
Set<Extent>	getDomainExtents() Returns the extent of the domain of the coverage.
Envelope	getEnvelope() Returns the bounding box for the coverage domain in coordinate reference system coordinates.
Locale	getLocale() Returns the default locale for logging, error messages, etc.
InternationalString	getName() Returns the coverage name, or null if none.
Set<AttributeValues>	getRangeElements() Returns the set of attribute values in the range.
RecordType	getRangeType() Describes the range of the coverage.
RenderableImage	getRenderableImage(int xAxis, int yAxis) Returns 2D view of this grid coverage as a renderable image.
List<? extends Coverage>	getSources() Returns the source data for a coverage.
Set<? extends GeometryValuePair>	list() Returns the dictionary of geometry-value pairs that contain the objects in the domain of the coverage each paired with its record of feature attribute values.
Set<? extends GeometryValuePair>	select(Geometry s, Period t) Returns the set of geometry-value pairs that contain domain objects that lie within the specified geometry and period.
void	show() Displays this coverage in a windows.
void	show(String title) Display this coverage in a windows.
void	show(String title, int xAxis, int yAxis) Display this coverage in a windows.
String	toString() Returns a string representation of this coverage.

Methods inherited from class PropertySourceImpl

getProperties, getProperty, getPropertyClass, getPropertyNames, getPropertyNames

Methods inherited from class Object

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

Methods inherited from interface Coverage

evaluate, getNumSampleDimensions, getSampleDimension

Field Detail

crs

protected final CoordinateReferenceSystem crs

The coordinate reference system, or null if there is none.

Constructor Detail

AbstractCoverage

protected AbstractCoverage(CharSequence name,
                           CoordinateReferenceSystem crs,
                           PropertySource propertySource,
                           Map<?,?> properties)

Constructs a coverage using the specified coordinate reference system. If the coordinate reference system is null, then the subclasses must override getDimension().

Parameters:

name - The coverage name, or null if none.

crs - The coordinate reference system. This specifies the CRS used when accessing a coverage or grid coverage with the evaluate(...) methods.

propertySource - The source for this coverage, or null if none. Source may be (but is not limited to) a PlanarImage or an other AbstractCoverage object.

properties - The set of properties for this coverage, or null if there is none. Keys are String objects (CaselessStringKey are accepted as well), while values may be any Object.

AbstractCoverage

protected AbstractCoverage(CharSequence name,
                           Coverage coverage)

Constructs a new coverage with the same parameters than the specified coverage.

Note: This constructor keeps a strong reference to the source coverage through the PropertySourceImpl super class

.

Parameters:

name - The name for this coverage, or null for the same than coverage.

coverage - The source coverage.

Method Detail

getName

public InternationalString getName()

Returns the coverage name, or null if none. The default implementation returns the name specified at construction time.

Returns:

The coverage name, or null.

getDimension

public final int getDimension()

Returns the dimension of this coverage. This is a shortcut for crs.getCoordinateSystem().getDimension().

Returns:

The dimension of this coverage.

getCoordinateReferenceSystem

public CoordinateReferenceSystem getCoordinateReferenceSystem()

Returns the coordinate reference system to which the objects in its domain are referenced. This is the CRS used when accessing a coverage or grid coverage with the evaluate(...) methods. This coordinate reference system is usually different than coordinate system of the grid. It is the target coordinate reference system of the gridToCRS math transform.

Grid coverage can be accessed (re-projected) with new coordinate reference system with the GridCoverageProcessor component. In this case, a new instance of a grid coverage is created.

Specified by:

getCoordinateReferenceSystem in interface Coverage

Returns:

The coordinate reference system used when accessing a coverage or grid coverage with the evaluate(...) methods.

See Also:

GeneralGridGeometry.getGridToCRS()

getEnvelope

public Envelope getEnvelope()

Returns the bounding box for the coverage domain in coordinate reference system coordinates. May be null if this coverage has no associated coordinate reference system. For grid coverages, the grid cells are centered on each grid coordinate. The envelope for a 2-D grid coverage includes the following corner positions.

(Minimum row - 0.5, Minimum column - 0.5) for the minimum coordinates
(Maximum row - 0.5, Maximum column - 0.5) for the maximum coordinates

The default implementation returns the domain of validity of the CRS, if there is one.

Specified by:

getEnvelope in interface Coverage

Returns:

The bounding box for the coverage domain in coordinate system coordinates.

getDomainExtents

public Set<Extent> getDomainExtents()

Returns the extent of the domain of the coverage. Extents may be specified in space, time or space-time. The collection must contains at least one element.

This method is not yet implemented.

Specified by:

getDomainExtents in interface Coverage

Since:

2.3

TODO:

Proposed default implementation: invokes getEnvelope(), extract the spatial and temporal parts and put them in a Extent object.

getDomainElements

public Set<? extends DomainObject<?>> getDomainElements()

Returns the set of domain objects in the domain. The collection must contains at least one element.

This method is not yet implemented.

Specified by:

getDomainElements in interface Coverage

Since:

2.3

TODO:

Proposed default implementation: invokes getEnvelope(), extract the spatial and temporal parts, get the grid geometry and create on-the-fly a DomainObject for each cell.

getRangeElements

public Set<AttributeValues> getRangeElements()

Returns the set of attribute values in the range. The range of a coverage shall be a homogeneous collection of records. That is, the range shall have a constant dimension over the entire domain, and each field of the record shall provide a value of the same attribute type over the entire domain.

In the case of a discrete coverage, the size of the range collection equals that of the domains collection. In other words, there is one instance of AttributeValues for each instance of DomainObject. Usually, these are stored values that are accessed by the evaluate operation.

In the case of a continuous coverage, there is a transfinite number of instances of AttributeValues for each DomainObject. A few instances may be stored as input for the evaluate operation, but most are generated as needed by that operation.

NOTE: ISO 19123 does not specify how the domain and range associations are to be implemented. The relevant data may be generated in real time, it may be held in persistent local storage, or it may be electronically accessible from remote locations.

This method is not yet implemented.

Specified by:

getRangeElements in interface Coverage

Since:

2.3

getRangeType

public RecordType getRangeType()

Describes the range of the coverage. It consists of a list of attribute name/data type pairs. A simple list is the most common form of range type, but RecordType can be used recursively to describe more complex structures. The range type for a specific coverage shall be specified in an application schema.

This method is not yet implemented.

Specified by:

getRangeType in interface Coverage

Since:

2.3

getCommonPointRule

public CommonPointRule getCommonPointRule()

Identifies the procedure to be used for evaluating the coverage at a position that falls either on a boundary between geometric objects or within the boundaries of two or more overlapping geometric objects. The geometric objects are either domain objects or value objects.

This method is not yet implemented.

Specified by:

getCommonPointRule in interface Coverage

Since:

2.3

list

public Set<? extends GeometryValuePair> list()

Returns the dictionary of geometry-value pairs that contain the objects in the domain of the coverage each paired with its record of feature attribute values. In the case of an analytical coverage, the operation shall return the empty set.

This method is not yet implemented.

Specified by:

list in interface Coverage

Since:

2.3

select

public Set<? extends GeometryValuePair> select(Geometry s,
                                               Period t)

Returns the set of geometry-value pairs that contain domain objects that lie within the specified geometry and period. If s is null, the operation shall return all geometry-value pairs that contain domain objects within t. If the value of t is null, the operation shall return all geometry-value pair that contain domain objects within s. In the case of an analytical coverage, the operation shall return the empty set.

This method is not yet implemented.

Specified by:

select in interface Coverage

Since:

2.3

find

public List<? extends GeometryValuePair> find(DirectPosition p,
                                              int limit)

Returns the sequence of geometry-value pairs that include the domain objects nearest to the direct position and their distances from the direction position. The sequence shall be ordered by distance from the direct position, beginning with the record containing the domain object nearest to the direct position. The length of the sequence (the number of geometry-value pairs returned) shall be no greater than the number specified by the parameter limit. The default shall be to return a single geometry-value pair. The operation shall return a warning if the last domain object in the sequence is at a distance from the direct position equal to the distance of other domain objects that are not included in the sequence. In the case of an analytical coverage, the operation shall return the empty set.

NOTE: This operation is useful when the domain of a coverage does not exhaustively partition the extent of the coverage. Even in that case, the first element of the sequence returned may be the geometry-value pair that contains the input direct position.

This method is not yet implemented.

Specified by:

find in interface Coverage

Since:

2.3

find

public GeometryValuePair find(DirectPosition p)

Returns the nearest geometry-value pair from the specified direct position. This is a shortcut for find(p,1).

Specified by:

find in interface Coverage

Since:

2.3

evaluate

public Set<Record> evaluate(DirectPosition p,
                            Collection<String> list)

Returns a set of records of feature attribute values for the specified direct position. The parameter list is a sequence of feature attribute names each of which identifies a field of the range type. If list is null, the operation shall return a value for every field of the range type. Otherwise, it shall return a value for each field included in list. If the direct position passed is not in the domain of the coverage, then an exception is thrown. If the input direct position falls within two or more geometric objects within the domain, the operation shall return records of feature attribute values computed according to the common point rule.

NOTE: Normally, the operation will return a single record of feature attribute values.

This method is not yet implemented.

Specified by:

evaluate in interface Coverage

Since:

2.3

evaluate

public boolean[] evaluate(DirectPosition coord,
                          boolean[] dest)
                   throws PointOutsideCoverageException,
                          CannotEvaluateException

Returns a sequence of boolean values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor, but it can be changed by some subclasses. The CRS of the point is the same as the grid coverage coordinate reference system.

Specified by:

evaluate in interface Coverage

Parameters:

coord - The coordinate point where to evaluate.

dest - An array in which to store values, or null to create a new array.

Returns:

The dest array, or a newly created array if dest was null.

Throws:

PointOutsideCoverageException - if the evaluation failed because the input point has invalid coordinates.

CannotEvaluateException - if the values can't be computed at the specified coordinate for an other reason. It may be thrown if the coverage data type can't be converted to boolean by an identity or widening conversion. Subclasses may relax this constraint if appropriate.

evaluate

public byte[] evaluate(DirectPosition coord,
                       byte[] dest)
                throws PointOutsideCoverageException,
                       CannotEvaluateException

Returns a sequence of byte values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor, but it can be changed by some subclasses. The CRS of the point is the same as the grid coverage coordinate reference system.

Specified by:

evaluate in interface Coverage

Parameters:

coord - The coordinate point where to evaluate.

dest - An array in which to store values, or null to create a new array.

Returns:

The dest array, or a newly created array if dest was null.

Throws:

PointOutsideCoverageException - if the evaluation failed because the input point has invalid coordinates.

CannotEvaluateException - if the values can't be computed at the specified coordinate for an other reason. It may be thrown if the coverage data type can't be converted to byte by an identity or widening conversion. Subclasses may relax this constraint if appropriate.

evaluate

public int[] evaluate(DirectPosition coord,
                      int[] dest)
               throws PointOutsideCoverageException,
                      CannotEvaluateException

Returns a sequence of integer values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor, but it can be changed by some subclasses. The CRS of the point is the same as the grid coverage coordinate reference system.

Specified by:

evaluate in interface Coverage

Parameters:

coord - The coordinate point where to evaluate.

dest - An array in which to store values, or null to create a new array.

Returns:

The dest array, or a newly created array if dest was null.

Throws:

PointOutsideCoverageException - if the evaluation failed because the input point has invalid coordinates.

CannotEvaluateException - if the values can't be computed at the specified coordinate for an other reason. It may be thrown if the coverage data type can't be converted to int by an identity or widening conversion. Subclasses may relax this constraint if appropriate.

evaluate

public float[] evaluate(DirectPosition coord,
                        float[] dest)
                 throws PointOutsideCoverageException,
                        CannotEvaluateException

Returns a sequence of float values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor, but it can be changed by some subclasses. The CRS of the point is the same as the grid coverage coordinate reference system.

Specified by:

evaluate in interface Coverage

Parameters:

coord - The coordinate point where to evaluate.

dest - An array in which to store values, or null to create a new array.

Returns:

The dest array, or a newly created array if dest was null.

Throws:

PointOutsideCoverageException - if the evaluation failed because the input point has invalid coordinates.

CannotEvaluateException - if the values can't be computed at the specified coordinate for an other reason. It may be thrown if the coverage data type can't be converted to float by an identity or widening conversion. Subclasses may relax this constraint if appropriate.

evaluate

public double[] evaluate(DirectPosition coord,
                         double[] dest)
                  throws PointOutsideCoverageException,
                         CannotEvaluateException

Returns a sequence of double values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor, but it can be changed by some subclasses. The CRS of the point is the same as the grid coverage coordinate reference system.

Specified by:

evaluate in interface Coverage

Parameters:

coord - The coordinate point where to evaluate.

dest - An array in which to store values, or null to create a new array.

Returns:

The dest array, or a newly created array if dest was null.

Throws:

PointOutsideCoverageException - if the evaluation failed because the input point has invalid coordinates.

CannotEvaluateException - if the values can't be computed at the specified coordinate for an other reason. It may be thrown if the coverage data type can't be converted to double by an identity or widening conversion. Subclasses may relax this constraint if appropriate.

evaluateInverse

public Set<? extends DomainObject<?>> evaluateInverse(Record v)

Returns a set of domain objects for the specified record of feature attribute values. Normally, this method returns the set of objects in the domain that are associated with values equal to those in the input record. However, the operation may return other objects derived from those in the domain, as specified by the application schema.

Example: The evaluateInverse operation could return a set of contours derived from the feature attribute values associated with the grid points of a grid coverage.

This method is not yet implemented.

Specified by:

evaluateInverse in interface Coverage

Since:

2.3

getRenderableImage

public RenderableImage getRenderableImage(int xAxis,
                                          int yAxis)

Returns 2D view of this grid coverage as a renderable image. This method allows inter-operability with Java2D.

Specified by:

getRenderableImage in interface Coverage

Parameters:

xAxis - Dimension to use for the x display axis.

yAxis - Dimension to use for the y display axis.

Returns:

A 2D view of this grid coverage as a renderable image.

show

@Debug
public void show(String title,
                       int xAxis,
                       int yAxis)

Display this coverage in a windows. This convenience method is used for debugging purpose. The exact appareance of the windows and the tools provided may changes in future versions.

Parameters:

title - The window title, or null for default value.

xAxis - Dimension to use for the x display axis.

yAxis - Dimension to use for the y display axis.

Since:

2.3

show

@Debug
public void show(String title)

Display this coverage in a windows. This convenience method is used for debugging purpose. The exact appareance of the windows and the tools provided may changes in future versions.

Parameters:

title - The window title, or null for default value.

Since:

2.3

show

@Debug
public void show()

Displays this coverage in a windows. This convenience method is used for debugging purpose. The exact appareance of the windows and the tools provided may changes in future versions.

getSources

public List<? extends Coverage> getSources()

Returns the source data for a coverage. The default implementation returns an empty list.

Specified by:

getSources in interface Coverage

getLocale

public Locale getLocale()

Returns the default locale for logging, error messages, etc.

Specified by:

getLocale in interface Localized

Returns:

The default locale for logging and error message.

toString

public String toString()

Returns a string representation of this coverage. This string is for debugging purpose only and may change in future version.

Overrides:

toString in class Object

dispose

public boolean dispose(boolean force)

Provides a hint that a coverage will no longer be accessed from a reference in user space. This can be used as a hint in situations where waiting for garbage collection would be overly conservative. The results of referencing a coverage after a call to dispose are undefined, except if this method returned false.

This method can work in a conservative mode or a forced mode, determined by the force argument:

• If force is false (the recommended value), this method may process only under some conditions. For example a grid coverage may dispose its planar image only if it has no sinks. This method returns true if it disposed all resources, or false if this method vetoed against the disposal. In the later case, this coverage can still be used.

• If force is true, then this method processes inconditionnally and returns always true. This is a more risky behavior.

The conservative mode (force = false) performs its safety checks on a best-effort basis, with no guarantees. Therefore, it would be wrong to write a program that depended on the safety checks for its correctness. In case of doubt about whatever this coverage still in use or not, it is safer to rely on the garbage collector.

Parameters:

force - true for forcing an inconditionnal disposal, or false for performing a conservative disposal. The recommended value is false.

Returns:

true if this method disposed at least some resources, or false if this method vetoed against the disposal.

Since:

2.4

See Also:

PlanarImage.dispose()