You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2017/05/09 23:04:36 UTC
svn commit: r1794656 [6/18] - in /sis/site/trunk/book: en/ en/annex/
en/coverage/ en/geometry/ en/introduction/ en/referencing/ en/utility/
en/xml/ fr/ fr/annex/ fr/coverage/ fr/geometry/ fr/introduction/
fr/referencing/ fr/utility/ fr/xml/
Copied: sis/site/trunk/book/en/referencing/ComponentsOfCRS.html (from r1794573, sis/site/trunk/book/en/referencing.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/referencing/ComponentsOfCRS.html?p2=sis/site/trunk/book/en/referencing/ComponentsOfCRS.html&p1=sis/site/trunk/book/en/referencing.html&r1=1794573&r2=1794656&rev=1794656&view=diff
==============================================================================
--- sis/site/trunk/book/en/referencing.html [UTF-8] (original)
+++ sis/site/trunk/book/en/referencing/ComponentsOfCRS.html [UTF-8] Tue May 9 23:04:35 2017
@@ -20,119 +20,22 @@
under the License.
-->
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
- xmlns:xi = "http://www.w3.org/2001/XInclude">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
- <title>Spatial reference systems</title>
+ <title>ComponentsOfCRS</title>
<meta charset="UTF-8"/>
- <link rel="stylesheet" type="text/css" href="../../content/book/book.css"/>
+ <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "../../content/book/en/developer-guide.html"
+ Content below this point is copied in "(…)/content/book/en/developer-guide.html" file
by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
-->
<section>
<header>
- <h1 id="Referencing">Spatial reference systems</h1>
+ <h2 id="ComponentsOfCRS">Components of a reference system by coordinates</h2>
</header>
<p>
- For locating a point on Earth one can use identifiers like city name or postal address
- — an approach known as <cite>spatial reference systems by identifiers</cite> —
- or use numerical values valid in a given coordinate system like latitudes and longitudes
- — an approach known as <cite>spatial reference systems by coordinates</cite>.
- Each reference system implies approximations like
- the choice of a figure of the Earth (geoid, ellipsoid, <i>etc.</i>) used as an approximation of Earth shape,
- the choice of geometric properties (angles, distances, <i>etc.</i>) to be preserved when a map is shown on plane surface, and
- a lost of precision when coordinates are transformed to systems using a different <a href="#GeodeticDatum">datum</a>.
- </p><p>
- A very common misbelief is that one can avoid this complexity by using a single coordinate reference system
- (typically <abbr title="World Geodetic System 1984">WGS84</abbr>) as a universal system for all data.
- The next chapters will explain why the reality is not so simple.
- Whether a universal reference system can suit an application needs or not depends on the desired positional accuracy
- and the kind of calculations to be performed with the data.
- Unless otherwise specified, Apache <abbr>SIS</abbr> aims to represent coordinates on Earth with an accuracy of one centimetre or better.
- But the accuracy can be altered by various situations:
- </p>
- <ul>
- <li>Points should be inside the domain of validity as given by <code>ReferenceSystem.getDomainOfValidity()</code>.</li>
- <li>Distance measurements in a given map projection are true only is some special locations,
- named for instance “standards parallels”.</li>
- <li>Positional accuracy is altered after coordinate transformations.
- The new accuracy is described by <code>CoordinateOperation.getCoordinateOperationAccuracy()</code>.</li>
- <li>Finding the most appropriate coordinate transformation parameters require the use of a geodetic dataset like <abbr>EPSG</abbr>.
- Declaring those parameters within the <abbr>CRS</abbr> (for example with a <code>TOWGS84</code> element) is often not sufficient.</li>
- </ul>
- <article>
- <header>
- <h2>“Early binding” versus “late binding” implementations</h2>
- </header>
- <p>
- Because of the <abbr>WGS84</abbr> ubiquity, it is tempting to use that system as a hub or a pivot system
- for all coordinate transformations.
- The use of an “universal” system as a pivot simplifies the design of coordinate transformations libraries.
- For example transformations from datum <var>A</var> to datum <var>B</var> can be done by first transforming
- from <var>A</var> to <abbr>WGS84</abbr>, then from <abbr>WGS84</abbr> to <var>B</var>.
- With such approach, a coordinate transformations library would only need to associate each
- <code>GeodeticDatum</code> instance with the transformation parameters from that datum to <abbr>WGS84</abbr>.
- This approach was encouraged in version 1 of <abbr>WKT</abbr> format, since that format specified a
- <code>TOWGS84[…]</code> element (removed in <abbr>WKT</abbr> version 2) precisely for that purpose.
- This approach is known in <abbr>EPSG</abbr> guidance notes as “early binding” implementations
- since information about coordinate transformations are associated early in geodetic object definitions,
- usually right at <code>GeographicCRS</code> creation time.
- While <abbr>EPSG</abbr> acknowledges that this approach is commonly used,
- this is not a recommended strategy for the following reasons:
- </p>
- <ul>
- <li>More than one transformation may exist from datum <var>A</var> to datum <var>B</var>,
- where each transformation is designed for a different geographic area.</li>
- <li>Some operations are designed specifically for transformations from <var>A</var> to <var>B</var>
- and do not have the same accuracy than an operation using <abbr>WGS84</abbr> as an intermediate step.</li>
- <li><abbr>WGS84</abbr> itself has been updated many times,
- which makes it a kind of moving target (admittedly slowly) for coordinate transformations libraries.</li>
- <li>Different systems could be used as the pivot system, for example the <cite>Galileo Reference Frame</cite>
- (<abbr>GTRF</abbr>) created for the European <abbr>GPS</abbr> competitor.</li>
- </ul>
- <div class="example"><p><b>Example:</b>
- the <abbr>EPSG</abbr> geodetic dataset defines about 50 transformations from <abbr>NAD27</abbr> to <abbr>NAD83</abbr>.
- In an early binding approach, the same geographic <abbr>CRS</abbr> (namely “<abbr>NAD27</abbr>”) in the <abbr>WKT</abbr> 1
- format would need to be defined with a <code>TOWGS84[-8, 160, 176]</code> element for coordinates in <abbr>USA</abbr>
- or with a <code>TOWGS84[-10, 158, 187]</code> element for coordinates in Canada.
- Different parameter values exist for other regions like Cuba, so it is not possible to represent such diversity
- with a single <code>TOWGS84[…]</code> element associated to a <abbr>CRS</abbr>.
- But even when restricting <abbr>CRS</abbr> usage to the domain of validity of its single <code>TOWGS84[…]</code> element,
- those transformations are still approximative with a 10 metres accuracy in the <abbr>USA</abbr> case.
- More accurate transformations exist in the form of <abbr>NADCON</abbr> grid shift files,
- but those transformations are from <abbr>NAD27</abbr> to <abbr>NAD83</abbr> (which move together on the same continental plate),
- not to <abbr>WGS84</abbr> (which move independently).
- The difference was often ignored when <abbr>NAD83</abbr> and <abbr>WGS84</abbr> were considered as practically equivalent,
- but that assumption is subject to more caution today.
- </p></div>
- <p>
- <abbr>EPSG</abbr> rather recommends the use of “late binding” approach,
- in which coordinate transformation methods and parameters are defined for
- “<var>A</var> to <var>B</var>” pairs of systems (eventually completed with domain of validity)
- rather than associated to standalone datums.
- Apache <abbr>SIS</abbr> is a “late binding” implementation,
- while some reminiscences of “early binding” approach still exist in the form of the
- <code>DefaultGeodeticDatum.getBursaWolfParameters()</code> property.
- The later is used only if <abbr>SIS</abbr> fails to apply the late binding approach for given reference systems.
- </p>
- </article>
- <p>
- The <code>sis-referencing</code> module provides a set of classes implementing
- different specializations of the <code>ReferenceSystem</code> interface, together with required components.
- Those implementations store spatial reference system descriptions, together with metadata like their domain of validity.
- However those objects do not perform any operation on coordinate values.
- Coordinates <cite>conversions</cite> or <cite>transformations</cite> are performed by another family of types,
- with <code>CoordinateOperation</code> as the root interface.
- Those types will be discussed in <a href="#CoordinateOperation">another section</a>.
- </p>
-
-
-
- <h2 id="CRS_Components">Components of a reference system by coordinates</h2>
- <p>
Spatial reference systems by coordinates provide necessary information for mapping numerical coordinate values
to real-world locations. In Apache <abbr>SIS</abbr>, most information is contained (directly or indirectly) in
classes with a name ending in <abbr>CRS</abbr>, the abbreviation of <i>Coordinate Reference System</i>.
@@ -295,608 +198,6 @@ crs = AbstractCRS.castOrCopy(crs).forCon
<h4 id="CompoundWKT"><i>Well-Known Text</i> format</h4>
<p style="color: red">TODO</p>
-
-
-
- <h2 id="GetCRS">Fetching a spatial reference system</h2>
- <p style="color: red">TODO</p>
-
- <h3 id="CRSAuthorityFactory">Looking <abbr>CRS</abbr> defined by authorities</h3>
- <p style="color: red">TODO</p>
-
- <h3 id="CRSParsing">Reading definitions in GML or WKT format</h3>
- <p style="color: red">TODO</p>
-
- <h3 id="CRSFactory">Constructing programmatically</h3>
- <p style="color: red">TODO</p>
-
- <h3 id="CRS_UserCode">Adding new <abbr>CRS</abbr> definitions</h3>
- <p style="color: red">TODO</p>
-
-
-
- <h2 id="CoordinateOperation">Coordinate operations</h2>
- <p>
- Given a <em>source</em> coordinate reference system (<abbr>CRS</abbr>) in which existing coordinate values are expressed,
- and a <em>target</em> coordinate reference system in which coordinate values are desired,
- Apache <abbr>SIS</abbr> can provide a <em>coordinate operation</em> performing the conversion or transformation work.
- The search for coordinate operations may use a third argument, optional but recommended,
- which is the geographic area of the data to transform.
- That later argument is recommended because coordinate operations are often valid only in a some geographic area
- (typically a particular country or state), and many transformations may exist
- for the same pair of source and target <abbr>CRS</abbr> but different domain of validity.
- Different coordinate operations may also be different compromises between accuracy and their domain of validity,
- and specifying a smaller area of interest may allow Apache <abbr>SIS</abbr> to select a more accurate operation.
- </p>
- <div class="example"><p><b>Example:</b>
- the <abbr>EPSG</abbr> geodetic dataset (as of version 7.9) defines 77 coordinate operations from the
- <cite>North American Datum 1927</cite> (EPSG:4267) coordinate reference system to the
- <cite>World Geodetic System 1984</cite> (EPSG:4326) <abbr>CRS</abbr>.
- There is one operation valid only for coordinate transformations in Québec,
- another operation valid for coordinate transformations in Texas west of 100°W,
- another operation for the same state but east of 100°W, <i>etc</i>.
- If the user did not specified any geographic area of interest,
- then Apache <abbr>SIS</abbr> defaults on the coordinate operation which is valid in the largest area.
- In this example, the “largest area” criterion results in the selection of a coordinate operation valid for Canada,
- not <abbr>USA</abbr>.</p>
- </div>
- <p>
- The easiest way to obtain a coordinate operation from above-cited information
- is to use the <code>org.apache.sis.referencing.CRS</code> convenience class:
- </p>
-
-<pre>CoordinateOperation cop = CRS.findOperation(sourceCRS, targetCRS, areaOfInterest);</pre>
-
- <p>
- Among the information provided by <code>CoordinateOperation</code> object, the following are of special interest:
- </p>
- <ul>
- <li>The <cite>domain of validity</cite>, either as a textual description (e.g. “Canada – onshore and offshore”)
- or with the coordinates of a geographic bounding box.</li>
- <li>The <cite>positional accuracy</cite>, which may be anything from 1 centimetre to a few kilometres.</li>
- <li>The coordinate operation subtype. Among them, two sub-types provide the same functionalities but with a significant conceptual difference:
- <ul class="verbose">
- <li>
- Coordinate <strong>conversions</strong> are fully determined by mathematical formulas.
- Those conversions would have an infinite precision if it was not for the unavoidable rounding errors
- inherent to floating-point calculations.
- Map projections are in this category.
- </li><li>
- Coordinate <strong>transformations</strong> are defined empirically.
- They often have errors of a few metres which are not caused by limitation in computer accuracy.
- Those errors exist because transformations are only approximations of a more complex reality.
- Datum shifts from <abbr title="North American Datum 1927">NAD27</abbr> to <abbr title="North American Datum 1983">NAD83</abbr>
- are in this category.
- </li>
- </ul>
- </li>
- </ul>
- <p>
- If the coordinate operation is an instance of <code>Transformation</code>,
- then the instance selected by <abbr>SIS</abbr> may be one among many possibilities depending on the area of interest.
- Furthermore its accuracy is certainly less than the centimetric accuracy that we can expect from a <code>Conversion</code>.
- Consequently verifying the domain of validity and the positional accuracy declared in the transformation metadata is of particular importance.
- </p>
-
- <h3 id="MathTransform">Executing an operation on coordinate values</h3>
- <p>
- The <code>CoordinateOperation</code> object introduced in above section provides high-level informations
- (source and target <abbr>CRS</abbr>, domain of validity, positional accuracy, operation parameters, <i>etc</i>).
- The actual mathematical work is performed by a separated object obtained by a call to <code>CoordinateOperation.getMathTransform()</code>.
- At the difference of <code>CoordinateOperation</code> instances, <code>MathTransform</code> instances do not carry any metadata.
- They are kind of black box which know nothing about the source and target <abbr>CRS</abbr>
- (actually the same <code>MathTransform</code> can be used for different pairs of <abbr>CRS</abbr> if the mathematical work is the same), domain or accuracy.
- Furthermore <code>MathTransform</code> may be implemented in a very different way than what <code>CoordinateOperation</code> said.
- In particular many conceptually different coordinate operations (e.g. longitude rotations,
- change of units of measurement, conversions between two Mercator projections on the same datum, <i>etc.</i>)
- are implemented by <code>MathTransform</code> as <a href="#AffineTransform">affine transforms</a> and concatenated for efficiency,
- even if <code>CoordinateOperation</code> reports them as a chain of Mercator and other operations.
- The “<a href="#CoordinateOperationSteps">conceptual versus real chain of coordinate operations</a>” section explains the differences in more details.
- </p>
- <p>
- The following Java code performs a map projection from geographic coordinates on the <cite>World Geodetic System 1984</cite> (<abbr>WGS84</abbr>) datum
- coordinates in the <cite>WGS 84 / UTM zone 33N</cite> coordinate reference system.
- In order to make the example a little bit simpler, this code uses predefined constants given by the <code>CommonCRS</code> convenience class.
- But more advanced applications will typically use <abbr>EPSG</abbr> codes instead.
- Note that all geographic coordinates below express latitude before longitude.
- </p>
-
-<pre>import org.opengis.geometry.DirectPosition;
-import org.opengis.referencing.crs.CoordinateReferenceSystem;
-import org.opengis.referencing.operation.CoordinateOperation;
-import org.opengis.referencing.operation.TransformException;
-import org.opengis.util.FactoryException;
-import org.apache.sis.referencing.CRS;
-import org.apache.sis.referencing.CommonCRS;
-import org.apache.sis.geometry.DirectPosition2D;
-
-public class MyApp {
- public static void main(String[] args) throws FactoryException, TransformException {
- CoordinateReferenceSystem sourceCRS = CommonCRS.WGS84.geographic();
- CoordinateReferenceSystem targetCRS = CommonCRS.WGS84.UTM(40, 14); // Get whatever zone is valid for 14°E.
- CoordinateOperation operation = CRS.findOperation(sourceCRS, targetCRS, null);
-
- // The above lines are costly and should be performed only once before to project many points.
- // In this example, the operation that we got is valid for coordinates in geographic area from
- // 12°E to 18°E (UTM zone 33) and 0°N to 84°N.
-
- DirectPosition ptSrc = new DirectPosition2D(40, 14); // 40°N 14°E
- DirectPosition ptDst = operation.getMathTransform().transform(ptSrc, null);
-
- System.out.println("Source: " + ptSrc);
- System.out.println("Target: " + ptDst);
- }
-}</pre>
-
-
- <h3 id="TransformDerivative">Partial derivatives of coordinate operations</h3>
- <p>
- Previous section shows how to project a coordinate from one reference system to another one.
- There is another, less known, operation which does not compute the projected coordinates of a given point,
- but instead the derivative of the projection function at that point.
- This operation was defined in an older Open Geospatial specification,
- <a href="http://www.opengeospatial.org/standards/ct">OGC 01-009</a>, now considered obsolete but still useful.
- Let <var>P</var> be a map projection converting degrees of latitude and longitude (<var>φ</var>, <var>λ</var>)
- into projected coordinates (<var>x</var>, <var>y</var>) in metres.
- The formula below represents the map projection result as a column matrix
- (reason will become clearer soon):
- </p>
-
- <table class="hidden">
- <tr>
- <th>Equation</th>
- <th>Java code</th>
- </tr>
- <tr>
- <td style="vertical-align:middle; min-width:350px; padding-right:60px">
- <math xmlns="http://www.w3.org/1998/Math/MathML" display="block" alttext="MathML capable browser required">
- <mi>P</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo>
- <mo>=</mo>
- <mfenced open="[" close="]">
- <mtable>
- <mtr><mtd><mi>x</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo></mtd></mtr>
- <mtr><mtd><mi>y</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo></mtd></mtr>
- </mtable>
- </mfenced>
- </math>
- </td>
- <td style="vertical-align:middle; min-width:500px; padding-left:60px">
-
-<pre style="margin:0">DirectPosition geographic = new DirectPosition2D(<var>φ</var>, <var>λ</var>);
-DirectPosition projected = <var><b>P</b></var>.transform(geographic, null);
-double <var>x</var> = projected.getOrdinate(0);
-double <var>y</var> = projected.getOrdinate(1);</pre>
-
- </td>
- </tr>
- </table>
-
- <p>The map projection partial derivate at this point can be represented by a Jacobian matrix:</p>
-
- <table class="hidden">
- <tr>
- <th>Equation</th>
- <th>Java code</th>
- </tr>
- <tr>
- <td style="vertical-align:middle; min-width:350px; padding-right:60px">
- <math xmlns="http://www.w3.org/1998/Math/MathML" display="block" alttext="MathML capable browser required">
- <msup><mi>P</mi><mo>′</mo></msup><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo>
- <mo>=</mo>
- <msub><mi>JAC</mi><mrow><mi>P</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo></mrow></msub>
- <mo>=</mo>
- <mfenced open="[" close="]">
- <mtable>
- <mtr>
- <mtd><mfrac><mrow><mo>∂</mo><mi>x</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo></mrow><mrow><mo>∂</mo><mi>φ</mi></mrow></mfrac></mtd>
- <mtd><mfrac><mrow><mo>∂</mo><mi>x</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo></mrow><mrow><mo>∂</mo><mi>λ</mi></mrow></mfrac></mtd>
- </mtr>
- <mtr>
- <mtd><mfrac><mrow><mo>∂</mo><mi>y</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo></mrow><mrow><mo>∂</mo><mi>φ</mi></mrow></mfrac></mtd>
- <mtd><mfrac><mrow><mo>∂</mo><mi>y</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo></mrow><mrow><mo>∂</mo><mi>λ</mi></mrow></mfrac></mtd>
- </mtr>
- </mtable>
- </mfenced>
- </math>
- </td>
- <td style="vertical-align:middle; min-width:500px; padding-left:60px">
-
-<pre style="margin:0">DirectPosition geographic = new DirectPosition2D(<var>φ</var>, <var>λ</var>);
-Matrix jacobian = <var><b>P</b></var>.derivative(geographic);
-double dx_dλ = jacobian.getElement(0,1);
-double dy_dφ = jacobian.getElement(1,0);</pre>
-
- </td>
- </tr>
- </table>
-
- <p>
- Remaining equations in this section will abridge
- ∂<var>x</var>(<var>λ</var>, <var>φ</var>) as ∂<var>x</var> and
- ∂<var>y</var>(<var>λ</var>, <var>φ</var>) as ∂<var>y</var>,
- but reader should keep in mind that each of those derivative values depends on the (<var>λ</var>, <var>φ</var>) coordinate given at Jacobian matrix calculation time.
- The first matrix column tells us that if we apply a small displacement of ∂<var>φ</var> degrees of latitude from the (<var>φ</var>, <var>λ</var>) position,
- — in other words if we move at the (<var>φ</var> + ∂<var>φ</var>, <var>λ</var>) geographic position —
- then the projected coordinate will be displaced by (∂<var>x</var>, ∂<var>λ</var>) metres
- — in other words it will become (<var>x</var> + ∂<var>x</var>, <var>y</var> + ∂<var>λ</var>).
- Similarly the last matrix column gives us the displacement that happen on the projected coordinate
- if we apply a small displacement of ∂<var>λ</var> degrees of longitude on the source geographic coordinate.
- We can visualize such displacements in a figure like below.
- This figure shows the derivative at two points, <var>P</var><sub>1</sub> and <var>P</var><sub>2</sub>,
- for emphasing that the result change for every points.
- In that figure, vectors <var>U</var> et <var>V</var> stand for the first and second column respectively
- in the Jacobian matrices.
- </p>
-
- <table class="hidden"><tr>
- <td><img style="border: solid 1px" src="../../content/book/images/Derivatives.png" alt="Exemple de dérivées d’une projection cartographique"/></td>
- <td style="padding-left: 30px; vertical-align: middle">
- <p>where vectors are related to the matrix by:</p>
- <math xmlns="http://www.w3.org/1998/Math/MathML" display="block" alttext="MathML capable browser required">
- <mtable><mtr>
- <mtd>
- <mover><mi>U</mi><mo>→</mo></mover><mo>=</mo>
- <mfenced open="[" close="]">
- <mtable>
- <mtr>
- <mtd><mfrac><mrow><mo>∂</mo><mi>x</mi></mrow><mrow><mo>∂</mo><mi>φ</mi></mrow></mfrac></mtd>
- </mtr>
- <mtr>
- <mtd><mfrac><mrow><mo>∂</mo><mi>y</mi></mrow><mrow><mo>∂</mo><mi>φ</mi></mrow></mfrac></mtd>
- </mtr>
- </mtable>
- </mfenced>
- </mtd>
- <mtd><mtext>et</mtext></mtd>
- <mtd>
- <mover><mi>V</mi><mo>→</mo></mover><mo>=</mo>
- <mfenced open="[" close="]">
- <mtable>
- <mtr>
- <mtd><mfrac><mrow><mo>∂</mo><mi>x</mi></mrow><mrow><mo>∂</mo><mi>λ</mi></mrow></mfrac></mtd>
- </mtr>
- <mtr>
- <mtd><mfrac><mrow><mo>∂</mo><mi>y</mi></mrow><mrow><mo>∂</mo><mi>λ</mi></mrow></mfrac></mtd>
- </mtr>
- </mtable>
- </mfenced>
- </mtd>
- </mtr></mtable>
- </math>
- </td>
- </tr></table>
-
- <p>
- Above figure shows one usage of map projection derivatives:
- they provide the direction of parallels and meridians at a given location in a map projection.
- One can use that information for determining if axes have been swapped or their direction reversed.
- But the usefulness of map projection derivatives goes further.
- </p>
-
- <h4 id="DerivativeAndEnvelope">Transform derivatives applied to envelopes</h4>
- <p>
- <span style="color: red">TODO</span>
- </p>
- <table class="hidden">
- <tr>
- <th>Envelope before projection</th>
- <th>Geometric shape after projection</th>
- </tr>
- <tr>
- <td><img style="border: solid 1px; margin-right: 15px" src="../../content/book/images/GeographicArea.png" alt="Envelope in a geographic CRS"/></td>
- <td><img style="border: solid 1px; margin-left: 15px" src="../../content/book/images/ConicArea.png" alt="Shape in a projected CRS"/></td>
- </tr>
- </table>
- <p>
- <span style="color: red">TODO</span>
- </p>
- <table class="hidden"><tr><td>
- <img src="../../content/book/images/Approximation.png" alt="Cubic approximation of an envelope bounds"/>
- </td><td style="padding-left: 60px">
- Legend:
- <ul>
- <li><b>Blue:</b> the geometric shape of the envelope after projection.
- This is the shape from which to get a new envelope.</li>
- <li><b>Red</b> (with hash): The
- <var>y</var> = <var>C</var>₀ + <var>C</var>₁λ + <var>C</var>₂λ² + <var>C</var>₃λ³ approximation.</li>
- <li><b>Green</b> (dashed line): Position λ<sub>m</sub> of approximation minimum, obtained by resolving
- 0 = <var>C</var>₁ + 2<var>C</var>₂λ<sub>m</sub> + 3<var>C</var>₃λ<sub>m</sub>².
- The same cubic line can have two minimums.</li>
- </ul>
- </td></tr></table>
- <p>
- <span style="color: red">TODO</span>
- </p>
-
-
- <h4 id="DerivativeAndRaster">Transform derivatives applied to rasters</h4>
- <p>
- <span style="color: red">TODO</span>
- </p>
- <table class="hidden">
- <tr>
- <th style="text-align: left">Source image</th>
- <th style="text-align: right">Destination image</th>
- </tr>
- <tr>
- <td colspan="2"><img src="../../content/book/images/RasterProjection.png" alt="Intersection of derivatives"/></td>
- </tr>
- </table>
- <p>
- <span style="color: red">TODO</span>
- </p>
- <table class="hidden"><tr>
- <td><img src="../../content/book/images/WarpGrid.png" alt="Intersection of derivatives"/></td>
- <td style="padding-left: 60px">
- Legend:
- <ul>
- <li><b>Blue dots:</b> first iteration (9 points).</li>
- <li><b>Green dots:</b> second iteration (25 points, including 16 news).</li>
- <li><b>Red dots:</b> third iteration (81 points, including 56 news).</li>
- </ul>
- Continuing…
- <ul>
- <li>Forth iteration: 289 points, including 208 news.</li>
- <li>Fifth iteration: 1089 points, including 800 news.</li>
- <li>Sixth iteration: 4225 points, including 3136 news.</li>
- <li>…</li>
- </ul>
- </td></tr></table>
- <p>
- <span style="color: red">TODO</span>
- </p>
- <p style="text-align:center"><img style="border: solid 1px" src="../../content/book/images/IntersectionOfDerivatives.png" alt="Intersection of derivatives"/></p>
- <p>
- <span style="color: red">TODO</span>
- </p>
-
- <h4 id="GetDerivative">Getting the derivative at a point</h4>
- <p>
- <span style="color: red">TODO</span>
- Example:</p>
-
-<pre>AbstractMathTransform projection = ...; // An Apache SIS map projection.
-double[] sourcePoint = {longitude, latitude}; // The geographic coordinate to project.
-double[] targetPoint = new double[2]; // Where to store the projection result.
-Matrix derivative = projection.<code class="SIS">transform</code>(sourcePoint, 0, targetPoint, 0, true);</pre>
-
- <p>
- <span style="color: red">TODO</span>
- </p>
-
-<pre>@Override
-public Matrix derivative(DirectPosition p) throws TransformException {
- Matrix jac = inverse().derivative(transform(p));
- return Matrices.inverse(jac);
-}</pre>
-
-
- <h3 id="CoordinateOperationSteps">Conceptual versus real chain of coordinate operations</h3>
- <p>
- Coordinate operations may include many steps, each with their own set of parameters.
- For example transformations from one datum (e.g. <abbr>NAD27</abbr>) to another datum (e.g. <abbr>WGS84</abbr>)
- can be approximated by an affine transform (translation, rotation and scale) applied on the <em>geocentric</em> coordinates.
- This implies that the coordinates must be converted from <em>geographic</em> to geocentric domain before the affine transform,
- then back to geographic domain after the affine transform.
- The result is a three-steps process illustrated in the “Conceptual chain of operations” column of the example below.
- However because that operation chain is very common, the <abbr>EPSG</abbr> geodetic dataset provides a shortcut
- named “Geocentric translation <em>in geographic domain</em>”.
- Using this operation, the conversion steps between geographic and geocentric <abbr>CRS</abbr> are implicit.
- Consequently the datum shifts as specified by <abbr>EPSG</abbr> appears as if it was a single operation,
- but this is not the real operation executed by Apache <abbr>SIS</abbr>.
- </p>
-
- <div class="example"><p><b>Example:</b>
- transformation of geographic coordinates from <abbr>NAD27</abbr> to <abbr>WGS84</abbr> in Canada
- can be approximated by the <abbr>EPSG</abbr>:1172 coordinate operation.
- This single <abbr>EPSG</abbr> operation is actually a chain of three operations in which two steps are implicit.
- The operation as specified by <abbr>EPSG</abbr> is shown in the first column below.
- The same operation with the two hidden steps made explicit is shown in the second column.
- The last column shows the same operation as implemented by Apache <abbr>SIS</abbr> under the hood,
- which contains additional operations discussed below.
- For all columns, input coordinates of the first step and output coordinates of the last step
- are (<var>latitude</var>, <var>longitude</var>) coordinates in degrees.
- </p>
- <div style="display:flex; padding-left:24px">
- <div style="width:30%; padding-right:15px; border-right:1px solid">
- <b>Operation specified by <abbr>EPSG</abbr>:</b>
- <ol>
- <li><b>Geocentric translation</b> in <em>geographic</em> domain
- <ul>
- <li>X-axis translation = -10 m</li>
- <li>Y-axis translation = 158 m</li>
- <li>Z-axis translation = 187 m</li>
- </ul>
- </li>
- </ol>
- Conversions between geographic and geocentric domains are implicit.
- The semi-major and semi-minor axis lengths required for those conversions
- are inferred from the source and target datum.
- </div>
- <div style="width:30%; padding-left:30px; padding-right:15px; border-right:1px solid">
- <b>Conceptual chain of operations:</b>
- <ol>
- <li><b>Geographic to geocentric</b> conversion
- <ul>
- <li>Source semi-major = 6378206.4 m</li>
- <li>Source semi-minor = 6356583.8 m</li>
- </ul>
- </li><li><b>Geocentric translation</b>
- <ul>
- <li>X-axis translation = -10 m</li>
- <li>Y-axis translation = 158 m</li>
- <li>Z-axis translation = 187 m</li>
- </ul>
- </li><li><b>Geocentric to geographic</b> conversion
- <ul>
- <li>Target semi-major = 6378137.0 m</li>
- <li>Target semi-minor ≈ 6356752.3 m</li>
- </ul>
- </li>
- </ol>
- Axis order and units are implicitly defined by the source and target <abbr>CRS</abbr>.
- It is implementation responsibility to perform any needed unit conversions and/or axis swapping.
- </div>
- <div style="width:30%; padding-left:30px">
- <b>Operations actually performed by Apache <abbr>SIS</abbr>:</b>
- <ol>
- <li><b>Affine parametric</b> conversion
- <ul>
- <li>Scale factors (λ and φ) = 0</li>
- <li>Shear factors (λ and φ) = π/180</li>
- </ul>
- </li><li>Ellipsoid (radians domain) to centric conversion
- <ul>
- <li>Eccentricity ≈ 0.08227</li>
- </ul>
- </li><li><b>Affine parametric transformation</b>
- <ul>
- <li>Scale factors (X, Y and Z) ≈ 1.00001088</li>
- <li>X-axis translation ≈ -1.568 E-6</li>
- <li>Y-axis translation ≈ 24.772 E-6</li>
- <li>Z-axis translation ≈ 29.319 E-6</li>
- </ul>
- </li><li>Centric to ellipsoid (radians domain) conversion
- <ul>
- <li>Eccentricity ≈ 0.08182</li>
- </ul>
- </li><li><b>Affine parametric</b> conversion
- <ul>
- <li>Scale factors (λ and φ) = 0</li>
- <li>Shear factors (λ and φ) = 180/π</li>
- </ul>
- </li>
- </ol>
- </div>
- </div>
- <p>
- The operation chain actually performed by Apache <abbr>SIS</abbr> is very different than the conceptual operation chain
- because the coordinate systems are not the same.
- Except for the first and last ones, all Apache <abbr>SIS</abbr> steps work on right-handed coordinate systems
- (as opposed to the left-handed coordinate system when <var>latitude</var> is before <var>longitude</var>),
- with angular units in radians (instead than degrees) and
- linear units relative to an ellipsoid of semi-major axis length of 1 (instead than Earth’s size).
- Working in those coordinate systems requires additional steps for unit conversions and axes swapping
- at the beginning and at the end of the chain.
- Apache <abbr>SIS</abbr> uses <cite>affine parametric conversions</cite> for this purpose,
- which allow to combine axes swapping and unit conversions in a single step
- (see <a href="#AffineTransform">affine transform</a> for more information).
- The reason why Apache <abbr>SIS</abbr> splits conceptual operations in such fine-grained operations
- is to allow more efficient concatenations of operation steps.
- This approach often allows cancellation of two consecutive affine transforms,
- for example a conversion from radians to degrees (e.g. after a <cite>geocentric to ellipsoid</cite> conversion)
- immediately followed by a conversion from degrees to radians (e.g. before a map projection).
- Another example is the <cite>Affine parametric transformation</cite> step above,
- which combines both the <cite>geocentric translation</cite> step
- and a scale factor implied by the ellipsoid change.
- </p>
- </div>
- <p>
- All those operation chains can be viewed in <cite>Well Known Text</cite> (<abbr>WKT</abbr>) or pseudo-<abbr>WKT</abbr> format.
- The simplest operation chain, as specified by the authority, is given directly by the
- <code>String</code> representation of the <code>CoordinateOperation</code> instance.
- This <abbr>WKT</abbr> 2 representation contains not only a description of operations with their parameter values,
- but also additional information about the context in which the operation applies (the source and target <abbr>CRS</abbr>)
- together with some metadata like the accuracy and domain of validity.
- Some operation steps and parameters may be omitted if they can be inferred from the context.
- </p>
- <div class="example">
- <div style="display:flex; padding-left:24px; padding-right:24px">
- <div>
- <p><b>Example:</b>
- the <abbr>WKT</abbr> 2 representation on the right is for the same coordinate operation than the one used in previous example.
- This representation can be obtained by a call to <code>System.out.println(cop)</code>
- where <code>cop</code> is a <code>CoordinateOperation</code> instance.
- Some characteristics of this representation are:
- </p>
- <ul>
- <li><p>The <code>SourceCRS</code> and <code>TargetCRS</code> elements determine axis order and units.
- For this reason, axis swapping and unit conversions do not need to be represented in this <abbr>WKT</abbr>.</p></li>
- <li><p>The “Geocentric translation in geographic domain” operation implies conversions between geographic and geocentric coordinate reference systems.
- Ellipsoid semi-axis lengths are inferred from above <code>SourceCRS</code> and <code>TargetCRS</code> elements,
- so they do not need to be specified in this <abbr>WKT</abbr>.</p></li>
- <li><p>The operation accuracy (20 metres) is much greater than the numerical floating-point precision.
- This kind of metadata could hardly be guessed from the mathematical function alone.</p></li>
- </ul>
- </div>
- <div>
-
-<pre>CoordinateOperation["NAD27 to WGS 84 (3)",
- SourceCRS[<span style="font-family:serif"><i>full CRS definition required here but omitted for brevity</i></span>],
- TargetCRS[<span style="font-family:serif"><i>full CRS definition required here but omitted for brevity</i></span>],
- Method["Geocentric translations (geog2D domain)"],
- Parameter["X-axis translation", -10.0, Unit["metre", 1]],
- Parameter["Y-axis translation", 158.0, Unit["metre", 1]],
- Parameter["Z-axis translation", 187.0, Unit["metre", 1]],
- OperationAccuracy[20.0],
- Area["Canada - onshore and offshore"],
- BBox[40.04, -141.01, 86.46, -47.74],
- Id["EPSG", 1172, "8.9"]]</pre>
-
- </div>
- </div>
- </div>
- <p>
- An operation chain closer to what Apache <abbr>SIS</abbr> really performs is given by the
- <code>String</code> representation of the <code>MathTransform</code> instance.
- In this <abbr>WKT</abbr> 1 representation, contextual information and metadata are lost;
- a <code>MathTransform</code> is like a mathematical function with no knowledge about the meaning of the coordinates on which it operates.
- Since contextual information are lost, implicit operations and parameters become explicit.
- This representation is useful for debugging since any axis swapping operation (for example) become visible.
- Apache <abbr>SIS</abbr> constructs this representation from the data structure in memory,
- but convert them in a more convenient form for human, for example by converting radians to degrees.
- </p>
- <div class="example">
- <div style="display:flex; padding-left:24px; padding-right:24px">
- <div>
- <p><b>Example:</b>
- the <abbr>WKT</abbr> 1 representation on the right is for the same coordinate operation than the one used in previous example.
- This representation can be obtained by a call to <code>System.out.println(cop.getMathTransform())</code>
- where <code>cop</code> is a <code>CoordinateOperation</code> instance.
- Some characteristics of this representation are:
- </p>
- <ul>
- <li><p>Since there is not anymore (on intend) any information about source and target <abbr>CRS</abbr>,
- axis swapping (if needed) and unit conversions must be performed explicitly.
- This is the task of the first and last affine operations in this <abbr>WKT</abbr>.</p></li>
- <li><p>The “Geocentric translation” operation is not anymore applied in the geographic domain, but in the geocentric domain.
- Consequently conversions between geographic and geocentric coordinate reference systems must be made explicit.
- Those explicit steps are also necessary for specifying the ellipsoid semi-axis lengths,
- since they can not anymore by inferred for source and target <abbr>CRS</abbr>.</p></li>
- <li><p>Conversions between geographic and geocentric coordinates are three-dimensional.
- Consequently operations for increasing and reducing the number of dimensions are inserted.
- By default the ellipsoidal height before conversion is set to zero.</p></li>
- </ul>
- </div>
- <div>
-
-<pre>Concat_MT[
- Param_MT["Affine parametric transformation",
- Parameter[<span style="font-family:serif"><i>parameters performing axis swapping omitted for brevity</i></span>]],
- Inverse_MT[Param_MT["Geographic3D to 2D conversion"]],
- Param_MT["Geographic/geocentric conversions",
- Parameter["semi_major", 6378206.4],
- Parameter["semi_minor", 6356583.8]],
- Param_MT["Geocentric translations (geocentric domain)",
- Parameter["X-axis translation", -10.0],
- Parameter["Y-axis translation", 158.0],
- Parameter["Z-axis translation", 187.0]],
- Param_MT["Geocentric_To_Ellipsoid",
- Parameter["semi_major", 6378137.0],
- Parameter["semi_minor", 6356752.314245179]],
- Param_MT["Geographic3D to 2D conversion"],
- Param_MT["Affine parametric transformation",
- Parameter[<span style="font-family:serif"><i>parameters performing axis swapping omitted for brevity</i></span>]]]</pre>
-
- </div>
- </div>
- </div>
- <p>
- Finally, the raw operation chain can be view by a call to <code>AbstractMathTransform.toString(Convention.INTERNAL)</code>.
- This pseudo-<abbr>WKT</abbr> representation shows exactly what Apache <abbr>SIS</abbr> does,
- but is rarely used because difficult to read.
- It may occasionally be useful for advanced debugging.
- </p>
</section>
</body>
</html>
Copied: sis/site/trunk/book/en/referencing/CoordinateOperations.html (from r1794573, sis/site/trunk/book/en/referencing.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/referencing/CoordinateOperations.html?p2=sis/site/trunk/book/en/referencing/CoordinateOperations.html&p1=sis/site/trunk/book/en/referencing.html&r1=1794573&r2=1794656&rev=1794656&view=diff
==============================================================================
--- sis/site/trunk/book/en/referencing.html [UTF-8] (original)
+++ sis/site/trunk/book/en/referencing/CoordinateOperations.html [UTF-8] Tue May 9 23:04:35 2017
@@ -20,303 +20,22 @@
under the License.
-->
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
- xmlns:xi = "http://www.w3.org/2001/XInclude">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
- <title>Spatial reference systems</title>
+ <title>CoordinateOperations</title>
<meta charset="UTF-8"/>
- <link rel="stylesheet" type="text/css" href="../../content/book/book.css"/>
+ <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "../../content/book/en/developer-guide.html"
+ Content below this point is copied in "(…)/content/book/en/developer-guide.html" file
by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
-->
<section>
<header>
- <h1 id="Referencing">Spatial reference systems</h1>
+ <h2 id="CoordinateOperations">Coordinate operations</h2>
</header>
<p>
- For locating a point on Earth one can use identifiers like city name or postal address
- — an approach known as <cite>spatial reference systems by identifiers</cite> —
- or use numerical values valid in a given coordinate system like latitudes and longitudes
- — an approach known as <cite>spatial reference systems by coordinates</cite>.
- Each reference system implies approximations like
- the choice of a figure of the Earth (geoid, ellipsoid, <i>etc.</i>) used as an approximation of Earth shape,
- the choice of geometric properties (angles, distances, <i>etc.</i>) to be preserved when a map is shown on plane surface, and
- a lost of precision when coordinates are transformed to systems using a different <a href="#GeodeticDatum">datum</a>.
- </p><p>
- A very common misbelief is that one can avoid this complexity by using a single coordinate reference system
- (typically <abbr title="World Geodetic System 1984">WGS84</abbr>) as a universal system for all data.
- The next chapters will explain why the reality is not so simple.
- Whether a universal reference system can suit an application needs or not depends on the desired positional accuracy
- and the kind of calculations to be performed with the data.
- Unless otherwise specified, Apache <abbr>SIS</abbr> aims to represent coordinates on Earth with an accuracy of one centimetre or better.
- But the accuracy can be altered by various situations:
- </p>
- <ul>
- <li>Points should be inside the domain of validity as given by <code>ReferenceSystem.getDomainOfValidity()</code>.</li>
- <li>Distance measurements in a given map projection are true only is some special locations,
- named for instance “standards parallels”.</li>
- <li>Positional accuracy is altered after coordinate transformations.
- The new accuracy is described by <code>CoordinateOperation.getCoordinateOperationAccuracy()</code>.</li>
- <li>Finding the most appropriate coordinate transformation parameters require the use of a geodetic dataset like <abbr>EPSG</abbr>.
- Declaring those parameters within the <abbr>CRS</abbr> (for example with a <code>TOWGS84</code> element) is often not sufficient.</li>
- </ul>
- <article>
- <header>
- <h2>“Early binding” versus “late binding” implementations</h2>
- </header>
- <p>
- Because of the <abbr>WGS84</abbr> ubiquity, it is tempting to use that system as a hub or a pivot system
- for all coordinate transformations.
- The use of an “universal” system as a pivot simplifies the design of coordinate transformations libraries.
- For example transformations from datum <var>A</var> to datum <var>B</var> can be done by first transforming
- from <var>A</var> to <abbr>WGS84</abbr>, then from <abbr>WGS84</abbr> to <var>B</var>.
- With such approach, a coordinate transformations library would only need to associate each
- <code>GeodeticDatum</code> instance with the transformation parameters from that datum to <abbr>WGS84</abbr>.
- This approach was encouraged in version 1 of <abbr>WKT</abbr> format, since that format specified a
- <code>TOWGS84[…]</code> element (removed in <abbr>WKT</abbr> version 2) precisely for that purpose.
- This approach is known in <abbr>EPSG</abbr> guidance notes as “early binding” implementations
- since information about coordinate transformations are associated early in geodetic object definitions,
- usually right at <code>GeographicCRS</code> creation time.
- While <abbr>EPSG</abbr> acknowledges that this approach is commonly used,
- this is not a recommended strategy for the following reasons:
- </p>
- <ul>
- <li>More than one transformation may exist from datum <var>A</var> to datum <var>B</var>,
- where each transformation is designed for a different geographic area.</li>
- <li>Some operations are designed specifically for transformations from <var>A</var> to <var>B</var>
- and do not have the same accuracy than an operation using <abbr>WGS84</abbr> as an intermediate step.</li>
- <li><abbr>WGS84</abbr> itself has been updated many times,
- which makes it a kind of moving target (admittedly slowly) for coordinate transformations libraries.</li>
- <li>Different systems could be used as the pivot system, for example the <cite>Galileo Reference Frame</cite>
- (<abbr>GTRF</abbr>) created for the European <abbr>GPS</abbr> competitor.</li>
- </ul>
- <div class="example"><p><b>Example:</b>
- the <abbr>EPSG</abbr> geodetic dataset defines about 50 transformations from <abbr>NAD27</abbr> to <abbr>NAD83</abbr>.
- In an early binding approach, the same geographic <abbr>CRS</abbr> (namely “<abbr>NAD27</abbr>”) in the <abbr>WKT</abbr> 1
- format would need to be defined with a <code>TOWGS84[-8, 160, 176]</code> element for coordinates in <abbr>USA</abbr>
- or with a <code>TOWGS84[-10, 158, 187]</code> element for coordinates in Canada.
- Different parameter values exist for other regions like Cuba, so it is not possible to represent such diversity
- with a single <code>TOWGS84[…]</code> element associated to a <abbr>CRS</abbr>.
- But even when restricting <abbr>CRS</abbr> usage to the domain of validity of its single <code>TOWGS84[…]</code> element,
- those transformations are still approximative with a 10 metres accuracy in the <abbr>USA</abbr> case.
- More accurate transformations exist in the form of <abbr>NADCON</abbr> grid shift files,
- but those transformations are from <abbr>NAD27</abbr> to <abbr>NAD83</abbr> (which move together on the same continental plate),
- not to <abbr>WGS84</abbr> (which move independently).
- The difference was often ignored when <abbr>NAD83</abbr> and <abbr>WGS84</abbr> were considered as practically equivalent,
- but that assumption is subject to more caution today.
- </p></div>
- <p>
- <abbr>EPSG</abbr> rather recommends the use of “late binding” approach,
- in which coordinate transformation methods and parameters are defined for
- “<var>A</var> to <var>B</var>” pairs of systems (eventually completed with domain of validity)
- rather than associated to standalone datums.
- Apache <abbr>SIS</abbr> is a “late binding” implementation,
- while some reminiscences of “early binding” approach still exist in the form of the
- <code>DefaultGeodeticDatum.getBursaWolfParameters()</code> property.
- The later is used only if <abbr>SIS</abbr> fails to apply the late binding approach for given reference systems.
- </p>
- </article>
- <p>
- The <code>sis-referencing</code> module provides a set of classes implementing
- different specializations of the <code>ReferenceSystem</code> interface, together with required components.
- Those implementations store spatial reference system descriptions, together with metadata like their domain of validity.
- However those objects do not perform any operation on coordinate values.
- Coordinates <cite>conversions</cite> or <cite>transformations</cite> are performed by another family of types,
- with <code>CoordinateOperation</code> as the root interface.
- Those types will be discussed in <a href="#CoordinateOperation">another section</a>.
- </p>
-
-
-
- <h2 id="CRS_Components">Components of a reference system by coordinates</h2>
- <p>
- Spatial reference systems by coordinates provide necessary information for mapping numerical coordinate values
- to real-world locations. In Apache <abbr>SIS</abbr>, most information is contained (directly or indirectly) in
- classes with a name ending in <abbr>CRS</abbr>, the abbreviation of <i>Coordinate Reference System</i>.
- Those objects contain:
- </p>
- <ul>
- <li>A <i>datum</i>, which specifies among other things which ellipsoid to use as an Earth shape approximation.</li>
- <li>A description for each axis: name, direction, units of measurement, range of values.</li>
- <li>Sometime a list of parameters, especially when using map projections.</li>
- </ul>
- <p>
- Those systems are described by the <abbr>ISO</abbr> 19111 standard (<i>Referencing by Coordinates</i>),
- which replaces for most parts the older <abbr>OGC 01-009</abbr> standard (<i>Coordinate Transformation Services</i>).
- Those standards are completed by two other standards defining exchange formats:
- <abbr>ISO</abbr> 19136 and 19162 respectively for the
- <cite>Geographic Markup Language</cite> (<abbr>GML</abbr>) — a <abbr>XML</abbr> format which is quite detailed but verbose —
- and the <cite>Well-Known Text</cite> (<abbr>WKT</abbr>) — a text format easier to read by humans.
- </p>
-
- <h3 id="Ellipsoid">Geoid et ellipsoid</h3>
- <p>
- Since the real topographic surface is difficult to represent mathematically, it is not used directly.
- A slightly more convenient surface is the geoid,
- a surface where the gravitational field has the same value everywhere (an equipotential surface).
- This surface is perpendicular to the direction of a plumb line at all points.
- The geoid surface would be equivalent to the mean sea level if all oceans where at rest,
- without winds or permanent currents like the Gulf Stream.
- </p><p>
- While much smoother than topographic surface, the geoid surface still have hollows and bumps
- caused by the uneven distribution of mass inside Earth.
- For more convenient mathematical operations, the geoid surface is approximated by an ellipsoid.
- This “figure of Earth” is represented in GeoAPI by the <code>Ellipsoid</code> interface,
- a fundamental component in coordinate reference systems of kind <code>GeographicCRS</code> and <code>ProjectedCRS</code>.
- Tenth of ellipsoids are commonly used for datum definitions.
- Some of them provide a very good approximation for a particular geographic area
- at the expense of the rest of the world for which the datum was not designed.
- Other datums are compromises applicable to the whole world.
- </p>
- <div class="example">
- <p><b>Example:</b>
- the <abbr>EPSG</abbr> geodetic dataset defines among others the “<abbr>WGS</abbr> 84”, “Clarke 1866”, “Clarke 1880”,
- “<abbr>GRS</abbr> 1980” and “<abbr>GRS</abbr> 1980 Authalic Sphere” (a sphere of same surface than the <abbr>GRS</abbr> 1980 ellipsoid).
- Ellipsoids may be used in various places of the world or may be defined for a very specific region.
- For example in <abbr>USA</abbr> at the beginning of XX<sup>th</sup> century,
- the Michigan state used an ellipsoid based on the “Clarke 1866” ellipsoid but with axis lengths expanded by 800 feet.
- This modification aimed to take in account the average state height above mean sea level.</p>
- </div>
-
- <h3 id="GeodeticDatum">Geodetic datum</h3>
- <p>
- For defining a geodetic system in a country, a national authority selects an ellipsoid matching closely the country surface.
- Differences between that ellipsoid and the geoid’s hollows and bumps are usually less than 100 metres.
- Parameters that relate an <code>Ellipsoid</code> to the Earth surface (for example the position of ellipsoid center)
- are represented by instances of <code>GeodeticDatum</code>.
- Many <code>GeodeticDatum</code> definitions can use the same <code>Ellipsoid</code>,
- but with different orientations or center positions.
- </p><p>
- Before the satellite era, geodetic measurements were performed exclusively from Earth surface.
- Consequently, two islands or continents not in range of sight from each other were not geodetically related.
- So the <cite>North American Datum 1983</cite> (<abbr>NAD83</abbr>) and the <cite>European Datum 1950</cite> (<abbr>ED50</abbr>)
- are independent: their ellipsoids have different sizes and are centered at a different positions.
- The same geographic coordinate will map different locations on Earth depending on whether the coordinate
- uses one reference system or the other.
- </p><p>
- The <abbr title="Global Positioning System">GPS</abbr> invention implied the creation of a
- world geodetic system named <abbr title="World Geodetic System 1984">WGS84</abbr>.
- The ellipsoid is then unique and centered at the Earth gravity center.
- <abbr>GPS</abbr> provides at any moment the receptor absolute position on that world geodetic system.
- But since <abbr>WGS84</abbr> is a world-wide system, it may differs significantly from local systems.
- For example the difference between <abbr>WGS84</abbr> and the European system <abbr>ED50</abbr> is about 150 metres,
- and the average difference between <abbr>WGS84</abbr> and the <cite>Réunion 1947</cite> system is 1.5 kilometres.
- Consequently we shall not blindly use <abbr>GPS</abbr> coordinates on a map,
- as transformations to the local system may be required.
- Those transformations are represented in GeoAPI by instances of the <code>Transformation</code> interface.
- </p><p>
- The <abbr>WGS84</abbr> ubiquity tends to reduce the need for <code>Transformation</code> operations with recent data,
- but does not eliminate it.
- The Earth moves under the effect of plate tectonic and new systems are defined every years for taking that fact in account.
- For example while <abbr>NAD83</abbr> was originally defined as practically equivalent to <abbr>WGS84</abbr>,
- there is now (as of 2016) a 1.5 metres difference.
- The <cite>Japanese Geodetic Datum 2000</cite> was also defined as practically equivalent to <abbr>WGS84</abbr>,
- but the <cite>Japanese Geodetic Datum 2011</cite> now differs.
- Even the <abbr>WGS84</abbr> datum, which was a terrestrial model realization at a specific time,
- got revisions because of improvements in instruments accuracy.
- Today, at least six <abbr>WGS84</abbr> versions exist.
- Furthermore many borders were legally defined in legacy datums, for example <abbr>NAD27</abbr> in <abbr>USA</abbr>.
- Updating data to the new datum would imply transforming some straight lines or simple geometric shapes
- into more irregular shapes, if the shapes are large enough.
- </p>
-
- <h3 id="CoordinateSystem">Coordinate systems</h3>
- <p style="color: red">TODO</p>
-
- <h4 id="AxisOrder">Axis order</h4>
- <p>
- The axis order is specified by the authority (typically a national agency) defining the <cite>Coordinate Reference System</cite> (<abbr>CRS</abbr>).
- The order depends on the <abbr>CRS</abbr> type and the country defining the <abbr>CRS</abbr>.
- In the case of geographic <abbr>CRS</abbr>, the (<var>latitude</var>, <var>longitude</var>) axis order is widely used by geographers and pilots for centuries.
- However software developers tend to consistently use the (<var>x</var>, <var>y</var>) order for every kind of <abbr>CRS</abbr>.
- Those different practices resulted in contradictory definitions of axis order for almost every <abbr>CRS</abbr> of kind <code>GeographicCRS</code>,
- for some <code>ProjectedCRS</code> in the South hemisphere (South Africa, Australia, <i>etc.</i>) and for some polar projections among others.
- </p><p>
- Recent <abbr>OGC</abbr> standards mandate the use of axis order as defined by the authority.
- Oldest <abbr>OGC</abbr> 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,
- maybe because such uniformization makes <abbr>CRS</abbr> implementation and usage <em>apparently</em> easier.
- Apache <abbr>SIS</abbr> supports both conventions with the following approach:
- by default, <abbr>SIS</abbr> creates <abbr>CRS</abbr> with axis order <em>as defined by the authority</em>.
- Those <abbr>CRS</abbr> are created by calls to the <code>CRS.forCode(String)</code> method
- and the actual axis order can be verified after the <abbr>CRS</abbr> creation with <code>System.out.println(crs)</code>.
- But if (<var>x</var>, <var>y</var>) axis order is wanted for compatibility with older <abbr>OGC</abbr> specifications or other softwares,
- then <abbr>CRS</abbr> forced to <cite>longitude first</cite> axis order can be created by a call to the following method:
- </p>
-
-<pre>CoordinateReferenceSystem crs = …; // CRS obtained by any means.
-crs = AbstractCRS.castOrCopy(crs).forConvention(AxesConvention.RIGHT_HANDED)</pre>
-
- <p>
- Among the legacy <abbr>OGC</abbr> standards that used the non-conform axis order,
- an influent one is version 1 of the <cite>Well Known Text</cite> (<abbr>WKT</abbr>) format specification.
- According that widely-used format, <abbr>WKT</abbr> 1 definitions without explicit <code>AXIS[…]</code> elements
- shall default to (<var>longitude</var>, <var>latitude</var>) or (<var>x</var>, <var>y</var>) axis order.
- In version 2 of <abbr>WKT</abbr> format, <code>AXIS[…]</code> elements are no longer optional
- and should contain an explicit <code>ORDER[…]</code> sub-element for making the intended order yet more obvious.
- But if <code>AXIS[…]</code> elements are nevertheless missing in a <abbr>WKT</abbr> 2 definition,
- Apache <abbr>SIS</abbr> defaults to (<var>latitude</var>, <var>longitude</var>) order.
- So in summary:
- </p>
- <ul>
- <li>Default <abbr>WKT</abbr> 1 axis order of geographic <abbr>CRS</abbr> is (<var>longitude</var>, <var>latitude</var>) as mandated by <abbr>OGC</abbr> 01-009 specification.</li>
- <li>Default <abbr>WKT</abbr> 2 axis order of geographic <abbr>CRS</abbr> is (<var>latitude</var>, <var>longitude</var>),
- but this is <abbr>SIS</abbr>-specific as <abbr>ISO</abbr> 19162 does not mention default axis order.</li>
- </ul>
- <p>
- To avoid ambiguities, users are encouraged to always provide explicit <code>AXIS[…]</code> elements in their <abbr>WKT</abbr>.
- The <abbr>WKT</abbr> format will be presented in more details in the next sections.
- </p>
-
- <h3 id="GeographicCRS">Geographic reference systems</h3>
- <p style="color: red">TODO</p>
-
- <h4 id="GeographicWKT"><i>Well-Known Text</i> format</h4>
- <p style="color: red">TODO</p>
-
- <h3 id="ProjectedCRS">Map projections</h3>
- <p>
- Map projections represent a curved surface (the Earth) on a plane surface (a map or a computer screen)
- with some control over deformations: one can preserve either the angles or the areas, but not both in same time.
- The geometric properties to preserve depend on the feature to represent and the work to do on that feature.
- For example countries elongated along the East-West axis often use a Lambert projection,
- while countries elongated along the North-South axis prefer a Transverse Mercator projection.
- </p>
- <p style="color: red">TODO</p>
-
- <h4 id="ProjectedWKT"><i>Well-Known Text</i> format</h4>
- <p style="color: red">TODO</p>
-
- <h3 id="CompoundCRS">Vertical and temporal dimensions</h3>
- <p style="color: red">TODO</p>
-
- <h4 id="CompoundWKT"><i>Well-Known Text</i> format</h4>
- <p style="color: red">TODO</p>
-
-
-
- <h2 id="GetCRS">Fetching a spatial reference system</h2>
- <p style="color: red">TODO</p>
-
- <h3 id="CRSAuthorityFactory">Looking <abbr>CRS</abbr> defined by authorities</h3>
- <p style="color: red">TODO</p>
-
- <h3 id="CRSParsing">Reading definitions in GML or WKT format</h3>
- <p style="color: red">TODO</p>
-
- <h3 id="CRSFactory">Constructing programmatically</h3>
- <p style="color: red">TODO</p>
-
- <h3 id="CRS_UserCode">Adding new <abbr>CRS</abbr> definitions</h3>
- <p style="color: red">TODO</p>
-
-
-
- <h2 id="CoordinateOperation">Coordinate operations</h2>
- <p>
Given a <em>source</em> coordinate reference system (<abbr>CRS</abbr>) in which existing coordinate values are expressed,
and a <em>target</em> coordinate reference system in which coordinate values are desired,
Apache <abbr>SIS</abbr> can provide a <em>coordinate operation</em> performing the conversion or transformation work.
@@ -529,7 +248,7 @@ double dy_dφ = jacobian.getElement(1,0)
</p>
<table class="hidden"><tr>
- <td><img style="border: solid 1px" src="../../content/book/images/Derivatives.png" alt="Exemple de dérivées d’une projection cartographique"/></td>
+ <td><img style="border: solid 1px" src="../../../content/book/images/Derivatives.png" alt="Example of a map projection derivative"/></td>
<td style="padding-left: 30px; vertical-align: middle">
<p>where vectors are related to the matrix by:</p>
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" alttext="MathML capable browser required">
@@ -583,15 +302,15 @@ double dy_dφ = jacobian.getElement(1,0)
<th>Geometric shape after projection</th>
</tr>
<tr>
- <td><img style="border: solid 1px; margin-right: 15px" src="../../content/book/images/GeographicArea.png" alt="Envelope in a geographic CRS"/></td>
- <td><img style="border: solid 1px; margin-left: 15px" src="../../content/book/images/ConicArea.png" alt="Shape in a projected CRS"/></td>
+ <td><img style="border: solid 1px; margin-right: 15px" src="../../../content/book/images/GeographicArea.png" alt="Envelope in a geographic CRS"/></td>
+ <td><img style="border: solid 1px; margin-left: 15px" src="../../../content/book/images/ConicArea.png" alt="Shape in a projected CRS"/></td>
</tr>
</table>
<p>
<span style="color: red">TODO</span>
</p>
<table class="hidden"><tr><td>
- <img src="../../content/book/images/Approximation.png" alt="Cubic approximation of an envelope bounds"/>
+ <img src="../../../content/book/images/Approximation.png" alt="Cubic approximation of an envelope bounds"/>
</td><td style="padding-left: 60px">
Legend:
<ul>
@@ -619,14 +338,14 @@ double dy_dφ = jacobian.getElement(1,0)
<th style="text-align: right">Destination image</th>
</tr>
<tr>
- <td colspan="2"><img src="../../content/book/images/RasterProjection.png" alt="Intersection of derivatives"/></td>
+ <td colspan="2"><img src="../../../content/book/images/RasterProjection.png" alt="Intersection of derivatives"/></td>
</tr>
</table>
<p>
<span style="color: red">TODO</span>
</p>
<table class="hidden"><tr>
- <td><img src="../../content/book/images/WarpGrid.png" alt="Intersection of derivatives"/></td>
+ <td><img src="../../../content/book/images/WarpGrid.png" alt="Intersection of derivatives"/></td>
<td style="padding-left: 60px">
Legend:
<ul>
@@ -645,7 +364,7 @@ double dy_dφ = jacobian.getElement(1,0)
<p>
<span style="color: red">TODO</span>
</p>
- <p style="text-align:center"><img style="border: solid 1px" src="../../content/book/images/IntersectionOfDerivatives.png" alt="Intersection of derivatives"/></p>
+ <p style="text-align:center"><img style="border: solid 1px" src="../../../content/book/images/IntersectionOfDerivatives.png" alt="Intersection of derivatives"/></p>
<p>
<span style="color: red">TODO</span>
</p>