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