/*$************************************************************************************************
**
** $Id: GeometryFactory.java 831 2006-05-01 00:27:23Z Desruisseaux $
**
** $URL: http://svn.code.sf.net/p/geoapi/code/branches/2.0.x/geoapi/src/main/java/org/opengis/spatialschema/geometry/geometry/GeometryFactory.java $
**
** Copyright (C) 2003-2005 Open GIS Consortium, Inc.
** All Rights Reserved. http://www.opengis.org/legal/
**
*************************************************************************************************/
package org.opengis.spatialschema.geometry.geometry;
// J2SE direct dependencies
import java.util.List;
import java.util.Set;
// OpenGIS direct dependencies
import org.opengis.referencing.crs.CoordinateReferenceSystem;
import org.opengis.spatialschema.geometry.DirectPosition;
import org.opengis.spatialschema.geometry.Envelope;
import org.opengis.spatialschema.geometry.MismatchedDimensionException;
import org.opengis.spatialschema.geometry.MismatchedReferenceSystemException;
import org.opengis.spatialschema.geometry.aggregate.MultiPrimitive;
import org.opengis.spatialschema.geometry.primitive.Ring;
import org.opengis.spatialschema.geometry.primitive.Surface;
import org.opengis.spatialschema.geometry.primitive.SurfaceBoundary;
// Annotations
import org.opengis.annotation.UML;
import static org.opengis.annotation.Obligation.*;
import static org.opengis.annotation.Specification.*;
/**
* A factory of {@linkplain org.opengis.spatialschema.geometry.Geometry geometries}.
* All geometries created through this interface will use the
* {@linkplain #getCoordinateReferenceSystem factory's coordinate reference system}.
* Creating geometries in a different CRS may requires a different instance of
* {@code GeometryFactory}.
*
* @version Abstract specification 5
* @author Martin Desruisseaux (IRD)
* @since GeoAPI 1.0
*/
public interface GeometryFactory {
/**
* Returns the coordinate reference system in use for all
* {@linkplain org.opengis.spatialschema.geometry.Geometry geometries}
* to be created through this interface.
*/
CoordinateReferenceSystem getCoordinateReferenceSystem();
/**
* Create a direct position with empty coordinates.
*/
DirectPosition createDirectPosition();
/**
* Create a direct position at the specified location specified by coordinates.
*/
DirectPosition createDirectPosition(double[] coordinates);
/**
* Creates a new Envelope with the given corners.
*
* @param lowerCorner A coordinate position consisting of all the maximal ordinates for each
* dimension for all points within the envelope.
* @param upperCorner A coordinate position consisting of all the minimal ordinates for each
* dimension for all points within the envelope.
*
* @throws MismatchedReferenceSystemException If the coordinate positions don't use
* compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If the coordinate position don't have compatible dimension.
*/
Envelope createEnvelope(DirectPosition lowerCorner, DirectPosition upperCorner)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Takes two positions and creates the appropriate line segment joining them.
*
* @param startPoint The {@linkplain LineSegment#getStartPoint start point}.
* @param endPoint The {@linkplain LineSegment#getEndPoint end point}.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
@UML(identifier="GM_LineSegment(GM_Position[2])", obligation=MANDATORY, specification=ISO_19107)
LineSegment createLineSegment(Position startPoint, Position endPoint)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Takes two or more positions and creates the appropriate line string joining them.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
@UML(identifier="GM_LineString(GM_Position[2..n])", obligation=MANDATORY, specification=ISO_19107)
LineString createLineString(List points)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Takes two positions and creates the appropriate geodesic joining them.
*
* @param startPoint The {@linkplain Geodesic#getStartPoint start point}.
* @param endPoint The {@linkplain Geodesic#getEndPoint end point}.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
Geodesic createGeodesic(Position startPoint, Position endPoint)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Takes two or more positions, interpolates using a geodesic defined from
* the geoid (or {@linkplain org.opengis.referencing.datum.Ellipsoid ellipsoid}) of the
* {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem coordinate reference system}
* being used, and creates the appropriate geodesic string joining them.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
@UML(identifier="GM_GeodesicString(GM_Position[2..n])", obligation=MANDATORY, specification=ISO_19107)
GeodesicString createGeodesicString(List points)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Takes three positions and constructs the corresponding arc.
*
* @param startPoint The {@linkplain Arc#getStartPoint start point}.
* @param midPoint Some point on the arc neither at the start or end.
* @param endPoint The {@linkplain Arc#getEndPoint end point}.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
@UML(identifier="GM_Arc(GM_Position[3])", obligation=MANDATORY, specification=ISO_19107)
Arc createArc(Position startPoint, Position midPoint, Position endPoint)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Takes two positions and the offset of the midpoint of the arc from the midpoint of
* the chord, given by a distance and direction, and constructs the corresponding arc.
* The midpoint of the resulting arc is given by:
*
* midPoint = ((startPoint + endPoint)/2.0) + bulge×normal
*
* In 2D coordinate reference systems, the bulge can be given a sign and the normal can be
* assumed to be the perpendicular to the line segment between the start and end point of
* the arc (the chord of the arc), pointing left. For example if the two points are
* P0 = (x0, y0) and
* P1 = (x1, y1), and
* the bulge is b, then the vector in the direction of P1
* from P0 is:
*
*
* u = (u0, u1) =
* (x1-x0,
* y1-y0) /
* {@link Math#sqrt sqrt}((x1-x0)2 +
* (y1-y0)2)
*
*
* To complete a right-handed local coordinate system {u,v}, the two vectors
* must have a vector dot product of zero and a vector cross product of 1. By inspection,
* the leftward normal to complete the pair is:
*
*
* v = (v0, v1) =
* (-u1, u0)
*
*
* The midpoint of the arc, which is the midpoint of the chord offset by the bulge, becomes:
*
*
* m = (P0 + P1)/2
* + b×v
*
*
* This is leftward if b > 0
* and rightward if b < 0.
*
* @param startPoint The {@linkplain Arc#getStartPoint start point}.
* @param endPoint The {@linkplain Arc#getEndPoint end point}.
* @param bulge The distance of the midpoint of the arc from the midpoint of the chord.
* @param normal A direction normal to the chord.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
@UML(identifier="GM_Arc(GM_Position[2],Real,Vector)", obligation=MANDATORY, specification=ISO_19107)
Arc createArc(Position startPoint, Position endPoint, double bulge, double[] normal)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Takes a sequence of {@linkplain Position positions} and constructs a sequence of
* 3-point arcs jointing them. By the nature of an arc string, the sequence must have
* an odd number of positions.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
@UML(identifier="GM_ArcString(GM_Position[3, 5, 7...])", obligation=MANDATORY, specification=ISO_19107)
ArcString createArcString(List points)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Equivalents to the {@linkplain #createArc(Position,Position,double,double[]) second
* constructor of arc}, except the bulge representation is maintained. The midpoint of
* the resulting arc is given by:
*
* midPoint = ((startPoint + endPoint)/2.0) + bulge×normal
*
* @param startPoint The {@linkplain ArcByBulge#getStartPoint start point}.
* @param endPoint The {@linkplain ArcByBulge#getEndPoint end point}.
* @param bulge The distance of the midpoint of the arc from the midpoint of the chord.
* @param normal A direction normal to the chord.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
@UML(identifier="GM_ArcByBulge(GM_Position[2],Real,Vector)", obligation=MANDATORY, specification=ISO_19107)
ArcByBulge createArcByBulge(Position startPoint, Position endPoint, double bulge, double[] normal)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Equivalent to the {@linkplain #createArc(Position,Position,double,double[]) second
* constructor of arc}, except the bulge representation is maintained internal to the
* object. The midpoints of the resulting arc is given by:
*
*
* midPoint[n] = ((points[n] + points[n+1])/2.0) + (bulge * normal)
*
*
* @param points The points to use as {@linkplain Arc#getStartPoint start} and
* {@linkplain Arc#getEndPoint end points} for each arc. This list size
* must be equals to the {@code bulge} array length plus 1.
* @param bulges The distances of the midpoint of the arc from the midpoint of the chord.
* @param normals The directions normal to the chord. This list size must be the same than
* the {@code bulge} array length.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
@UML(identifier="GM_ArcStringByBulge(GM_Position[2..n],Real[1..n],Vector[1..n])", obligation=MANDATORY, specification=ISO_19107)
ArcStringByBulge createArcStringByBulge(List points, double[] bulges,
List normals)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Constructs a B-spline curve. If the {@code knotSpec} is {@code null}, then the
* {@link KnotType} is uniform and the knots are evenly spaced, and except for the
* first and last have multiplicity = 1. At the ends the knots are of multiplicity =
* {@code degree}+1. If the {@code knotType} is uniform they need not be specified.
*
* NOTE: If the B-spline curve is uniform and degree = 1, the B-spline
* is equivalent to a polyline ({@link LineString}). If the {@code knotType} is
* {@linkplain KnotType#PIECEWISE_BEZIER piecewise Bezier}, then the knots are
* defaulted so that they are evenly spaced, and except for the first and last
* have multiplicity equal to degree. At the ends the knots are of multiplicity =
* {@code degree}+1.
*
* @param degree The algebraic degree of the basis functions.
* @param points An array of points that are used in the interpolation in this spline curve.
* @param knots The sequence of distinct knots used to define the spline basis functions.
* @param knotSpec The type of knot distribution used in defining this spline.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
@UML(identifier="GM_BSplineCurve(Integer,GM_PointArray,Sequence,GM_KnotType)", obligation=MANDATORY, specification=ISO_19107)
BSplineCurve createBSplineCurve(int degree, PointArray points, List knots, KnotType knotSpec)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Constructs a B-spline surface. If the {@code knotSpec} is not present, then the
* {@code knotType} is uniform and the knots are evenly spaced, and, except for the
* first and last, have multiplicity = 1. At the ends the knots are of multiplicity
* = degree+1. If the {@code knotType} is uniform they need not be specified.
*
* @param points Arrays of points that are used in the interpolation in this spline surface.
* @param degree The algebraic degree of the basis functions for the first and second parameter,
* as an array of length 1 or 2. If only one value is given, then the two degrees
* are equal.
* @param knots The sequence of knots as an array of length 2, or {@code null} if unspecified.
* @param knotSpec The type of knot distribution used in defining this spline, or
* {@code null} if unspecified.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
@UML(identifier="GM_BSplineSurface(Sequence,Integer,Sequence,GM_KnotType)", obligation=MANDATORY, specification=ISO_19107)
BSplineSurface createBSplineSurface(List points, int[] degree, List[] knots, KnotType knotSpec)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Creates a polygon directly from a set of boundary curves (organized into a
* surface boundary) which shall be defined using coplanar {@linkplain Position positions}
* as control points.
*
* NOTE: The meaning of exterior in the surface boundary is consistent
* with the plane of the constructed planar polygon.
*
* @param boundary The surface boundary.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
@UML(identifier="GM_Polygon(GM_SurfaceBondary)", obligation=MANDATORY, specification=ISO_19107)
Polygon createPolygon(SurfaceBoundary boundary)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Creates a polygon lying on a spanning surface. There is no restriction of the types of
* interpolation used by the composite curves used in the {@linkplain SurfaceBoundary
* surface boundary}, but they must all be lie on the
* {@linkplain Polygon#getSpanningSurface spanning surface} for the process to succeed.
*
* NOTE: It is important that the boundary components be oriented properly
* for this to work. It is often the case that in bounded manifolds, such as the sphere,
* there is an ambiguity unless the orientation is properly used.
*
* @param boundary The surface boundary.
* @param spanSurface The spanning surface.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
@UML(identifier="GM_Polygon(GM_SurfaceBondary,GM_Surface)", obligation=MANDATORY, specification=ISO_19107)
Polygon createPolygon(SurfaceBoundary boundary, Surface spanSurface)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Constructs a restricted Delaunay network from triangle corners (posts),
* breaklines, stoplines, and maximum length of a triangle side.
*
* @param post The corners of the triangles in the TIN.
* @param stopLines lines where the local continuity or regularity of the surface is questionable.
* @param breakLines lines of a critical nature to the shape of the surface.
* @param maxLength Maximal length for retention.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
@UML(identifier="GM_Tin(Set,Set,Set,Number)", obligation=MANDATORY, specification=ISO_19107)
Tin createTin(Set post, Set stopLines,
Set breakLines, double maxLength)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Constructs polyhedral surface from the facet polygons.
*
* @param tiles The facet polygons. Must contains at least one polygon.
*
* @throws MismatchedReferenceSystemException If geometric objects given in argument don't
* use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
* @throws MismatchedDimensionException If geometric objects given in argument don't have
* the expected dimension.
*/
@UML(identifier="GM_PolyhedralSurace(GM_Polygon)", obligation=MANDATORY, specification=ISO_19107)
PolyhedralSurface createPolyhedralSurface(List tiles)
throws MismatchedReferenceSystemException, MismatchedDimensionException;
/**
* Placeholder to create a MultiPrimitive (or derivatives).
*
* @deprecated This method is temporary. It will move to some {@code MultiPrimitive}
* factory when the creation of Geometry interfaces will be completed.
* See GEO-1 on JIRA.
*/
@Deprecated
MultiPrimitive createMultiPrimitive();
}
Ads help maintain this website.