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 java.util.List;
035 import org.opengis.geometry.coordinate.GenericSurface;
036 import org.opengis.annotation.Association;
037 import org.opengis.annotation.UML;
038
039 import static org.opengis.annotation.Obligation.*;
040 import static org.opengis.annotation.Specification.*;
041
042
043 /**
044 * Surface with a positive orientation.
045 * {@code Surface} is a subclass of {@link Primitive} and is the basis for 2-dimensional
046 * geometry. Unorientable surfaces such as the Möbius band are not allowed. The orientation of
047 * a surface chooses an "up" direction through the choice of the upward normal, which, if the
048 * surface is not a cycle, is the side of the surface from which the exterior boundary appears
049 * counterclockwise. Reversal of the surface orientation reverses the curve orientation of each
050 * boundary component, and interchanges the conceptual "up" and "down" direction of the surface.
051 * If the surface is the boundary of a solid, the "up" direction is usually outward. For closed
052 * surfaces, which have no boundary, the up direction is that of the surface patches, which must
053 * be consistent with one another. Its included {@linkplain SurfacePatch surface patches} describe
054 * the interior structure of a {@code Surface}.
055 *
056 * <blockquote><font size=2>
057 * <strong>NOTE:</strong> Other than the restriction on orientability, no other "validity" condition is required for GM_Surface.
058 * </font></blockquote>
059 *
060 * @version <A HREF="http://www.opengeospatial.org/standards/as">ISO 19107</A>
061 * @author Martin Desruisseaux (IRD)
062 * @since GeoAPI 1.0
063 *
064 * @see PrimitiveFactory#createSurface(List)
065 * @see PrimitiveFactory#createSurface(SurfaceBoundary)
066 */
067 @UML(identifier="GM_Surface", specification=ISO_19107)
068 public interface Surface extends OrientableSurface, GenericSurface {
069 /**
070 * Relates this {@code Surface} to a set of {@linkplain SurfacePatch surface patches} that
071 * shall be joined together to form this surface. Depending on the interpolation method, the set
072 * of patches may require significant additional structure.
073 *
074 * If the surface {@linkplain #getCoordinateDimension coordinate dimension} is 2, then the
075 * entire {@code Surface} is one logical patch defined by linear interpolation from the
076 * boundary.
077 *
078 * @return The list of surface patches. Should never be {@code null} neither empty.
079 *
080 * @see SurfacePatch#getSurface
081 * @see Curve#getSegments
082 * @issue http://jira.codehaus.org/browse/GEO-63
083 */
084 @Association("Segmentation")
085 @UML(identifier="patch", obligation=MANDATORY, specification=ISO_19107)
086 List<? extends SurfacePatch> getPatches();
087
088 /**
089 * Returns the orientable surfaces associated with this surface.
090 *
091 * @return The orientable surfaces as an array of length 2.
092 *
093 * @see OrientableSurface#getPrimitive
094 * @issue http://jira.codehaus.org/browse/GEO-63
095 */
096 @Association("Oriented")
097 @UML(identifier="proxy", obligation=MANDATORY, specification=ISO_19107)
098 OrientableSurface[] getProxy();
099 }