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.grid;
033
034 import java.util.Set;
035 import java.util.Collection;
036 import org.opengis.util.Record;
037 import org.opengis.coverage.ContinuousCoverage;
038 import org.opengis.coverage.InterpolationMethod;
039 import org.opengis.coverage.CannotEvaluateException;
040 import org.opengis.coverage.PointOutsideCoverageException;
041 import org.opengis.geometry.DirectPosition;
042 import org.opengis.annotation.UML;
043
044 import static org.opengis.annotation.Obligation.*;
045 import static org.opengis.annotation.Specification.*;
046
047
048 /**
049 * A continuous coverage that operates on a {@linkplain GridValuesMatrix grid values matrix}.
050 * The domain of a continuous quadrilateral grid coverage is the convex hull of the collection
051 * of {@linkplain GridPoint grid points} defined by the grid values matrix. Evaluation of a
052 * continuous quadrilateral grid coverage generates feature attribute values at direct positions
053 * within the convex hull of the grid points provided by the grid values matrix. The general idea
054 * is to extend the coverage to direct positions within the interior of each grid cell by
055 * interpolation from the grid points at the corners of the cell.
056 *
057 * @version ISO 19123:2004
058 * @author Wim Koolhoven
059 * @author Martin Desruisseaux (IRD)
060 * @since GeoAPI 2.1
061 */
062 @UML(identifier="CV_ContinousQuadrilateralGridCoverage", specification=ISO_19123)
063 public interface ContinuousQuadrilateralGridCoverage extends ContinuousCoverage {
064 /**
065 * Returns the set of {@linkplain GridValueCell grid value cells} that provide the structure
066 * to support the {@linkplain #evaluate evaluate} operation.
067 */
068 @UML(identifier="element", obligation=MANDATORY, specification=ISO_19123)
069 Set<GridValueCell> getElements();
070
071 /**
072 * Returns a code that identifies the interpolation method that shall be used to derive a
073 * feature attribute value at any direct position within the {@linkplain GridValueCell grid
074 * value cell}. This value is often {@linkplain InterpolationMethod#BILINEAR bilinear}.
075 *
076 * @return The interpolation method.
077 */
078 @UML(identifier="interpolationType", obligation=MANDATORY, specification=ISO_19123)
079 InterpolationMethod getInterpolationMethod();
080
081 /**
082 * Returns the grid value cell that contains the specified direct position.
083 * This method always returns a set of 1 member.
084 */
085 @UML(identifier="locate", obligation=MANDATORY, specification=ISO_19123)
086 Set<GridValueCell> locate(DirectPosition p);
087
088 /**
089 * Returns a set of records of feature attribute values for the specified direct position.
090 * Evaluation of a continuous quadrilateral grid coverage involves two steps. The first is
091 * to use the information from the {@linkplain GridValuesMatrix values matrix} at {@linkplain
092 * #getSource quadrilateral grid coverage source} to generate the
093 * {@linkplain GridValueCell grid value cell} that contains the input {@linkplain DirectPosition
094 * direct position}; the second is to interpolate the feature attribute values at the direct
095 * position from the {@linkplain GridPointValuePair grid point value pairs} at the corners of
096 * the {@linkplain GridValueCell grid value cell}. Some interpolation methods (e.g.
097 * {@linkplain InterpolationMethod#BICUBIC bicubic interpolation}) may require the use of
098 * {@linkplain GridPointValuePair grid point value pairs} outside of the {@linkplain GridValueCell
099 * grid value cell} that contains the {@linkplain DirectPosition direct position}.
100 * <p>
101 * <B>NOTE:</B>
102 * {@linkplain InterpolationMethod#NEAREST_NEIGHBOUR Nearest neighbour interpolation} will return
103 * for any direct position within a {@linkplain GridValueCell grid value cell} the record associated
104 * with the {@linkplain GridPointValuePair grid point value pair} at the nearest corner of the
105 * {@linkplain GridValueCell grid value cell}. In other words, a continuous grid coverage
106 * that uses nearest neighbour interpolation acts as a discrete surface coverage.
107 *
108 * @throws PointOutsideCoverageException if the point is outside the coverage domain.
109 * @throws CannotEvaluateException If the point can't be evaluated for some other reason.
110 */
111 @UML(identifier="evaluate", obligation=MANDATORY, specification=ISO_19123)
112 Set<Record> evaluate(DirectPosition p, Collection<String> list)
113 throws PointOutsideCoverageException, CannotEvaluateException;
114
115 /**
116 * Provides the data for the {@linkplain #evaluate evaluate} operation.
117 *
118 * @return The underlying data.
119 */
120 @UML(identifier="source", obligation=MANDATORY, specification=ISO_19123)
121 GridValuesMatrix getSource();
122 }