org.opengis.geometry.coordinate.Conic Maven / Gradle / Ivy
Show all versions of gt-opengis Show documentation
/*
* 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;
import org.opengis.geometry.Geometry;
import org.opengis.geometry.primitive.CurveSegment;
/**
* Any general conic curve. Any of the conic section curves can be canonically represented in polar
* co-ordinates (ρ, φ) as:
*
* 
where "P" is semi-latus rectum and "e" is the eccentricity. This gives a
* conic with focus at the pole (origin), and the vertex on the conic nearest this focus in the
* direction of the polar axis, φ=0.
*
*
For e=0, this is a circle. For 0 < e < 1, this
* is an ellipse. For e=1, this is a parabola. For e>1, this is one branch
* of a hyperbola.
*
*
These generic conics can be viewed in a two-dimensional Cartesian parameter space
* (u, v) given by the usual coordinate conversions
* u=ρcos(φ) and
* v=ρsin(φ). We can then convert this to a 3D coordinate
* reference system by using an affine transformation, (u, v) →
* (x, y, z) which is defined by:
*
*
(TODO: paste the matrix here, same as AffinePlacement)
*
* This gives us φ as the constructive parameter. The {@linkplain DirectPosition
* direct position} given by (x0, y0,
* z0) is the image of the origin in the local coordinate space (u,
* v) Alternatively, the origin may be shifted to the vertex of the conic as
*
*
u' = ρcos(φ) - P/(1 + e)
* and v' = ρsin(φ)
*
*
and v can be used as the constructive parameter. In general, conics with small
* eccentricity and small P, use the first or "central" representation. Those with large
* eccentricity or large P tend to use the second or "linear" representation.
*
* @version ISO 19107
* @author Martin Desruisseaux (IRD)
* @since GeoAPI 1.0
*/
@UML(identifier = "GM_Conic", specification = ISO_19107)
public interface Conic extends CurveSegment {
/**
* Returns an affine transformation object that maps the conic from parameter space into the
* coordinate space of the target coordinate reference system of the conic corresponding to the
* coordinate reference system of the {@linkplain Geometry}. This affine transformation is given
* by the formulae in the class description.
*/
@UML(identifier = "position", obligation = MANDATORY, specification = ISO_19107)
AffinePlacement getPosition();
/**
* Returns {@code false} if the affine transformation is used on the unshifted (u,
* v) and {@code true} if the affine transformation is applied to the shifted
* parameters (u', v'). This controls whether the focus or the vertex of
* the conic is at the origin in parameter space.
*/
@UML(identifier = "shifted", obligation = MANDATORY, specification = ISO_19107)
boolean isShifted();
/**
* Returns the value of the eccentricity parameter "e" used in the defining equation
* above. It controls the general shape of the curve, determining whether the curve is a circle,
* ellipse, parabola, or hyperbola.
*/
@UML(identifier = "eccentricity", obligation = MANDATORY, specification = ISO_19107)
double getEccentricity();
/**
* Returns the value of the parameter "P" used in the defining equation above. It
* controls how broad the conic is at each of its foci.
*/
@UML(identifier = "semiLatusRectum", obligation = MANDATORY, specification = ISO_19107)
double getSemiLatusRectum();
/**
* Return the start point parameter used in the constructive paramerization.
* The following relation must be hold:
*
*
{@linkplain #forConstructiveParam forConstructiveParam}(getStartConstructiveParam())
* .{@linkplain Object#equals equals}( {@link #getStartPoint getStartPoint}() )
*
* There is no assumption that the
* {@linkplain #getStartConstructiveParam start constructive parameter} is less than the
* {@linkplain #getEndConstructiveParam end constructive parameter}, but the parameterization
* must be strictly monotonic (strictly increasing, or strictly decreasing).
*/
@UML(identifier = "startConstrParam", obligation = MANDATORY, specification = ISO_19107)
double getStartConstructiveParam();
/**
* Return the end point parameter used in the constructive paramerization.
* The following relation must be hold:
*
* {@linkplain #forConstructiveParam forConstructiveParam}(getEndConstructiveParam())
* .{@linkplain Object#equals equals}( {@link #getEndPoint getEndPoint}() )
*
* There is no assumption that the
* {@linkplain #getStartConstructiveParam start constructive parameter} is less than the
* {@linkplain #getEndConstructiveParam end constructive parameter}, but the parameterization
* must be strictly monotonic (strictly increasing, or strictly decreasing).
*/
@UML(identifier = "endConstrParam", obligation = MANDATORY, specification = ISO_19107)
double getEndConstructiveParam();
}