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.cs;
019
020import java.util.Map;
021import org.opengis.annotation.UML;
022import static org.opengis.annotation.Specification.*;
023
024
025/**
026 * A 2- or 3-dimensional coordinate system with one distance measured from the origin and two angular coordinates.
027 * In the two-dimensional case, the radius is omitted and may be implicitly an ellipsoid surface.
028 * Not to be confused with an {@link EllipsoidalCS} based on an ellipsoid "degenerated" into a sphere.
029 *
030 * <p>This type of <abbr>CS</abbr> can be used by coordinate reference systems of type
031 * {@link org.opengis.referencing.crs.GeodeticCRS} or
032 * {@link org.opengis.referencing.crs.EngineeringCRS}, potentially in combination with
033 * {@link org.opengis.referencing.crs.DerivedCRS}.
034 * The following examples describe some possible set of axes for spherical CS used with the above-cited CRS:</p>
035 *
036 * <table class="ogc">
037 *   <caption>Example 1: used with a Geocentric CRS</caption>
038 *   <tr><th>Axis name</th> <th>Abbr.</th> <th>Direction</th> <th>Unit</th></tr>
039 *   <tr><td>Spherical latitude</td> <td>Θ</td> <td>{@link AxisDirection#NORTH}</td> <td>degree</td></tr>
040 *   <tr><td>Spherical longitude</td><td>Ω</td> <td>{@link AxisDirection#EAST}</td>  <td>degree</td></tr>
041 *   <tr><td>Geocentric radius</td>  <td>R</td> <td>{@link AxisDirection#UP}</td>    <td>metre</td></tr>
042 * </table>
043 *
044 * <table class="ogc">
045 *   <caption>Example 2: used with an Engineering CRS</caption>
046 *   <tr><th>Axis name</th> <th>Abbr.</th> <th>Direction</th> <th>Unit</th></tr>
047 *   <tr><td>Distance</td>  <td>r</td> <td>{@link AxisDirection#AWAY_FROM}</td>         <td>kilometre</td></tr>
048 *   <tr><td>Longitude</td> <td>φ</td> <td>{@link AxisDirection#COUNTER_CLOCKWISE}</td> <td>degree</td></tr>
049 *   <tr><td>Elevation</td> <td>Θ</td> <td>{@link AxisDirection#UP}</td>                <td>degree</td></tr>
050 * </table>
051 *
052 * @author  OGC Topic 2 (for abstract model and documentation)
053 * @author  Martin Desruisseaux (IRD, Geomatys)
054 * @version 3.1
055 * @since   1.0
056 *
057 * @see CSAuthorityFactory#createSphericalCS(String)
058 * @see CSFactory#createSphericalCS(Map, CoordinateSystemAxis, CoordinateSystemAxis, CoordinateSystemAxis)
059 */
060@UML(identifier="SphericalCS", specification=ISO_19111)
061public interface SphericalCS extends CoordinateSystem {
062}