001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2005-2013 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.coverage;
033
034 import java.util.Set;
035 import java.util.List;
036 import java.util.Collection;
037 import java.awt.image.Raster;
038 import java.awt.image.renderable.RenderableImage;
039 import org.opengis.metadata.extent.Extent;
040 import org.opengis.geometry.Envelope;
041 import org.opengis.geometry.Geometry;
042 import org.opengis.geometry.DirectPosition;
043 import org.opengis.referencing.crs.CoordinateReferenceSystem;
044 import org.opengis.temporal.Period;
045 import org.opengis.util.Record;
046 import org.opengis.util.RecordType;
047 import org.opengis.annotation.UML;
048
049 import static org.opengis.annotation.Obligation.*;
050 import static org.opengis.annotation.Specification.*;
051
052
053 /**
054 * A function from a spatial, temporal or spatiotemporal domain to an attribute range. A coverage
055 * associates a {@linkplain DirectPosition position} within its domain to a record of values of
056 * defined data types. Examples include a raster image, polygon overlay, or digital elevation matrix.
057 * The essential property of coverage is to be able to generate a value for any point
058 * within its domain. How coverage is represented internally is not a concern.
059 *
060 * For example consider the following different internal representations of coverage:<br>
061 * <UL>
062 * <li>A coverage may be represented by a set of polygons which exhaustively
063 * tile a plane (that is each point on the plane falls in precisely one polygon).
064 * The value returned by the coverage for a point is the value of an attribute of
065 * the polygon that contains the point.</li>
066 * <li>A coverage may be represented by a grid of values
067 * (a {@linkplain DiscreteGridPointCoverage Discrete Grid Point Coverage}).
068 * If the coverage is a {@linkplain ContinuousQuadrilateralGridCoverage Continuous
069 * Quadrilateral Grid Coverage} using {@linkplain InterpolationMethod#NEAREST_NEIGHBOUR
070 * Nearest Neighbour} interpolation method, then the value returned by the coverage for
071 * a point is that of the grid value whose location is nearest the point.</li>
072 * <li>Coverage may be represented by a mathematical function.
073 * The value returned by the coverage for a point is just the return value
074 * of the function when supplied the coordinates of the point as arguments.</li>
075 * <li>Coverage may be represented by combination of these.
076 * For example, coverage may be represented by a combination of mathematical
077 * functions valid over a set of polynomials.</LI>
078 * </UL>
079 *
080 * <h3>Metadata</h3>
081 * The legacy {@linkplain Specification#OGC_01004 OGC 01-004} specification provided some methods for
082 * fetching metadata values attached to a coverage. The {@linkplain Specification#ISO_19123 ISO 19123}
083 * specification do not provides such methods. Implementations that want to provide such metadata are
084 * encouraged to implement the {@link javax.media.jai.PropertySource} or
085 * {@link javax.media.jai.WritablePropertySource} interface.
086 *
087 * @version ISO 19123:2004
088 * @author Stephane Fellah
089 * @author Martin Desruisseaux (IRD)
090 * @author Wim Koolhoven
091 * @author Alexander Petkov
092 * @since GeoAPI 2.1
093 */
094 @UML(identifier="CV_Coverage", specification=ISO_19123)
095 public interface Coverage {
096 /**
097 * Returns the coordinate reference system to which the objects in its domain are referenced.
098 * This is the CRS used when accessing a coverage or grid coverage with the {@code evaluate(...)}
099 * methods. This coordinate reference system is usually different than coordinate system of the
100 * grid. It is the target coordinate reference system of the
101 * {@link org.opengis.coverage.grid.GridGeometry#getGridToCRS gridToCRS} math transform.
102 * <p>
103 * Grid coverage can be accessed (re-projected) with new coordinate reference system with the
104 * {@link org.opengis.coverage.processing.GridCoverageProcessor} component. In this case, a new
105 * instance of a grid coverage is created.
106 *
107 * @return The coordinate reference system used when accessing a coverage or
108 * grid coverage with the {@code evaluate(...)} methods.
109 */
110 @UML(identifier="CRS", obligation=MANDATORY, specification=ISO_19123)
111 CoordinateReferenceSystem getCoordinateReferenceSystem();
112
113 /**
114 * The bounding box for the coverage domain in {@linkplain #getCoordinateReferenceSystem
115 * coordinate reference system} coordinates. For grid coverages, the grid cells are centered
116 * on each grid coordinate. The envelope for a 2-D grid coverage includes the following corner
117 * positions.
118 *
119 * <blockquote><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></blockquote>
123 *
124 * If a grid coverage does not have any associated coordinate reference system,
125 * the minimum and maximum coordinate points for the envelope will be empty sequences.
126 *
127 * @return The bounding box for the coverage domain in coordinate system coordinates.
128 *
129 * @todo We need to explain the relationship with {@link #getDomainExtents}, if any.
130 */
131 @UML(identifier="envelope", obligation=MANDATORY, specification=OGC_01004)
132 Envelope getEnvelope();
133
134 /**
135 * Returns the extent of the domain of the coverage. Extents may be specified in space,
136 * time or space-time. The collection must contains at least one element.
137 *
138 * @return The domain extent of the coverage.
139 */
140 @UML(identifier="domainExtent", obligation=MANDATORY, specification=ISO_19123)
141 Set<Extent> getDomainExtents();
142
143 /**
144 * Returns the set of domain objects in the domain.
145 * The collection must contains at least one element.
146 *
147 * @return The domain elements.
148 */
149 @UML(identifier="domainElement", obligation=MANDATORY, specification=ISO_19123)
150 Set<? extends DomainObject<?>> getDomainElements();
151
152 /**
153 * Returns the set of attribute values in the range. The range of a coverage shall be a
154 * homogeneous collection of records. That is, the range shall have a constant dimension
155 * over the entire domain, and each field of the record shall provide a value of the same
156 * attribute type over the entire domain.
157 * <p>
158 * In the case of a {@linkplain DiscreteCoverage discrete coverage}, the size of the range
159 * collection equals that of the {@linkplain #getDomainElements domains} collection. In other
160 * words, there is one instance of {@link AttributeValues} for each instance of {@link DomainObject}.
161 * Usually, these are stored values that are accessed by the
162 * {@link #evaluate(DirectPosition,Collection) evaluate} operation.
163 * <p>
164 * In the case of a {@linkplain ContinuousCoverage continuous coverage}, there is a transfinite
165 * number of instances of {@link AttributeValues} for each {@link DomainObject}. A few instances
166 * may be stored as input for the {@link #evaluate(DirectPosition,Collection) evaluate} operation,
167 * but most are generated as needed by that operation.
168 * <p>
169 * <B>NOTE:</B> ISO 19123 does not specify how the {@linkplain #getDomainElements domain}
170 * and {@linkplain #getRangeElements range} associations are to be implemented. The relevant
171 * data may be generated in real time, it may be held in persistent local storage, or it may
172 * be electronically accessible from remote locations.
173 *
174 * @return The attribute values in the range.
175 */
176 @UML(identifier="rangeElement", obligation=OPTIONAL, specification=ISO_19123)
177 Collection<AttributeValues> getRangeElements();
178
179 /**
180 * Describes the range of the coverage. It consists of a list of attribute name/data type pairs.
181 * A simple list is the most common form of range type, but {@code RecordType} can be used
182 * recursively to describe more complex structures. The range type for a specific coverage
183 * shall be specified in an application schema.
184 *
185 * @return The coverage range.
186 */
187 @UML(identifier="rangeType", obligation=MANDATORY, specification=ISO_19123)
188 RecordType getRangeType();
189
190 /**
191 * Identifies the procedure to be used for evaluating the coverage at a position that falls
192 * either on a boundary between geometric objects or within the boundaries of two or more
193 * overlapping geometric objects. The geometric objects are either {@linkplain DomainObject
194 * domain objects} or {@linkplain ValueObject value objects}.
195 *
196 * @return The procedure for evaluating the coverage on overlapping geometries.
197 */
198 @UML(identifier="commonPointRule", obligation=MANDATORY, specification=ISO_19123)
199 CommonPointRule getCommonPointRule();
200
201 /**
202 * Returns the dictionary of <var>geometry</var>-<var>value</var> pairs that contain the
203 * {@linkplain DomainObject objects} in the domain of the coverage each paired with its
204 * record of feature attribute values. In the case of an analytical coverage, the operation
205 * shall return the empty set.
206 *
207 * @return The geometry-value pairs.
208 */
209 @UML(identifier="list", obligation=MANDATORY, specification=ISO_19123)
210 Set<? extends GeometryValuePair> list();
211
212 /**
213 * Returns the set of <var>geometry</var>-<var>value</var> pairs that contain
214 * {@linkplain DomainObject domain objects} that lie within the specified geometry and period.
215 * If {@code s} is null, the operation shall return all <var>geometry</var>-<var>value</var>
216 * pairs that contain {@linkplain DomainObject domain objects} within {@code t}. If the value
217 * of {@code t} is null, the operation shall return all <var>geometry</var>-<var>value</var>
218 * pair that contain {@linkplain DomainObject domain objects} within {@code s}. In the case
219 * of an analytical coverage, the operation shall return the empty set.
220 *
221 * @param s The spatial component.
222 * @param t The temporal component.
223 * @return The values in the given spatio-temporal domain.
224 */
225 @UML(identifier="select", obligation=MANDATORY, specification=ISO_19123)
226 Set<? extends GeometryValuePair> select(Geometry s, Period t);
227
228 /**
229 * Returns the sequence of <var>geometry</var>-<var>value</var> pairs that include the
230 * {@linkplain DomainObject domain objects} nearest to the direct position and their distances
231 * from the direction position. The sequence shall be ordered by distance from the direct position,
232 * beginning with the record containing the {@linkplain DomainObject domain object} nearest to the
233 * direct position. The length of the sequence (the number of <var>geometry</var>-<var>value</var>
234 * pairs returned) shall be no greater than the number specified by the parameter {@code limit}.
235 * The default shall be to return a single <var>geometry</var>-<var>value</var> pair. The operation
236 * shall return a warning if the last {@linkplain DomainObject domain object} in the sequence is at
237 * a distance from the direct position equal to the distance of other {@linkplain DomainObject domain
238 * objects} that are not included in the sequence. In the case of an analytical coverage, the operation
239 * shall return the empty set.
240 * <p>
241 * <B>NOTE:</B> This operation is useful when the domain of a coverage does not exhaustively
242 * partition the extent of the coverage. Even in that case, the first element of the sequence
243 * returned may be the <var>geometry</var>-<var>value</var> pair that contains the input direct
244 * position.
245 *
246 * @param p The search position.
247 * @param limit The maximal size of the list to be returned.
248 * @return The <var>geometry</var>-<var>value</var> pairs nearest to the given position.
249 */
250 @UML(identifier="find", obligation=MANDATORY, specification=ISO_19123)
251 List<? extends GeometryValuePair> find(DirectPosition p, int limit);
252
253 /**
254 * Returns the nearest <var>geometry</var>-<var>value</var> pair from the specified direct
255 * position. This is a shortcut for <code>{@linkplain #find(DirectPosition,int) find}(p,1)</code>.
256 *
257 * @param p The search position.
258 * @return The <var>geometry</var>-<var>value</var> pair nearest to the given position.
259 */
260 @UML(identifier="find", obligation=MANDATORY, specification=ISO_19123)
261 GeometryValuePair find(DirectPosition p);
262
263 /**
264 * Returns a set of records of feature attribute values for the specified direct position. The
265 * parameter {@code list} is a sequence of feature attribute names each of which identifies a
266 * field of the range type. If {@code list} is null, the operation shall return a value for
267 * every field of the range type. Otherwise, it shall return a value for each field included in
268 * {@code list}. If the direct position passed is not in the domain of the coverage, then an
269 * exception is thrown. If the input direct position falls within two or more geometric objects
270 * within the domain, the operation shall return records of feature attribute values computed
271 * according to the {@linkplain #getCommonPointRule common point rule}.
272 * <P>
273 * <B>NOTE:</B> Normally, the operation will return a single record of feature attribute values.
274 *
275 * @param p The position where to evaluate.
276 * @param list The field of interest, or {@code null} for every fields.
277 * @return The feature attributes.
278 * @throws PointOutsideCoverageException if the point is outside the coverage domain.
279 * @throws CannotEvaluateException If the point can't be evaluated for some other reason.
280 */
281 @UML(identifier="evaluate", obligation=MANDATORY, specification=ISO_19123)
282 Set<Record> evaluate(DirectPosition p, Collection<String> list)
283 throws PointOutsideCoverageException, CannotEvaluateException;
284
285 /**
286 * Return the value vector for a given point in the coverage.
287 * A value for each sample dimension is included in the vector.
288 * The default interpolation type used when accessing grid values for points
289 * which fall between grid cells is nearest neighbor.
290 * <p>
291 * The coordinate reference system of the point is the same as the grid coverage coordinate
292 * reference system (specified by the {@link #getCoordinateReferenceSystem} method).
293 * <p>
294 * <strong>WARNING:</strong> This method is inherited from the legacy OGC 01-004
295 * specification and may be deprecated in a future version. We are for more experience
296 * and feedbacks on the value of this method.
297 *
298 * @param point Point at which to find the grid values.
299 * @return The value vector for a given point in the coverage.
300 * @throws PointOutsideCoverageException if the point is outside the coverage
301 * {@linkplain #getEnvelope envelope}.
302 * @throws CannotEvaluateException If the point can't be evaluated for some other reason.
303 * @see Raster#getDataElements(int, int, Object)
304 */
305 @UML(identifier="evaluate", obligation=MANDATORY, specification=OGC_01004)
306 Object evaluate(DirectPosition point) throws PointOutsideCoverageException, CannotEvaluateException;
307
308 /**
309 * Return a sequence of boolean values for a given point in the coverage.
310 * A value for each sample dimension is included in the sequence.
311 * The default interpolation type used when accessing grid values for points which
312 * fall between grid cells is nearest neighbor.
313 * <p>
314 * The coordinate reference system of the point is the same as the grid coverage coordinate
315 * reference system (specified by the {@link #getCoordinateReferenceSystem} method).
316 *
317 * @param point Point at which to find the coverage values.
318 * @param destination An optionally preallocated array in which to store the values,
319 * or {@code null} if none.
320 * @return A sequence of boolean values for a given point in the coverage.
321 * If {@code destination} was non-null, then it is returned.
322 * Otherwise, a new array is allocated and returned.
323 * @throws PointOutsideCoverageException if the point is outside the coverage
324 * {@linkplain #getEnvelope envelope}.
325 * @throws CannotEvaluateException if the point can't be evaluated for some othe reason.
326 * @throws ArrayIndexOutOfBoundsException if the {@code destination} array is not null
327 * and too small to hold the output.
328 */
329 @UML(identifier="evaluateAsBoolean", obligation=MANDATORY, specification=OGC_01004)
330 boolean[] evaluate(DirectPosition point, boolean[] destination)
331 throws PointOutsideCoverageException, CannotEvaluateException, ArrayIndexOutOfBoundsException;
332
333 /**
334 * Return a sequence of unsigned byte values for a given point in the coverage.
335 * A value for each sample dimension is included in the sequence.
336 * The default interpolation type used when accessing grid values for points which
337 * fall between grid cells is nearest neighbor.
338 * <p>
339 * The coordinate reference system of the point is the same as the grid coverage coordinate
340 * reference system (specified by the {@link #getCoordinateReferenceSystem} method).
341 *
342 * @param point Point at which to find the coverage values.
343 * @param destination An optionally preallocated array in which to store the values,
344 * or {@code null} if none.
345 * @return A sequence of unsigned byte values for a given point in the coverage.
346 * If {@code destination} was non-null, then it is returned.
347 * Otherwise, a new array is allocated and returned.
348 * @throws PointOutsideCoverageException if the point is outside the coverage
349 * {@linkplain #getEnvelope envelope}.
350 * @throws CannotEvaluateException if the point can't be evaluated for some othe reason.
351 * @throws ArrayIndexOutOfBoundsException if the {@code destination} array is not null
352 * and too small to hold the output.
353 */
354 @UML(identifier="evaluateAsByte", obligation=MANDATORY, specification=OGC_01004)
355 byte[] evaluate(DirectPosition point, byte[] destination)
356 throws PointOutsideCoverageException, CannotEvaluateException, ArrayIndexOutOfBoundsException;
357
358 /**
359 * Return a sequence of integer values for a given point in the coverage.
360 * A value for each sample dimension is included in the sequence.
361 * The default interpolation type used when accessing grid values for points which
362 * fall between grid cells is nearest neighbor.
363 * <p>
364 * The coordinate reference system of the point is the same as the grid coverage coordinate
365 * reference system (specified by the {@link #getCoordinateReferenceSystem} method).
366 *
367 * @param point Point at which to find the grid values.
368 * @param destination An optionally preallocated array in which to store the values,
369 * or {@code null} if none.
370 * @return A sequence of integer values for a given point in the coverage.
371 * If {@code destination} was non-null, then it is returned.
372 * Otherwise, a new array is allocated and returned.
373 * @throws PointOutsideCoverageException if the point is outside the coverage
374 * {@linkplain #getEnvelope envelope}.
375 * @throws CannotEvaluateException if the point can't be evaluated for some othe reason.
376 * @throws ArrayIndexOutOfBoundsException if the {@code destination} array is not null
377 * and too small to hold the output.
378 *
379 * @see Raster#getPixel(int, int, int[])
380 */
381 @UML(identifier="evaluateAsInteger", obligation=MANDATORY, specification=OGC_01004)
382 int[] evaluate(DirectPosition point, int[] destination)
383 throws PointOutsideCoverageException, CannotEvaluateException, ArrayIndexOutOfBoundsException;
384
385 /**
386 * Return a sequence of float values for a given point in the coverage.
387 * A value for each sample dimension is included in the sequence.
388 * The default interpolation type used when accessing grid values for points which
389 * fall between grid cells is nearest neighbor.
390 * <p>
391 * The coordinate reference system of the point is the same as the grid coverage coordinate
392 * reference system (specified by the {@link #getCoordinateReferenceSystem} method).
393 *
394 * @param point Point at which to find the grid values.
395 * @param destination An optionally preallocated array in which to store the values,
396 * or {@code null} if none.
397 * @return A sequence of float values for a given point in the coverage.
398 * If {@code destination} was non-null, then it is returned.
399 * Otherwise, a new array is allocated and returned.
400 * @throws PointOutsideCoverageException if the point is outside the coverage
401 * {@linkplain #getEnvelope envelope}.
402 * @throws CannotEvaluateException if the point can't be evaluated for some othe reason.
403 * @throws ArrayIndexOutOfBoundsException if the {@code destination} array is not null
404 * and too small to hold the output.
405 *
406 * @see Raster#getPixel(int, int, float[])
407 */
408 float[] evaluate(DirectPosition point, float[] destination)
409 throws PointOutsideCoverageException, CannotEvaluateException, ArrayIndexOutOfBoundsException;
410
411 /**
412 * Return a sequence of double values for a given point in the coverage.
413 * A value for each sample dimension is included in the sequence.
414 * The default interpolation type used when accessing grid values for points which
415 * fall between grid cells is nearest neighbor.
416 * <p>
417 * The coordinate reference system of the point is the same as the grid coverage coordinate
418 * reference system (specified by the {@link #getCoordinateReferenceSystem} method).
419 *
420 * @departure integration
421 * OGC 01-004 defines this method as <code>evaluate(DirectPosition)</code>. GeoAPI adds
422 * the <code>double[]</code> argument for reusing pre-allocated arrays, which is consistent
423 * with usage in <code>java.awt.image.Raster</code>.
424 *
425 * @param point Point at which to find the grid values.
426 * @param destination An optionally preallocated array in which to store the values,
427 * or {@code null} if none.
428 * @return A sequence of double values for a given point in the coverage.
429 * If {@code destination} was non-null, then it is returned.
430 * Otherwise, a new array is allocated and returned.
431 * @throws PointOutsideCoverageException if the point is outside the coverage
432 * {@linkplain #getEnvelope envelope}.
433 * @throws CannotEvaluateException If the point can't be evaluated for some othe reason.
434 * @throws ArrayIndexOutOfBoundsException if the {@code destination} array is not null
435 * and too small to hold the output.
436 *
437 * @see Raster#getPixel(int, int, double[])
438 */
439 @UML(identifier="evaluateAsDouble", obligation=MANDATORY, specification=OGC_01004)
440 double[] evaluate(DirectPosition point, double[] destination)
441 throws PointOutsideCoverageException, CannotEvaluateException, ArrayIndexOutOfBoundsException;
442
443 /**
444 * Returns a set of {@linkplain DomainObject domain objects} for the specified record of feature
445 * attribute values. Normally, this method returns the set of {@linkplain DomainObject objects}
446 * in the domain that are associated with values equal to those in the input record. However,
447 * the operation may return other {@linkplain DomainObject objects} derived from those in the
448 * domain, as specified by the application schema.
449 * <p>
450 * <B>Example:</B> The {@code evaluateInverse} operation could return a set
451 * of contours derived from the feature attribute values associated with the
452 * {@linkplain org.opengis.coverage.grid.GridPoint grid points} of a grid coverage.
453 *
454 * @param v The feature attributes.
455 * @return The domain where the attributes are found.
456 */
457 @UML(identifier="evaluateInverse", obligation=MANDATORY, specification=ISO_19123)
458 Set<? extends DomainObject<?>> evaluateInverse(Record v);
459
460 /**
461 * The number of sample dimensions in the coverage.
462 * For grid coverages, a sample dimension is a band.
463 * <p>
464 * <strong>WARNING:</strong> This method is inherited from the legacy OGC 01-004
465 * specification and may be deprecated in a future version. We are for more experience
466 * and feedbacks on the value of this method.
467 *
468 * @return The number of sample dimensions in the coverage.
469 */
470 @UML(identifier="numSampleDimensions", obligation=MANDATORY, specification=OGC_01004)
471 int getNumSampleDimensions();
472
473 /**
474 * Retrieve sample dimension information for the coverage.
475 * For a grid coverage a sample dimension is a band. The sample dimension information
476 * include such things as description, data type of the value (bit, byte, integer...),
477 * the no data values, minimum and maximum values and a color table if one is
478 * associated with the dimension. A coverage must have at least one sample dimension.
479 * <p>
480 * <strong>WARNING:</strong> This method is inherited from the legacy OGC 01-004
481 * specification and may be deprecated in a future version. We are for more experience
482 * and feedbacks on the value of this method.
483 *
484 * @param index Index for sample dimension to retrieve. Indices are numbered 0 to
485 * (<var>{@linkplain #getNumSampleDimensions n}</var>-1).
486 * @return Sample dimension information for the coverage.
487 * @throws IndexOutOfBoundsException if {@code index} is out of bounds.
488 */
489 @UML(identifier="getSampleDimension", obligation=MANDATORY, specification=OGC_01004)
490 SampleDimension getSampleDimension(int index) throws IndexOutOfBoundsException;
491
492 /**
493 * Returns the sources data for a coverage.
494 * This is intended to allow applications to establish what {@code Coverage}s
495 * will be affected when others are updated, as well as to trace back to the "raw data".
496 * <p>
497 * This implementation specification does not include interfaces for creating
498 * collections of coverages therefore the list size will usually be one indicating
499 * an adapted grid coverage, or zero indicating a raw grid coverage.
500 * <p>
501 * <strong>WARNING:</strong> This method is inherited from the legacy OGC 01-004
502 * specification and may be deprecated in a future version. We are for more experience
503 * and feedbacks on the value of this method.
504 *
505 * @departure generalization
506 * Return type of <code>Coverage.getSource(int)</code> has been relaxed from <code>GridCoverage</code>
507 * to <code>Coverage</code>. Instead, the return type has been constrained to <code>GridCoverage</code>
508 * only in <code>GridCoverage.getSource(int)</code>. This approach (<cite>return type covariance</cite>)
509 * was already used in "<cite>Spatial Referencing by Coordinates</cite>" (ISO 19111). It avoid forward
510 * dependency of <code>Coverage</code> toward <code>GridCoverage</code> and give more flexibility for
511 * use of <code>Coverage</code> with non-gridded sources.
512 *
513 * @return The list of sources data for a coverage.
514 */
515 @UML(identifier="getSource, numSource", obligation=MANDATORY, specification=OGC_01004)
516 List<? extends Coverage> getSources();
517
518 /**
519 * Returns 2D view of this coverage as a renderable image.
520 * This optional operation allows interoperability with
521 * <A HREF="http://java.sun.com/products/java-media/2D/">Java2D</A>.
522 * If this coverage is a {@link org.opengis.coverage.grid.GridCoverage} backed
523 * by a {@link java.awt.image.RenderedImage}, the underlying image can be obtained
524 * with:
525 *
526 * <code>getRenderableImage(0,1).{@linkplain RenderableImage#createDefaultRendering()
527 * createDefaultRendering()}</code>
528 *
529 * @departure integration
530 * Added this optional method for interoperability with Java2D.
531 *
532 * @param xAxis Dimension to use for the <var>x</var> axis.
533 * @param yAxis Dimension to use for the <var>y</var> axis.
534 * @return A 2D view of this coverage as a renderable image.
535 * @throws UnsupportedOperationException if this optional operation is not supported.
536 * @throws IndexOutOfBoundsException if {@code xAxis} or {@code yAxis} is out of bounds.
537 */
538 RenderableImage getRenderableImage(int xAxis, int yAxis)
539 throws UnsupportedOperationException, IndexOutOfBoundsException;
540 }