sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1534328 - in /sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum: BursaWolfParameters.java DefaultGeodeticDatum.java
Date Mon, 21 Oct 2013 19:10:17 GMT
Author: desruisseaux
Date: Mon Oct 21 19:10:17 2013
New Revision: 1534328

URL: http://svn.apache.org/r1534328
Log:
Added javadoc.

Modified:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/BursaWolfParameters.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultGeodeticDatum.java

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/BursaWolfParameters.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/BursaWolfParameters.java?rev=1534328&r1=1534327&r2=1534328&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/BursaWolfParameters.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/BursaWolfParameters.java
[UTF-8] Mon Oct 21 19:10:17 2013
@@ -39,9 +39,12 @@ import java.util.Objects;
 
 /**
  * Parameters for a geographic transformation between two datum.
- * The Bursa Wolf parameters shall be applied to geocentric coordinates,
+ * For an explanation of Bursa-Wolf parameters purpose, see the <cite>Bursa-Wolf parameters</cite>
+ * section of {@link DefaultGeodeticDatum} class javadoc.
+ *
+ * <p>The Bursa-Wolf parameters shall be applied to geocentric coordinates,
  * where the <var>X</var> axis points towards the Greenwich Prime Meridian,
- * the <var>Y</var> axis points East, and the <var>Z</var> axis points
North.
+ * the <var>Y</var> axis points East, and the <var>Z</var> axis points
North.</p>
  *
  * {@note The upper case letters are intentional. By convention, (<var>X</var>,
<var>Y</var>, <var>Z</var>)
  *        stand for <cite>geocentric</cite> coordinates while (<var>x</var>,
<var>y</var>, <var>z</var>)
@@ -78,7 +81,7 @@ import java.util.Objects;
  *     </mtable>
  *   </mfenced>
  *   <mo>=</mo>
- *   <mi>dS</mi>
+ *   <mfenced><mn>1</mn><mo>+</mo><mi>dS</mi></mfenced>
  *   <mo>⋅</mo>
  *   <mfenced open="[" close="]">
  *     <mtable>
@@ -142,6 +145,8 @@ import java.util.Objects;
  * @since   0.4 (derived from geotk-1.2)
  * @version 0.4
  * @module
+ *
+ * @see DefaultGeodeticDatum#getBursaWolfParameters()
  */
 @Immutable
 public class BursaWolfParameters extends FormattableObject implements Serializable {
@@ -319,7 +324,7 @@ public class BursaWolfParameters extends
     }
 
     /**
-     * Returns {@code true} if this Bursa Wolf parameters performs no operation.
+     * Returns {@code true} if this Bursa-Wolf parameters performs no operation.
      * This is true when all parameters are set to zero.
      *
      * @return {@code true} if the parameters describe no operation.
@@ -331,7 +336,7 @@ public class BursaWolfParameters extends
     }
 
     /**
-     * Returns {@code true} if this Bursa Wolf parameters contains only translation terms.
+     * Returns {@code true} if this Bursa-Wolf parameters contains only translation terms.
      *
      * @return {@code true} if the parameters describe to a translation only.
      */

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultGeodeticDatum.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultGeodeticDatum.java?rev=1534328&r1=1534327&r2=1534328&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultGeodeticDatum.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultGeodeticDatum.java
[UTF-8] Mon Oct 21 19:10:17 2013
@@ -41,9 +41,36 @@ import java.util.Objects;
 
 
 /**
- * Defines the location and precise orientation in 3-dimensional space of a defined ellipsoid
- * (or sphere) that approximates the shape of the earth. Used also for Cartesian coordinate
- * system centered in this ellipsoid (or sphere).
+ * Defines the location and orientation of an ellipsoid that approximates the shape of the
earth.
+ * Geodetic datum are used together with ellipsoidal coordinate system, and also with Cartesian
+ * coordinate system centered in the ellipsoid (or sphere).
+ *
+ * {@section Bursa-Wolf parameters}
+ * One or many {@link BursaWolfParameters} can optionally be associated to each {@code DefaultGeodeticDatum}
instance.
+ * This association is not part of the ISO 19111 model, but still a common practice (especially
in older standards).
+ * Associating Bursa-Wolf parameters to geodetic datum is known as the <cite>early-binding</cite>
approach.
+ * A recommended alternative, discussed below, is the <cite>late-binding</cite>
approach.
+ *
+ * <p>There is different methods for transforming coordinates from one geodetic datum
to an other datum,
+ * and Bursa-Wolf parameters are used with some of them. However different set of parameters
may exist
+ * for the same pair of (<var>source</var>, <var>target</var>) datum,
so it is often not sufficient to
+ * know those datum. The (<var>source</var>, <var>target</var>) pair
of CRS are often necessary,
+ * sometime together with the geographic extent of the coordinates to transform.</p>
+ *
+ * <p>Apache SIS searches for datum shift methods (including Bursa-Wolf parameters)
in the EPSG database when a
+ * {@link org.opengis.referencing.operation.CoordinateOperation} or a
+ * {@link org.opengis.referencing.operation.MathTransform} is requested for a pair of CRS.
+ * This is known as the <cite>late-binding</cite> approach.
+ * If a datum shift method is found in the database, it will have precedence over any {@code
BursaWolfParameters}
+ * instance associated to this {@code DefaultGeodeticDatum}. Only if no datum shift method
is found in the database,
+ * then the {@code BursaWolfParameters} associated to the datum may be used as a fallback.</p>
+ *
+ * <p>The Bursa-Wolf parameters association serves an other purpose: when a CRS is
formatted in
+ * <cite>Well Known Text</cite> (WKT) format, the formatted string may contain
a {@code TOWGS84[…]} element
+ * with the parameter values of the transformation to the WGS 84 datum. This element is provided
as a help
+ * for other Geographic Information Systems that support only the <cite>early-binding</cite>
approach.
+ * Apache SIS usually does not need the {@code TOWGS84} element, except as a fallback for
datum that
+ * do not exist in the EPSG database.</p>
  *
  * {@section Creating new geodetic datum instances}
  * New instances can be created either directly by specifying all information to a factory
method (choices 3
@@ -113,7 +140,7 @@ public class DefaultGeodeticDatum extend
     private final PrimeMeridian primeMeridian;
 
     /**
-     * Bursa Wolf parameters for datum shifts, or {@code null} if none.
+     * Bursa-Wolf parameters for datum shifts, or {@code null} if none.
      */
     private final BursaWolfParameters[] bursaWolf;
 
