001: //$HeadURL: https://svn.wald.intevation.org/svn/deegree/base/trunk/src/org/deegree/model/coverage/Coverage.java $
002: /*---------------- FILE HEADER ------------------------------------------
003:
004: This file is part of deegree.
005: Copyright (C) 2001-2008 by:
006: EXSE, Department of Geography, University of Bonn
007: http://www.giub.uni-bonn.de/deegree/
008: lat/lon GmbH
009: http://www.lat-lon.de
010:
011: This library is free software; you can redistribute it and/or
012: modify it under the terms of the GNU Lesser General Public
013: License as published by the Free Software Foundation; either
014: version 2.1 of the License, or (at your option) any later version.
015:
016: This library is distributed in the hope that it will be useful,
017: but WITHOUT ANY WARRANTY; without even the implied warranty of
018: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
019: Lesser General Public License for more details.
020:
021: You should have received a copy of the GNU Lesser General Public
022: License along with this library; if not, write to the Free Software
023: Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
024:
025: Contact:
026:
027: Andreas Poth
028: lat/lon GmbH
029: Aennchenstr. 19
030: 53115 Bonn
031: Germany
032: E-Mail: poth@lat-lon.de
033:
034: Prof. Dr. Klaus Greve
035: Department of Geography
036: University of Bonn
037: Meckenheimer Allee 166
038: 53115 Bonn
039: Germany
040: E-Mail: greve@giub.uni-bonn.de
041:
042:
043: ---------------------------------------------------------------------------*/
044: package org.deegree.model.coverage;
045:
046: import java.awt.image.renderable.RenderableImage;
047:
048: import org.deegree.model.crs.CoordinateSystem;
049: import org.opengis.pt.PT_Envelope;
050:
051: /**
052: * Provides access to a coverage. The essential property of coverage is to be able to generate a
053: * value for any point within its domain. How coverage is represented internally is not a concern.
054: *
055: * For example consider the following different internal representations of coverage:<br>
056: * <UL>
057: * <li>A coverage may be represented by a set of polygons which exhaustively tile a plane (that is
058: * each point on the plane falls in precisely one polygon). The value returned by the coverage for a
059: * point is the value of an attribute of the polygon that contains the point.</li>
060: * <li>A coverage may be represented by a grid of values. The value returned by the coverage for a
061: * point is that of the grid value whose location is nearest the point.</li>
062: * <li>Coverage may be represented by a mathematical function. The value returned by the coverage
063: * for a point is just the return value of the function when supplied the coordinates of the point
064: * as arguments.</li>
065: * <li>Coverage may be represented by combination of these. For example, coverage may be
066: * represented by a combination of mathematical functions valid over a set of polynomials.</LI>
067: * </UL>
068: *
069: * A coverage has a corresponding {@link SampleDimension} for each sample dimension in the coverage.
070: * <br>
071: * <br>
072: * <STRONG>Implementation note:</STRONG><BR>
073: * We expect that many implementations of {@link "org.opengis.coverage.grid.GridCoverage"} will want
074: * to leverage the rich set of <A HREF="http://java.sun.com/products/java-media/jai/">Java Advanced
075: * Imaging (JAI)</A> features. For those implementations, it is recommended (but not required) to
076: * implement the {@link javax.media.jai.PropertySource} interface as well. In this case,
077: * implementation of {@link javax.media.jai.PropertySource} methods must be consistent with
078: * {@link #getMetadataNames} and {@link #getMetadataValue} methods.
079: *
080: * @UML abstract CV_Coverage
081: * @author <A HREF="http://www.opengis.org">OpenGIS® consortium</A>
082: * @version <A HREF="http://www.opengis.org/docs/01-004.pdf">Grid Coverage specification 1.0</A>
083: *
084: * @author last edited by: $Author: apoth $
085: *
086: * @version $Revision: 9343 $, $Date: 2007-12-27 05:30:32 -0800 (Thu, 27 Dec 2007) $
087: *
088: * @see RenderableImage
089: * @see javax.media.jai.ImageFunction
090: */
091: public interface Coverage {
092: /**
093: * Specifies the coordinate reference system used when accessing a coverage or grid coverage
094: * with the <code>evaluate(...)</code> methods. It is also the coordinate reference system of
095: * the coordinates used with the math transform
096: *
097: * This coordinate reference system is usually different than coordinate system of the grid.
098: * Grid coverage can be accessed (re-projected) with new coordinate reference system with the
099: * {@link "org.opengis.coverage.processing.GridCoverageProcessor"} component. In this case, a
100: * new instance of a grid coverage is created. <br>
101: * <br>
102: * Note: If a coverage does not have an associated coordinate reference system, the returned
103: * value will be <code>null</code>.
104: *
105: * @return The coordinate reference system used when accessing a coverage or grid coverage with
106: * the <code>evaluate(...)</code> methods, or <code>null</code>.
107: * @UML mandatory coordinateSystem
108: */
109: CoordinateSystem getCoordinateReferenceSystem();
110:
111: /**
112: * The bounding box for the coverage domain in
113: * {@linkplain #getCoordinateReferenceSystem coordinate reference system} coordinates. For grid
114: * coverages, the grid cells are centered on each grid coordinate. The envelope for a 2-D grid
115: * coverage includes the following corner positions.
116: *
117: * <blockquote>
118: *
119: * <pre>
120: * (Minimum row - 0.5, Minimum column - 0.5) for the minimum coordinates
121: * (Maximum row - 0.5, Maximum column - 0.5) for the maximum coordinates
122: * </pre>
123: *
124: * </blockquote>
125: *
126: * If a grid coverage does not have any associated coordinate reference system, the minimum and
127: * maximum coordinate points for the envelope will be empty sequences.
128: *
129: * @return The bounding box for the coverage domain in coordinate system coordinates.
130: * @UML mandatory envelope
131: */
132: PT_Envelope getEnvelope();
133:
134: /**
135: * The names of each dimension in the coverage. Typically these names are <var>x</var>, <var>y</var>,
136: * <var>z</var> and <var>t</var>. The number of items in the sequence is the number of
137: * dimensions in the coverage. Grid coverages are typically 2D (<var>x</var>, <var>y</var>)
138: * while other coverages may be 3D (<var>x</var>, <var>y</var>, <var>z</var>) or 4D (<var>x</var>,
139: * <var>y</var>, <var>z</var>, <var>t</var>). The number of dimensions of the coverage is the
140: * number of entries in the list of dimension names.
141: *
142: * @return The names of each dimension in the coverage.
143: * @UML mandatory dimensionNames
144: */
145: String[] getDimensionNames();
146:
147: /**
148: * The number of sample dimensions in the coverage. For grid coverages, a sample dimension is a
149: * band.
150: *
151: * @return The number of sample dimensions in the coverage.
152: * @UML mandatory numSampleDimensions
153: */
154: int getNumSampleDimensions();
155:
156: /**
157: * Retrieve sample dimension information for the coverage. For a grid coverage a sample
158: * dimension is a band. The sample dimension information include such things as description,
159: * data type of the value (bit, byte, integer...), the no data values, minimum and maximum
160: * values and a color table if one is associated with the dimension. A coverage must have at
161: * least one sample dimension.
162: *
163: * @param index
164: * Index for sample dimension to retrieve. Indices are numbered 0 to (<var>{@linkplain #getNumSampleDimensions n}</var>-1).
165: * @return Sample dimension information for the coverage.
166: * @throws IndexOutOfBoundsException
167: * if <code>index</code> is out of bounds.
168: * @UML operation getSampleDimension
169: */
170: SampleDimension getSampleDimension(int index)
171: throws IndexOutOfBoundsException;
172:
173: /**
174: * Number of grid coverages which the grid coverage was derived from. This implementation
175: * specification does not include interfaces for creating collections of coverages therefore
176: * this value will usually be one indicating an adapted grid coverage, or zero indicating a raw
177: * grid coverage.
178: *
179: * @return The number of grid coverages which the grid coverage was derived from.
180: * @UML mandatory numSource
181: */
182: int getNumSources();
183:
184: /**
185: * Returns the source data for a coverage. This is intended to allow applications to establish
186: * what <code>Coverage</code>s will be affected when others are updated, as well as to trace
187: * back to the "raw data".
188: *
189: * @param sourceDataIndex
190: * Source coverage index. Indexes start at 0.
191: * @return The source data for a coverage.
192: * @throws IndexOutOfBoundsException
193: * if <code>sourceDataIndex</code> is out of bounds.
194: * @UML operation getSource
195: *
196: * @see #getNumSources
197: * @see "org.opengis.coverage.grid.GridCoverage#getSource"
198: */
199: Coverage getSource(int sourceDataIndex)
200: throws IndexOutOfBoundsException;
201:
202: /**
203: * List of metadata keywords for a coverage. If no metadata is available, the sequence will be
204: * empty.
205: *
206: * @return the list of metadata keywords for a coverage.
207: * @UML mandatory metadataNames
208: *
209: * @see #getMetadataValue
210: * @see javax.media.jai.PropertySource#getPropertyNames()
211: */
212: String[] getMetadataNames();
213:
214: /**
215: * Retrieve the metadata value for a given metadata name.
216: *
217: * @param name
218: * Metadata keyword for which to retrieve data.
219: * @return the metadata value for a given metadata name.
220: * @throws MetadataNameNotFoundException
221: * if there is no value for the specified metadata name.
222: * @UML operation getMetadataValue
223: *
224: * @see #getMetadataNames
225: * @see javax.media.jai.PropertySource#getProperty
226: */
227: String getMetadataValue(String name)
228: throws MetadataNameNotFoundException;
229:
230: /**
231: * Returns 2D view of this coverage as a renderable image. This optional operation allows
232: * interoperability with <A HREF="http://java.sun.com/products/java-media/2D/">Java2D</A>. If
233: * this coverage is a {@link "org.opengis.coverage.grid.GridCoverage"} backed by a
234: * {@link java.awt.image.RenderedImage}, the underlying image can be obtained with:
235: *
236: * <code>getRenderableImage(0,1).{@linkplain RenderableImage#createDefaultRendering()
237: * createDefaultRendering()}</code>
238: *
239: * @param xAxis
240: * Dimension to use for the <var>x</var> axis.
241: * @param yAxis
242: * Dimension to use for the <var>y</var> axis.
243: * @return A 2D view of this coverage as a renderable image.
244: * @throws UnsupportedOperationException
245: * if this optional operation is not supported.
246: * @throws IndexOutOfBoundsException
247: * if <code>xAxis</code> or <code>yAxis</code> is out of bounds.
248: */
249: RenderableImage getRenderableImage(int xAxis, int yAxis)
250: throws UnsupportedOperationException,
251: IndexOutOfBoundsException;
252:
253: }
|