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.Collection;
035 import java.util.Set;
036 import org.opengis.util.Record;
037 import org.opengis.geometry.DirectPosition;
038 import org.opengis.geometry.primitive.Surface;
039 import org.opengis.annotation.UML;
040
041 import static org.opengis.annotation.Obligation.*;
042 import static org.opengis.annotation.Specification.*;
043
044
045 /**
046 * Evaluates a coverage at direct positions within a Thiessen polygon network constructed from a set
047 * of discrete {@linkplain PointValuePair point-value pairs}. Evaluation is based on interpolation
048 * between the centeres of the {@linkplain ThiessenValuePolygon Thiessen value polygons} surrounding
049 * the input position.
050 * <p>
051 * <h3>Thiessen polygon networks</h3>
052 * A finite collection of points on a plane determines a partition of the plane into a collection of
053 * polygons equal in number to the collection of points. A Thiessen polygon is generated from one of
054 * a defining set of points by forming the set of direct positions that are closer to that point than
055 * to any other point in the defining set. The specific point is called the centre of the resulting
056 * polygon. The boundaries between neighbouring polygons are the perpendicular bisectors of the lines
057 * between their respective centres. Each polygon shares each of its edges with exactly one other
058 * polygon. Each polygon contains exactly one point from the defining set. Thiessen polygons are
059 * also known as Voronoi Diagrams or Proximal Sets.
060 * <p>
061 * A Thiessen polygon network is a tessellation of a 2D space using Thiessen polygons. A Thiessen
062 * polygon network provides a structure that supports interpolation of feature attribute values from
063 * the polygon centres to direct positions within the polygons.
064 *
065 * @version ISO 19123:2004
066 * @author Alessio Fabiani
067 * @author Martin Desruisseaux (IRD)
068 * @since GeoAPI 2.1
069 *
070 * @todo Provide a figure derived from figure 11 in ISO 19123.
071 */
072 @UML(identifier="CV_ThiessenPolygonCoverage", specification=ISO_19123)
073 public interface ThiessenPolygonCoverage extends ContinuousCoverage {
074 /**
075 * Returns the set of value objects used to evaluate the coverage. This
076 * association is optional - an analytical coverage needs no value objects.
077 */
078 @UML(identifier="element", obligation=OPTIONAL, specification=ISO_19123)
079 Set<ThiessenValuePolygon> getElements();
080
081 /**
082 * Returns the extent of the Thiessen polygon network. Its boundary determines the boundaries
083 * of the outermost polygons in the network, which would otherwise be unbounded.
084 *
085 * @return The extent of th polygon network.
086 */
087 @UML(identifier="clipArea", obligation=MANDATORY, specification=ISO_19123)
088 Surface getClipArea();
089
090 /**
091 * Returns the interpolation method to be used in evaluating the coverage. The most common
092 * interpolation methods are "{@linkplain InterpolationMethod#LOST_AREA lost area}" and
093 * "{@linkplain InterpolationMethod#NEAREST_NEIGHBOUR nearest neighbour}". Lost area
094 * interpolation can return a different record of feature attribute values for each
095 * direct position within a {@linkplain ThiessenValuePolygon Thiessen value polygon}. On
096 * the other hand, nearest neighbour interpolation will return for any direct position
097 * within a Thiessen polygon the record associated with the {@linkplain PointValuePair
098 * point-value pair} at the centre of the Thiessen polygon. In other words, a
099 * Thiessen polygon coverage that uses nearest neighbour interpolation acts like
100 * a {@linkplain DiscreteSurfaceCoverage discrete surface coverage}.
101 */
102 @UML(identifier="interpolationType", obligation=OPTIONAL, specification=ISO_19123)
103 InterpolationMethod getInterpolationMethod();
104
105 /**
106 * Returns the set of Thiessen values polygon that include the
107 * {@linkplain DomainObject domain objects} containing the specified direct position.
108 */
109 @UML(identifier="locate", obligation=OPTIONAL, specification=ISO_19123)
110 Set<ThiessenValuePolygon> locate(DirectPosition p);
111
112 /**
113 * Returns a set of records of feature attribute values for the specified direct position.
114 * Evaluation of a Thiessen polygon coverage involves two steps. The first is to locate the
115 * {@linkplain ThiessenValuePolygon Thiessen value polygon} that contains the input direct
116 * position; the second is to interpolate the feature attribute values at the direct position
117 * from the {@linkplain PointValuePair point-value pairs} at the centres of the surrounding
118 * Thiessen value polygons.
119 *
120 * @throws PointOutsideCoverageException if the point is outside the coverage domain.
121 * @throws CannotEvaluateException If the point can't be evaluated for some other reason.
122 */
123 @UML(identifier="evaluate", obligation=MANDATORY, specification=ISO_19123)
124 Set<Record> evaluate(DirectPosition p, Collection<String> list) throws CannotEvaluateException;
125 }