@@ -208,16 +235,17 @@ public class DefaultGeodeticDatum extend
     }
 
     /**
-     * Returns all Bursa Wolf parameters specified in the {@code properties} map at construction
time.
+     * Returns all Bursa-Wolf parameters specified in the {@code properties} map at construction
time.
+     * For a discussion about what Bursa-Wolf parameters are, see the class javadpc.
      *
-     * @return The Bursa Wolf parameters, or an empty array if none.
+     * @return The Bursa-Wolf parameters, or an empty array if none.
      */
     public BursaWolfParameters[] getBursaWolfParameters() {
         return (bursaWolf != null) ? bursaWolf.clone() : EMPTY_ARRAY;
     }
 
     /**
-     * Returns Bursa Wolf parameters for a datum shift toward the specified target, or {@code
null} if none.
+     * Returns Bursa-Wolf parameters for a datum shift toward the specified target, or {@code
null} if none.
      * This method searches only for Bursa-Wolf parameters explicitly specified in the {@code
properties} map
      * given at construction time. This method doesn't try to infer a set of parameters from
indirect informations.
      * For example it does not try to inverse the parameters specified in the {@code target}
datum if none were found
@@ -225,7 +253,7 @@ public class DefaultGeodeticDatum extend
      * If a more elaborated search is wanted, use {@link #getPositionVectorTransformation(GeodeticDatum)}
instead.
      *
      * @param  target The target geodetic datum.
-     * @return Bursa Wolf parameters from this datum to the given target datum, or {@code
null} if none.
+     * @return Bursa-Wolf parameters from this datum to the given target datum, or {@code
null} if none.
      */
     public BursaWolfParameters getBursaWolfParameters(final GeodeticDatum target) {
         if (bursaWolf != null) {
@@ -365,11 +393,11 @@ public class DefaultGeodeticDatum extend
                     return deepEquals(getEllipsoid(),     that.getEllipsoid(),     mode)
&&
                            deepEquals(getPrimeMeridian(), that.getPrimeMeridian(), mode);
                     /*
-                     * HACK: We do not consider Bursa Wolf parameters as a non-metadata field.
+                     * HACK: We do not consider Bursa-Wolf parameters as a non-metadata field.
                      *       This is needed in order to get equalsIgnoreMetadata(...) to
returns
                      *       'true' when comparing the WGS84 constant in this class with
a WKT
                      *       DATUM element with a TOWGS84[0,0,0,0,0,0,0] element. Furthermore,
-                     *       the Bursa Wolf parameters are not part of ISO 19111 specification.
+                     *       the Bursa-Wolf parameters are not part of ISO 19111 specification.
                      *       We don't want two CRS to be considered as different because
one has
                      *       more of those transformation informations (which is nice, but
doesn't
                      *       change the CRS itself).



Mime
View raw message