001    /*
002     *    GeoAPI - Java interfaces for OGC/ISO standards
003     *    http://www.geoapi.org
004     *
005     *    Copyright (C) 2004-2012 Open Geospatial Consortium, Inc.
006     *    All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007     *
008     *    Permission to use, copy, and modify this software and its documentation, with
009     *    or without modification, for any purpose and without fee or royalty is hereby
010     *    granted, provided that you include the following on ALL copies of the software
011     *    and documentation or portions thereof, including modifications, that you make:
012     *
013     *    1. The full text of this NOTICE in a location viewable to users of the
014     *       redistributed or derivative work.
015     *    2. Notice of any changes or modifications to the OGC files, including the
016     *       date changes were made.
017     *
018     *    THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019     *    NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020     *    TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021     *    THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022     *    PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023     *
024     *    COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025     *    CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026     *
027     *    The name and trademarks of copyright holders may NOT be used in advertising or
028     *    publicity pertaining to the software without specific, written prior permission.
029     *    Title to copyright in this software and any associated documentation will at all
030     *    times remain with copyright holders.
031     */
032    package org.opengis.geometry.coordinate;
033    
034    import org.opengis.geometry.primitive.CurveSegment;
035    import org.opengis.annotation.UML;
036    
037    import static org.opengis.annotation.Obligation.*;
038    import static org.opengis.annotation.Specification.*;
039    
040    
041    /**
042     * The clothoid (or Cornu's spiral), a plane curve whose curvature is a fixed function of
043     * its length. In suitably chosen co-ordinates it is given by Fresnel's integrals:
044     *
045     * <P><center>(TODO: paste the equation here)</center></P>
046     *
047     * This geometry is mainly used as a transition curve between curves of type straight
048     * line/circular arc or circular arc/circular arc. With this curve type it is possible
049     * to achieve a C2-continous transition between the above mentioned curve types. One
050     * formula for the clothoid is <var>A</var><sup>2</sup> = <var>R</var>&times;<var>t</var>
051     * where <var>A</var> is a constant, <var>R</var> is the varying radius of curvature along
052     * the curve and <var>t</var> is the length along the curve and given in the Fresnel integrals.
053     *
054     * @version <A HREF="http://www.opengeospatial.org/standards/as">ISO 19107</A>
055     * @author Martin Desruisseaux (IRD)
056     * @since GeoAPI 2.0
057     */
058    @UML(identifier="GM_Clothoid", specification=ISO_19107)
059    public interface Clothoid extends CurveSegment {
060        /**
061         * Returns an affine mapping that places the curve defined by the Fresnel Integrals
062         * into the coordinate reference system of this object.
063         */
064        @UML(identifier="refLocation", obligation=MANDATORY, specification=ISO_19107)
065        AffinePlacement getReferenceLocation();
066    
067        /**
068         * Gives the value for <var>A</var> in the equations above.
069         */
070        @UML(identifier="scaleFactor", obligation=MANDATORY, specification=ISO_19107)
071        double getScaleFactor();
072    
073        /**
074         * Returns the arc length distance from the inflection point that will be the
075         * {@linkplain #getStartPoint start point} for this curve segment. This shall
076         * be lower limit <var>t</var> used in the Fresnel integral and is the value
077         * of the constructive parameter of this curve segment at its start point. The
078         * start parameter can be either positive or negative. The parameter <var>t</var>
079         * acts as a constructive parameter.
080         *
081         * <P>NOTE: If 0 lies between the {@linkplain #getStartConstructiveParam start constructive
082         * parameter} and {@linkplain #getEndConstructiveParam end constructive parameter} of the
083         * clothoid, then the curve goes through the clothoid's inflection point, and the direction
084         * of its radius of curvature, given by the second derivative vector, changes sides
085         * with respect to the tangent vector. The term "length" for the parameter {@code t}
086         * is applicable only in the parameter space, and its relation to arc length after use of
087         * the placement, and with respect to the coordinate reference system of the curve is not
088         * deterministic.</P>
089         */
090        @UML(identifier="startParameter", obligation=MANDATORY, specification=ISO_19107)
091        double getStartConstructiveParam();
092    
093        /**
094         * Returns the arc length distance from the inflection point that will be the
095         * {@linkplain #getEndPoint end point} for this curve segment. This shall be
096         * upper limit <var>t</var> used in the Fresnel integral and is the constructive
097         * parameter of this curve segment at its end point. The end constructive param
098         * can be either positive or negative.
099         */
100        @UML(identifier="endParameter", obligation=MANDATORY, specification=ISO_19107)
101        double getEndConstructiveParam();
102    }