org.opengis.geometry.coordinate.GenericCurve Maven / Gradle / Ivy
/*
* GeoTools - The Open Source Java GIS Toolkit
* http://geotools.org
*
* (C) 2011, Open Source Geospatial Foundation (OSGeo)
* (C) 2003-2005, Open Geospatial Consortium Inc.
*
* All Rights Reserved. http://www.opengis.org/legal/
*/
package org.opengis.geometry.coordinate;
import static org.opengis.annotation.Obligation.*;
import static org.opengis.annotation.Specification.*;
import org.opengis.annotation.UML;
import org.opengis.geometry.DirectPosition;
/**
* Common interface for {@linkplain org.opengis.geometry.primitive.Curve curve} and {@linkplain
* org.opengis.geometry.primitive.CurveSegment curve segment}. {@code Curve} and {@code
* CurveSegment} both represent sections of curvilinear geometry, and therefore share a number of
* operation signatures.
*
* @version ISO 19107
* @author Martin Desruisseaux (IRD)
* @since GeoAPI 1.0
*/
@UML(identifier = "GM_GenericCurve", specification = ISO_19107)
public interface GenericCurve {
/**
* Returns the direct position of the first point on the {@code GenericCurve}. This differs from
* the boundary operator in {@link org.opengis.geometry.primitive.Primitive}, since it returns
* only the values of this point, not representative objects.
*
* @return The first point on the {@code GenericCurve}.
* @see #getStartParam
* @see #getEndPoint
*/
@UML(identifier = "startPoint", obligation = MANDATORY, specification = ISO_19107)
DirectPosition getStartPoint();
/**
* Returns the direct position of the last point on the {@code GenericCurve}. This differs from
* the boundary operator in {@link org.opengis.geometry.primitive.Primitive}, since it returns
* only the values of this point, not representative objects.
*
* @return The last point on the {@code GenericCurve}.
* @see #getEndParam
* @see #getStartPoint
*/
@UML(identifier = "endPoint", obligation = MANDATORY, specification = ISO_19107)
DirectPosition getEndPoint();
/**
* Returns the tangent vector along this {@code 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.
*
* @param s The parameter value along this curve.
* @return The tangent unit vector.
* @unitof Distance
* @see #getStartParam
* @see #getEndParam
*/
@UML(identifier = "tangent", obligation = MANDATORY, specification = ISO_19107)
double[] getTangent(double s);
/**
* Indicates the parameter for the {@linkplain #getStartPoint start point}. The start parameter
* of a {@linkplain org.opengis.geometry.primitive.Curve curve} shall always be 0. For
* {@linkplain org.opengis.geometry.primitive.CurveSegment curve segments} within a {@linkplain
* org.opengis.geometry.primitive.Curve curve}, the start of the {@linkplain
* org.opengis.geometry.primitive.CurveSegment curve segment} shall be equal to those of the
* {@linkplain org.opengis.geometry.primitive.Curve 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.
*
* @return The parameter for the {@linkplain #getStartPoint start point}.
* @unitof Distance
* @see #getStartPoint
* @see #getStartConstructiveParam
* @see #getEndParam
* @see #forParam
*/
@UML(identifier = "startParam", obligation = MANDATORY, specification = ISO_19107)
double getStartParam();
/**
* Indicates the parameter for the {@linkplain #getEndPoint end point}. The end parameter of a
* {@linkplain org.opengis.geometry.primitive.Curve curve} shall always be the arc length of the
* curve. For {@linkplain org.opengis.geometry.primitive.CurveSegment curve segments} within a
* {@linkplain org.opengis.geometry.primitive.Curve curve}, the end parameters of the
* {@linkplain org.opengis.geometry.primitive.CurveSegment curve segment} shall be equal to
* those of the {@linkplain org.opengis.geometry.primitive.Curve 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.
*
* @return The parameter for the {@linkplain #getEndPoint end point}.
* @unitof Distance
* @see #getEndPoint
* @see #getEndConstructiveParam
* @see #getStartParam
* @see #forParam
*/
@UML(identifier = "endParam", obligation = MANDATORY, specification = ISO_19107)
double getEndParam();
/**
* Indicates the parameter used in the constructive paramerization for the start point. There is
* no assumption that the {@code startConstructiveParam} is less than the {@code
* 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.
*
*
*
* @return The parameter used in the constructive paramerization for the start point.
* @see #getStartParam
* @see #getEndConstructiveParam
* @see #forConstructiveParam
*/
@UML(identifier = "startConstrParam", obligation = MANDATORY, specification = ISO_19107)
double getStartConstructiveParam();
/**
* Indicates the parameter used in the constructive paramerization for the end point. There is
* no assumption that the {@code startConstructiveParam} is less than the {@code
* 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.
*
*
*
* @return The parameter used in the constructive paramerization for the end point.
* @see #getEndParam
* @see #getStartConstructiveParam
* @see #forConstructiveParam
*/
@UML(identifier = "endConstrParam", obligation = MANDATORY, specification = ISO_19107)
double getEndConstructiveParam();
/**
* 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 {@linkplain org.opengis.geometry.primitive.Curve curve} and its component
* {@linkplain org.opengis.geometry.primitive.CurveSegment 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.
*
* @param cp The constructive parameter.
* @return The direct position for the given constructive parameter.
* @see #getStartConstructiveParam
* @see #getEndConstructiveParam
* @see #forParam
*/
@UML(identifier = "constrParam", obligation = MANDATORY, specification = ISO_19107)
DirectPosition forConstructiveParam(double cp);
/**
* 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 {@code GenericCurve} at the distance passed. The
* parameterization shall be by arc length, i.e. distance along the {@code GenericCurve}
* measured from the start point and added to the start parameter.
*
* @param s The distance from the start point and added to the start parameter.
* @return The direct position for the given parameter.
* @see #getStartParam
* @see #getEndParam
* @see #forConstructiveParam
*/
@UML(identifier = "param", obligation = MANDATORY, specification = ISO_19107)
DirectPosition forParam(double s);
/**
* Returns the parameter for this {@code GenericCurve} at the passed direct position. If the
* direct position is not on the curve, the nearest point on the curve shall be used.
*
* @param p The direct position on the curve.
* @return The parameter closest to the given position.
* @see #getStartPoint
* @see #getEndPoint
* @see #forParam
*/
@UML(identifier = "paramForPoint", obligation = MANDATORY, specification = ISO_19107)
ParamForPoint getParamForPoint(DirectPosition p);
/**
* 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 {@linkplain DirectPosition 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 {@linkplain
* org.opengis.geometry.primitive.Curve curve}.
*
* @param point1 The first point, or {@code null} for the {@linkplain #getStartPoint start
* point}.
* @param point2 The second point, or {@code null} for the {@linkplain #getEndPoint end point}.
* @return The length between the two specified points.
* @unitof Length
*/
@UML(identifier = "length", obligation = MANDATORY, specification = ISO_19107)
double length(Position point1, Position point2);
/**
* Returns the length between two constructive parameters. This second form of the method {@code
* 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({@linkplain #getStartConstructiveParam startConstructiveParam}, constructiveParam)
* + {@linkplain #getStartParam startParam}
*
*
* 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 {@code 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 {@code 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.
*
*
*
* @param maxSpacing The maximal distance between control points along the generated curve, or 0
* for no constraint.
* @param maxOffset The maximal distance between generated curve at any point and the original
* curve, or 0 for no constraint.
* @return The an approximation of this curve as a line string.
* @unitof Distance (for arguments)
*/
@UML(identifier = "asLineString", obligation = MANDATORY, specification = ISO_19107)
LineString asLineString(double maxSpacing, double maxOffset);
}