001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-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.geometry;
033
034 import org.opengis.annotation.UML;
035
036 import static org.opengis.annotation.Obligation.*;
037 import static org.opengis.annotation.Specification.*;
038
039
040 /**
041 * A possibly infinite set; restricted only to values. For example, the integers and the real
042 * numbers are transfinite sets. This is actually the usual definition of set in mathematics,
043 * but programming languages restrict the term set to mean finite set.
044 *
045 * @version <A HREF="http://www.opengeospatial.org/standards/as">ISO 19107</A>
046 * @author Martin Desruisseaux (IRD)
047 * @since GeoAPI 1.0
048 */
049 @UML(identifier="TransfiniteSet", specification=ISO_19107)
050 public interface TransfiniteSet {
051 /**
052 * Returns {@code true} if this {@code TransfiniteSet} contains another
053 * {@code TransfiniteSet}. If the passed {@code TransfiniteSet} is a
054 * {@linkplain org.opengis.geometry.primitive.Point point}, then this operation is the
055 * equivalent of a set-element test for the {@linkplain DirectPosition direct position}
056 * of that point within this {@code TransfiniteSet}.
057 *
058 * <blockquote><font size=2>
059 * <strong>NOTE:</strong> {@code contains} is strictly a set theoretic containment,
060 * and has no dimensionality constraint. In a {@linkplain org.opengis.geometry.complex.Complex
061 * complex}, no {@linkplain org.opengis.geometry.primitive.Primitive primitive} will contain
062 * another unless a dimension is skipped.
063 * </font></blockquote>
064 *
065 * @param pointSet The set to be checked for containment in this set.
066 * @return {@code true} if this set contains all of the elements of the specified set.
067 */
068 boolean contains(TransfiniteSet pointSet);
069
070 /**
071 * Returns {@code true} if this {@code TransfiniteSet} contains a
072 * single point given by a coordinate.
073 *
074 * @param point The point to be checked for containment in this set.
075 * @return {@code true} if this set contains the specified point.
076 */
077 boolean contains(DirectPosition point);
078
079 /**
080 * Returns {@code true} if this {@code TransfiniteSet} intersects another
081 * {@code TransfiniteSet}. Withing a {@linkplain org.opengis.geometry.complex.Complex complex},
082 * the {@linkplain org.opengis.geometry.primitive.Primitive primitives} do not intersect one another.
083 * In general, topologically structured data uses shared geometric objects to
084 * capture intersection information.
085 *
086 * <blockquote><font size=2>
087 * <strong>NOTE:</strong> This intersect is strictly a set theoretic common containment of
088 * {@linkplain DirectPosition direct positions}.
089 * Two {@linkplain org.opengis.geometry.primitive.Curve curves} do not intersect if they share a common
090 * end point because {@linkplain org.opengis.geometry.primitive.Primitive primitives} are considered to be
091 * open (do not contain their boundary).
092 * If two {@linkplain org.opengis.geometry.complex.CompositeCurve composite curves} share a common end point,
093 * then they intersect because {@linkplain org.opengis.geometry.complex.Complex complexes} are considered to
094 * be closed (contain their boundary).
095 * </font></blockquote>
096 *
097 * @param pointSet The set to be checked for intersection with this set.
098 * @return {@code true} if this set intersects some of the elements of the specified set.
099 */
100 boolean intersects(TransfiniteSet pointSet);
101
102 /**
103 * Returns {@code true} if this {@code TransfiniteSet} is equal to another
104 * {@code TransfiniteSet}. Two different instances of {@code TransfiniteSet}
105 * are equal if they return the same boolean value for the operation
106 * {@link #contains(DirectPosition) contains} for every tested {@linkplain DirectPosition
107 * direct position} within the valid range of the coordinate reference system associated
108 * to the object.
109 *
110 * <blockquote><font size=2>
111 * <strong>NOTE:</strong> Since an infinite set of direct positions cannot be tested,
112 * the internal implementation of equal must test for equivalence between two, possibly
113 * quite different, representations. This test may be limited to the resolution of the
114 * coordinate system or the accuracy of the data. Implementations may define a tolerance
115 * that returns {@code true} if the two {@code TransfiniteSet} have the same
116 * dimension and each direct position in this {@code TransfiniteSet} is within a
117 * tolerance distance of a direct position in the passed {@code TransfiniteSet} and
118 * vice versa.
119 * </font></blockquote>
120 *
121 * @param pointSet The set to test for equality.
122 * @return {@code true} if the two set are equals.
123 */
124 boolean equals(TransfiniteSet pointSet);
125
126 /**
127 * Returns the set theoretic union of this {@code TransfiniteSet} and the passed
128 * {@code TransfiniteSet}.
129 *
130 * @param pointSet The second set.
131 * @return The union of both sets.
132 */
133 TransfiniteSet union(TransfiniteSet pointSet);
134
135 /**
136 * Returns the set theoretic intersection of this {@code TransfiniteSet} and the passed
137 * {@code TransfiniteSet}.
138 *
139 * @param pointSet The second set.
140 * @return The intersection of both sets.
141 */
142 TransfiniteSet intersection(TransfiniteSet pointSet);
143
144 /**
145 * Returns the set theoretic difference of this {@code TransfiniteSet} and the passed
146 * {@code TransfiniteSet}.
147 *
148 * @param pointSet The second set.
149 * @return The difference between both sets.
150 */
151 TransfiniteSet difference(TransfiniteSet pointSet);
152
153 /**
154 * Returns the set theoretic symmetric difference of this {@code TransfiniteSet} and the
155 * passed {@code TransfiniteSet}.
156 *
157 * @param pointSet The second set.
158 * @return The symmetric difference between both sets.
159 */
160 TransfiniteSet symmetricDifference(TransfiniteSet pointSet);
161 }