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.Collection;
036 import org.opengis.geometry.Geometry;
037 import org.opengis.geometry.DirectPosition;
038 import org.opengis.temporal.Period;
039 import org.opengis.util.Record;
040 import org.opengis.util.RecordType;
041 import org.opengis.annotation.UML;
042
043 import static org.opengis.annotation.Obligation.*;
044 import static org.opengis.annotation.Specification.*;
045
046
047 /**
048 * A coverage that returns a distinct record of feature attribute values for any direct position
049 * within its domain. Although the domain of a continuous coverage is ordinarily bounded in terms
050 * of its spatial and/or temporal extent, it can be subdivided into an infinite number of direct
051 * positions.
052 *
053 * @version ISO 19123:2004
054 * @author Martin Desruisseaux (IRD)
055 * @author Wim Koolhoven
056 * @since GeoAPI 2.1
057 */
058 @UML(identifier="CV_ContinuousCoverage", specification=ISO_19123)
059 public interface ContinuousCoverage extends Coverage {
060 /**
061 * Returns the set of value objects used to evaluate the coverage. This
062 * association is optional - an analytical coverage needs no value objects.
063 *
064 * @return The value used to evaluate the coverage, or {@code null} if not applicable.
065 */
066 @UML(identifier="element", obligation=OPTIONAL, specification=ISO_19123)
067 Set<? extends ValueObject> getElements();
068
069 /**
070 * Returns a code that identifies the interpolation method that shall be used to derive a
071 * feature attribute value at any direct position within the {@linkplain ValueObject value
072 * object}. This attribute is optional - no value is needed for an analytical coverage (one
073 * that maps direct position to attribute value by using a mathematical function rather than
074 * by interpolation).
075 *
076 * @return The interpolation method, or {@code null} if not applicable.
077 */
078 @UML(identifier="interpolationType", obligation=OPTIONAL, specification=ISO_19123)
079 InterpolationMethod getInterpolationMethod();
080
081 /**
082 * Returns the optional parameter types for interpolation. Although many interpolation methods
083 * use only the values in the coverage range as input to the interpolation function, there are
084 * some methods that require additional parameters. This optional attribute specifies the types
085 * of parameters that are needed to support the interpolation method identified by the
086 * {@linkplain #getInterpolationMethod interpolation method}. It is a dictionary of names
087 * and data types.
088 *
089 * @return The interpolation parameter types, or {@code null} if not applicable.
090 */
091 @UML(identifier="interpolationParameterTypes", obligation=OPTIONAL, specification=ISO_19123)
092 RecordType getInterpolationParameterTypes();
093
094 /**
095 * Returns the set of value objects that contains the specified direct position.
096 * It shall return an empty set if the direct position is not on any of the
097 * {@linkplain DomainObject objects} within the domain of the continuous coverage.
098 *
099 * @param p The position where to locate objects.
100 * @return The objects at the given location.
101 */
102 @UML(identifier="locate", obligation=OPTIONAL, specification=ISO_19123)
103 Set<? extends ValueObject> locate(DirectPosition p);
104
105 /**
106 * Returns the set of <var>geometry</var>-<var>value</var> pairs associated with the
107 * {@linkplain ValueObject value objects} of which this continuous coverage is composed.
108 *
109 * @param s The spatial component.
110 * @param t The temporal component.
111 * @return The values in the given spatio-temporal domain.
112 */
113 @UML(identifier="select", obligation=MANDATORY, specification=ISO_19123)
114 Set<? extends GeometryValuePair> select(Geometry s, Period t);
115
116 /**
117 * Returns a set of records of feature attribute values for the specified direct position. Most
118 * evaluation methods involve interpolation within or around a {@linkplain ValueObject value object}.
119 * Normally, the input direct position will fall within only one value object, and the operation will
120 * return a record of feature attribute values interpolated within that value object. If the direct
121 * position falls on the boundary between two value objects, or within two or more overlapping value
122 * objects, the operation shall return a record of feature attribute values derived according to the
123 * {@linkplain Coverage#getCommonPointRule common point rule}. It shall return an empty set if the direct
124 * position is not on any {@linkplain ValueObject value object}.
125 *
126 * @throws PointOutsideCoverageException if the point is outside the coverage domain.
127 * @throws CannotEvaluateException If the point can't be evaluated for some other reason.
128 */
129 @UML(identifier="evaluate", obligation=MANDATORY, specification=ISO_19123)
130 Set<Record> evaluate(DirectPosition p, Collection<String> list)
131 throws PointOutsideCoverageException, CannotEvaluateException;
132
133 /**
134 * Locates the <var>geometry</var>-<var>value</var> pairs for which value equals the specified
135 * record, and return the set of {@linkplain DomainObject domain objects} belonging to those pairs.
136 * Normally, the {@linkplain DomainObject domain objects} that shall be returned are those belonging
137 * to the <var>geometry</var>-<var>value</var> pairs associated with the {@linkplain ValueObject
138 * value objects} of which this continuous coverage is composed. However, the operation may return
139 * other domain objects derived from those in the domain, as specified by the application schema.
140 * The operation shall return an empty set if none of the <var>geometry</var>-<var>value</var> pairs
141 * associated with the continuous coverage has a value equal to the specified record.
142 * <p>
143 * <b>Example:</b>This operation could return a set of contours derived from the feature
144 * attribute values associated with the {@linkplain org.opengis.coverage.grid.GridPoint
145 * grid points} of a grid coverage.
146 *
147 * @param v The feature attributes.
148 * @return The domain where the attributes are found.
149 */
150 @UML(identifier="evaluateInverse", obligation=MANDATORY, specification=ISO_19123)
151 Set<? extends DomainObject<?>> evaluateInverse(Record v);
152 }