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.geometry.primitive;
033
034 import javax.measure.unit.Unit;
035 import javax.measure.quantity.Angle;
036
037 import org.opengis.annotation.UML;
038 import org.opengis.annotation.Extension;
039
040 import static org.opengis.annotation.Obligation.*;
041 import static org.opengis.annotation.Specification.*;
042
043
044 /**
045 * Represents direction in the coordinate reference system. In a 2D coordinate reference
046 * system, this can be accomplished using a "angle measured from true north" or a 2D vector
047 * point in that direction. In a 3D coordinate reference system, two angles or any 3D vector
048 * is possible. If both a set of angles and a vector are given, then they shall be consistent
049 * with one another.
050 *
051 * @version <A HREF="http://www.opengeospatial.org/standards/as">ISO 19107</A>
052 * @author Martin Desruisseaux (IRD)
053 * @since GeoAPI 1.0
054 */
055 @UML(identifier="Bearing", specification=ISO_19107)
056 public interface Bearing {
057 /**
058 * Returns the unit of values returned by the {@link #getAngles()} method.
059 *
060 * @return The unit of angles.
061 *
062 * @since GeoAPI 2.3
063 */
064 @Extension
065 Unit<Angle> getAngleUnit();
066
067 /**
068 * Returns the azimuth and (optionnaly) the altitude.
069 * In this variant of bearing usually used for 2D coordinate systems, the first angle (azimuth)
070 * is measured from the first coordinate axis (usually north) in a counterclockwise fashion
071 * parallel to the reference surface tangent plane. If two angles are given, the second angle
072 * (altitude) usually represents the angle above (for positive angles) or below (for negative
073 * angles) a local plane parallel to the tangent plane of the reference surface.
074 *
075 * @return An array of length 0, 1 or 2 containing the azimuth and altitude angles,
076 * in units of {@link #getAngleUnit()}.
077 */
078 @UML(identifier="angle", obligation=MANDATORY, specification=ISO_19107)
079 double[] getAngles();
080
081 /**
082 * Returns the direction as a vector.
083 * In this variant of bearing usually used for 3D coordinate systems, the direction is
084 * express as an arbitrary vector, in the coordinate system.
085 *
086 * @return The direction.
087 */
088 @UML(identifier="direction", obligation=MANDATORY, specification=ISO_19107)
089 double[] getDirection();
090 }