sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1557065 - /sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AxesConvention.java
Date Fri, 10 Jan 2014 09:35:37 GMT
Author: desruisseaux
Date: Fri Jan 10 09:35:36 2014
New Revision: 1557065

URL: http://svn.apache.org/r1557065
Log:
Javadoc.

Modified:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AxesConvention.java

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AxesConvention.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AxesConvention.java?rev=1557065&r1=1557064&r2=1557065&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AxesConvention.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AxesConvention.java
[UTF-8] Fri Jan 10 09:35:36 2014
@@ -17,24 +17,44 @@
 package org.apache.sis.referencing.cs;
 
 import org.opengis.referencing.cs.AxisDirection; // For javadoc
+import org.opengis.referencing.cs.CoordinateSystem;
 
 
 /**
- * High-level characteristics about the axes of an ellipsoidal coordinate system.
+ * High-level characteristics about the axes of a coordinate system.
  * This enumeration provides a convenient way to identify some common axes conventions like
- * (<var>latitude</var>, <var>longitude</var>) versus (<var>longitude</var>,
<var>latitude</var>) order,
+ * (<var>latitude</var>, <var>longitude</var>) versus (<var>longitude</var>,
<var>latitude</var>) axis order,
  * or [-180 … +180]° versus [0 … 360]° longitude range.
  *
- * <p>Enumeration values are inferred from the properties of given {@link EllipsoidalCS}
instances.
+ * <p>Enumeration values are inferred from the properties of given {@link CoordinateSystem}
instances.
  * This enumeration does not add new information and does not aim to cover all possible conventions
– it is
  * only a convenience for identifying some common patterns.</p>
  *
+ * {@section Axis order}
+ * The axis order is specified by the authority (typically a national agency) defining the
Coordinate Reference System
+ * (CRS). The order depends on the CRS type and the country defining the CRS. In the case
of geographic CRS, the
+ * (<var>latitude</var>, <var>longitude</var>) axis order is widely
used by geographers and pilotes for centuries.
+ * However software developers tend to consistently use the (<var>x</var>,<var>y</var>)
order for every kind of CRS.
+ * Those different practices resulted in contradictory definitions of axis order for almost
every CRS of kind
+ * {@code GeographicCRS}, for some {@code ProjectedCRS} in the South hemisphere (South Africa,
Australia, <i>etc.</i>)
+ * and for some polar projections among others.
+ *
+ * <p>Recent OGC standards mandate the use of axis order as defined by the authority.
Oldest OGC standards used the
+ * (<var>x</var>,<var>y</var>) axis order instead, ignoring any authority
specification. Many softwares still use the
+ * old (<var>x</var>,<var>y</var>) axis order, because it is easier
to implement. Apache SIS supports both conventions.
+ * By default, SIS creates CRS with axis order as defined by the authority. Those CRS are
created by calls to the
+ * {@link org.apache.sis.referencing.CRS#forCode(String)} method. The actual axis order can
be verified after the CRS
+ * creation with {@code System.out.println(crs)}. If (<var>x</var>,<var>y</var>)
axis order is wanted for compatibility
+ * with older OGC specifications or other softwares, CRS forced to longitude first axis order
can be created using the
+ * {@link #RIGHT_HANDED} enumeration value.</p>
+ *
  * {@section Range of longitude values}
- * This enumeration provides a way to specify whether the range of longitude values is expected
to be positive
- * (typically [0 … 360]°) or if the range mixes positive and negative values (typically
[-180 … +180]°).
- * This information usually has no impact on coordinate transformations. However, they have
an impact on
- * methods that verify the <cite>domain of validity</cite>, for example
- * {@link org.apache.sis.geometry.GeneralEnvelope#normalize()}.
+ * Most geographic CRS have a longitude axis defined in the [-180 … +180]° range. All
map projections in Apache SIS are
+ * designed to work in that range. This is also the range of {@link Math} trigonometric functions
like {@code atan2}.
+ * However some data use the [0 … 360]° range instead. A geographic CRS can be shifted
to that range of longitude values
+ * using the {@link #POSITIVE_RANGE} enumeration value. The choice of longitude range will
impact not only some
+ * coordinate conversions, but also the methods that verify the <cite>domain of validity</cite>
+ * (e.g. {@link org.apache.sis.geometry.GeneralEnvelope#normalize()}).
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.4 (derived from geotk-3.20)
@@ -44,22 +64,26 @@ import org.opengis.referencing.cs.AxisDi
 public enum AxesConvention {
     /**
      * Axis order and ranges are as specified by the authority. For ellipsoidal coordinate
systems defined by
-     * EPSG database, this is often - but not always - (<var>latitude</var>,
<var>longitude</var>) axis order
+     * EPSG database, this is often – but not always – (<var>latitude</var>,
<var>longitude</var>) axis order
      * with longitude values in the [-180 … +180]° range.
      */
     AS_SPECIFIED,
 
     /**
      * Axes are reordered for a <cite>right-handed</cite> coordinate system.
Axis orientations and ranges are unchanged.
-     * This enum is often used for deriving a coordinate system with the (<var>longitude</var>,
<var>latitude</var>)
-     * or (<var>x</var>, <var>y</var>) axis order, but actually does
not guarantee that longitude or <var>x</var> will
-     * be first (see for example the (South, East) case below). Note also that the "<var>x</var>
first" criterion has
-     * no meaning for map projections having their origin on a pole, while the right-handed
rule applies everywhere.
+     * This enum is often used for deriving a coordinate system with the (<var>longitude</var>,
<var>latitude</var>) or
+     * (<var>x</var>,<var>y</var>) axis order. Strictly speaking
a right-handed coordinate system does not guarantee
+     * that longitude or <var>x</var> axis will be first (see for example the
(South, East) case below).
+     * But in practice this works for the coordinate reference systems defined in the EPSG
database.
+     *
+     * {@note We do not provide "<cite>longitude/<var>x</var> axis first</cite>"
enumeration value because
+     *        such criterion has no meaning for map projections over a pole, while the right-handed
rule
+     *        can apply everywhere.}
      *
      * {@example The following table lists some axis orientations in the first column, and
      *           how those axes are reordered in a right-handed coordinate system (second
column):
      * <ul>
-     *   <table>
+     *   <table class="sis">
      *     <tr><th>Left-handed</th>   <th>Right-handed</th>
 <th>Remarks</th></tr>
      *     <tr><td>(North, East)</td> <td>(East, North)</td>
<td>This is the most common case.</td></tr>
      *     <tr><td>(East, South)</td> <td>(South, East)</td>
<td>This right-handed system has latitude first.</td></tr>
@@ -74,14 +98,14 @@ public enum AxesConvention {
     RIGHT_HANDED,
 
     /**
-     * Axes having a <cite>wraparound</cite> range meaning are shifted to their
ranges of positive values.
-     * The unit and range period are unchanged.
+     * Axes having a <cite>wraparound</cite>
+     * {@linkplain org.apache.sis.referencing.cs.DefaultCoordinateSystemAxis#getRangeMeaning()
range meaning}
+     * are shifted to their ranges of positive values. The unit and range period are unchanged.
      *
-     * <p>The most frequent usage of this enum is for shifting longitude values from
[-180 … +180]° to the [0 … 360]°
-     * range. However this enum could also be used with climatological calendars if their
time axis has a wrapround
-     * range meaning.</p>
+     * <p>The most frequent usage of this enum is for shifting longitude values from
the [-180 … +180]° range
+     * to the [0 … 360]° range. However this enum could also be used with climatological
calendars if their
+     * time axis has a wrapround range meaning.</p>
      *
-     * @see org.apache.sis.referencing.cs.DefaultCoordinateSystemAxis#getRangeMeaning()
      * @see org.opengis.referencing.cs.RangeMeaning#WRAPAROUND
      */
     POSITIVE_RANGE



Mime
View raw message