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.crs;
033
034 import java.util.Map;
035 import org.opengis.referencing.cs.VerticalCS;
036 import org.opengis.referencing.datum.VerticalDatum;
037 import org.opengis.annotation.UML;
038
039 import static org.opengis.annotation.Obligation.*;
040 import static org.opengis.annotation.Specification.*;
041
042
043 /**
044 * A 1D coordinate reference system used for recording heights or depths. Vertical CRSs make use
045 * of the direction of gravity to define the concept of height or depth, but the relationship with
046 * gravity may not be straightforward.
047 * <p>
048 * By implication, ellipsoidal heights (<var>h</var>) cannot be captured in a vertical coordinate
049 * reference system. Ellipsoidal heights cannot exist independently, but only as inseparable part
050 * of a 3D coordinate tuple defined in a geographic 3D coordinate reference system. However GeoAPI
051 * does not enforce this rule. Some applications may relax this rule and accept ellipsoidal heights
052 * in the following context:
053 *
054 * <ul>
055 * <li><p>As a transient state while parsing <A HREF="../doc-files/WKT.html">Well Known Text</A>,
056 * or any other format based on legacy specifications where ellipsoidal heights were allowed
057 * as an independent axis.</p></li>
058 *
059 * <li><p>As short-lived objects to be passed or returned by methods enforcing type safety, for
060 * example {@link org.opengis.metadata.extent.VerticalExtent#getVerticalCRS}.</p></li>
061 *
062 * <li><p>Other cases at implementor convenience. However implementors are encouraged to
063 * assemble the full 3D CRS as soon as they can.</p></li>
064 * </ul>
065 *
066 * <TABLE CELLPADDING='6' BORDER='1'>
067 * <TR BGCOLOR="#EEEEFF"><TH NOWRAP>Used with CS type(s)</TH></TR>
068 * <TR><TD>
069 * {@link org.opengis.referencing.cs.VerticalCS Vertical}
070 * </TD></TR></TABLE>
071 *
072 * @author Martin Desruisseaux (IRD)
073 * @version 3.0
074 * @since 1.0
075 *
076 * @navassoc 1 - - VerticalDatum
077 * @navassoc 1 - - VerticalCS
078 *
079 * @see CRSAuthorityFactory#createVerticalCRS(String)
080 * @see CRSFactory#createVerticalCRS(Map, VerticalDatum, VerticalCS)
081 */
082 @UML(identifier="SC_VerticalCRS", specification=ISO_19111)
083 public interface VerticalCRS extends SingleCRS {
084 /**
085 * Returns the coordinate system, which must be vertical.
086 */
087 @Override
088 @UML(identifier="coordinateSystem", obligation=MANDATORY, specification=ISO_19111)
089 VerticalCS getCoordinateSystem();
090
091 /**
092 * Returns the datum, which must be vertical.
093 */
094 @Override
095 @UML(identifier="datum", obligation=MANDATORY, specification=ISO_19111)
096 VerticalDatum getDatum();
097 }