Application: gvSIG desktop » gvSIG projections

/**

 * gvSIG. Desktop Geographic Information System.

 *

 * Copyright (C) 2018 gvSIG Association.

 * 

 * This file has been adapted from GeoAPI, see 

 * the original copyright headers bellow.

 *

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

 * 

 * ----------

 * 

 *    GeoAPI - Java interfaces for OGC/ISO standards

 *    http://www.geoapi.org

 *

 *    Copyright (C) 2004-2017 Open Geospatial Consortium, Inc.

 *    All Rights Reserved. http://www.opengeospatial.org/ogc/legal

 *

 *    Permission to use, copy, and modify this software and its documentation, with

 *    or without modification, for any purpose and without fee or royalty is hereby

 *    granted, provided that you include the following on ALL copies of the software

 *    and documentation or portions thereof, including modifications, that you make:

 *

 *    1. The full text of this NOTICE in a location viewable to users of the

 *       redistributed or derivative work.

 *    2. Notice of any changes or modifications to the OGC files, including the

 *       date changes were made.

 *

 *    THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE

 *    NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED

 *    TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT

 *    THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY

 *    PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

 *

 *    COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR

 *    CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.

 *

 *    The name and trademarks of copyright holders may NOT be used in advertising or

 *    publicity pertaining to the software without specific, written prior permission.

 *    Title to copyright in this software and any associated documentation will at all

 *    times remain with copyright holders.

 */

package org.gvsig.proj.catalogue.datum;

import java.util.Date;

import org.gvsig.proj.catalogue.IdentifiedObject;

import org.gvsig.proj.catalogue.ref.Extent;

/**

 * Specifies the relationship of a {@linkplain org.opengis.referencing.cs.CoordinateSystem coordinate system}

 * to the earth, thus creating a {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem coordinate

 * reference system}. For {@linkplain org.opengis.referencing.crs.GeocentricCRS geodetic} and

 * {@linkplain org.opengis.referencing.crs.VerticalCRS vertical} coordinate reference systems,

 * the datum relates the coordinate system to the Earth. With other types of coordinate reference systems,

 * the datum may relate the coordinate system to another physical or virtual object.

 *

 * <p>A datum uses a parameter or set of parameters that determine the location of the origin of the

 * coordinate reference system. Each datum subtype can be associated with only specific types of

 * {@linkplain org.opengis.referencing.cs.CoordinateSystem coordinate systems}, documented in their

 * javadoc.</p>

 *

 * Note: gvSIG derived these interfaces from GeoAPI in order to have a simpler API and also to

 * avoid namespace collisions (e.g. GeoAPI 3 vs GeoTools interfaces). There is no plans

 * to evolve these interfaces to adapt them to future GeoAPI versions.

 * 

 * @author  gvSIG Team

 * @author  Martin Desruisseaux (IRD)

 * @version 3.1

 * @since   1.0

 *

 * @see org.opengis.referencing.cs.CoordinateSystem

 * @see org.opengis.referencing.crs.CoordinateReferenceSystem

 */

public interface Datum  extends IdentifiedObject {

    /**

     * A description, possibly including coordinates of an identified point or points, of the

     * relationship used to anchor the coordinate system to the Earth or alternate object.

     * Also known as the "origin", especially for Engineering and Image Datums.

     *

     * <ul>

     *   <li>For a {@link GeodeticDatum}, this anchor may be a point known as the fundamental point,

     *       which is traditionally the point where the relationship between geoid and ellipsoid is defined,

     *       together with a direction from that point. In other cases, the anchor may consist of a

     *       number of points. In those cases, the parameters defining the geoid/ellipsoid relationship

     *       have then been averaged for these points, and the coordinates of the points adopted as the

     *       datum definition.</li>

     *

     *   <li>For an {@link EngineeringDatum}, the anchor may be an identified physical point with the

     *       orientation defined relative to the object.</li>

     *

     *   <li>For an {@link ImageDatum}, the anchor point is usually either the centre of the image or the

     *       corner of the image. The coordinate system orientation is defined through the

     *       {@link org.opengis.referencing.cs.AxisDirection} class.</li>

     *

     *   <li>For a {@link TemporalDatum}, this attribute is not defined. Instead of the anchor point,

     *       a temporal datum carries a separate {@linkplain TemporalDatum#getOrigin() time origin}

     *       of type {@link Date}.</li>

     * </ul>

     *

     * @departure historic

     *   This method has been kept conformant with the specification published in 2003 for compatibility reasons.

     *   The revision published in 2007 renamed this property as <code>anchorDefinition</code>.

     *

     * @return a description of the anchor point, or {@code null} if none.

     *

     * @see VerticalDatum#getVerticalDatumType()

     */

    String getAnchorPoint();

    /**

     * The time after which this datum definition is valid. This time may be precise (e.g. 1997

     * for IRTF97) or merely a year (e.g. 1983 for NAD83). In the latter case, the epoch usually

     * refers to the year in which a major recalculation of the geodetic control network, underlying

     * the datum, was executed or initiated.

     *

     * <p>An old datum can remain valid after a new datum is defined.

     * Alternatively, a datum may be superseded by a later datum, in which case the realization epoch

     * for the new datum defines the upper limit for the validity of the superseded datum.</p>

     *

     * <div class="warning"><b>Upcoming API change - temporal schema</b><br>

     * The return type of this method may change in GeoAPI 4.0 release. It may be replaced by a

     * type matching more closely either ISO 19108 (<cite>Temporal Schema</cite>) or ISO 19103.

     * </div>

     *

     * @return the datum realization epoch, or {@code null} if not available.

     */

    Date getRealizationEpoch();

    /**

     * Area or region or timeframe in which this datum is valid.

     *

     * @return the datum valid domain, or {@code null} if not available.

     *

     * @since 2.1

     */

    Extent getDomainOfValidity();

    /**

     * Description of domain of usage, or limitations of usage, for which this datum object is valid.

     *

     * @return a description of domain of usage, or {@code null} if none.

     *

     * @departure historic

     *   This method has been kept conformant with the specification published in 2003. The revision

     *   published in 2007 replaced the singleton by a collection and changed the obligation

     *   from "optional" to "mandatory", requiring a return value of <cite>"not known"</cite>

     *   if the scope is unknown.

     */

    String getScope();

}