org.opengis.geometry.coordinate
Interface GenericCurve

Show UML class diagram

All Known Subinterfaces:

Arc, ArcByBulge, ArcString, ArcStringByBulge, Bezier, BSplineCurve, Circle, Clothoid, Conic, CubicSpline, Curve, CurveSegment, Geodesic, GeodesicString, LineSegment, LineString, OffsetCurve, PolynomialSpline, SplineCurve

@UML(identifier="GM_GenericCurve",
     specification=ISO_19107)
public interface GenericCurve

Common interface for curve and curve segment. Curve and CurveSegment both represent sections of curvilinear geometry, and therefore share a number of operation signatures.

Since:

1.0

Method Summary

LineString	asLineString(double maxSpacing, double maxOffset) Constructs a line string (sequence of line segments) where the control points (ends of the segments) lie on this curve.
DirectPosition	forConstructiveParam(double cp) Returns the direct position for a constructive parameter.
DirectPosition	forParam(double s) Returns the direct position for a parameter.
CurveBoundary	getBoundary() Returns the geometry of the curve topological boundary.
double	getEndConstructiveParam() Indicates the parameter used in the constructive paramerization for the end point.
double	getEndParam() Indicates the parameter for the end point.
DirectPosition	getEndPoint() Returns the direct position of the last point on the GenericCurve.
ParamForPoint	getParamForPoint(DirectPosition p) Returns the parameter for this GenericCurve at the passed direct position.
PointArray	getSamplePoints() Returns an ordered array of point values that lie on the curve.
double	getStartConstructiveParam() Indicates the parameter used in the constructive paramerization for the start point.
double	getStartParam() Indicates the parameter for the start point.
DirectPosition	getStartPoint() Returns the direct position of the first point on the GenericCurve.
double[]	getTangent(double s) Returns the tangent vector along this GenericCurve at the passed parameter value.
double	length(DirectPosition point1, DirectPosition point2) Returns the length between two points.
double	length(double cparam1, double cparam2) Returns the length between two constructive parameters.
GenericCurve	reverse() Reverses the orientation of the parameterizations of the curve.

Method Detail

getStartPoint

@UML(identifier="startPoint",
     obligation=MANDATORY,
     specification=ISO_19107)
DirectPosition getStartPoint()

Returns the direct position of the first point on the GenericCurve. This differs from the boundary operator in Primitive, since it returns only the values of this point, not representative objects.

Returns:

The first point on the GenericCurve.

See Also:

getStartParam(), getEndPoint()

getEndPoint

@UML(identifier="endPoint",
     obligation=MANDATORY,
     specification=ISO_19107)
DirectPosition getEndPoint()

Returns the direct position of the last point on the GenericCurve. This differs from the boundary operator in Primitive, since it returns only the values of this point, not representative objects.

Returns:

The last point on the GenericCurve.

See Also:

getEndParam(), getStartPoint()

getTangent

@UML(identifier="tangent",
     obligation=MANDATORY,
     specification=ISO_19107)
double[] getTangent(double s)

Returns the tangent vector along this GenericCurve at the passed parameter value. This vector approximates the derivative of the parameterization of the curve. The tangent shall be a unit vector (have length 1.0), which is consistent with the parameterization by arc length.

Parameters:

s - The parameter value along this curve.

Returns:

The tangent unit vector.

See Also:

getStartParam(), getEndParam()

Unit:

Distance

getStartParam

@UML(identifier="startParam",
     obligation=MANDATORY,
     specification=ISO_19107)
double getStartParam()

Indicates the parameter for the start point. The start parameter of a curve shall always be 0. For curve segments within a curve, the start of the curve segment shall be equal to those of the curve where this segment begins, so that the start parameter of any segment (except the first) shall be equal to the end parameter of the previous segment.

Returns:

The parameter for the start point.

See Also:

getStartPoint(), getStartConstructiveParam(), getEndParam(), forParam(double)

Unit:

Distance

getEndParam

@UML(identifier="endParam",
     obligation=MANDATORY,
     specification=ISO_19107)
double getEndParam()

Indicates the parameter for the end point. The end parameter of a curve shall always be the arc length of the curve. For curve segments within a curve, the end parameters of the curve segment shall be equal to those of the curve where this segment ends, so that the start parameter of any segment (except the first) shall be equal to the end parameter of the previous segment.

