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.List;
035 import java.util.Set;
036 import org.opengis.util.Record;
037 import org.opengis.temporal.Period;
038 import org.opengis.coverage.grid.GridPoint;
039 import org.opengis.coverage.grid.GridPointValuePair;
040 import org.opengis.coverage.grid.GridCoordinates;
041 import org.opengis.coverage.grid.GridValuesMatrix;
042 import org.opengis.geometry.Geometry;
043 import org.opengis.geometry.DirectPosition;
044 import org.opengis.annotation.UML;
045
046 import static org.opengis.annotation.Obligation.*;
047 import static org.opengis.annotation.Specification.*;
048
049
050 /**
051 * A {@linkplain DiscreteCoverage discrete coverage} with a domain defined as a set of
052 * {@linkplain GridPoint grid points} that are associated with records of feature attribute
053 * values through a {@linkplain GridValuesMatrix grid values matrix}.
054 * <p>
055 * {@code DiscreteGridPointCoverage} inherits the {@linkplain #getElements elements} and the
056 * operations {@link #locate locate}, {@link #find(DirectPosition,int) find}, and
057 * {@link #list list}, from {@link DiscreteCoverage}, with the restriction that the
058 * associated {@linkplain GeometryValuePair geometry-value pairs} and those returned by the
059 * operations shall be limited to
060 * {@linkplain GridPointValuePair (grid point)-(value) pairs}. The
061 * {@linkplain #getElements elements} may be generated from the
062 * {@linkplain GridValuesMatrix grid values matrix} through the
063 * {@linkplain #getValueAssignment value assignment}. The inherited operations
064 * {@link #evaluate evaluate} and {@link #evaluateInverse evaluateInverse} use
065 * {@linkplain GridValuesMatrix grid values matrix} to assign values to the
066 * {@linkplain GeometryValuePair geometry-value pairs}.
067 *
068 * @version ISO 19123:2004
069 * @author Wim Koolhoven
070 * @author Martin Desruisseaux (IRD)
071 * @since GeoAPI 2.1
072 *
073 * @todo Should we restrict {@link DomainObject} to {@link GridPoint} as well? It sound like
074 * a logical consequence of {@link GridPointValuePair} restriction.
075 * @todo Should we move this interface to org.opengis.coverage.grid as all the other grid interfaces,
076 * or should it remain in org.opengis.coverage to follow the ordering in ISO19123?
077 * @todo What should be the behavior of {@link #evaluate(DirectPosition)} when the position
078 * is not exactly on a grid point? Current proposal is to return an empty set.
079 */
080 @UML(identifier="CV_DiscreteGridPointCoverage", specification=ISO_19123)
081 public interface DiscreteGridPointCoverage extends DiscreteCoverage {
082 /**
083 * Returns the set of <var>point</var>-<var>value</var> pairs included in this coverage.
084 */
085 @UML(identifier="element", obligation=OPTIONAL, specification=ISO_19123)
086 Set<GridPointValuePair> getElements();
087
088 /**
089 * Links this discrete grid point coverage to the grid values matrix
090 * for which it is an evaluator.
091 *
092 * @return The underlying grid values matrix.
093 */
094 @UML(identifier="valueAssignment", obligation=MANDATORY, specification=ISO_19123)
095 GridValuesMatrix getValueAssignment();
096
097 /**
098 * Returns the set of <var>point</var>-<var>value</var> pairs that include the
099 * {@linkplain DomainObject domain objects} containing the specified direct position.
100 */
101 @UML(identifier="locate", obligation=OPTIONAL, specification=ISO_19123)
102 Set<GridPointValuePair> locate(DirectPosition p);
103
104 /**
105 * Returns the dictionary of <var>point</var>-<var>value</var> pairs that contain the
106 * {@linkplain DomainObject objects} in the domain of the coverage each paired with its
107 * record of feature attribute values.
108 */
109 @UML(identifier="list", obligation=MANDATORY, specification=ISO_19123)
110 Set<GridPointValuePair> list();
111
112 /**
113 * Returns the set of <var>point</var>-<var>value</var> pairs that contain
114 * {@linkplain DomainObject domain objects} that lie within the specified geometry and period.
115 * If {@code s} is null, the operation shall return all <var>point</var>-<var>value</var>
116 * pairs that contain {@linkplain DomainObject domain objects} within {@code t}. If the value
117 * of {@code t} is null, the operation shall return all <var>point</var>-<var>value</var>
118 * pair that contain {@linkplain DomainObject domain objects} within {@code s}.
119 */
120 @UML(identifier="select", obligation=MANDATORY, specification=ISO_19123)
121 Set<GridPointValuePair> select(Geometry s, Period t);
122
123 /**
124 * Returns the sequence of <var>point</var>-<var>value</var> pairs that include the
125 * {@linkplain DomainObject domain objects} nearest to the direct position and their distances
126 * from the direction position. The sequence shall be ordered by distance from the direct position,
127 * beginning with the record containing the {@linkplain DomainObject domain object} nearest to the
128 * direct position. The length of the sequence (the number of <var>point</var>-<var>value</var>
129 * pairs returned) shall be no greater than the number specified by the parameter {@code limit}.
130 * The default shall be to return a single <var>point</var>-<var>value</var> pair. The operation
131 * shall return a warning if the last {@linkplain DomainObject domain object} in the sequence is at
132 * a distance from the direct position equal to the distance of other
133 * {@linkplain DomainObject domain objects} that are not included in the sequence.
134 */
135 @UML(identifier="find", obligation=MANDATORY, specification=ISO_19123)
136 List<GridPointValuePair> find(DirectPosition p, int limit);
137
138 /**
139 * Returns the nearest <var>point</var>-<var>value</var> pair from the specified direct
140 * position. This is a shortcut for <code>{@linkplain #find(DirectPosition,int) find}(p,1)</code>.
141 */
142 @UML(identifier="find", obligation=MANDATORY, specification=ISO_19123)
143 GridPointValuePair find(DirectPosition p);
144
145 /**
146 * Uses data from the associated {@linkplain GridValuesMatrix grid values matrix} to construct
147 * and return the grid point value pair associated with the specified grid position.
148 *
149 * @param g The position where to search for a value.
150 * @return The point and value at the specified position.
151 */
152 @UML(identifier="point", obligation=MANDATORY, specification=ISO_19123)
153 GridPointValuePair point(GridCoordinates g);
154
155 /**
156 * Returns a set of {@linkplain GridPoint grid points} for the specified record of feature
157 * attribute values. Normally, this method returns the set of {@linkplain GridPoint points}
158 * in the domain that are associated with values equal to those in the input record. However,
159 * the operation may return other {@linkplain GridPoint points} derived from those in the
160 * domain, as specified by the application schema.
161 */
162 @UML(identifier="evaluateInverse", obligation=MANDATORY, specification=ISO_19123)
163 Set<GridPoint> evaluateInverse(Record v);
164 }