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.referencing.datum;
033
034 import java.util.Date;
035 import org.opengis.referencing.IdentifiedObject;
036 import org.opengis.metadata.extent.Extent;
037 import org.opengis.util.InternationalString;
038 import org.opengis.annotation.UML;
039
040 import static org.opengis.annotation.Obligation.*;
041 import static org.opengis.annotation.Specification.*;
042
043
044 /**
045 * Specifies the relationship of a {@linkplain org.opengis.referencing.cs.CoordinateSystem coordinate system}
046 * to the earth, thus creating a {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem coordinate
047 * reference system}. For {@linkplain org.opengis.referencing.crs.GeocentricCRS geodetic} and
048 * {@linkplain org.opengis.referencing.crs.VerticalCRS vertical} coordinate reference systems,
049 * the datum relates the coordinate system to the Earth. With other types of coordinate reference systems,
050 * the datum may relate the coordinate system to another physical or virtual object.
051 * <p>
052 * A datum uses a parameter or set of parameters that determine the location of the origin of the
053 * coordinate reference system. Each datum subtype can be associated with only specific types of
054 * {@linkplain org.opengis.referencing.cs.CoordinateSystem coordinate systems}, documented in their
055 * javadoc.
056 *
057 * @author Martin Desruisseaux (IRD)
058 * @version 3.0
059 * @since 1.0
060 *
061 * @see org.opengis.referencing.cs.CoordinateSystem
062 * @see org.opengis.referencing.crs.CoordinateReferenceSystem
063 *
064 * @navassoc 1 - - Extent
065 */
066 @UML(identifier="CD_Datum", specification=ISO_19111)
067 public interface Datum extends IdentifiedObject {
068 /**
069 * Key for the <code>{@value}</code> property to be given to the
070 * {@linkplain DatumFactory datum factory} <code>createFoo(…)</code> methods.
071 * This is used for setting the value to be returned by {@link #getAnchorPoint()}.
072 *
073 * @see #getAnchorPoint()
074 */
075 String ANCHOR_POINT_KEY = "anchorPoint";
076
077 /**
078 * Key for the <code>{@value}</code> property to be given to the
079 * {@linkplain DatumFactory datum factory} <code>createFoo(…)</code> methods.
080 * This is used for setting the value to be returned by {@link #getRealizationEpoch()}.
081 *
082 * @see #getRealizationEpoch()
083 */
084 String REALIZATION_EPOCH_KEY = "realizationEpoch";
085
086 /**
087 * Key for the <code>{@value}</code> property to be given to the
088 * {@linkplain DatumFactory datum factory} <code>createFoo(…)</code> methods.
089 * This is used for setting the value to be returned by {@link #getDomainOfValidity()}.
090 *
091 * @see #getDomainOfValidity()
092 *
093 * @since 2.1
094 */
095 String DOMAIN_OF_VALIDITY_KEY = "domainOfValidity";
096
097 /**
098 * Key for the <code>{@value}</code> property to be given to the
099 * {@linkplain DatumFactory datum factory} <code>createFoo(…)</code> methods.
100 * This is used for setting the value to be returned by {@link #getScope()}.
101 *
102 * @see #getScope()
103 */
104 String SCOPE_KEY = "scope";
105
106 /**
107 * A description, possibly including coordinates of an identified point or points, of the
108 * relationship used to anchor the coordinate system to the Earth or alternate object.
109 * Also known as the "origin", especially for Engineering and Image Datums.
110 * <p>
111 * <ul>
112 * <li>For a geodetic datum, this anchor may be a point known as the fundamental point, which
113 * is traditionally the point where the relationship between geoid and ellipsoid is defined,
114 * together with a direction from that point. In other cases, the anchor may consist of a
115 * number of points. In those cases, the parameters defining the geoid/ellipsoid relationship
116 * have then been averaged for these points, and the coordinates of the points adopted as the
117 * datum definition.</li>
118 *
119 * <li>For an engineering datum, the anchor may be an identified physical point with the
120 * orientation defined relative to the object.</li>
121 *
122 * <li>For an image datum, the anchor point is usually either the centre of the image or the
123 * corner of the image. The coordinate system orientation is defined through the
124 * {@link org.opengis.referencing.cs.AxisDirection} class.</li>
125 *
126 * <li>For a temporal datum, this attribute is not defined. Instead of the anchor point,
127 * a temporal datum carries a separate time origin of type {@link Date}.</li>
128 * </ul>
129 *
130 * @return A description of the anchor point, or {@code null} if none.
131 *
132 * @see VerticalDatum#getVerticalDatumType()
133 */
134 @UML(identifier="anchorPoint", obligation=OPTIONAL, specification=ISO_19111)
135 InternationalString getAnchorPoint();
136
137 /**
138 * The time after which this datum definition is valid. This time may be precise (e.g. 1997
139 * for IRTF97) or merely a year (e.g. 1983 for NAD83). In the latter case, the epoch usually
140 * refers to the year in which a major recalculation of the geodetic control network, underlying
141 * the datum, was executed or initiated. An old datum can remain valid after a new datum is
142 * defined. Alternatively, a datum may be superseded by a later datum, in which case the
143 * realization epoch for the new datum defines the upper limit for the validity of the
144 * superseded datum.
145 * <p>
146 * <TABLE WIDTH="80%" ALIGN="center" CELLPADDING="18" BORDER="4" BGCOLOR="#FFE0B0">
147 * <TR><TD>
148 * <P align="justify"><B>Warning:</B> The return type of this method may change
149 * in GeoAPI 3.1 release. It may be replaced by a type matching more closely
150 * either ISO 19108 (<cite>Temporal Schema</cite>) or ISO 19103.</P>
151 * </TD></TR>
152 * </TABLE>
153 *
154 * @return The datum realization epoch, or {@code null} if not available.
155 */
156 @UML(identifier="realizationEpoch", obligation=OPTIONAL, specification=ISO_19111)
157 Date getRealizationEpoch();
158
159 /**
160 * Area or region or timeframe in which this datum is valid.
161 *
162 * @return The datum valid domain, or {@code null} if not available.
163 *
164 * @since 2.1
165 */
166 @UML(identifier="domainOfValidity", obligation=OPTIONAL, specification=ISO_19111)
167 Extent getDomainOfValidity();
168
169 /**
170 * Description of domain of usage, or limitations of usage, for which this
171 * datum object is valid.
172 *
173 * @return A description of domain of usage, or {@code null} if none.
174 *
175 * @departure historic
176 * This method has been kept conformant with the specification published in 2003. The revision
177 * published in 2007 replaced the singleton by a collection and changed the obligation
178 * from "optional" to "mandatory", requiring a return value of "<cite>not known</cite>"
179 * if the scope is unknown. This change is still under review.
180 */
181 @UML(identifier="scope", obligation=OPTIONAL, specification=ISO_19111)
182 InternationalString getScope();
183 }