001 //$HeadURL: svn+ssh://jwilden@svn.wald.intevation.org/deegree/base/branches/2.5_testing/src/org/deegree/model/coverage/Coverage.java $
002 /*----------------------------------------------------------------------------
003 This file originated as a part of GeoAPI.
004
005 GeoAPI is free software. GeoAPI may be used, modified and
006 redistributed by anyone for any purpose requring only maintaining the
007 copyright and license terms on the source code and derivative files.
008 See the OGC legal page for details.
009
010 The copyright to the GeoAPI interfaces is held by the Open Geospatial
011 Consortium, see http://www.opengeospatial.org/ogc/legal
012 ----------------------------------------------------------------------------*/
013 package org.deegree.model.coverage;
014
015 import java.awt.image.renderable.RenderableImage;
016
017 import org.deegree.model.crs.CoordinateSystem;
018 import org.deegree.model.spatialschema.Envelope;
019
020 /**
021 * Provides access to a coverage. The essential property of coverage is to be able to generate a value for any point
022 * within its domain. How coverage is represented internally is not a concern.
023 *
024 * For example consider the following different internal representations of coverage:<br>
025 * <UL>
026 * <li>A coverage may be represented by a set of polygons which exhaustively tile a plane (that is each point on the
027 * plane falls in precisely one polygon). The value returned by the coverage for a point is the value of an attribute of
028 * the polygon that contains the point.</li>
029 * <li>A coverage may be represented by a grid of values. The value returned by the coverage for a point is that of the
030 * grid value whose location is nearest the point.</li>
031 * <li>Coverage may be represented by a mathematical function. The value returned by the coverage for a point is just
032 * the return value of the function when supplied the coordinates of the point as arguments.</li>
033 * <li>Coverage may be represented by combination of these. For example, coverage may be represented by a combination of
034 * mathematical functions valid over a set of polynomials.</LI>
035 * </UL>
036 *
037 * A coverage has a corresponding {@link SampleDimension} for each sample dimension in the coverage. <br>
038 * <br>
039 * <STRONG>Implementation note:</STRONG><BR>
040 * We expect that many implementations of {@link "org.opengis.coverage.grid.GridCoverage"} will want to leverage the
041 * rich set of <A HREF="http://java.sun.com/products/java-media/jai/">Java Advanced Imaging (JAI)</A> features. For
042 * those implementations, it is recommended (but not required) to implement the {@link javax.media.jai.PropertySource}
043 * interface as well. In this case, implementation of {@link javax.media.jai.PropertySource} methods must be consistent
044 * with {@link #getMetadataNames} and {@link #getMetadataValue} methods.
045 *
046 * @UML abstract CV_Coverage
047 * @author <A HREF="http://www.opengis.org">OpenGIS® consortium</A>
048 * @version <A HREF="http://www.opengis.org/docs/01-004.pdf">Grid Coverage specification 1.0</A>
049 *
050 * @author last edited by: $Author: mschneider $
051 *
052 * @version $Revision: 20326 $, $Date: 2009-10-22 18:41:56 +0200 (Do, 22 Okt 2009) $
053 *
054 * @see RenderableImage
055 * @see javax.media.jai.ImageFunction
056 */
057 public interface Coverage {
058 /**
059 * Specifies the coordinate reference system used when accessing a coverage or grid coverage with the
060 * <code>evaluate(...)</code> methods. It is also the coordinate reference system of the coordinates used with the
061 * math transform
062 *
063 * This coordinate reference system is usually different than coordinate system of the grid. Grid coverage can be
064 * accessed (re-projected) with new coordinate reference system with the
065 * {@link "org.opengis.coverage.processing.GridCoverageProcessor"} component. In this case, a new instance of a grid
066 * coverage is created. <br>
067 * <br>
068 * Note: If a coverage does not have an associated coordinate reference system, the returned value will be
069 * <code>null</code>.
070 *
071 * @return The coordinate reference system used when accessing a coverage or grid coverage with the
072 * <code>evaluate(...)</code> methods, or <code>null</code>.
073 * @UML mandatory coordinateSystem
074 */
075 CoordinateSystem getCoordinateReferenceSystem();
076
077 /**
078 * The bounding box for the coverage domain in {@linkplain #getCoordinateReferenceSystem coordinate reference
079 * system} coordinates. For grid coverages, the grid cells are centered on each grid coordinate. The envelope for a
080 * 2-D grid coverage includes the following corner positions.
081 *
082 * <blockquote>
083 *
084 * <pre>
085 * (Minimum row - 0.5, Minimum column - 0.5) for the minimum coordinates
086 * (Maximum row - 0.5, Maximum column - 0.5) for the maximum coordinates
087 * </pre>
088 *
089 * </blockquote>
090 *
091 * If a grid coverage does not have any associated coordinate reference system, the minimum and maximum coordinate
092 * points for the envelope will be empty sequences.
093 *
094 * @return The bounding box for the coverage domain in coordinate system coordinates.
095 * @UML mandatory envelope
096 */
097 Envelope getEnvelope();
098
099 /**
100 * The names of each dimension in the coverage. Typically these names are <var>x</var>, <var>y</var>, <var>z</var>
101 * and <var>t</var>. The number of items in the sequence is the number of dimensions in the coverage. Grid coverages
102 * are typically 2D (<var>x</var>, <var>y</var>) while other coverages may be 3D (<var>x</var>, <var>y</var>,
103 * <var>z</var>) or 4D (<var>x</var>, <var>y</var>, <var>z</var>, <var>t</var>). The number of dimensions of the
104 * coverage is the number of entries in the list of dimension names.
105 *
106 * @return The names of each dimension in the coverage.
107 * @UML mandatory dimensionNames
108 */
109 String[] getDimensionNames();
110
111 /**
112 * The number of sample dimensions in the coverage. For grid coverages, a sample dimension is a band.
113 *
114 * @return The number of sample dimensions in the coverage.
115 * @UML mandatory numSampleDimensions
116 */
117 int getNumSampleDimensions();
118
119 /**
120 * Retrieve sample dimension information for the coverage. For a grid coverage a sample dimension is a band. The
121 * sample dimension information include such things as description, data type of the value (bit, byte, integer...),
122 * the no data values, minimum and maximum values and a color table if one is associated with the dimension. A
123 * coverage must have at least one sample dimension.
124 *
125 * @param index
126 * Index for sample dimension to retrieve. Indices are numbered 0 to (<var>
127 * {@linkplain #getNumSampleDimensions n}</var>-1).
128 * @return Sample dimension information for the coverage.
129 * @throws IndexOutOfBoundsException
130 * if <code>index</code> is out of bounds.
131 * @UML operation getSampleDimension
132 */
133 SampleDimension getSampleDimension( int index )
134 throws IndexOutOfBoundsException;
135
136 /**
137 * Number of grid coverages which the grid coverage was derived from. This implementation specification does not
138 * include interfaces for creating collections of coverages therefore this value will usually be one indicating an
139 * adapted grid coverage, or zero indicating a raw grid coverage.
140 *
141 * @return The number of grid coverages which the grid coverage was derived from.
142 * @UML mandatory numSource
143 */
144 int getNumSources();
145
146 /**
147 * Returns the source data for a coverage. This is intended to allow applications to establish what
148 * <code>Coverage</code>s will be affected when others are updated, as well as to trace back to the "raw data".
149 *
150 * @param sourceDataIndex
151 * Source coverage index. Indexes start at 0.
152 * @return The source data for a coverage.
153 * @throws IndexOutOfBoundsException
154 * if <code>sourceDataIndex</code> is out of bounds.
155 * @UML operation getSource
156 *
157 * @see #getNumSources
158 * @see "org.opengis.coverage.grid.GridCoverage#getSource"
159 */
160 Coverage getSource( int sourceDataIndex )
161 throws IndexOutOfBoundsException;
162
163 /**
164 * List of metadata keywords for a coverage. If no metadata is available, the sequence will be empty.
165 *
166 * @return the list of metadata keywords for a coverage.
167 * @UML mandatory metadataNames
168 *
169 * @see #getMetadataValue
170 * @see javax.media.jai.PropertySource#getPropertyNames()
171 */
172 String[] getMetadataNames();
173
174 /**
175 * Retrieve the metadata value for a given metadata name.
176 *
177 * @param name
178 * Metadata keyword for which to retrieve data.
179 * @return the metadata value for a given metadata name.
180 * @throws MetadataNameNotFoundException
181 * if there is no value for the specified metadata name.
182 * @UML operation getMetadataValue
183 *
184 * @see #getMetadataNames
185 * @see javax.media.jai.PropertySource#getProperty
186 */
187 String getMetadataValue( String name )
188 throws MetadataNameNotFoundException;
189
190 /**
191 * Returns 2D view of this coverage as a renderable image. This optional operation allows interoperability with <A
192 * HREF="http://java.sun.com/products/java-media/2D/">Java2D</A>. If this coverage is a
193 * {@link "org.opengis.coverage.grid.GridCoverage"} backed by a {@link java.awt.image.RenderedImage}, the underlying
194 * image can be obtained with:
195 *
196 * <code>getRenderableImage(0,1).{@linkplain RenderableImage#createDefaultRendering()
197 * createDefaultRendering()}</code>
198 *
199 * @param xAxis
200 * Dimension to use for the <var>x</var> axis.
201 * @param yAxis
202 * Dimension to use for the <var>y</var> axis.
203 * @return A 2D view of this coverage as a renderable image.
204 * @throws UnsupportedOperationException
205 * if this optional operation is not supported.
206 * @throws IndexOutOfBoundsException
207 * if <code>xAxis</code> or <code>yAxis</code> is out of bounds.
208 */
209 RenderableImage getRenderableImage( int xAxis, int yAxis )
210 throws UnsupportedOperationException, IndexOutOfBoundsException;
211
212 }