org.opengis.geometry.coordinate.Conic 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;
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 (x₀, y₀,
 * z₀) 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();
}