Returns:

The parameter for the end point.

See Also:

getEndPoint(), getEndConstructiveParam(), getStartParam(), forParam(double)

Unit:

Distance

getStartConstructiveParam

@UML(identifier="startConstrParam",
     obligation=MANDATORY,
     specification=ISO_19107)
double getStartConstructiveParam()

Indicates the parameter used in the constructive paramerization for the start point. There is no assumption that the startConstructiveParam is less than the endConstructiveParam, but the parameterization must be strictly monotonic (strictly increasing, or strictly decreasing).

NOTE: Constructive parameters are often chosen for convenience of calculation, and seldom have any simple relation to arc distances, which are defined as the default parameterization. Normally, geometric constructions will use constructive parameters, as the programmer deems reasonable, and calculate arc length parameters when queried.

Returns:

The parameter used in the constructive paramerization for the start point.

See Also:

getStartParam(), getEndConstructiveParam(), forConstructiveParam(double)

getEndConstructiveParam

@UML(identifier="endConstrParam",
     obligation=MANDATORY,
     specification=ISO_19107)
double getEndConstructiveParam()

Indicates the parameter used in the constructive paramerization for the end point. There is no assumption that the startConstructiveParam is less than the endConstructiveParam, but the parameterization must be strictly monotonic (strictly increasing, or strictly decreasing).

NOTE: Constructive parameters are often chosen for convenience of calculation, and seldom have any simple relation to arc distances, which are defined as the default parameterization. Normally, geometric constructions will use constructive parameters, as the programmer deems reasonable, and calculate arc length parameters when queried.

Returns:

The parameter used in the constructive paramerization for the end point.

See Also:

getEndParam(), getStartConstructiveParam(), forConstructiveParam(double)

forConstructiveParam

@UML(identifier="constrParam",
     obligation=MANDATORY,
     specification=ISO_19107)
DirectPosition forConstructiveParam(double cp)

Returns the direct position for a constructive parameter. This method shall be an alternate representation of the curve as the continuous image of a real number interval without the restriction that the parameter represents the arc length of the curve, nor restrictions between a curve and its component curve segments. The most common use of this operation is to expose the constructive equations of the underlying curve, especially useful when that curve is used to construct a parametric surface.

Parameters:

cp - The constructive parameter.

Returns:

The direct position for the given constructive parameter.

See Also:

getStartConstructiveParam(), getEndConstructiveParam(), forParam(double)

forParam

@UML(identifier="param",
     obligation=MANDATORY,
     specification=ISO_19107)
DirectPosition forParam(double s)

Returns the direct position for a parameter. This method shall be the parameterized representation of the curve as the continuous image of a real number interval. The method returns the direct position on the GenericCurve at the distance passed. The parameterization shall be by arc length, i.e. distance along the GenericCurve measured from the start point and added to the start parameter.

Parameters:

s - The distance from the start point and added to the start parameter.

Returns:

The direct position for the given parameter.

See Also:

getStartParam(), getEndParam(), forConstructiveParam(double)

getParamForPoint

@UML(identifier="paramForPoint",
     obligation=MANDATORY,
     specification=ISO_19107)
ParamForPoint getParamForPoint(DirectPosition p)

Returns the parameter for this GenericCurve at the passed direct position. If the direct position is not on the curve, the nearest point on the curve shall be used.

Parameters:

p - The direct position on the curve.

Returns:

The parameter closest to the given position.

See Also:

getStartPoint(), getEndPoint(), forParam(double)

length

@UML(identifier="length",
     obligation=MANDATORY,
     specification=ISO_19107)
double length(DirectPosition point1,
                                                                     DirectPosition point2)

Returns the length between two points. The length of a piece of curvilinear geometry shall be a numeric measure of its length in a coordinate reference system. Since length is an accumulation of distance, its return value shall be in a unit of measure appropriate for measuring distances. This method shall return the distance between the two points along the curve. The default values of the two parameters shall be the start point and the end point, respectively. If either of the points is not on the curve, then it shall be projected to the nearest direct position on the curve before the distance is calculated. If the curve is not simple and passes through either of the two points more than once, the distance shall be the minimal distance between the two points on this curve.

Parameters:

point1 - The first point, or null for the start point.

point2 - The second point, or null for the end point.

Returns:

The length between the two specified points.

