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.primitive;
033
034 import org.opengis.annotation.Association;
035 import org.opengis.annotation.UML;
036
037 import static org.opengis.annotation.Obligation.*;
038 import static org.opengis.annotation.Specification.*;
039
040
041 /**
042 * Primitives that can be mirrored into new geometric objects in terms of their internal local
043 * coordinate systems (manifold charts). For curves, the orientation reflects the direction in
044 * which the curve is traversed, that is, the sense of its parameterization. When used as boundary
045 * curves, the surface being bounded is to the "left" of the oriented curve. For surfaces, the
046 * orientation reflects from which direction the local coordinate system can be viewed as right
047 * handed, the "top" or the surface being the direction of a completing <var>z</var>-axis that
048 * would form a right-handed system. When used as a boundary surface, the bounded solid is "below"
049 * the surface. The orientation of points and solids has no immediate geometric interpretation in
050 * 3-dimensional space.
051 * <p>
052 * {@code OrientablePrimitive} objects are essentially references to geometric primitives
053 * that carry an "orientation" reversal flag (either "+" or "-") that determines whether this
054 * primitive agrees or disagrees with the orientation of the referenced object.
055 *
056 * <blockquote><font size=2>
057 * <strong>NOTE:</strong> There are several reasons for subclassing the "positive" primitives
058 * under the orientable primitives. First is a matter of the semantics of subclassing. Subclassing
059 * is assumed to be a "is type of" hierarchy. In the view used, the "positive" primitive is simply
060 * the orientable one with the positive orientation. If the opposite view were taken, and orientable
061 * primitives were subclassed under the "positive" primitive, then by subclassing logic, the
062 * "negative" primitive would have to hold the same sort of geometric description that the
063 * "positive" primitive does. The only viable solution would be to separate "negative" primitives
064 * under the geometric root as being some sort of reference to their opposite. This adds a great
065 * deal of complexity to the subclassing tree. To minimize the number of objects and to bypass this
066 * logical complexity, positively oriented primitives are self-referential (are instances of the
067 * corresponding primitive subtype) while negatively oriented primitives are not.
068 * </font></blockquote>
069 *
070 * @version <A HREF="http://www.opengeospatial.org/standards/as">ISO 19107</A>
071 * @author Martin Desruisseaux (IRD)
072 * @since GeoAPI 1.0
073 */
074 @UML(identifier="GM_OrientablePrimitive", specification=ISO_19107)
075 public interface OrientablePrimitive extends Primitive {
076 /**
077 * Determines which of the two possible orientations this object represents.
078 *
079 * @return +1 for a positive orientation, or -1 for a negative orientation.
080 */
081 @UML(identifier="orientation", obligation=MANDATORY, specification=ISO_19107)
082 int getOrientation();
083
084 /**
085 * Returns the primitive associated with this {@code OrientablePrimitive}.
086 * Each {@linkplain Primitive primitive} of dimension 1 or 2 is associated
087 * to two {@code OrientablePrimitive}s, one for each possible orientation.
088 * For curves and surfaces, there are exactly two orientable primitives
089 * for each geometric object. For the positive orientation, the orientable
090 * primitive shall be the corresponding {@linkplain Curve curve} or
091 * {@linkplain Surface surface}.
092 * <p>
093 * This method is <em>optional</em> since the association in ISO 19107 is navigable
094 * only from {@code Primitive} to {@code OrientablePrimitive}, not the other way.
095 *
096 * @return The primitive, or {@code null} if the association is
097 * not available or not implemented that way.
098 *
099 * @see Primitive#getProxy
100 * @issue http://jira.codehaus.org/browse/GEO-63
101 */
102 @Association("Oriented")
103 @UML(identifier="primitive", obligation=OPTIONAL, specification=ISO_19107)
104 Primitive getPrimitive();
105 }