sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1557608 - in /sis/branches/JDK7/core: sis-referencing/src/main/java/org/apache/sis/referencing/cs/ sis-utility/src/main/java/org/apache/sis/measure/
Date Sun, 12 Jan 2014 20:21:36 GMT
Author: desruisseaux
Date: Sun Jan 12 20:21:35 2014
New Revision: 1557608

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

Modified:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AxesConvention.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Angle.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Latitude.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Longitude.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=1557608&r1=1557607&r2=1557608&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] Sun Jan 12 20:21:35 2014
@@ -50,7 +50,7 @@ import org.opengis.referencing.cs.Coordi
  *
  * {@section Range of longitude values}
  * 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}.
+ * designed to work in that range. This is also the range of {@link Math} trigonometric functions
like {@code atan2(y,x)}.
  * 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>
@@ -72,13 +72,12 @@ public enum AxesConvention {
     /**
      * 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. 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.
+     * (<var>x</var>,<var>y</var>) axis order. However a right-handed
coordinate system does not guarantee
+     * that longitude or <var>x</var> axis will be first (see for example the
(North, West) case below).
      *
-     * {@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.}
+     * {@note We do not provide a "<cite>longitude or <var>x</var> axis
first</cite>" enumeration value because
+     *        such criterion is hard to apply to inter-cardinal directions and 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):
@@ -86,7 +85,7 @@ public enum AxesConvention {
      *   <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>
+     *     <tr><td>(West, North)</td> <td>(North, West)</td>
<td>This right-handed system has latitude first.</td></tr>
      *     <tr><td>(South, West)</td> <td>(West, South)</td>
<td>Used for the mapping of southern Africa.</td></tr>
      *     <tr><td>(South along 0°,<br>South along 90° West)</td>
      *         <td>(South along 90° West,<br>South along 0°)</td> <td>Can
be used for the mapping of North pole.</td></tr>

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Angle.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Angle.java?rev=1557608&r1=1557607&r2=1557608&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Angle.java [UTF-8]
(original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Angle.java [UTF-8]
Sun Jan 12 20:21:35 2014
@@ -30,9 +30,20 @@ import static org.apache.sis.math.MathFu
 
 
 /**
- * An angle in decimal degrees. An angle is the amount of rotation needed to bring one line
or
- * plane into coincidence with another, generally measured in degrees, sexagesimal degrees
or
- * grads.
+ * An angle in decimal degrees. An angle is the amount of rotation needed to bring one line
or plane
+ * into coincidence with another, generally measured in degrees, sexagesimal degrees or grads.
+ * Various kind of angles are used in geographic information systems,
+ * some of them having a specialized class in Apache SIS:
+ *
+ * <ul>
+ *   <li>{@linkplain Latitude} is an angle which ranges from 0° at the equator to
90° at the poles.</li>
+ *   <li>{@linkplain Longitude} is an angle measured east-west from a prime meridian
+ *       (usually Greenwich, but not necessarily).</li>
+ *   <li><cite>Azimuth</cite> is a direction given by an angle between
0° and 360° measured clockwise from North.</li>
+ *   <li><cite>Bearing</cite> is a direction given by an angle between
0° and 90° in a quadrant defined by a cardinal
+ *       direction. Bearing is also sometime used for an angle relative to a vessel forward
direction.</li>
+ *   <li><cite>Interior angle</cite> is an angle measured between two lines
of sight.</li>
+ * </ul>
  *
  * {@section Formatting angles}
  * The recommended way to format angles is to instantiate an {@link AngleFormat} once, then
to

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Latitude.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Latitude.java?rev=1557608&r1=1557607&r2=1557608&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Latitude.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Latitude.java
[UTF-8] Sun Jan 12 20:21:35 2014
@@ -20,6 +20,27 @@ package org.apache.sis.measure;
 /**
  * A latitude angle in decimal degrees.
  * Positive latitudes are North, while negative latitudes are South.
+ * The latitude symbol is the Greek lower-case letter phi (φ).
+ *
+ * <p>Because the Earth is not a perfect sphere, there is small differences in the
latitude values of a point
+ * depending on how the latitude is defined:</p>
+ *
+ * <ul>
+ *   <li><cite>Geodetic latitude</cite> is the angle between the equatorial
plane and a line perpendicular
+ *       to the {@linkplain org.apache.sis.referencing.datum.DefaultEllipsoid ellipsoid}
surface.</li>
+ *   <li><cite>Geocentric latitude</cite> is the angle between the equatorial
plane and a line going from
+ *       the Earth center. It differs from geodetic latitude by less than 11 angular minutes.</li>
+ *   <li><cite>Astronomical latitude</cite> is the angle between the equatorial
plane and a line given
+ *       by the direction of a plumb line (the "true vertical").</li>
+ *   <li>Above list is not exhaustive. There is also <cite>geomagnetic latitude</cite>,
<i>etc.</i></li>
+ * </ul>
+ *
+ * The kind of latitude is unspecified by this {@code Latitude} class, and rather depends
on the context:
+ * the latitude is <cite>geodetic</cite> if the coordinate reference system is
+ * {@linkplain org.apache.sis.referencing.crs.DefaultGeographicCRS geographic},
+ * or <cite>geocentric</cite> if the coordinate reference system is
+ * {@linkplain org.apache.sis.referencing.crs.DefaultGeocentricCRS geocentric}.
+ * If the context is unknown, geodetic latitude can usually be assumed.
  *
  * {@section Immutability and thread safety}
  * This final class is immutable and thus inherently thread-safe.

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Longitude.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Longitude.java?rev=1557608&r1=1557607&r2=1557608&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Longitude.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/Longitude.java
[UTF-8] Sun Jan 12 20:21:35 2014
@@ -20,6 +20,12 @@ package org.apache.sis.measure;
 /**
  * A longitude angle in decimal degrees.
  * Positive longitudes are East, while negative longitudes are West.
+ * The longitude symbol is the Greek lower-case letter lambda (λ).
+ *
+ * <p>Longitudes are not necessarily relative to the Greenwich meridian. The
+ * {@linkplain org.apache.sis.referencing.datum.DefaultPrimeMeridian prime meridian}
+ * depends on the context, typically specified through the geodetic datum of a
+ * {@linkplain org.apache.sis.referencing.crs.DefaultGeographicCRS geographic CRS}.</p>
  *
  * {@section Immutability and thread safety}
  * This final class is immutable and thus inherently thread-safe.
@@ -74,7 +80,7 @@ public final class Longitude extends Ang
      *
      * @param  string A string to be converted to a {@code Longitude}.
      * @throws NumberFormatException if the string does not contain a parsable angle,
-     *         or represents a latitude angle.
+     *         or represents a longitude angle.
      *
      * @see AngleFormat#parse(String)
      */



Mime
View raw message