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.gvsig.proj.catalog.CRSDefinition;

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

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

     * @throws UnsupportedOperationException 

     * @throws CoordinateReferenceSystemNotFoundException 

     */

    CRSDefinition getDefinition() throws CoordinateReferenceSystemNotFoundException, UnsupportedOperationException;

    /**

     * 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.

     */

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

    /**

     * 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.

     */

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

}