Application: gvSIG desktop » gvSIG projections

/* gvSIG. Desktop Geographic Information System.

 *

 * Copyright ? 2007-2012 gvSIG Association

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or (at your option) any later version.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,

 * MA  02110-1301, USA.

 *

 * For any additional information, do not hesitate to contact us

 * at info AT gvsig.com, or visit our website www.gvsig.com.

 */

package org.gvsig.proj;

import javax.measure.Unit;

import javax.measure.quantity.Length;

import org.cresques.cts.IProjection;

import org.gvsig.proj.catalog.CRSDefinition;

import org.gvsig.proj.catalog.CRSType;

import org.gvsig.proj.catalog.TransformationDefinition;

import org.gvsig.proj.catalog.exception.CoordinateReferenceSystemException;

import org.gvsig.proj.catalog.exception.TransformationException;

import org.gvsig.proj.catalog.exception.UnsupportedCoordinateReferenceSystemException;

import org.gvsig.tools.lang.Cloneable;

/**

 * Coordinate Reference System (CRS). A CRS defines how a set of coordinates relate

 * to real positions (on earth, on other planet or in the space). Some CRSs include

 * a projection, which defines a mathematical model to approximate the surface of an

 * area of the earth using a planar surface.

 * 

 * Note that a set of coordinates is meaningless if their CRS is not defined, as these

 * values can refer to different locations on the Earth depending on the CRS being used.

 * 

 * @see http://en.wikipedia.org/wiki/Coordinate_reference_system

 * @see http://en.wikipedia.org/wiki/Map_projection

 * @author gvSIG Team

 */

public interface CoordinateReferenceSystem extends Cloneable {    

    /**

     * Gets the definition of the coordinate reference system. The CRSDefinition

     * fully defines the CRS

     * 

     * @return

     */

    CRSDefinition getDefinition();

    /**

     * Some CRSs include a projection, which defines a mathematical model to approximate

     * the surface of an area of the earth using a planar surface. CRS including a

     * projection are called projected CRSs

     * 

     * @return true if the CRS is projected, false otherwise. It also returns true

     * for derived CRSs whose {@link #getBaseCRS() base CRS} is a projected CRS

     */

    boolean isProjected();

    /**

     * Returns true if the CRS is geographic. It also returns true for derived CRSs

     * whose {@link #getBaseCRS() base CRS} is a geographic CRS. 

     * 

     * @return

     */

    boolean isGeographic();

    /**

     * If this CRS is a projected CRS (or a derived CRS whose base CRS is a projected

     * CRS), it converts coordinates from this CoordinateReferenceSystem to the

     * base Geographic CRS. If the CRS is a geographic CRS, it returns the same

     * coordinates without further transformation.

     * 

     * @param point

     * @return

     * @throws TransformationException if {@link #isProjected()} and 

     * {@link #isGeographic()} are both false

     */

    double[] toGeo(double[] point) throws TransformationException;

    /**

     * Calculates the distance between 2 points on the surface of the Earth.

     * 

     * The distances are calculated based on the characteristics of CRSDefinition,

     * using geodetic distances when possible. Geodetic distances offer highly

     * accurate measurements and are based on the exact shape of the ellipsoid.

     * 

     * If this CRSDefinition is projected, then the geodetic calculations are done

     * using its base (geographic) CRS. If this CRSDefinition is not geodetic nor

     * projected, then Euclidean distances are calculated.

     * 

     * The provided points are considered to be 2D points

     * (additional dimensions are ignored).

     * 

     * @param point1

     * @param point2

     * @param the unit in which the distance should be measure

     * 

     * @return The distance between point1 and point2 measured in the units

     * provided by the unit parameter.

     * @throws CoordinateReferenceSystemException if an error is produced calculating the distance

     */

    double getDistance(double[] point1, double[] point2, Unit<Length> unit) throws CoordinateReferenceSystemException;

    /**

     * Calculates the distance between 2 points on the surface of the Earth.

     *  

     * If this CRS is projected and useBaseCRS is <code>false</code>, then

     * the Euclidean distance is calculated. If the CRS is projected and

     * <code>useBaseCRS</code> is <code>true<code>, then the

     * geodetic distance is calculated, using its base (geographic) CRS.

     * 

     * If the CRS is geodetic, then the geodetic distance is calculated.

     * If the CRS is not projected nor geometric, then the Euclidean distance

     * is calculated.

     * 

     * Geodetic distances offer highly accurate measurements and are based on

     * the exact shape of the ellipsoid.

     * 

     * The provided points are considered to be 2D points

     * (additional dimensions are ignored).

     * 

     * @param point1

     * @param point2

     * @param the unit in which the distance should be measure

     * 

     * @return The distance between point1 and point2 measured in the units

     * provided by the unit parameter.

     * @throws CoordinateReferenceSystemException if an error is produced calculating the distance

     */

    double getDistance(double[] point1, double[] point2, boolean useBaseCRS, Unit<Length> unit) throws CoordinateReferenceSystemException;

    /**

     * Returns a legacy IProjection object, the interface used in older gvSIG

     * versions to represent CoordinateReferenceSystems. This method will be

     * removed in the future, so migrate your code to {@link CoordinateReferenceSystem}

     * and the new API as soon as possible.

     * 

     * @return

     */

    @Deprecated

    IProjection getIProjection();

}