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.util.Record;
037 import org.opengis.geometry.DirectPosition;
038 import org.opengis.annotation.UML;
039
040 import static org.opengis.annotation.Obligation.*;
041 import static org.opengis.annotation.Specification.*;
042
043
044 /**
045 * A coverage that returns the same record of feature attribute values for any direct position
046 * within a single {@linkplain DomainObject object} in its domain. The domain of a discrete coverage
047 * consists of a collection of geometric objects. Discrete coverages are subclassed on the basis of
048 * the type of geometric object in the spatial domain. Each subclass of {@code DiscreteCoverage} is
049 * associated with a specific subclass of {@link GeometryValuePair}.
050 *
051 * @version ISO 19123:2004
052 * @author Martin Desruisseaux (IRD)
053 * @author Wim Koolhoven
054 * @since GeoAPI 2.1
055 */
056 @UML(identifier="CV_DiscreteCoverage", specification=ISO_19123)
057 public interface DiscreteCoverage extends Coverage {
058 /**
059 * Returns the set of <var>geometry</var>-<var>value</var> pairs included in this coverage.
060 *
061 * @return The set of <var>geometry</var>-<var>value</var> pairs, or {@code null}.
062 *
063 * @todo Is it duplicating {@link Coverage#list}?
064 */
065 @UML(identifier="element", obligation=OPTIONAL, specification=ISO_19123)
066 Set<? extends GeometryValuePair> getElements();
067
068 /**
069 * Returns the set of <var>geometry</var>-<var>value</var> pairs that include the
070 * {@linkplain DomainObject domain objects} containing the specified direct position.
071 * It shall return {@code null} if the direct position is not on any of the
072 * {@linkplain DomainObject objects} within the domain of the discrete coverage.
073 *
074 * @param p The position where to search for <var>geometry</var>-<var>value</var> pairs.
075 * @return <var>geometry</var>-<var>value</var> pairs, or {@code null}.
076 */
077 @UML(identifier="locate", obligation=OPTIONAL, specification=ISO_19123)
078 Set<? extends GeometryValuePair> locate(DirectPosition p);
079
080 /**
081 * Returns a set of records of feature attribute values for the specified direct position.
082 * Normally, the input direct position will fall within only one <var>geometry</var>-<var>value</var>
083 * pair, and the operation will return the record of feature attribute values associated with that
084 * <var>geometry</var>-<var>value</var> pair. If the direct position falls on the boundary between
085 * two <var>geometry</var>-<var>value</var> pairs, or within two or more overlapping
086 * <var>geometry</var>-<var>value</var> pairs, the operation shall return a record of feature
087 * attribute values derived according to the {@linkplain Coverage#getCommonPointRule common point rule}.
088 * It shall return an empty set if the direct position is not on any of the
089 * {@linkplain DomainObject objects} within the domain of the discrete coverage.
090 *
091 * @throws PointOutsideCoverageException if the point is outside the coverage domain.
092 * @throws CannotEvaluateException If the point can't be evaluated for some other reason.
093 */
094 @UML(identifier="evaluate", obligation=MANDATORY, specification=ISO_19123)
095 Set<Record> evaluate(DirectPosition p, Collection<String> list) throws CannotEvaluateException;
096
097 /**
098 * Locates the <var>geometry</var>-<var>value</var> pairs for which value equals the input
099 * record, and return the set of {@linkplain DomainObject domain objects} belonging to those
100 * <var>geometry</var>-<var>value</var> pairs. It shall return {@code null} set if none of the
101 * <var>geometry</var>-<var>value</var> pairs associated with this discrete coverage has a
102 * value equal to the input record.
103 */
104 @UML(identifier="evaluateInverse", obligation=OPTIONAL, specification=ISO_19123)
105 Set<? extends DomainObject<?>> evaluateInverse(Record v);
106 }