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)
*/
