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.Curve;
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 * Model phenomena that vary continuously or discontinuously along curves, which may be elements
047 * of a network. The domain of a segmented curve coverage is described by a set of curves and
048 * includes all the direct positions in all of the curves in the set.
049 * <p>
050 * Arc-length parameterization of a curve simplifies interpolation between direct positions on the
051 * curve. Representation of phenomena that vary discontinuously along a curve requires segmentation
052 * of the curve into regions of continuous variation. Such segmentation is also simplified by
053 * arc-length parameterization. {@link Curve} supports arc-length parameterization. In particular,
054 * the operation:
055 * <p>
056 * <blockquote>{@link Curve#getParamForPoint}</blockquote>
057 * <p>
058 * returns the arc-length distance from the start point of the curve to the input direct position.
059 * <p>
060 * A segmented curve coverage operates on a domain composed of {@linkplain Curve curves}. It is
061 * composed of a set of {@link ValueCurve}s, each of which maps feature attribute values to
062 * position on a {@linkplain Curve curve}.
063 *
064 * @version ISO 19123:2004
065 * @author Alessio Fabiani
066 * @author Martin Desruisseaux (IRD)
067 * @since GeoAPI 2.1
068 */
069 @UML(identifier="CV_SegmentedCurveCoverage", specification=ISO_19123)
070 public interface SegmentedCurveCoverage extends ContinuousCoverage {
071 /**
072 * Returns the set of value objects used to evaluate the coverage. This
073 * association is optional - an analytical coverage needs no value objects.
074 */
075 @UML(identifier="element", obligation=OPTIONAL, specification=ISO_19123)
076 Set<ValueCurve> getElements();
077
078 /**
079 * Returns the interpolation method to be used in evaluating the coverage. The default value
080 * shall be "{@linkplain InterpolationMethod#LINEAR linear}". An application schema may define
081 * other interpolation methods.
082 */
083 @UML(identifier="interpolationType", obligation=OPTIONAL, specification=ISO_19123)
084 InterpolationMethod getInterpolationMethod();
085
086 /**
087 * Return the value curve nearest to the specified direct position. The operation shall throw
088 * an exception if the direct position is not close (i.e., within the distance specified by the
089 * tolerance parameter) to one of the {@linkplain ValueCurve value curves} in this segmented
090 * curve coverage. The default value for tolerance is zero.
091 *
092 * @param position The position where to search for a value curve.
093 * @param tolerance The maximal distance between the curve and the specified position.
094 * @return The curve nearest to the specified position.
095 */
096 @UML(identifier="curve", obligation=MANDATORY, specification=ISO_19123)
097 ValueCurve curve(DirectPosition position, double tolerance);
098
099 /**
100 * Return the value curve nearest to the specified direct position. This method is equivalent
101 * to <code>{@linkplain #curve(DirectPosition,double) curve}(position, 0)</code>.
102 *
103 * @param position The position where to search for a value curve.
104 * @return The curve nearest to the specified position.
105 */
106 @UML(identifier="curve", obligation=MANDATORY, specification=ISO_19123)
107 ValueCurve curve(DirectPosition position);
108
109 /**
110 * Returns a set of records of feature attribute values for the specified direct position.
111 * Evaluation of a segmented curve coverage involves several steps:
112 * <p>
113 * <ul>
114 * <li>Invoke {@link #curve} in order to find the {@linkplain ValueCurve value curve}
115 * that contains the input direct position.</li>
116 *
117 * <li>Invoke {@link ValueCurve#segment} in order to find the {@linkplain ValueSegment
118 * value segment} that contains the input direct position.</li>
119 *
120 * <li>If {@code segment} returns a single value segment, use the specified interpolation
121 * type to compute feature attribute values from the associated control values.</li>
122 *
123 * <li>If {@code segment} returns a pair of conterminous {@code ValueSegments}, compute the
124 * feature attribute values according to the rule specified by the {@linkplain
125 * #getCommonPointRule common point rule}.</li>
126 * </ul>
127 *
128 * @throws PointOutsideCoverageException if the point is outside the coverage domain.
129 * @throws CannotEvaluateException If the point can't be evaluated for some other reason.
130 */
131 @UML(identifier="evaluate", obligation=MANDATORY, specification=ISO_19123)
132 Set<Record> evaluate(DirectPosition p, Collection<String> list) throws CannotEvaluateException;
133 }