001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2003-2023 Open Geospatial Consortium, Inc.
004 *    http://www.geoapi.org
005 *
006 *    Licensed under the Apache License, Version 2.0 (the "License");
007 *    you may not use this file except in compliance with the License.
008 *    You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *    Unless required by applicable law or agreed to in writing, software
013 *    distributed under the License is distributed on an "AS IS" BASIS,
014 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 *    See the License for the specific language governing permissions and
016 *    limitations under the License.
017 */
018package org.opengis.referencing.crs;
019
020import org.opengis.referencing.ReferenceSystem;
021import org.opengis.referencing.cs.CoordinateSystem;
022import org.opengis.annotation.UML;
023import org.opengis.annotation.Classifier;
024import org.opengis.annotation.Stereotype;
025
026import static org.opengis.annotation.Specification.*;
027
028
029/**
030 * Base type of all Coordinate Reference Systems (<abbr>CRS</abbr>).
031 * This is the base interface for two cases:
032 *
033 * <ul>
034 *   <li>{@link SingleCRS}, defined by a
035 *       {@linkplain org.opengis.referencing.cs.CoordinateSystem coordinate system} and a
036 *       {@linkplain org.opengis.referencing.datum.Datum datum} or datum ensemble;</li>
037 *   <li>{@link CompoundCRS}, defined as a sequence of {@code SingleCRS}.</li>
038 * </ul>
039 *
040 * <h2>Purpose</h2>
041 * A coordinate reference system (<abbr>CRS</abbr>) captures the choice of values
042 * for the parameters that constitute the degrees of freedom of the coordinate space.
043 * The fact that such a choice has to be made, either arbitrarily or by adopting values from survey measurements,
044 * leads to the large number of coordinate reference systems in use around the world.
045 * It is also the cause of the little understood fact that the latitude and longitude of a point are not unique.
046 * Without the full specification of the coordinate reference system,
047 * coordinates are ambiguous at best and meaningless at worst.
048 *
049 * <h2>Spatiotemporal <abbr>CRS</abbr></h2>
050 * The concept of coordinates may be expanded from a strictly spatial context to include time.
051 * Time is then added as another coordinate to the coordinate tuple. It is even possible to add
052 * two time-coordinates, provided the two coordinates describe different independent quantities.
053 * An example of the latter is the time/space position of a subsurface point of which the vertical
054 * coordinate is expressed as the two-way travel time of a sound signal in milliseconds, as is
055 * common in seismic imaging. A second time-coordinate indicates the time of observation.
056 *
057 * @author  OGC Topic 2 (for abstract model and documentation)
058 * @author  Martin Desruisseaux (IRD, Geomatys)
059 * @version 3.1
060 * @since   1.0
061 */
062@Classifier(Stereotype.ABSTRACT)
063@UML(identifier="CRS", specification=ISO_19111)
064public interface CoordinateReferenceSystem extends ReferenceSystem {
065    /**
066     * Returns the coordinate axes with specified units of measure.
067     * The type of the returned coordinate system <em>should</em> be one of the sub-interfaces defined in
068     * the {@link org.opengis.referencing.cs} package. The subtype implies the mathematical rules that define
069     * how coordinate values are calculated from distances, angles and other geometric elements and vice versa.
070     *
071     * <p>An exception to above recommendation is when this <abbr>CRS</abbr> is an instance of {@link CompoundCRS}.
072     * In that case, the coordinate system type may be hidden and the implied mathematical rules are unspecified.
073     * However the coordinate system object is still useful as a list of axes.</p>
074     *
075     * @return the coordinate axes with specified units of measure.
076     *
077     * @departure generalization
078     *   ISO 19111 defines this method for {@link SingleCRS} only. GeoAPI declares this method in this parent interface
079     *   for user convenience, because <abbr>CRS</abbr> dimension and axes are commonly requested information and are
080     *   always available, directly or indirectly, even for {@link CompoundCRS}.
081     */
082    CoordinateSystem getCoordinateSystem();
083}