Departure from OGC/ISO specification:
In the ISO 19107:2003 specification, the arguments were {@link org.opengis.geometry.coordinate.Position} objects. However in the ISO 19107:2008 draft specification, the type has been changed to {@link DirectPosition}.

Unit:

Length

length

@UML(identifier="length",
     obligation=MANDATORY,
     specification=ISO_19107)
double length(double cparam1,
                                                                     double cparam2)

Returns the length between two constructive parameters. This second form of the method length shall work directly from the constructive parameters, allowing the direct conversion between the variables used in parameterization and constructive parameters. Distances between direct positions determined by the default parameterization are simply the difference of the parameter. The length function also allows for the conversion of the constructive parameter to the arc length parameter using the following idiom:

param=length(startConstructiveParam, constructiveParam) + startParam

Parameters:

cparam1 - The first constructive parameter.

cparam2 - The second constructive parameter.

Returns:

The length between the two specified constructive parameter.

Unit:

Length

getBoundary

@Draft
@UML(identifier="boundary",
     obligation=MANDATORY,
     specification=ISO_19107)
CurveBoundary getBoundary()

Returns the geometry of the curve topological boundary. If the start point is not equal to the end point, the boundary is a two point array. If the start point is equal to the end point, the boundary is an empty array.

NOTE: The above point array will almost always be two distinct positions, but both curves and CurveSegment can be cycles in themselves. The most likely scenario is that all of the points used will be transients (constructed to support the return value), except for the start point and end point of the aggregated curve. These two positions, in the case where the curve is involved in a complex, will be represented as points in the same complex.

Returns:

The sets of positions on the boundary.

getSamplePoints

@Draft
@UML(identifier="samplePoints",
     obligation=MANDATORY,
     specification=ISO_19107)
PointArray getSamplePoints()

Returns an ordered array of point values that lie on the curve. In most cases, these will be related to control points used in the construction of the segment.

NOTE: The control points of a curve segment are used to control its shape, and are not always on the curve segment itself. For example in a spline curve, the curve segment is given as a weighted vector sum of the control points. Each weight function will have a maximum within the constructive parameter interval, which will roughly correspond to the point on the curve where it passes closest that the corresponding control point. These points, the values of the curve at the maxima of the weight functions, will be the sample points for the curve segment.

Returns:

The control points.

Departure from OGC/ISO specification:
The ISO 19107 specification returns an array of {@link org.opengis.geometry.primitive.Point} object. GeoAPI returns a {@link PointArray} object instead, in order to allow deferred point creation for implementors, and convenient access to the {@code PointArray} methods for users.

asLineString

@UML(identifier="asLineString",
     obligation=MANDATORY,
     specification=ISO_19107)
LineString asLineString(double maxSpacing,
                                                                               double maxOffset)

Constructs a line string (sequence of line segments) where the control points (ends of the segments) lie on this curve. If maxSpacing is given (not zero), then the distance between control points along the generated curve shall be not more than maxSpacing. If maxOffset is given (not zero), the distance between generated curve at any point and the original curve shall not be more than the maxOffset. If both parameters are set, then both criteria shall be met. If the original control points of the curve lie on the curve, then they shall be included in the returned line string's control points. If both parameters are set to zero, then the line string returned shall be constructed from the control points of the original curve.

NOTE: This function is useful in creating linear approximations of the curve for simple actions such as display. It is often referred to as a "stroked curve". For this purpose, the maxOffset version is useful in maintaining a minimal representation of the curve appropriate for the display device being targeted. This function is also useful in preparing to transform a curve from one coordinate reference system to another by transforming its control points. In this case, the maxSpacing version is more appropriate. Allowing both parameters to default to zero does not seem to have any useful geographic nor geometric interpretation unless further information is known about how the curves were constructed.

Parameters:

maxSpacing - The maximal distance between control points along the generated curve, or 0 for no constraint.

maxOffset - The maximal distance between generated curve at any point and the original curve, or 0 for no constraint.

Returns:

The an approximation of this curve as a line string.

Unit:

Distance (for arguments)

reverse

@Draft
@UML(identifier="reverse",
     obligation=MANDATORY,
     specification=ISO_19107)
GenericCurve reverse()

Reverses the orientation of the parameterizations of the curve. In most cases this involves a reversal of the ordering of parameters in the curve segments, and a reversal of the order of the segments with a curve.

Returns:

The reverse of the curve.