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 2022/05/19 17:37:54 UTC
[sis-site] branch main updated: Reorganise the developer guide with more text moved to annex.
This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/sis-site.git
The following commit(s) were added to refs/heads/main by this push:
new daec927f Reorganise the developer guide with more text moved to annex.
daec927f is described below
commit daec927f6884dd8536d09924b7e0df17b0c1389e
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Thu May 19 19:37:30 2022 +0200
Reorganise the developer guide with more text moved to annex.
---
.../annexes/design/AffineTransform.html | 106 +----
.../annexes/design/EarlyOrLateBinding.html | 91 ++++
.../annexes/design/JacobianUsage.html | 230 ++++++++++
.../annexes/design/MatrixLibrary.html | 14 +-
.../developer-guide/annexes/design/XMLTools.html | 63 +++
source/developer-guide/annexes/design/index.html | 13 +-
.../geoapi}/ConceptualModels.html | 6 +-
.../annexes/geoapi/DefinitionProcess.html | 12 +-
.../{introduction => annexes/geoapi}/GeoAPI.html | 60 +--
source/developer-guide/annexes/geoapi/Modules.html | 8 +-
.../annexes/geoapi/ReduceDependency.html | 16 +-
source/developer-guide/annexes/geoapi/index.html | 51 ++-
.../annexes/{geoapi => }/index.html | 20 +-
.../annexes/tests/GeoApiConformance.html | 12 +-
source/developer-guide/annexes/tests/index.html | 8 +-
.../developer-guide/coverage/AffineTransform.html | 127 ++++++
.../index.html => coverage/GridGeometry.html} | 17 +-
.../developer-guide/coverage/SampleDimension.html | 70 ++++
source/developer-guide/coverage/index.html | 100 ++---
.../geometry/{GeometryBase.html => Envelope.html} | 110 ++---
source/developer-guide/geometry/index.html | 25 +-
source/developer-guide/index.html | 10 +-
source/developer-guide/introduction/AboutBook.html | 89 ----
.../developer-guide/introduction/Conventions.html | 113 +++++
.../{overview => introduction}/DataAccess.html | 57 ++-
.../developer-guide/introduction/Installation.html | 105 +++++
source/developer-guide/introduction/index.html | 69 ++-
.../{overview => metadata}/GetMetadataElement.html | 22 +-
.../{storage => metadata}/index.html | 13 +-
source/developer-guide/referencing/AxisOrder.html | 82 ++++
.../referencing/ComponentsOfCRS.html | 230 +++++-----
.../referencing/CoordinateOperationSteps.html | 261 ++++++++++++
.../referencing/CoordinateOperations.html | 461 +--------------------
source/developer-guide/referencing/GetCRS.html | 21 +-
source/developer-guide/referencing/index.html | 71 +---
source/developer-guide/storage/XML-ISO-19115.html | 4 +-
source/developer-guide/storage/XML-ISO.html | 42 +-
source/developer-guide/storage/index.html | 6 +-
.../developer-guide/utility/ComparisonModes.html | 4 +-
.../utility/Internationalization.html | 10 +-
.../developer-guide/utility/ObjectConverters.html | 16 +-
source/developer-guide/utility/index.html | 4 +-
static/book/book.css | 25 +-
static/book/toc.js | 23 +-
44 files changed, 1634 insertions(+), 1263 deletions(-)
diff --git a/source/developer-guide/annexes/design/AffineTransform.html b/source/developer-guide/annexes/design/AffineTransform.html
index f03705ab..386e3c01 100644
--- a/source/developer-guide/annexes/design/AffineTransform.html
+++ b/source/developer-guide/annexes/design/AffineTransform.html
@@ -22,115 +22,23 @@
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
<head>
- <title>DesignNotes</title>
+ <title>AffineTransform</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../../book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h2 id="AffineTransform">Affine transform</h2>
+ <h3 id="AffineTransformAPI">Integration with graphical libraries</h3>
</header>
<p>
- Among the many kinds of operations performed by <abbr>GIS</abbr> software products on spatial coordinates,
- <cite>affine transforms</cite> are both relatively simple and very common.
- Affine transforms can represent any combination of scales, shears, flips, rotations and translations,
- which are <em>linear</em> operations.
- Affine transforms can not handle <em>non-linear</em> operations like map projections,
- but the affine transform capabilities nevertheless cover many other cases:
- </p>
- <ul>
- <li>Axis order changes, for example from (<var>latitude</var>, <var>longitude</var>) to (<var>longitude</var>, <var>latitude</var>).</li>
- <li>Axis direction changes, for example the <var>y</var> axis oriented toward down in images.</li>
- <li>Prime meridian rotations, for example from <cite>Paris</cite> to <cite>Greenwich</cite> prime meridian.</li>
- <li>Dimensionality changes, for example from 3-dimensional coordinates to 2-dimensional coordinates by dropping the height.</li>
- <li>Unit conversion, for example from feet to metres.</li>
- <li>Pixel to geodetic coordinate, for example the conversion represented in the <code>.tfw</code> files associated to some <abbr>TIFF</abbr> images.</li>
- <li>Part of map projections, for example the <cite>False Easting</cite>, <cite>False Northing</cite> and <cite>Scale factor</cite> parameters.</li>
- </ul>
- <p>
- Affine transforms can be concatenated efficiently.
- No matter how many affine transforms are chained, the result can be represented by a single affine transform.
- This property is more easily seen when affine transforms are represented by matrices:
- in order to concatenate those operations, we only need to multiply those matrices.
- The “pixel to geographic coordinate conversions” case below gives an example.
- </p>
-
- <div class="example">
- <p><b>Example:</b>
- given an image with pixel coordinates represented by (<var>x</var>,<var>y</var>) tuples
- and given the following assumptions:
- </p>
- <ul>
- <li>There is no shear, no rotation and no flip.</li>
- <li>All pixels have the same width in degrees of longitude.</li>
- <li>All pixels have the same height in degrees of latitude.</li>
- <li>Pixel indices are positive integers starting at (0,0) inclusive.</li>
- </ul>
- <p>Then conversions from pixel coordinates (<var>x</var>,<var>y</var>)
- to geographic coordinates (<var>λ</var>,<var>φ</var>) can be represented by the following equations,
- where <var>N</var><sub><var>x</var></sub> is the image width and
- <var>N</var><sub><var>y</var></sub> the image height in number of pixels:
- </p><p>
- <xi:include href="../../../../layouts/partials/math/PixelToGeographicTerms.html"/>
- </p><p>
- Above equations can be represented in matrix form as below:
- </p><p>
- <xi:include href="../../../../layouts/partials/math/PixelToGeographic.html"/>
- </p><p>
- In this particular case, scale factors <var>S</var> are the pixel size in degrees
- and translation terms <var>T</var> are the geographic coordinate of an image corner
- (not necessarily the lower-left corner if some axes have been flipped).
- This straightforward interpretation holds because of above-cited assumptions, but
- matrix coefficients become more complex if the image has shear or rotation
- or if pixel coordinates do not start at (0,0).
- However it is not necessary to use more complex equations for supporting more generic cases.
- The following example starts with an “initial conversion” matrix
- where the <var>S</var> and <var>T</var> terms are set to the most straightforward values.
- Then the <var>y</var> axis direction is reversed for matching the most common convention in image coordinate systems (change 1),
- and axis are swapped resulting in latitude before longitude (change 2).
- Note that when affine transform concatenations are written as matrix multiplications, operations are ordered from right to left:
- <var>A</var>×<var>B</var>×<var>C</var> is equivalent to first applying operation <var>C</var>,
- then operation <var>B</var> and finally operation <var>A</var>.
- </p>
- <div style="display:table; margin:auto">
- <div style="display:table-row">
- <div style="display:table-cell" class="caption">Change 2</div>
- <div style="display:table-cell" class="caption"> </div>
- <div style="display:table-cell" class="caption">Change 1</div>
- <div style="display:table-cell" class="caption"> </div>
- <div style="display:table-cell" class="caption">Initial conversion</div>
- <div style="display:table-cell" class="caption"> </div>
- <div style="display:table-cell" class="caption">Concatenated operation</div>
- </div>
- <div style="display:table-row">
- <div style="display:table-cell; vertical-align:middle"><xi:include href="../../../../layouts/partials/math/AxisSwapping2D.html"/></div>
- <div style="display:table-cell; vertical-align:middle; padding-left: 15px; padding-right: 15px">×</div>
- <div style="display:table-cell; vertical-align:middle"><xi:include href="../../../../layouts/partials/math/InverseAxisY.html"/></div>
- <div style="display:table-cell; vertical-align:middle; padding-left: 15px; padding-right: 15px">×</div>
- <div style="display:table-cell; vertical-align:middle"><xi:include href="../../../../layouts/partials/math/PixelToGeographicSameAxisDirections.html"/></div>
- <div style="display:table-cell; vertical-align:middle; padding-left: 15px; padding-right: 15px">=</div>
- <div style="display:table-cell; vertical-align:middle"><xi:include href="../../../../layouts/partials/math/PixelToGeographicReverseOrderAndY.html"/></div>
- </div>
- </div>
- <p>
- A key principle is that there is no need to write Java code dedicated to above kinds of axis changes.
- Those operations, and many other, can be handled by matrix algebra.
- This approach makes easier to write generic code and improves performance.
- Apache <abbr>SIS</abbr> follows this principle by using affine transforms for every operations
- that can be performed by such transform.
- For instance there is no code dedicated to changing order of ordinate values in a coordinate.
- </p>
- </div>
-
- <h3 id="AffineTransformAPI">Integration with graphical libraries</h3>
- <p>
- About all graphical libraries support some kind of coordinate operations, usually as <cite>affine transforms</cite>
- or a slight generalization like <cite>perspective transforms</cite>.
+ Affine transforms, introduced <a href="#AffineTransform">earlier</a>, are extensively used by Apache <abbr>SIS</abbr>.
+ About all graphical libraries support some kind of coordinate operations, usually as <dfn>affine transforms</dfn>
+ or a slight generalization like <dfn>perspective transforms</dfn>.
Each library defines its own <abbr>API</abbr>. Some examples are listed below:
</p>
<table>
diff --git a/source/developer-guide/annexes/design/EarlyOrLateBinding.html b/source/developer-guide/annexes/design/EarlyOrLateBinding.html
new file mode 100644
index 00000000..123c6352
--- /dev/null
+++ b/source/developer-guide/annexes/design/EarlyOrLateBinding.html
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
+ <head>
+ <title>EarlyOrLateBinding</title>
+ <meta charset="UTF-8"/>
+ <link rel="stylesheet" type="text/css" href="../../book.css"/>
+ </head>
+ <body>
+ <!--
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
+ -->
+ <section>
+ <header>
+ <h3 id="EarlyOrLateBinding">Early binding versus late binding</h3>
+ </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 class="verbose">
+ <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>
+ </section>
+ </body>
+</html>
diff --git a/source/developer-guide/annexes/design/JacobianUsage.html b/source/developer-guide/annexes/design/JacobianUsage.html
new file mode 100644
index 00000000..9859e931
--- /dev/null
+++ b/source/developer-guide/annexes/design/JacobianUsage.html
@@ -0,0 +1,230 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
+ <head>
+ <title>JacobianUsage</title>
+ <meta charset="UTF-8"/>
+ <link rel="stylesheet" type="text/css" href="../../book.css"/>
+ </head>
+ <body>
+ <!--
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
+ -->
+ <section>
+ <header>
+ <h3 id="JacobianUsage">Usages of Jacobian matrix</h3>
+ </header>
+ <p>
+ The Jacobian matrix (or transform derivative) was introduced in the
+ <a href="#TransformDerivative">section about coordinate operations</a>.
+ This section explains how derivatives are used by the Apache <abbr>SIS</abbr>
+ implementation of some high-level operations.
+ </p>
+
+ <h4 id="DerivativeAndEnvelope">Transform derivatives applied to envelopes</h4>
+ <p>
+ Geographic information systems often need to transform an envelope from one <abbr>CRS</abbr> to another.
+ A <a href="#EnvelopeTransform">previous section</a> has shown why a naive approach transforming the 4 corners is not sufficient.
+ A simple way to reduce the problem could be to sample a large number of points on each envelope border.
+ For example we could sample 40 points on each border, transform them to the target <abbr>CRS</abbr>
+ and compute an envelope containing all the transformed points.
+ But even with 40 points, the point which is closest to the minimum in above figure can still be above that minimum.
+ Consequently we still miss a small portion of the projected shape.
+ It may be tempting to declare this error is negligible, but a single missing pixel can be enough for
+ causing artifacts such as thin black lines in a mosaic or missing “piece of pie” in a projection over a pole.
+ A workaround could be to arbitrarily increase the envelope size by some percentage,
+ but a percentage too high will cause a larger amount of unnecessary data processing (e.g. more data to load from a file)
+ while a percentage too low will leave some artifacts.
+ </p><p>
+ Map projection derivatives offer a more efficient way to resolve this problem.
+ The figure below reproduces the same projected shape than above figure but with exaggerated deformations.
+ The Apache <abbr>SIS</abbr> algorithm projects the 4 corners as in the naive approach,
+ but opportunistically computes also their derivatives (the Jacobian matrices).
+ Between two corners and using derivative information, there is only one possible cubic curve.
+ We can describe that curve by the
+
+ <i>f(<var>x</var>)</i> = <var>C</var>₀ + <var>C</var>₁<var>x</var> + <var>C</var>₂<var>x</var>² + <var>C</var>₃<var>x</var>³ equation
+
+ with <var>C</var> coefficients computed from corner positions and derivatives.
+ This approximation (shown by the red curve in above figure) does not match exactly the desired curve
+ (shown by the blue shape in above figure) but is close.
+ We do not use directly the cubic curve minimum,
+ but instead we take the longitude λ (for above example) where this minimum is located.
+ This is shown by the green dashed line in above figure.
+ This position is easy to compute when the <var>C</var> coefficients are known.
+ Assuming that the λ coordinate of the cubic curve minimum is close to the λ coordinates of the projected shape minimum,
+ we can project the point on the envelope border at that location instead of projecting blindly 40 points on that border.
+ </p>
+ <div class="row-of-boxes">
+ <div>
+ <img src="../../../static/book/images/Approximation.png" alt="Cubic approximation of an envelope bounds"/>
+ </div><div>
+ 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>
+ </div>
+ </div>
+ <p>
+ In practice Apache <abbr>SIS</abbr> uses 8 points:
+ the 4 corners plus one point at the center of each border of the envelope to project.
+ The center points are added as a safety for map projections having symmetric deformations above and below equator.
+ According our tests, using only those 8 points together with derivatives as described above
+ gives more accurate results than “brute force” approach with 160 points on the 4 envelope borders.
+ Saving 150 points seems small compared to computer performances.
+ But above discussion used a two-dimensional envelope as an example.
+ The same discussion applies to <var>n</var>-dimensional envelopes as well.
+ Apache <abbr>SIS</abbr> can apply this algorithm on envelopes with any number of dimensions up to 64.
+ The performance gain offered by this algorithm compared to “brute force” approach
+ increases exponentially with the number of dimensions.
+ </p><p>
+ Apache <abbr>SIS</abbr> implements the algorithm described in this section
+ by the static <code>Envelopes.transform(CoordinateOperation, Envelope)</code> method.
+ An alternative <code>Envelopes.transform(MathTransform, Envelope)</code> method is also available,
+ but should be used only when the <code>CoordinateOperation</code> is unknown.
+ The reason is because <code>MathTransform</code> objects does not contain any information about coordinate system axes,
+ which prevent the <code>Envelopes.transform(…)</code> method to handle special cases such as envelopes containing a pole.
+ </p>
+
+
+ <h4 id="DerivativeAndRaster">Transform derivatives applied to rasters</h4>
+ <p>
+ A raster can be projected by preparing an initially empty raster which will contain the resampled pixel values.
+ Then for each pixel in the <em>destination</em> raster, we use the <em>inverse</em> of the map projection
+ (<var>T</var>⁻¹) for computing the coordinates of the corresponding pixel in source raster.
+ The transformed coordinates may not fall at the center of a source raster pixel,
+ so source pixel values usually need to be interpolated.
+ </p>
+ <div style="display:flex; flex-direction:column; align-items:center">
+ <div style="display:flex; justify-content:space-between; width:564px">
+ <div class="caption">Source image</div>
+ <div class="caption">Destination image</div>
+ </div>
+ <img src="../../../static/book/images/RasterProjection.png" alt="Raster reprojection"/>
+ </div>
+ <p>
+ However applying the inverse transform on all pixel coordinates can be relatively slow.
+ We can accelerate raster reprojections by pre-computing an <dfn>interpolation grid</dfn>.
+ This grid contains the coordinate values of inverse transform <var>T</var>⁻¹ for only a few points.
+ The coordinate values of other points are obtained by bilinear interpolations between interpolation grid points.
+ Historically, this algorithm was implemented in the <code>WarpGrid</code> object of <cite>Java Advanced Imaging</cite> library.
+ The performance gain is yet better if the same interpolation grid is reused for many rasters having their pixels at the same coordinates.
+ </p><p>
+ A difficulty in using interpolation grids is to determine how many points we need for keeping errors
+ (defined as the difference between interpolated positions and actual positions computed by <var>T</var>⁻¹)
+ below some threshold value (for example ¼ of pixel size).
+ A “brute force” approach is to begin with a grid of size 3×3, then increase the number of points iteratively:
+ </p>
+ <div class="row-of-boxes">
+ <div>
+ <img src="../../../static/book/images/WarpGrid.png" alt="Warp grid"/>
+ </div><div>
+ 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>
+ </div>
+ </div>
+ <p>
+ We could stop dividing the grid when, after having computed new points,
+ we verified that the differences between coordinates computed by <var>T</var>⁻¹ during last iteration
+ and coordinates computed by bilinear interpolations for the same points are lower than the threshold value.
+ Unfortunately this approach can only tell us <strong>after</strong> computing new points… that those new points were unnecessary.
+ This is unfortunate considering that each iteration adds an amount of points approximately equal to
+ 3 times the <em>sum</em> of the number of points of all previous iterations.
+ </p><p>
+ Map projection derivatives help to improve the speed of interpolation grid computations.
+ Using the derivatives, we can estimate whether another iteration is necessary <strong>before</strong> to execute it.
+ The basic idea is to check if the derivatives at two neighbor points define two tangent lines that are almost parallel.
+ In such case, we assume that the transform between those two points is almost linear.
+ In order to define numerically the meaning of “almost linear”,
+ we compute the intersection of the two tangent lines as illustrated below (the blue arrows).
+ Then we compute the distance between that intersection and the straight line connecting the two points
+ (the dashed line in the figure below).
+ </p>
+ <p style="text-align:center"><img style="border: solid 1px" src="../../../static/book/images/IntersectionOfDerivatives.png" alt="Intersection of derivatives"/></p>
+ <p>
+ In “brute force” algorithm without derivatives, iteration stops when the distance between interpolated positions (blue dashed line)
+ and actual projected positions (red curve) is less than the threshold value.
+ This criteria requires to compute the projected positions before the decision can be made.
+ But with an algorithm using derivatives, the projected positions (red curve) are replaced by the tangents intersection point.
+ If the actual projected curve does not have too much deformations
+ (which should be the case for pairs of neighbor points close enough),
+ then the red curve stay between the blue dashed line and the tangents intersection point.
+ By using that intersection point, we reduce greatly the number of points to transform
+ (3× the sum of all previous iterations).
+ </p>
+
+ <h4 id="GetDerivative">Getting the derivative at a point</h4>
+ <p>
+ The algorithms discussed in previous section would be irrelevant if map projection derivatives were costly to compute.
+ But analytic derivations of their formulas show that map projection and derivative formulas have many terms in common.
+ Furthermore map projection formulas are simplified by Apache <abbr>SIS</abbr> implementation strategy,
+ which takes out linear terms (delegated to affine transforms)
+ so that <code>NormalizedProjection</code> subclasses can focus on the non-linear terms only.
+ Map projection implementations in Apache <abbr>SIS</abbr> exploit those characteristics
+ for computing Jacobian matrices (if required) together with projected points in a single operation,
+ reusing many common terms between the two set of formulas.
+ Example:</p>
+
+<pre><code>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);</code></pre>
+
+ <p>
+ If only the Jacobian matrix is desired (without the projected point),
+ then the <code>MathTransform.derivative(DirectPosition)</code> method offers a more readable alternative.
+ </p><p>
+ Many operations on coordinate transforms can also be applied on transform derivatives:
+ concatenation of a chain of transforms, inversion, taking a subset of the dimensions, <i>etc.</i>
+ Inverse projection formulas are usually more complicated than forward projections formulas,
+ but thankfully their derivatives do not need to be computed:
+ the Jacobian matrix of an inverse transform is the inverse of the Jacobian matrix of the forward transform.
+ Calculation of inverse projections can be implemented as below:
+ </p>
+
+<pre><code>@Override
+public Matrix derivative(DirectPosition p) throws TransformException {
+ Matrix jac = inverse().derivative(transform(p));
+ return Matrices.inverse(jac);
+}</code></pre>
+ </section>
+ </body>
+</html>
diff --git a/source/developer-guide/annexes/design/MatrixLibrary.html b/source/developer-guide/annexes/design/MatrixLibrary.html
index d5353d2a..14c2365a 100644
--- a/source/developer-guide/annexes/design/MatrixLibrary.html
+++ b/source/developer-guide/annexes/design/MatrixLibrary.html
@@ -22,18 +22,18 @@
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
<head>
- <title>DesignNotes</title>
+ <title>MatrixLibrary</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../../book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h2 id="MatrixLibrary">Specificities of a matrix library for <abbr>GIS</abbr></h2>
+ <h3 id="MatrixLibrary">Specificities of a matrix library for <abbr>GIS</abbr></h3>
</header>
<p>
<abbr>GIS</abbr> make an extensive usage of matrices for displaying maps or for transforming coordinates.
@@ -79,7 +79,7 @@
at the cost of performance in a phase (transform <em>preparation</em>) where performance is not considered critical.
</p>
- <h3 id="NonSquareMatrix">What to do with non-square matrices (and why)</h3>
+ <h4 id="NonSquareMatrix">What to do with non-square matrices (and why)</h4>
<p>
Apache <abbr>SIS</abbr> often needs to inverse matrices, in order to perform a coordinate operation in reverse direction.
Matrix inversions are typically performed on square matrices, but <abbr>SIS</abbr> also needs to inverse non-square matrices.
@@ -114,7 +114,7 @@
and invert the matrix using only the remaining dimensions.
If <abbr>SIS</abbr> does not found a sufficient amount of independent dimensions, an exception is thrown.
But if a matrix inversion has been possible, then we need to decide which value to assign to the dimensions that <abbr>SIS</abbr> temporarily excluded.
- By default, <abbr>SIS</abbr> assigns the <code>NaN</code> (<cite>Not-a-Number</cite>) value to those dimensions.
+ By default, <abbr>SIS</abbr> assigns the <code>NaN</code> (<dfn>Not-a-Number</dfn>) value to those dimensions.
However in the particular case of ellipsoidal height <var>h</var> in a (<var>φ₂</var>, <var>λ₂</var>) → (<var>φ₁</var>, <var>λ₁</var>, <var>h</var>) operation,
the zero value may also be appropriate on the assumption that the coordinates are usually close to the ellipsoid surface.
In any case, the coefficients that Apache <abbr>SIS</abbr> sets to zero or <code>NaN</code> is based on the assumption
@@ -136,7 +136,7 @@
but in case of success the resulting coordinate operation is guaranteed to be exact (ignoring rounding errors).
</p>
- <h3 id="MatrixLibrarySummary">Apache <abbr>SIS</abbr> matrix library</h3>
+ <h4 id="MatrixLibrarySummary">Apache <abbr>SIS</abbr> matrix library</h4>
<p>
In summary, Apache <abbr>SIS</abbr> provides its own matrix library for the following reasons:
</p>
diff --git a/source/developer-guide/annexes/design/XMLTools.html b/source/developer-guide/annexes/design/XMLTools.html
new file mode 100644
index 00000000..a5b854a8
--- /dev/null
+++ b/source/developer-guide/annexes/design/XMLTools.html
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
+ <head>
+ <title>XMLTools</title>
+ <meta charset="UTF-8"/>
+ <link rel="stylesheet" type="text/css" href="../../book.css"/>
+ </head>
+ <body>
+ <!--
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
+ -->
+ <section>
+ <header>
+ <h3 id="XMLTools">Tools for reading and writing <abbr>XML</abbr> documents</h3>
+ </header>
+ <p>
+ Apache <abbr>SIS</abbr> uses different libraries to read and write different types of objects.
+ The library used depends on the complexity of the object and on performance constraints.
+ For example, <abbr title="Java Architecture for XML Binding">JAXB</abbr> annotations have the advantage of being close to code,
+ which makes it easier to maintain mapping between Java and <abbr>XML</abbr>.
+ On the other hand, <abbr title="Simple API for XML">SAX</abbr> is more efficient.
+ In general, Apache <abbr>SIS</abbr> uses:
+ </p>
+ <ul class="verbose">
+ <li>
+ <abbr>JAXB</abbr> for objects that do not occur very often in <abbr>XML</abbr> documents, but with complex structures and deep hierarchies.
+ The metadata set in <abbr>ISO</abbr> 19115-3 standard is a typical example
+ </li>
+ <li>
+ <abbr>SAX</abbr> for objects that are relatively simple, but which may exist in very large numbers.
+ The set of points in a geometry is a typical example.
+ </li>
+ <li>
+ <abbr title="Document Object Model">DOM</abbr> as an alternative to <abbr>JAXB</abbr>
+ when the <abbr>XML</abbr> elements do not correspond exactly to Java attributes.
+ <i>Features</i> are an example, as their structure is dynamic.
+ </li>
+ </ul>
+ </section>
+ </body>
+</html>
diff --git a/source/developer-guide/annexes/design/index.html b/source/developer-guide/annexes/design/index.html
index 15e60899..dcd1eb70 100644
--- a/source/developer-guide/annexes/design/index.html
+++ b/source/developer-guide/annexes/design/index.html
@@ -22,23 +22,26 @@
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
<head>
- <title>Annexes</title>
+ <title>DesignNotes</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../../book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h1 id="DesignNotes">Design notes</h1>
+ <h2 id="DesignNotes">Design notes</h2>
</header>
<p>Following sections explain the rational behind some implementation choices done in Apache <abbr>SIS</abbr>.</p>
- <xi:include href="AffineTransform.html"/>
+ <xi:include href="EarlyOrLateBinding.html"/>
<xi:include href="MatrixLibrary.html"/>
+ <xi:include href="JacobianUsage.html"/>
+ <xi:include href="AffineTransform.html"/>
+ <xi:include href="XMLTools.html"/>
</section>
</body>
</html>
diff --git a/source/developer-guide/introduction/ConceptualModels.html b/source/developer-guide/annexes/geoapi/ConceptualModels.html
similarity index 98%
rename from source/developer-guide/introduction/ConceptualModels.html
rename to source/developer-guide/annexes/geoapi/ConceptualModels.html
index 40aa030e..9e9a20f8 100644
--- a/source/developer-guide/introduction/ConceptualModels.html
+++ b/source/developer-guide/annexes/geoapi/ConceptualModels.html
@@ -28,12 +28,12 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html"
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h2 id="ConceptualModels">Sources of conceptual models used by Apache SIS</h2>
+ <h3 id="ConceptualModels">Sources of conceptual models used by Apache SIS</h3>
</header>
<p>
Most standards used by Apache <abbr>SIS</abbr> have been devised by the <a href="https://www.ogc.org/">Open Geospatial Consortium</a> (<abbr>OGC</abbr>),
diff --git a/source/developer-guide/annexes/geoapi/DefinitionProcess.html b/source/developer-guide/annexes/geoapi/DefinitionProcess.html
index 713a252c..5465068a 100644
--- a/source/developer-guide/annexes/geoapi/DefinitionProcess.html
+++ b/source/developer-guide/annexes/geoapi/DefinitionProcess.html
@@ -22,19 +22,19 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
- <title>GeoAPI</title>
+ <title>SpecificationToInterfaces</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../../book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html"
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h2 id="SpecificationToInterfaces">From <abbr>OGC</abbr> specifications to Java interfaces</h2>
+ <h3 id="SpecificationToInterfaces">From <abbr>OGC</abbr> specifications to Java interfaces</h3>
</header>
<p>
GeoAPI interfaces are sometime generated from other files provided by <abbr>OGC</abbr>, like <abbr>XSD</abbr> files.
@@ -148,7 +148,7 @@
- <h3 id="UML-annotation">Explicit mapping given by <code>@UML</code> annotations</h3>
+ <h4 id="UML-annotation">Explicit mapping given by <code>@UML</code> annotations</h4>
<p>
For each class, method and constant defined by an <abbr>OGC</abbr> or <abbr>ISO</abbr> standard,
GeoAPI indicates its provenance using annotations defined in the <code>org.opengis.annotation</code> package.
@@ -196,7 +196,7 @@ System.out.println("Standard name of type " + type.getName() + " is " + Types.ge
- <h3 id="MappingToJDK">Implicit mapping to standard <abbr>JDK</abbr></h3>
+ <h4 id="MappingToJDK">Implicit mapping to standard <abbr>JDK</abbr></h4>
<p>
Some classes and methods have neither an <code>@UML</code> annotation, nor an entry in the <code class="GeoAPI">class-index.properties</code> file.
They are either extensions of GeoAPI, or else types defined in other libraries, such as standard <abbr title="Java Development Kit">JDK</abbr>.
diff --git a/source/developer-guide/introduction/GeoAPI.html b/source/developer-guide/annexes/geoapi/GeoAPI.html
similarity index 65%
rename from source/developer-guide/introduction/GeoAPI.html
rename to source/developer-guide/annexes/geoapi/GeoAPI.html
index bc2ec089..395a9e4a 100644
--- a/source/developer-guide/introduction/GeoAPI.html
+++ b/source/developer-guide/annexes/geoapi/GeoAPI.html
@@ -28,12 +28,12 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html"
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h2 id="GeoAPI">From conceptual models to Java interfaces: GeoAPI</h2>
+ <h3 id="GeoAPI">From conceptual models to Java interfaces: GeoAPI</h3>
</header>
<p>
The <a href="http://www.geoapi.org">GeoAPI</a> project offers a set of Java interfaces for geospatial applications.
@@ -111,60 +111,6 @@
</p>
</article>
</details>
-
- <p id="GeoAPI-core">
- GeoAPI is composed of many modules.
- The <code>geoapi</code> and <code>geoapi-pending</code> modules
- provide interfaces derived from <abbr>UML</abbr> schemas of international standards.
- The conceptual model will be explained in detail in the chapters describing Apache <abbr>SIS</abbr> implementation.
- However, we can get an overview of its content by consulting the page listing the mapping between
- <a href="http://www.geoapi.org/3.0/javadoc/content.html">GeoAPI methods and the standards where they come from</a>.
- Those modules and the mapping between GeoAPI and international standards are described in more details <a href="#SpecificationToInterfaces">in annex</a>.
- </p>
-
-
-
- <h3 id="GeoAPI-implementation">Implementations provided by Apache SIS</h3>
- <p>
- Apache SIS implements most GeoAPI interfaces by a class of the same name than the interface
- but prefixed by “<code>Abstract</code>”, “<code>Default</code>” or “<code>General</code>”.
- Apache SIS classes prefixed by “<code>Default</code>” can be instantiated directly by a
- <code>new DefaultXXX(…)</code> statement or by a call to the <code>createXXX(…)</code> method in a factory.
- </p>
- <div class="example"><b>Example:</b> to represent a projected coordinate reference system (Mercator, Lambert, <i>etc</i>):
- <ul>
- <li><code>org.opengis.referencing.crs.ProjectedCRS</code> is the GeoAPI interface derived from ISO 19111 standard, and</li>
- <li><code>org.apache.sis.referencing.crs.DefaultProjectedCRS</code> is the implementation provided by Apache SIS.</li>
- </ul>
- An instance can be created by:
- <ul>
- <li><code>ProjectedCRS crs = new DefaultProjectedCRS(…)</code>, ou</li>
- <li><code>ProjectedCRS crs = CRSFactory.createProjectedCRS(…)</code>.</li>
- </ul>
- Both approaches expect the same arguments (omitted in this example for brevity).
- </div>
- <p>
- In the default Apache SIS configuration, using <code>FooFactory.createXXX(…)</code> or <code>new DefaultXXX(…)</code>
- is almost the same except that <code>FooFactory</code> may return existing instances instead than creating new instances,
- and that exceptions thrown in case of invalid arguments are different types.
- In more advanced configurations, using <code>Factory</code> reduces the
- <a href="#ServiceLoader">direct dependencies toward Apache SIS</a>
- and allows inversion of control.
- </p><p>
- The “<code>General</code>” prefix is sometime used instead than “<code>Default</code>”
- to indicate that alternative implementations are available for some specific cases.
- For example the <code>Envelope</code> interface is implemented by at least two Apache SIS classes:
- <code>GeneralEnvelope</code> and <code>Envelope2D</code>.
- The first implementation can represent envelopes with any number of dimensions
- while the second implementation is specialized for two-dimensional envelopes.
- </p><p>
- Apache SIS classes prefixed by “<code>Abstract</code>” should not – in principle – be instantiated.
- Users should instantiate a non-abstract subclass instead.
- But many SIS classes are only conceptually abstract, without <code>abstract</code> Java keyword in class definition.
- Such classes can be instantiated by a <code>new AbstractXXX(…)</code> statement
- – but not by <code>Factory</code> – despite being conceptually abstract.
- However such instantiations should be done only in last resort, when it is not possible to determine the exact subtype.
- </p>
</section>
</body>
</html>
diff --git a/source/developer-guide/annexes/geoapi/Modules.html b/source/developer-guide/annexes/geoapi/Modules.html
index 77a49b13..15c7778b 100644
--- a/source/developer-guide/annexes/geoapi/Modules.html
+++ b/source/developer-guide/annexes/geoapi/Modules.html
@@ -22,19 +22,19 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
- <title>GeoAPI</title>
+ <title>GeoAPI-modules</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../../book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html"
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h2 id="GeoAPI-modules">GeoAPI modules</h2>
+ <h3 id="GeoAPI-modules">GeoAPI modules</h3>
</header>
<p>
The GeoAPI project consists of a standardized part (<code>geoapi</code>)
diff --git a/source/developer-guide/annexes/geoapi/ReduceDependency.html b/source/developer-guide/annexes/geoapi/ReduceDependency.html
index 9c94a480..650f59d1 100644
--- a/source/developer-guide/annexes/geoapi/ReduceDependency.html
+++ b/source/developer-guide/annexes/geoapi/ReduceDependency.html
@@ -28,12 +28,12 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h2 id="ReduceDependency">Reduce direct dependency to Apache SIS</h2>
+ <h3 id="ReduceDependency">Reduce direct dependency to Apache SIS</h3>
</header>
<p>
Previous chapters used Apache SIS static methods for convenience.
@@ -44,7 +44,7 @@
The following sections provide some tip for easing this task.
</p>
- <h3 id="UML-annotation-indep">Mapping given by <code>@UML</code> annotations</h3>
+ <h4 id="UML-annotation-indep">Mapping given by <code>@UML</code> annotations</h4>
<p>
For each class, method and constant defined by an <abbr>OGC</abbr> or <abbr>ISO</abbr> standard,
GeoAPI indicates its provenance using annotations defined in the <code>org.opengis.annotation</code> package.
@@ -84,7 +84,7 @@ System.out.println("The GeoAPI interface for <abbr>ISO</abbr> type " + isoName +
- <h3 id="ServiceLoader">Fetching implementations of GeoAPI interfaces</h3>
+ <h4 id="ServiceLoader">Fetching implementations of GeoAPI interfaces</h4>
<p>
GeoAPI defines factories (<code>Factory</code>) that can create implementations of interfaces.
For example, <code>DatumFactory</code> provides methods that can create instances which implement interfaces of the
@@ -119,7 +119,7 @@ public class MyApplication {
- <h4 id="GeoAPI-simple">Defining custom implementations</h4>
+ <h5 id="GeoAPI-simple">Defining custom implementations</h5>
<p>
Implementing GeoAPI oneself in order to meet very specific needs is not difficult.
A developer might concentrate on a handful of interfaces among the hundreds available,
@@ -127,8 +127,8 @@ public class MyApplication {
</p>
<p>
The conceptual model that the interfaces represent is complex. But this complexity may be reduced by combining certain interfaces.
- For example, many libraries, even well-known ones, do not distinguish between a <cite>Coordinate System</cite> (<abbr>CS</abbr>)
- and a <cite>Coordinate <u>Reference</u> System</cite> (<abbr>CRS</abbr>).
+ For example, many libraries, even well-known ones, do not distinguish between a <dfn>Coordinate System</dfn> (<abbr>CS</abbr>)
+ and a <dfn>Coordinate <u>Reference</u> System</dfn> (<abbr>CRS</abbr>).
A developer that also wishes not to make this distinction may implement these two interfaces with the same class.
The resulting implementation may have a simpler class hierarchy than that of GeoAPI interfaces.
The <code>geoapi-examples</code> module, discussed later, provides such combinations.
diff --git a/source/developer-guide/annexes/geoapi/index.html b/source/developer-guide/annexes/geoapi/index.html
index 84f636fd..1e6776e6 100644
--- a/source/developer-guide/annexes/geoapi/index.html
+++ b/source/developer-guide/annexes/geoapi/index.html
@@ -22,26 +22,63 @@
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
<head>
- <title>Annexes</title>
+ <title>Standards</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../../book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h1 id="GeoAPI-details">GeoAPI relationship with standards</h1>
+ <h2 id="Standards">Standards and norms</h2>
</header>
<p>
- The GeoAPI project has been briefly presented <a href="#GeoAPI">in introduction</a> to this document.
- This annex explains in more details how GeoAPI relates to international standards.
- The goal is to allow developers to reduce their dependency toward GeoAPI or Apache SIS specificities.
+ A geospatial information community is a collection of systems or individuals capable of exchanging their geospatial data
+ through the use of common standards, allowing them to communicate with one another.
+ As there are many ways to represent geospatial information, each community tends to structure this information in light of its areas of interest.
+ This diversity complicates the task of Spatial Information System (<abbr>SIS</abbr>) users
+ by confronting them with an apparently chaotic variety of data formats and structures.
+ The characteristics of these structures vary according to the observed phenomenon and measurement methods,
+ as well as the habits of the organizations producing the data.
+ Such a variety represents an obstacle in studies that require heterogeneous combinations of data,
+ especially when they originate in communities that are traditionally distinct.
+ For example, a researcher studying cholera might be interested in populations of shrimp as a propagation vector of the disease.
+ But as doctors and oceanographers may not be used to share their work,
+ the participants of such a study may be limited by the effort required to convert the data.
+ </p><p>
+ We cannot impose a uniform format on all data collections, as the diversity of formats is tied to factors
+ such as the constraints imposed by the measuring apparatus, and the statistical distribution of values.
+ A more flexible solution is to ensure the interoperability of data across a common programming interface
+ (<abbr title="Application Programming Interface">API</abbr>).
+ This <abbr>API</abbr> is not necessarily defined in a programming language;
+ the actual tendency is rather to define conventions that use existing web protocols, which we can translate into various programming languages.
+ But in order for this approach to be viable, the <abbr>API</abbr> must be generally accepted by independent developers.
+ In other words, the <abbr>API</abbr> must come as near as possible to industrial standards.
+ </p><p>
+ For example, one task that benefit from a successful standardization is the accessing of relational databases.
+ The industry has established a common language — the <abbr title="Structured Query Language">SQL</abbr> standard —
+ that the creators of Java have embedded in standard <abbr title="Java DataBase Connectivity">JDBC</abbr> programming interfaces.
+ Today, these interfaces are implemented by many software programs, both free and commercial.
+ Like databases, methods of accessing geographic information have been standardized.
+ In this case, however, the efforts have been more recent, and their integration in software — especially in older programs — is incomplete and not always coherent.
+ At the time of writing, no product to our knowledge has implemented all of the specifications in their entirety.
+ However, there are many implementations that cover a fairly large spectrum.
+ One of these is the Apache <abbr>SIS</abbr>™ library that is described in this document.
+ </p><p>
+ Apache <abbr title="Spatial Information System">SIS</abbr> is characterized by a sustained effort to comply with standards.
+ In general, complying with standards demands a greater effort than would be required for an isolated development,
+ but rewards us with a double advantage: not only does it improve the interoperability of our data with that of external projects,
+ it also points towards a robust way of elaborating the conceptual model reflected in the <abbr>API</abbr>.
+ In effect, the groups of experts who conceived the standards anticipated difficulties that sometimes escape the engineer at the beginning of a project,
+ but which risk to hit them before the end.
</p>
+ <xi:include href="ConceptualModels.html"/>
+ <xi:include href="GeoAPI.html"/>
<xi:include href="Modules.html"/>
<xi:include href="DefinitionProcess.html"/>
<xi:include href="ReduceDependency.html"/>
diff --git a/source/developer-guide/annexes/geoapi/index.html b/source/developer-guide/annexes/index.html
similarity index 63%
copy from source/developer-guide/annexes/geoapi/index.html
copy to source/developer-guide/annexes/index.html
index 84f636fd..774b8bcd 100644
--- a/source/developer-guide/annexes/geoapi/index.html
+++ b/source/developer-guide/annexes/index.html
@@ -28,23 +28,23 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h1 id="GeoAPI-details">GeoAPI relationship with standards</h1>
+ <h1 id="Annexes">Annexes</h1>
</header>
-
<p>
- The GeoAPI project has been briefly presented <a href="#GeoAPI">in introduction</a> to this document.
- This annex explains in more details how GeoAPI relates to international standards.
- The goal is to allow developers to reduce their dependency toward GeoAPI or Apache SIS specificities.
+ The rest of this document provides historical contexts, rational behind some design choices
+ and guidance for reducing the dependency of an application to Apache SIS.
+ Those annexes can be safely ignored by most Apache SIS users,
+ but may be useful for developers wanting to create their own geospatial libraries.
</p>
- <xi:include href="Modules.html"/>
- <xi:include href="DefinitionProcess.html"/>
- <xi:include href="ReduceDependency.html"/>
+ <xi:include href="geoapi/index.html"/>
+ <xi:include href="tests/index.html"/>
+ <xi:include href="design/index.html"/>
</section>
</body>
</html>
diff --git a/source/developer-guide/annexes/tests/GeoApiConformance.html b/source/developer-guide/annexes/tests/GeoApiConformance.html
index a998c046..3530f628 100644
--- a/source/developer-guide/annexes/tests/GeoApiConformance.html
+++ b/source/developer-guide/annexes/tests/GeoApiConformance.html
@@ -22,18 +22,18 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
- <title>Tests</title>
+ <title>GeoAPI-conformance</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../../book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h2 id="GeoAPI-conformance">GeoAPI conformance</h2>
+ <h3 id="GeoAPI-conformance">GeoAPI conformance</h3>
</header>
<p>
The <code>geoapi-conformance</code> module provides <i>validators</i>, a JUnit <i>test suite</i>, and <i>report generators</i>
@@ -50,7 +50,7 @@
- <h3 id="GeoAPI-validators">Instance validations</h3>
+ <h4 id="GeoAPI-validators">Instance validations</h4>
<p>
GeoAPI can validate an instance of its interfaces by checking that certain constraints are observed.
Many constraints can not be expressed in the method signature. Those constraints
@@ -136,7 +136,7 @@ public class MyTest {
- <h3 id="GeoAPI-tests">Executing pre-defined tests</h3>
+ <h4 id="GeoAPI-tests">Executing pre-defined tests</h4>
<p>
JUnit tests are defined in the <code>org.opengis.test</code> sub-packages.
All test classes bear a name ending in "<code>Test</code>".
diff --git a/source/developer-guide/annexes/tests/index.html b/source/developer-guide/annexes/tests/index.html
index 06a9fc1f..c609c93e 100644
--- a/source/developer-guide/annexes/tests/index.html
+++ b/source/developer-guide/annexes/tests/index.html
@@ -22,18 +22,18 @@
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
<head>
- <title>Annexes</title>
+ <title>Tests</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../../book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h1 id="Tests">Test suites</h1>
+ <h2 id="Tests">Test suites</h2>
</header>
<p>
In addition to its own tests, Apache SIS uses tests defined by GeoAPI.
diff --git a/source/developer-guide/coverage/AffineTransform.html b/source/developer-guide/coverage/AffineTransform.html
new file mode 100644
index 00000000..764e6229
--- /dev/null
+++ b/source/developer-guide/coverage/AffineTransform.html
@@ -0,0 +1,127 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
+ <head>
+ <title>AffineTransform</title>
+ <meta charset="UTF-8"/>
+ <link rel="stylesheet" type="text/css" href="../../book.css"/>
+ </head>
+ <body>
+ <!--
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
+ -->
+ <section>
+ <header>
+ <h3 id="AffineTransform">Affine transform</h3>
+ </header>
+ <p>
+ Among the many kinds of operations performed by <abbr>GIS</abbr> software products on spatial coordinates,
+ <dfn>affine transforms</dfn> are both relatively simple and very common.
+ Affine transforms can represent any combination of scales, shears, flips, rotations and translations,
+ which are <em>linear</em> operations.
+ Affine transforms can not handle <em>non-linear</em> operations like map projections,
+ but the affine transform capabilities nevertheless cover many other cases:
+ </p>
+ <ul>
+ <li>Axis order changes, for example from (<var>latitude</var>, <var>longitude</var>) to (<var>longitude</var>, <var>latitude</var>).</li>
+ <li>Axis direction changes, for example the <var>y</var> axis oriented toward down in images.</li>
+ <li>Prime meridian rotations, for example from <cite>Paris</cite> to <cite>Greenwich</cite> prime meridian.</li>
+ <li>Dimensionality changes, for example from 3-dimensional coordinates to 2-dimensional coordinates by dropping the height.</li>
+ <li>Unit conversion, for example from feet to metres.</li>
+ <li>Pixel to geodetic coordinate, for example the conversion represented in the <code>.tfw</code> files associated to some <abbr>TIFF</abbr> images.</li>
+ <li>Part of map projections, for example the <cite>False Easting</cite>, <cite>False Northing</cite> and <cite>Scale factor</cite> parameters.</li>
+ </ul>
+ <p>
+ Affine transforms can be concatenated efficiently.
+ No matter how many affine transforms are chained, the result can be represented by a single affine transform.
+ Affine transforms are extensively used by Apache <abbr>SIS</abbr> for “pixel to geographic or projected coordinate” conversions.
+ Given an image with pixel coordinates represented by (<var>x</var>,<var>y</var>) tuples and given the following assumptions:
+ </p>
+ <ul>
+ <li>There is no shear, no rotation and no flip.</li>
+ <li>All pixels have the same width in degrees of longitude.</li>
+ <li>All pixels have the same height in degrees of latitude.</li>
+ <li>Pixel indices are positive integers starting at (0,0) inclusive.</li>
+ </ul>
+ <p>Then conversions from pixel coordinates (<var>x</var>,<var>y</var>)
+ to geographic coordinates (<var>λ</var>,<var>φ</var>) can be represented by the following equations,
+ where <var>N</var><sub><var>x</var></sub> is the image width and
+ <var>N</var><sub><var>y</var></sub> the image height in number of pixels:
+ </p><p>
+ <xi:include href="../../../layouts/partials/math/PixelToGeographicTerms.html"/>
+ </p><p>
+ Above equations can be represented in matrix form as below:
+ </p><p>
+ <xi:include href="../../../layouts/partials/math/PixelToGeographic.html"/>
+ </p><p>
+ In this particular case, scale factors <var>S</var> are the pixel size in degrees
+ and translation terms <var>T</var> are the geographic coordinate of an image corner
+ (not necessarily the lower-left corner if some axes have been flipped).
+ This straightforward interpretation holds because of above-cited assumptions, but
+ matrix coefficients become more complex if the image has shear or rotation
+ or if pixel coordinates do not start at (0,0).
+ However it is not necessary to use more complex equations for supporting more generic cases.
+ The following example starts with an “initial conversion” matrix
+ where the <var>S</var> and <var>T</var> terms are set to the most straightforward values.
+ Then the <var>y</var> axis direction is reversed for matching the most common convention in image coordinate systems (change 1),
+ and axis are swapped resulting in latitude before longitude (change 2).
+ Note that when affine transform concatenations are written as matrix multiplications, operations are ordered from right to left:
+ <var>A</var>×<var>B</var>×<var>C</var> is equivalent to first applying operation <var>C</var>,
+ then operation <var>B</var> and finally operation <var>A</var>.
+ </p>
+ <div style="display:table; margin:auto">
+ <div style="display:table-row">
+ <div style="display:table-cell" class="caption">Change 2</div>
+ <div style="display:table-cell" class="caption"> </div>
+ <div style="display:table-cell" class="caption">Change 1</div>
+ <div style="display:table-cell" class="caption"> </div>
+ <div style="display:table-cell" class="caption">Initial conversion</div>
+ <div style="display:table-cell" class="caption"> </div>
+ <div style="display:table-cell" class="caption">Concatenated operation</div>
+ </div>
+ <div style="display:table-row">
+ <div style="display:table-cell; vertical-align:middle"><xi:include href="../../../layouts/partials/math/AxisSwapping2D.html"/></div>
+ <div style="display:table-cell; vertical-align:middle; padding-left: 15px; padding-right: 15px">×</div>
+ <div style="display:table-cell; vertical-align:middle"><xi:include href="../../../layouts/partials/math/InverseAxisY.html"/></div>
+ <div style="display:table-cell; vertical-align:middle; padding-left: 15px; padding-right: 15px">×</div>
+ <div style="display:table-cell; vertical-align:middle"><xi:include href="../../../layouts/partials/math/PixelToGeographicSameAxisDirections.html"/></div>
+ <div style="display:table-cell; vertical-align:middle; padding-left: 15px; padding-right: 15px">=</div>
+ <div style="display:table-cell; vertical-align:middle"><xi:include href="../../../layouts/partials/math/PixelToGeographicReverseOrderAndY.html"/></div>
+ </div>
+ </div>
+ <p>
+ A key principle is that there is no need to write Java code dedicated to above kinds of axis changes.
+ Those operations, and many other, can be handled by matrix algebra.
+ This approach makes easier to write generic code and improves performance.
+ Apache <abbr>SIS</abbr> follows this principle by using affine transforms for every operations
+ that can be performed by such transform.
+ For instance there is no code dedicated to changing order of ordinate values in a coordinate.
+ </p>
+
+ <div class="warning">
+ This section is incomplete.
+ </div>
+ </section>
+ </body>
+</html>
diff --git a/source/developer-guide/geometry/index.html b/source/developer-guide/coverage/GridGeometry.html
similarity index 65%
copy from source/developer-guide/geometry/index.html
copy to source/developer-guide/coverage/GridGeometry.html
index 1419f94c..92f17f86 100644
--- a/source/developer-guide/geometry/index.html
+++ b/source/developer-guide/coverage/GridGeometry.html
@@ -22,25 +22,28 @@
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
<head>
- <title>Geometry</title>
+ <title>GridGeometry</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html"
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h1 id="Geometry">Geometries</h1>
+ <h2 id="GridGeometry">Grid coverage domain</h2>
</header>
<p>
- This chapter introduces a few aspects of <abbr>ISO</abbr> 19107 standard (<i>Spatial schema</i>)
- and the Apache <abbr>SIS</abbr> classes that implement them.
+ The domain of a coverage is the set of valid input values.
+ In Apache <abbr>SIS</abbr>, the domain of grid coverages is described by the <code>GridGeometry</code> class.
</p>
+ <div class="warning">
+ This section is incomplete. See Javadoc for more details.
+ </div>
- <xi:include href="GeometryBase.html"/>
+ <xi:include href="AffineTransform.html"/>
</section>
</body>
</html>
diff --git a/source/developer-guide/coverage/SampleDimension.html b/source/developer-guide/coverage/SampleDimension.html
new file mode 100644
index 00000000..9cc55283
--- /dev/null
+++ b/source/developer-guide/coverage/SampleDimension.html
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+ <head>
+ <title>SampleDimension</title>
+ <meta charset="UTF-8"/>
+ <link rel="stylesheet" type="text/css" href="../book.css"/>
+ </head>
+ <body>
+ <!--
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
+ -->
+ <section>
+ <header>
+ <h2 id="SampleDimension">Sample dimensions</h2>
+ </header>
+ <p>
+ The range of a coverage is the set of valid output values.
+ In Apache <abbr>SIS</abbr>, the distinction between ranges of numerical values and range of any types of values is represented by
+ <code>NumberRange</code> and <code>Range</code> classes respectively.
+ The <code>NumberRange</code> is used more often, and is also the one that most closely approaches the
+ <a href="http://en.wikipedia.org/wiki/Interval_%28mathematics%29">the common mathematical concept of an interval</a>.
+ This textual representation approaches the specifications of <abbr>ISO</abbr> 31-11 standard,
+ except that the comma is replaced by the character “…” as the separator of minimal and maximal values.
+ For example, “[0 … 256)” represents the range of values from 0 inclusive to 256 exclusive.
+ </p><p>
+ <code>Range</code> objects are only indirectly associated with coverages.
+ In <abbr>SIS</abbr>, the values that can return coverages are described by objects of the
+ <code>SampleDimension</code> type.
+ It is these that contain instances of <code>Range</code>,
+ as well as other information such as <i>transfer function</i> (described later).
+ </p>
+ <div class="warning">
+ This section is incomplete. See Javadoc for more details.
+ </div>
+
+ <p>
+ The <code class="SIS">SampleDimension.Builder</code> provides convenience methods for building the sample dimensions of a coverage.
+ The usage pattern is to invoke the following methods:
+ </p>
+ <ul>
+ <li><code>setName(…)</code> for giving a name to a band.</li>
+ <li><code>addQuantitative(…)</code> for declaring a range of sample values to convert to units of measurement.</li>
+ <li><code>addQualitative(…)</code> for declaring "no data" values.</li>
+ <li><code>setBackground(…)</code> for declaring a "no data" value which can also be used for filling empty space.</li>
+ </ul>
+ </section>
+ </body>
+</html>
diff --git a/source/developer-guide/coverage/index.html b/source/developer-guide/coverage/index.html
index ac52b67c..777acac0 100644
--- a/source/developer-guide/coverage/index.html
+++ b/source/developer-guide/coverage/index.html
@@ -20,88 +20,52 @@
under the License.
-->
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
<head>
- <title>Data coverages</title>
+ <title>Coverage</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h1 id="Coverage">Data coverages</h1>
+ <h1 id="Coverage">Data as coverage</h1>
</header>
<p>
- Images, or <i>rasters</i>, are a particular case of a data structure called a <i>coverage</i>.
- We could think of this as a “coverage of data.”
- The title of the <abbr>ISO</abbr> 19123 standard that describes them, “Coverage Geometry and Functions”,
- nicely summarizes the two essential elements of coverages:
+ Images, or <dfn>rasters</dfn>, are a particular case of a data structure called a <dfn>coverage</dfn>.
+ A coverage is a function which returns attribute values from an input coordinate.
+ The set of valid input values is called the <dfn>domain</dfn>, while the set of possible output values is called the <dfn>range</dfn>.
+ The domain is often the spatio-temporal area covered by the data,
+ but <abbr>SIS</abbr> does not prevents coverages from extending to other dimensions.
+ For example, thermodynamic studies often use an area where the dimensions are temperature and pressure.
</p>
- <ul>
- <li>
- <p>
- A coverage is a function which returns an attribute value from an entered coordinate.
- The set of values that may be entered is called the domain, while the set of values that may be returned is called the range.
- The domain is often the spatio-temporal area covered by the data,
- but nothing in <abbr>SIS</abbr> prevents coverages from extending to other dimensions.
- For example, thermodynamic studies often use an area where the dimensions are temperature and pressure.
- </p>
- <div class="example"><p><b>Example:</b>
- The pixel values of an image may contain measures for terrain elevation.
- If the function <var>h</var> = <var>f</var>(φ,λ) allows us to obtain (eventually, with the help of interpolations)
- the elevation <var>h</var> according the the geographic coordinate (φ,λ),
- then the geographic envelope of the image defined by the domain — the function <var>f</var> — is the <i>coverage</i>,
- and the set of values <var>h</var> that this function can return is the <i>range</i>.
- </p></div>
- </li>
- <li>
- <p>
- Different types of coverages may be characterized by the geometry of their cells.
- In particular, a coverage is not necessarily composed of quadrilateral cells.
- However, given that quadrilateral cells are by far the most frequent (since this is the usual geometry of image pixels),
- we often use the term “grid coverage” to specify coverages composed of such cells.
- In <abbr>SIS</abbr>, the geometry of coverages is described by the <code>GridGeometry</code> class.
- </p>
- </li>
- </ul>
+ <div class="example"><p><b>Example:</b>
+ Digital Elevation Models (<abbr>DEM</abbr>) are often represented as images where pixel values are terrain elevation values.
+ This image can be used as the basis of an <var>h</var> = <var>f</var>(φ,λ) function providing
+ (eventually by interpolations between pixels) the elevation <var>h</var> at the geographic coordinate (φ,λ).
+ In that case, the <var>f</var> function is the <dfn>coverage</dfn>,
+ the geographic envelope of the image is the <dfn>domain</dfn>,
+ and the set of pixel values <var>h</var> that this function can return is the <dfn>range</dfn>.
+ </p></div>
<p>
- The characteristics of the spatial domain are defined by <abbr>ISO</abbr> 19123 standard,
- while the characteristics of range are not included in the standard.
- The standard simply mentions that ranges may be finite or infinite,
- and are not necessarily numerical.
- For example, the values returned by a coverage may come from an enumeration (“this is a forest,” “this is a lake,” etc.).
- However, the standard defines two important types of coverage which have an impact on the types of authorized ranges:
- <i>discrete</i> coverages and <i>continuous</i> coverages.
- Stated simply, continuous coverages are functions that can use interpolation methods.
- Thus, since interpolations are only possible with numeric values, the ranges of non-numeric values may only be used with coverages of the
- <code>CV_DiscreteCoverage</code> type.
+ Ranges may be finite or infinite, and are not necessarily numerical.
+ For example, the values returned by a coverage may come from an enumeration (“this is a forest”, “this is a lake”, <i>etc.</i>).
+ However in the enumeration case, interpolations are not allowed.
+ A coverage without interpolation is called a <dfn>discrete coverage</dfn>
+ while a coverage that allows interpolations is called a <dfn>continuous coverage</dfn>.
+ </p><p>
+ Different types of coverages may also be characterized by the geometry of their cells.
+ In particular, a coverage is not necessarily composed of quadrilateral cells.
+ However, given that quadrilateral cells are by far the most frequent (since this is the usual geometry of image pixels),
+ we use the <dfn>grid coverage</dfn> term to specify coverages composed of such cells.
</p>
- <aside>
- <h2>SIS’s <code>Range</code> class and its relationship to the standards</h2>
- <p>
- The distinction between the ranges of all types of values and the ranges of numeric values is represented in
- <abbr>SIS</abbr> by the <code>Range</code> and <code>NumberRange</code>
- classes respectively.
- The <code>NumberRange</code> is used more often, and is also the one that most closely approaches the
- <a href="http://en.wikipedia.org/wiki/Interval_%28mathematics%29">the common mathematical concept of an interval</a>.
- This textual representation approaches the specifications of <abbr>ISO</abbr> 31-11 standard,
- except that the comma is replaced by the character “…” as the separator of minimal and maximal values.
- For example, “[0 … 256)” represents the range of values from 0 inclusive to 256 exclusive.
- </p>
- <p>
- <code>Range</code> objects are only indirectly associated with coverages.
- In <abbr>SIS</abbr>, the values that can return coverages are described by objects of the
- <code class="SIS">SampleDimension</code> type. It is these that contain instances of <code>Range</code>,
- as well as other information such as <i>transfer function</i> (described later).
- </p>
- </aside>
- <div class="warning">
- This section is incomplete. See Javadoc for more details.
- </div>
+
+ <xi:include href="GridGeometry.html"/>
+ <xi:include href="SampleDimension.html"/>
</section>
</body>
</html>
diff --git a/source/developer-guide/geometry/GeometryBase.html b/source/developer-guide/geometry/Envelope.html
similarity index 74%
rename from source/developer-guide/geometry/GeometryBase.html
rename to source/developer-guide/geometry/Envelope.html
index eb7ef2d2..df851109 100644
--- a/source/developer-guide/geometry/GeometryBase.html
+++ b/source/developer-guide/geometry/Envelope.html
@@ -22,66 +22,22 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
- <title>GeometryBase</title>
+ <title>Envelope</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html"
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h2 id="GeometryBase">Base classes</h2>
+ <h2 id="Envelope">Envelopes</h2>
</header>
- <p>
- Each geometric object is considered an infinite set of points.
- As a set, their most fundamental operations are of the same nature as the standard operations of Java collections.
- We may therefore see a geometry as a kind of <code>java.util.Set</code> in which the elements are points,
- except that the number of elements contained in the set is infinite (with the exception of geometries representing a simple point).
- To better represent this concept, the <abbr>ISO</abbr> standard and GeoAPI define a <code class="OGC">TransfiniteSet</code> interface
- which we could see as a <code>Set</code> of infinite size.
- Although a parent relationship exists conceptually between these interfaces,
- GeoAPI does not define <code>TransfiniteSet</code> as a sub-interface of <code>java.util.Set</code>,
- as the definition of certain methods such as <code>size()</code> and <code>iterator()</code> would be problematic.
- However, we find very similar methods such as <code class="GeoAPI">contains(…)</code> and <code class="GeoAPI">intersects(…)</code>.
- </p>
- <p>
- All geometries are specializations of <code>TransfiniteSet</code>.
- The parent class of those geometries is called <code>GM_Object</code> in <abbr>ISO</abbr> 19107 standard.
- GeoAPI interfaces use the <code>Geometry</code> name instead, as the omission of the <code class="OGC">GM_</code>
- prefix (as prescribed in GeoAPI convention) would leave a name too similar to Java’s <code>Object</code> class.
- </p>
-
-
-
- <h3 id="DirectPosition">Direct points and positions</h3>
- <p>
- <abbr>ISO</abbr> 19107 defines two types of structures to represent a point:
- <code>GM_Point</code> and <code class="OGC">DirectPosition</code>.
- The first type is a true geometry and may therefore be relatively cumbersome, depending on the implementation.
- The second type is not formally considered to be a geometry;
- it extends neither <code>GM_Object</code> nor <code class="OGC">TransfiniteSet</code>.
- It barely defines any operations besides the storing of a sequence of numbers representing a coordinate.
- It may therefore be a more lightweight object.
- </p>
- <p>
- In order to allow the <abbr>API</abbr> to work equally with these two types of positions,
- <abbr>ISO</abbr> 19107 defines <code class="OGC">Position</code> as a <cite>union</cite> of
- <code class="OGC">DirectPosition</code> and <code>GM_Point</code>.
- It is a union in the sense of C/C++. For the Java language, GeoAPI obtains the same effect by defining
- <code>Position</code> as the parent interface of <code>DirectPosition</code> and <code>Point</code>.
- In practice, the great majority of Apache <abbr>SIS</abbr>’s <abbr>API</abbr> works on <code>DirectPosition</code>s,
- or occasionally on <code>Position</code>s when it seems useful to also allow geometric points.
- </p>
-
-
-
- <h3 id="Envelope">Envelopes</h3>
<p>
Envelopes store minimal and maximal coordinate values of a geometry.
- Envelopes are <em>not</em> geometries themselves; they are not infinite sets of points (<code class="OGC">TransfiniteSet</code>).
+ Envelopes are <em>not</em> geometries themselves; they are not infinite sets of points (<code>TransfiniteSet</code>).
There is no guarantee that all the positions contained within the limits of an envelope are geographically valid.
Envelopes must be seen as information about extreme values that might take the coordinates of a geometry as if
each dimension were independent of the others, nothing more.
@@ -91,10 +47,10 @@
<div class="example"><p><b>Example:</b>
We could test whether a position is within the limits of an envelope.
A positive result does not guarantee that the position is within the geometry delimited by the envelope,
- but a negative result guarantees that it is outside the envelope.
+ but a negative result guarantees that it is outside the geometry.
We can perform intersection tests in the same way.
On the other hand, it makes little sense to apply a rotation to an envelope,
- as the result may be very different from that which we would obtain be performing a rotation on the original geometry,
+ as the result may be very different from that which we would obtain by performing a rotation on the original geometry,
and then recalculating its envelope.
</p></div>
<p>
@@ -109,7 +65,7 @@
- <h4 id="AntiMeridian">Envelopes that cross the antimeridian</h4>
+ <h3 id="AntiMeridian">Crossing the antimeridian</h3>
<p>
Minimums and maximums are the values most often assigned to <code class="OGC">lowerCorner</code>
and <code class="OGC">upperCorner</code>.
@@ -182,13 +138,13 @@
Moreover, the envelope’s coordinates must be included within the system of coordinates,
unless the developer explicitly decides to consider (for example) 300° longitude as a position distinct from -60°.
The <code>GeneralEnvelope</code> class provides a <code class="SIS">normalize()</code> method to bring
- coordinates within the desired limits, sometimes at the coast of <cite><i>lower</i></cite> values being higher than
- <cite><i>upper</i></cite> values.
+ coordinates within the desired limits, sometimes at the cost of <var>lower</var> values being higher than
+ <var>upper</var> values.
</p>
<aside>
<h5>The special case of [+0 … -0] range</h5>
<p>
- Java (or more generally, IEEE Standard 754) defines two values distinct from zero:
+ Java (or more generally, IEEE Standard 754) defines two zero values:
a positive zero and a negative zero. These two values are considered equal when we compare them with the <code>==</code> operator in Java.
But in <abbr>SIS</abbr> envelopes, they may actually return opposite results for axes using <code>RangeMeaning.WRAPAROUND</code>.
An envelope whose range is [0 … 0], [-0 … -0] or [-0 … +0] would normally be considered an empty envelope,
@@ -200,6 +156,50 @@
then it is guaranteed that the envelope is empty.
</p>
</aside>
+
+
+
+ <h3 id="EnvelopeTransform">Transforming to another reference system</h3>
+ <p>
+ Geographic information systems often need to transform an envelope
+ from one Coordinate Reference System (<abbr>CRS</abbr>) to another.
+ But a naive approach transforming the 4 corners is not sufficient.
+ The figure below shows an envelope before a map projection and the geometric shape
+ that we would get if all points (not only the corners) were projected.
+ The resulting geometric shape is more complex than a rectangle because of the curvature caused by the map projection.
+ Computing the envelope that contains the 4 corners of that shape is not enough,
+ because the area in the bottom of the projected shape is lower than the two bottom corners.
+ That surface would be outside the envelope.
+ </p>
+ <div class="row-of-boxes">
+ <div>
+ <div class="caption">Envelope before projection</div>
+ <img style="border: solid 1px; margin-right: 15px" src="../../../static/book/images/GeographicArea.png" alt="Envelope in a geographic CRS"/>
+ </div><div>
+ <div class="caption">Geometric shape after projection</div>
+ <img style="border: solid 1px; margin-left: 15px" src="../../../static/book/images/ConicArea.png" alt="Shape in a projected CRS"/>
+ </div>
+ </div>
+ <p>
+ Sampling a larger number of points reduces the problem but does not resolve it.
+ <a href="#TransformDerivative">Map projection derivatives</a> offer a more efficient way to resolve this problem
+ (see the <a href="#DerivativeAndEnvelope">annex</a> for more mathematical details).
+ Another complication occurs if the envelope contains the North or South pole.
+ For making a long story short, transforming an envelope is <em>a lot</em> more complicated than it looks like.
+ Apache <abbr>SIS</abbr> contains a few utility methods for making this task easier.
+ For transforming an envelope to another <abbr>CRS</abbr> (<cite>WGS 84 / World Mercator</cite> in this example):
+ </p>
+<pre><code>CoordinateReferenceSystem targetCRS = CRS.forCode("EPSG:3395");
+Envelope transformed = Envelopes.transform(envelope, targetCRS);</code></pre>
+ <p>
+ If envelopes are transformed in the goal of using a common <abbr>CRS</abbr> before to compute the union of many envelopes,
+ an additional complication is that each envelope may use a <abbr>CRS</abbr> with a relatively small domain of validity.
+ The union operation needs to find a <abbr>CRS</abbr> valid in a domain large enough for containing all envelopes.
+ It may be a <abbr>CRS</abbr> different than all <abbr>CRS</abbr> used by the source envelopes.
+ Apache <abbr>SIS</abbr> has an utility method for handling this additional complexity.
+ This method accepts an arbitrary amount of envelopes that may be in different <abbr>CRS</abbr>:
+ </p>
+ <pre><code>Envelope union = Envelopes.union(envelope1, envelope2, envelope3);</code></pre>
</section>
</body>
</html>
diff --git a/source/developer-guide/geometry/index.html b/source/developer-guide/geometry/index.html
index 1419f94c..4dcafc1e 100644
--- a/source/developer-guide/geometry/index.html
+++ b/source/developer-guide/geometry/index.html
@@ -28,19 +28,34 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html"
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
<h1 id="Geometry">Geometries</h1>
</header>
<p>
- This chapter introduces a few aspects of <abbr>ISO</abbr> 19107 standard (<i>Spatial schema</i>)
- and the Apache <abbr>SIS</abbr> classes that implement them.
+ Each geometric object is considered as an infinite set of points
+ (except the <code>Point</code> object which contains only itself).
+ To better represent this concept, the <code>TransfiniteSet</code> interface
+ can be seen as a <code>Set</code> of potentially infinite size in which the elements are points.
+ All geometries are specializations of <code>TransfiniteSet</code>.
+ </p><p>
+ There is two types of structures to represent a point: <code>Point</code> and <code>DirectPosition</code>.
+ The first type is a true geometry and may therefore be relatively cumbersome, depending on the implementation.
+ The second type is not formally considered to be a geometry;
+ it extends neither <code>Geometry</code> nor <code>TransfiniteSet</code>.
+ It barely defines any operations besides the storing of a sequence of numbers representing a coordinate.
+ It may therefore be a more lightweight object.
+ </p><p>
+ In order to allow the <abbr>API</abbr> to work equally with these two types of positions,
+ <code>Position</code> is defined as a common interface implemented by <code>DirectPosition</code> and <code>Point</code>.
+ In practice, the great majority of Apache <abbr>SIS</abbr>’s <abbr>API</abbr> works on <code>DirectPosition</code>s,
+ and occasionally on <code>Position</code>s when it seems useful to also allow geometric points.
</p>
- <xi:include href="GeometryBase.html"/>
+ <xi:include href="Envelope.html"/>
</section>
</body>
</html>
diff --git a/source/developer-guide/index.html b/source/developer-guide/index.html
index 14474e39..e911f09f 100644
--- a/source/developer-guide/index.html
+++ b/source/developer-guide/index.html
@@ -25,7 +25,7 @@
xml:lang = "en">
<head>
- <title>Introduction to Apache SIS</title>
+ <title>Apache SIS developer guide</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../book.css"/>
<script src="../toc.js">/* highlighter */</script>
@@ -38,18 +38,16 @@
<main>
<p style="margin-top:30pt; font-size:30pt; font-weight:900; text-align:center">
- Introduction to Apache SIS™
+ Apache SIS™ developer guide
</p>
<xi:include href="introduction/index.html"/>
- <xi:include href="overview/DataAccess.html"/>
<xi:include href="coverage/index.html"/>
<xi:include href="geometry/index.html"/>
<xi:include href="referencing/index.html"/>
+ <xi:include href="metadata/index.html"/>
<xi:include href="storage/index.html"/>
<xi:include href="utility/index.html"/>
- <xi:include href="annexes/geoapi/index.html"/>
- <xi:include href="annexes/tests/index.html"/>
- <xi:include href="annexes/design/index.html"/>
+ <xi:include href="annexes/index.html"/>
</main>
</body>
</html>
diff --git a/source/developer-guide/introduction/AboutBook.html b/source/developer-guide/introduction/AboutBook.html
deleted file mode 100644
index 98d45d26..00000000
--- a/source/developer-guide/introduction/AboutBook.html
+++ /dev/null
@@ -1,89 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE html>
-
-<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
--->
-
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
- <head>
- <title>AboutBook</title>
- <meta charset="UTF-8"/>
- <link rel="stylesheet" type="text/css" href="../book.css"/>
- </head>
- <body>
- <!--
- Content below this point is copied in "/static/book/en/developer-guide.html"
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
- -->
- <section>
- <header>
- <h2 id="AboutBook">Conventions used in this guide</h2>
- </header>
- <p>
- The elements defined in a computer language, such as classes and methods in Java or elements in an <abbr>XML</abbr> document,
- appear in monospaced font.
- In order to facilitate an understanding of the relationships between Apache <abbr>SIS</abbr> and the standards,
- these elements are also represented using the following colour codes:
- </p>
- <ul>
- <li>
- Elements in blue are defined in an <abbr title="Open Geospatial Consortium">OGC</abbr> standard
- or an <abbr title="International Organization for Standardization">ISO</abbr> standard.
- Example: <code>CD_Ellipsoid</code>.
- </li>
- <li>
- Elements in green are defined in GeoAPI.
- Example: <code>Ellipsoid</code>.
- </li>
- <li>
- Elements in brown are defined in Apache <abbr title="Spatial Information System">SIS</abbr>.
- Example: <code>DefaultEllipsoid</code>.
- </li>
- <li>
- Elements left in black are either defined elsewhere (example: <code>String</code>),
- or there is simply no emphasis on that element for the discussion.
- </li>
- </ul>
- <p>
- Text in gray boxes are for information purpose only and can be ignored.
- </p>
-
-
-
- <h3 id="ChosenTerms">Chosen terms</h3>
- <p>
- Standards sometimes favour the application of certain generic terms to particular contexts,
- which may differ from the context in which other communities use these terms.
- For example, the terms <i>domain</i> and <i>range</i> may apply to arbitrary functions in order to designate
- a set of possible values of inputs and outputs respectively.
- But the functions to which they are applied by certain <abbr>ISO</abbr> standards are not the same as the functions to which they are applied by other libraries.
- For example, <abbr>ISO</abbr> 19123 applies these terms to <code>CV_Coverage</code> objects,
- seen as functions in which the <i>domain</i> is the set of spatio-temporal coordinates encompassed by the data,
- and the <i>range</i> is the set of values encompassed.
- But <abbr title="University Corporation for Atmospheric Research">UCAR</abbr>’s <abbr title="Network Common Data Form">netCDF</abbr> library
- applies these terms instead to the function of converting pixel indices (its <i>domain</i>) to spatial-temporal coordinates (its <i>range</i>).
- Thus the <abbr>UCAR</abbr> library’s <i>range</i> may be the <i>domain</i> of <abbr>ISO</abbr> 19123.
- </p><p>
- The Apache <abbr>SIS</abbr> library prefers as much as possible to use terms in the sense of <abbr>OGC</abbr> and <abbr>ISO</abbr> norms.
- Particular care must be taken, however, with the interfaces between <abbr>SIS</abbr> and certain other external libraries,
- in order to reduce the risk of confusion.
- </p>
- </section>
- </body>
-</html>
diff --git a/source/developer-guide/introduction/Conventions.html b/source/developer-guide/introduction/Conventions.html
new file mode 100644
index 00000000..daacaf70
--- /dev/null
+++ b/source/developer-guide/introduction/Conventions.html
@@ -0,0 +1,113 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+ <head>
+ <title>Conventions</title>
+ <meta charset="UTF-8"/>
+ <link rel="stylesheet" type="text/css" href="../book.css"/>
+ </head>
+ <body>
+ <!--
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
+ -->
+ <section>
+ <header>
+ <h2 id="Conventions">Typographic and naming conventions</h2>
+ </header>
+ <p>
+ The elements defined in a computer language, such as classes and methods in Java or elements in an <abbr>XML</abbr> document,
+ appear in monospaced font in this document.
+ In order to facilitate an understanding of the relationships between Apache <abbr>SIS</abbr> and the standards,
+ these elements are also represented using the following colour codes:
+ </p>
+ <ul>
+ <li>
+ Elements in blue are defined in an <abbr title="International Organization for Standardization">ISO</abbr>
+ or <abbr title="Open Geospatial Consortium">OGC</abbr> standard other than GeoAPI.
+ </li>
+ <li>
+ Elements in green are Java element defined in GeoAPI.
+ </li>
+ <li>
+ Elements in brown are defined in Apache <abbr title="Spatial Information System">SIS</abbr>.
+ </li>
+ <li>
+ Elements left in black are either defined elsewhere (for example the standard Java library),
+ or there is simply no emphasis on that element for the discussion.
+ </li>
+ </ul>
+ <p>
+ For example to represent a projected coordinate reference system (Mercator, Lambert, <i>etc</i>),
+ <code class="OGC">SC_ProjectedCRS</code> is an <abbr>UML</abbr> and <abbr>XML</abbr> element defined by the <abbr>ISO</abbr> 19111 standard.
+ Then <code class="GeoAPI">org.opengis.referencing.crs.<b>ProjectedCRS</b></code> is the implementation-neutral GeoAPI interface derived from that standard,
+ and <code class="SIS">org.apache.sis.referencing.crs.<b>DefaultProjectedCRS</b></code> is the implementation class provided by Apache SIS.
+ </p><p>
+ Apache SIS implements most GeoAPI interfaces by a classes of the same name than the interface
+ but prefixed by <code>Abstract</code>, <code>Default</code> or <code>General</code> word.
+ The <code>General</code> prefix is sometime used instead of <code>Default</code>
+ to indicate that alternative implementations are available for some specific cases.
+ For example the <code class="GeoAPI">Envelope</code> interface is implemented by at least two Apache SIS classes:
+ <code class="SIS">GeneralEnvelope</code> and <code class="SIS">Envelope2D</code>.
+ The first implementation can represent envelopes with any number of dimensions
+ while the second implementation is specialized for two-dimensional envelopes.
+ </p><p>
+ Apache SIS classes prefixed by <code>Abstract</code> should not (in principle) be instantiated.
+ Users should instantiate a non-abstract subclass instead.
+ However many <abbr>SIS</abbr> classes are only conceptually abstract,
+ without <code>abstract</code> Java keyword in class definition.
+ Such classes can be instantiated by a <code>new AbstractXXX(…)</code> statement despite being conceptually abstract.
+ Such instantiations should be avoided, but are nevertheless permitted in last resort when it is not possible to determine the exact subtype.
+ </p>
+ <p>
+ Text in gray boxes, like below (click to expand), are for information purpose only and can be ignored.
+ </p>
+ <details>
+ <summary>Note about the definition of terms</summary>
+ <article id="ChosenTerms">
+ <header>
+ <h2>Source of term definitions</h2>
+ </header>
+ <p>
+ Standards sometimes favour the application of certain generic terms to particular contexts,
+ which may differ from the context in which other communities use these terms.
+ For example, the terms <i>domain</i> and <i>range</i> may apply to arbitrary mathematical functions in order to designate
+ a set of possible values of inputs and outputs respectively.
+ The <abbr>ISO</abbr> 19123 standard applies these terms to <code>CV_Coverage</code> objects,
+ seen as functions in which the <i>domain</i> is the set of spatio-temporal coordinates encompassed by the data,
+ and the <i>range</i> is the set of values encompassed.
+ </p><p>
+ However the functions to which above terms are applied by <abbr>ISO</abbr> standards are not the same as the functions to which they are applied by other libraries.
+ For example <abbr title="University Corporation for Atmospheric Research">UCAR</abbr>’s <abbr title="Network Common Data Form">netCDF</abbr> library
+ applies these terms instead to the function for converting pixel indices (its <i>domain</i>) to spatial-temporal coordinates (its <i>range</i>).
+ Thus the <abbr>UCAR</abbr> library’s <i>range</i> may be the <i>domain</i> of <abbr>ISO</abbr> 19123.
+ </p><p>
+ The Apache <abbr>SIS</abbr> library prefers as much as possible to use terms in the sense of <abbr>OGC</abbr> and <abbr>ISO</abbr> norms.
+ Particular care must be taken, however, with the interfaces between <abbr>SIS</abbr> and certain other external libraries,
+ in order to reduce the risk of confusion.
+ </p>
+ </article>
+ </details>
+ </section>
+ </body>
+</html>
diff --git a/source/developer-guide/overview/DataAccess.html b/source/developer-guide/introduction/DataAccess.html
similarity index 82%
rename from source/developer-guide/overview/DataAccess.html
rename to source/developer-guide/introduction/DataAccess.html
index ef92a2a0..19baeb49 100644
--- a/source/developer-guide/overview/DataAccess.html
+++ b/source/developer-guide/introduction/DataAccess.html
@@ -28,12 +28,12 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h1 id="DataAccess">Geospatial data access</h1>
+ <h2 id="DataAccess">Data access overview</h2>
</header>
<p>
It is possible to instantiate data structures programmatically in memory.
@@ -47,10 +47,9 @@
or other kinds of object specific to the data source.
The <code class="SIS">DataStores.open(Object)</code> method detects data formats
and returns a <code>DataStore</code> instance for that format.
- </p>
- <p>
+ </p><p>
<code>DataStore</code> functionalities depend on the kind of data (coverage, feature set, time series, <i>etc.</i>).
- But in any cases, there is always some metadata that can be obtained.
+ But in all cases, there is always some metadata that can be obtained.
Metadata allows to identify the phenomenon or features described by the data
(temperature, land occupation, <i>etc.</i>),
the geographic area or temporal period covered by the data, together with their resolution.
@@ -59,33 +58,28 @@
legal or technical constraints on data usage,
the history of processing apply on the data,
expected updates schedule, <i>etc.</i>
- </p>
- <p>
+ </p><p>
Various data formats have their own metadata model, but Apache <abbr>SIS</abbr> translates all of them
in a unique metadata model in order to hide this heterogeneity.
- This approach — to select a single metadata model as the <em>pivot model</em> — is often used by other libraries.
- For example Apache Tika uses <cite>Dublin Core</cite> as the pivot metadata model,
- while Java Image I/O defines its own standard metadata model in its <code>javax.imageio.metadata</code> package.
- For Apache <abbr>SIS</abbr>, the chosen pivot model is the <abbr>ISO</abbr> <cite>19115-1:2014 — Fundamentals</cite>
- international standard, completed by <abbr>ISO</abbr> 19115-2 — <cite>Extensions for imagery and gridded data</cite>.
+ This <em>pivot model</em> approach is often used by various libraries,
+ with <cite>Dublin Core</cite> as a popular choice.
+ For Apache <abbr>SIS</abbr>, the chosen pivot model is the <abbr>ISO</abbr> <cite>19115</cite> international standard.
This model organizes metadata in a tree structure where each information is accessible by a well-defined path,
regardless the origin of that information.
For example if a data format can provides a geographic bounding box encompassing all data,
then that information will always be accessible (regardless the data format) from the root <code>Metadata</code> object
- under the <code class="OGC">identificationInfo</code> node, <code class="OGC">extent</code> sub-node,
- <code class="OGC">geographicElement</code> sub-node.
+ under the <code class="OGC">identificationInfo</code> node, <code class="OGC">extent</code> sub-node,
+ <code class="OGC">geographicElement</code> sub-node.
</p>
<div class="example"><p><b>Example:</b>
following code read a metadata file from a Landsat-8 image and prints the declared geographic bounding box:
</p>
-<pre><code>try (DataStore ds = DataStores.open(new File("LC81230522014071LGN00_MTL.txt"))) {
- Metadata md = ds.<code class="SIS">getMetadata()</code>;
+<pre><code>try (DataStore store = DataStores.open(new File("LC81230522014071LGN00_MTL.txt"))) {
+ Metadata overview = store.<code class="SIS">getMetadata()</code>;
- // In order to make this example simpler, null values and empty collection checks are omited.
- Identification idInfo = md .<code class="GeoAPI">getIdentificationInfo()</code>.iterator().next();
- Extent extent = idInfo.<code class="GeoAPI">getExtents()</code> .iterator().next();
- GeographicExtent bbox = extent.<code class="GeoAPI">getGeographicElements()</code>.iterator().next();
+ // Convenience method for fetching the geographic bounding box at the right location in metadata tree.
+ GeographicBoundingBox bbox = <code class="SIS">Extents.getGeographicBoundingBox</code>(overview);
System.out.println("The geographic bounding box is:");
System.out.println(bbox);
@@ -101,12 +95,6 @@ Geographic Bounding Box
├─East bound longitude…………………………… 110°26′39.66″E
├─South bound latitude…………………………… 10°29′59.604″N
└─North bound latitude…………………………… 12°37′25.716″N</samp></pre>
-
- <p>
- The Java code in this example extracts metadata elements by Java method invocations like <code class="GeoAPI">getExtents()</code>,
- but the next chapters will introduce another way using paths given as character strings.
- That later approach is more convenient when the methods to invoke are not known at compile-time.
- </p>
</div>
<p>
@@ -117,9 +105,9 @@ Geographic Bounding Box
For example the <code class="OGC">extent</code> node may contain many geographic areas.
</p>
- <table style="line-height:1">
+ <table class="monospacedHeaderColumn" style="font-size:0.82vw">
<caption>Extract of a few metadata elements from ISO 19115</caption>
- <tr><th>Élément</th> <th>Description</th></tr>
+ <tr><th>Element</th> <th>Description</th></tr>
<tr><td style="padding-top:9px">Metadata</td> <td style="padding-top:9px">Metadata about a dataset, service or other resources.</td></tr>
<tr><td> ├─Reference system info</td> <td>Description of the spatial and temporal reference systems used in the dataset.</td></tr>
<tr><td> ├─Identification info</td> <td>Basic information about the resource(s) to which the metadata applies.</td></tr>
@@ -156,7 +144,16 @@ Geographic Bounding Box
<tr><td> ├─Source</td> <td>Information about the source data used in creating the data specified by the scope.</td></tr>
<tr><td> └─Process step</td> <td>Information about events in the life of a resource specified by the scope.</td></tr>
</table>
- <xi:include href="GetMetadataElement.html"/>
+ <p>
+ Among metadata elements introduced in this chapter, there is one which will be the topic of
+ a <a href="#Referencing">dedicated chapter</a>: <code class="OGC">referenceSystemInfo</code>.
+ Its content is essential for accurate data positioning;
+ without this element, even positions given by latitudes and longitudes are ambiguous.
+ Reference systems have many characteristics that make them apart from other metadata:
+ they are immutable, can not be handled by <code class="SIS">MetadataStandard.ISO_19115.asValueMap(…)</code>,
+ have a particular text representation and are associated to an engine
+ performing coordinate transformation from one reference system to an other.
+ </p>
</section>
</body>
</html>
diff --git a/source/developer-guide/introduction/Installation.html b/source/developer-guide/introduction/Installation.html
new file mode 100644
index 00000000..18f1e5b0
--- /dev/null
+++ b/source/developer-guide/introduction/Installation.html
@@ -0,0 +1,105 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+ <head>
+ <title>Installation</title>
+ <meta charset="UTF-8"/>
+ <link rel="stylesheet" type="text/css" href="../book.css"/>
+ </head>
+ <body>
+ <!--
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
+ -->
+ <section>
+ <header>
+ <h2 id="Installation">Installation</h2>
+ </header>
+ <p>
+ The easiest way to use Apache <abbr>SIS</abbr> is to declare Maven dependencies in the application project.
+ <abbr>SIS</abbr> is divided in about 20 modules, which allow applications to import a subset of the library.
+ The <a href="../../downloads.html">Apache SIS downloads</a> page lists the main modules.
+ The <code>pom.xml</code> fragment below gives all dependencies needed by the code snippets in this document
+ (ignoring core modules such as <code>sis-referencing</code> which are inherited by transitive dependencies).
+ <em>Note that the <code>sis-epsg</code> optional module is not under Apache license.</em>
+ Inclusion of that module is subject to acceptation of <a href="https://epsg.org/terms-of-use.html">EPSG terms of use</a>.
+ It is optional but recommended;
+ see <a href="../../epsg.html">How to use EPSG geodetic dataset</a> page for more information.
+ </p>
+<pre><properties>
+ <sis.version>1.2</sis.version>
+</properties>
+<dependencies>
+ <dependency>
+ <groupId>org.apache.sis.storage</groupId>
+ <artifactId>sis-geotiff</artifactId>
+ <version>${sis.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.sis.storage</groupId>
+ <artifactId>sis-netcdf</artifactId>
+ <version>${sis.version}</version>
+ </dependency>
+
+ <!-- Specialization of GeoTIFF reader for Landsat data. -->
+ <dependency>
+ <groupId>org.apache.sis.storage</groupId>
+ <artifactId>sis-earth-observation</artifactId>
+ <version>${sis.version}</version>
+ </dependency>
+
+ <!-- The following dependency can be omitted if XML support is not desired. -->
+ <dependency>
+ <groupId>org.glassfish.jaxb</groupId>
+ <artifactId>jaxb-runtime</artifactId>
+ <version>2.3.6</version>
+ <scope>runtime</scope>
+ </dependency>
+
+ <!-- <b>This optional dependency requires agreement with EPSG terms of use.</b> -->
+ <dependency>
+ <groupId>org.apache.sis.non-free</groupId>
+ <artifactId>sis-epsg</artifactId>
+ <version>${sis.version}</version>
+ <scope>runtime</scope>
+ </dependency>
+</dependencies></pre>
+
+ <p>
+ The <code>sis-epsg</code> optional module needs a directory where it will install the geodetic database.
+ That directory can be anywhere on the local machine, it shall exist (but should be initially empty),
+ and its location should be specified by the <code>SIS_DATA</code> environment variable.
+ For example on a Unix system
+ (replace <code>user</code> by the actual user name and <code>some_directory</code> by anything):
+ </p>
+<pre>export SIS_DATA=/home/user/some_directory
+mkdir $SIS_DATA</pre>
+ <p>
+ It is possible to avoid the need to setup <code>SIS_DATA</code> directory
+ if the <code>sis-epsg</code> dependency is replaced by <code>sis-embedded-data</code>.
+ However the latter is slower, and an <code>SIS_DATA</code> directory is still needed
+ for other purposes such as the installation of datum shift grids.
+ </p>
+ </section>
+ </body>
+</html>
diff --git a/source/developer-guide/introduction/index.html b/source/developer-guide/introduction/index.html
index 040ea629..0563bfbd 100644
--- a/source/developer-guide/introduction/index.html
+++ b/source/developer-guide/introduction/index.html
@@ -22,63 +22,48 @@
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
<head>
- <title>Standards</title>
+ <title>Introduction</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html"
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h1 id="Standards">Standards and norms</h1>
+ <h1 id="Introduction">Introduction</h1>
</header>
<p>
- A geospatial information community is a collection of systems or individuals capable of exchanging their geospatial data
- through the use of common standards, allowing them to communicate with one another.
- As there are many ways to represent geospatial information, each community tends to structure this information in light of its areas of interest.
- This diversity complicates the task of Spatial Information System (<abbr>SIS</abbr>) users
- by confronting them with an apparently chaotic variety of data formats and structures.
- The characteristics of these structures vary according to the observed phenomenon and measurement methods,
- as well as the habits of the organizations producing the data.
- Such a variety represents an obstacle in studies that require heterogeneous combinations of data,
- especially when they originate in communities that are traditionally distinct.
- For example, a researcher studying cholera might be interested in populations of shrimp as a propagation vector of the disease.
- But as doctors and oceanographers may not be used to share their work,
- the participants of such a study may be limited by the effort required to convert the data.
+ Apache <abbr title="Spatial Information System">SIS</abbr> is a free software,
+ Java language library for developing geospatial desktop or server applications.
+ This library provides services for data discovery (metadata), reading and writing vector or raster data,
+ filtering the data and applying operations such as map projections.
+ Apache <abbr>SIS</abbr> data structures follow closely the geospatial models defined in the international standards published by
+ the Open Geospatial Consortium (<abbr>OGC</abbr>) and the International Organization for Standardization (<abbr>ISO</abbr>).
+ The <a href="#Annexes">annex</a> provides more context about international standards.
</p><p>
- We cannot impose a uniform format on all data collections, as the diversity of formats is tied to factors
- such as the constraints imposed by the measuring apparatus, and the statistical distribution of values.
- A more flexible solution is to ensure the interoperability of data across a common programming interface
- (<abbr title="Application Programming Interface">API</abbr>).
- This <abbr>API</abbr> is not necessarily defined in a programming language;
- the actual tendency is rather to define conventions that use existing web protocols, which we can translate into various programming languages.
- But in order for this approach to be viable, the <abbr>API</abbr> must be generally accepted by independent developers.
- In other words, the <abbr>API</abbr> must come as near as possible to industrial standards.
+ The library is an implementation of <abbr title="Open Geospatial Consortium">OGC</abbr> <a href="http://www.geoapi.org">GeoAPI</a> interfaces.
+ In a series of <code>org.opengis.*</code> packages, GeoAPI offers a set of implementation-neutral Java interfaces for geospatial applications.
+ These interfaces closely follow the specifications of the <abbr>OGC</abbr>, while interpreting and adapting them
+ to meet the needs of Java developers — for example, conforming with Java naming conventions.
+ The conceptual model of GeoAPI will be explained in detail in the chapters describing Apache <abbr>SIS</abbr> implementation.
+ However, we can get an overview of its content by consulting the page listing the mapping between
+ <a href="http://www.geoapi.org/3.0/javadoc/content.html">GeoAPI methods and the standards where they come from</a>.
+ The <a href="#GeoAPI">annex</a> provides more details about GeoAPI history and how to use it.
</p><p>
- For example, one task that benefit from a successful standardization is the accessing of relational databases.
- The industry has established a common language — the <abbr title="Structured Query Language">SQL</abbr> standard —
- that the creators of Java have embedded in standard <abbr title="Java DataBase Connectivity">JDBC</abbr> programming interfaces.
- Today, these interfaces are implemented by many software programs, both free and commercial.
- Like databases, methods of accessing geographic information have been standardized.
- In this case, however, the efforts have been more recent, and their integration in software — especially in older programs — is incomplete and not always coherent.
- At the time of writing, no product to our knowledge has implemented all of the specifications in their entirety.
- However, there are many implementations that cover a fairly large spectrum.
- One of these is the Apache <abbr>SIS</abbr>™ library that is described in this document.
+ While Apache <abbr>SIS</abbr> is primarily a library for helping developers to create their own applications,
+ <abbr>SIS</abbr> provides also an optional JavaFX application for testing its capability to read, transform and visualize data files.
+ Screenshots of this application are used in this document for illustrative purposes.
</p><p>
- Apache <abbr title="Spatial Information System">SIS</abbr> is characterized by a sustained effort to comply with standards.
- In general, complying with standards demands a greater effort than would be required for an isolated development,
- but rewards us with a double advantage: not only does it improve the interoperability of our data with that of external projects,
- it also points towards a robust way of elaborating the conceptual model reflected in the <abbr>API</abbr>.
- In effect, the groups of experts who conceived the standards anticipated difficulties that sometimes escape the engineer at the beginning of a project,
- but which risk to hit them before the end.
+ <b>Note:</b> this document contains mathematical formulas expressed in MathML.
+ For viewing those formulas, a MathML-capable browser (e.g. Firefox) is required.
</p>
- <xi:include href="ConceptualModels.html"/>
- <xi:include href="GeoAPI.html"/>
- <xi:include href="AboutBook.html"/>
+ <xi:include href="Conventions.html"/>
+ <xi:include href="Installation.html"/>
+ <xi:include href="DataAccess.html"/>
</section>
</body>
</html>
diff --git a/source/developer-guide/overview/GetMetadataElement.html b/source/developer-guide/metadata/GetMetadataElement.html
similarity index 79%
rename from source/developer-guide/overview/GetMetadataElement.html
rename to source/developer-guide/metadata/GetMetadataElement.html
index b9579cff..591e7b25 100644
--- a/source/developer-guide/overview/GetMetadataElement.html
+++ b/source/developer-guide/metadata/GetMetadataElement.html
@@ -28,8 +28,8 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html"
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
@@ -46,12 +46,13 @@
<pre><code>GeographicBoundingBox bbox = Extents.getGeographicBoundingBox(extent);</code></pre>
<p>
Those conveniences are defined as static methods in order to allow their use with different metadata implementations.
- Even in Apache <abbr>SIS</abbr> library, the <code>DefaultExtent</code> class is not the only implementation of <code>Extent</code> interface.
- There is also implementations fetching information on-demand in a database, or implementations for particular data formats.
Some other classes providing static methods for specific interfaces are
<code>Citations</code>, <code>Envelopes</code>, <code>Matrices</code> and <code>MathTransforms</code>.
- </p><p>
- Those static methods explore fragments of metadata tree in search for requested information,
+ </p>
+
+ <h3 id="MetadataAsMap">View as key-value pairs</h3>
+ <p>
+ Above static methods explore fragments of metadata tree in search for requested information,
but the searches are still targeted to elements whose types and at least part of their paths are known at compile-time.
Sometime the element to search is known only at runtime, or sometime there is a need to iterate over all elements.
In such cases, one can view the metadata as a <code>java.util.Map</code> like below:
@@ -84,15 +85,6 @@ for (String name : elements.keySet()) {
For more information on metadata views, see
<a href="../../apidocs/org/apache/sis/metadata/package-summary.html#package.description"><code>org.apache.sis.metadata</code></a>
package javadoc.
- </p><p>
- Among metadata elements introduced in this chapter, there is one which will be the topic of
- a <a href="#Referencing">dedicated chapter</a>: <code class="OGC">referenceSystemInfo</code>.
- Its content is essential for accurate data positioning;
- without this element, even positions given by latitudes and longitudes are ambiguous.
- Reference systems have many characteristics that make them apart from other metadata:
- they are immutable, can not be handled by <code class="SIS">MetadataStandard.ISO_19115.asValueMap(…)</code>,
- have a particular text representation and are associated to an engine
- performing coordinate transformation from one reference system to an other.
</p>
</section>
</body>
diff --git a/source/developer-guide/storage/index.html b/source/developer-guide/metadata/index.html
similarity index 73%
copy from source/developer-guide/storage/index.html
copy to source/developer-guide/metadata/index.html
index f1a7ca71..f1960d31 100644
--- a/source/developer-guide/storage/index.html
+++ b/source/developer-guide/metadata/index.html
@@ -22,24 +22,21 @@
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
<head>
- <title>Formats</title>
+ <title>Metadata</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../book.css"/>
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h2 id="Formats">Data storage formats</h2>
+ <h1 id="Metadata">Metadata</h1>
</header>
- <p>
- Apache SIS can read and write spatial data and associated metadata in different formats.
- </p>
- <xi:include href="XML-ISO.html"/>
+ <xi:include href="GetMetadataElement.html"/>
</section>
</body>
</html>
diff --git a/source/developer-guide/referencing/AxisOrder.html b/source/developer-guide/referencing/AxisOrder.html
new file mode 100644
index 00000000..3a37acbf
--- /dev/null
+++ b/source/developer-guide/referencing/AxisOrder.html
@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+ <head>
+ <title>AxisOrder</title>
+ <meta charset="UTF-8"/>
+ <link rel="stylesheet" type="text/css" href="../book.css"/>
+ </head>
+ <body>
+ <!--
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
+ -->
+ <section>
+ <header>
+ <h2 id="AxisOrder">Axis order</h2>
+ </header>
+ <p>
+ The axis order is specified by the authority (typically a national agency) defining the <dfn>Coordinate Reference System</dfn> (<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 software products 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 software products,
+ then <abbr>CRS</abbr> forced to <em>longitude first</em> axis order can be created by a call to the following method:
+ </p>
+
+<pre><code>CoordinateReferenceSystem crs = …; // CRS obtained by any means.
+crs = AbstractCRS.castOrCopy(crs).forConvention(AxesConvention.RIGHT_HANDED)</code></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>.
+ </p>
+ </section>
+ </body>
+</html>
diff --git a/source/developer-guide/referencing/ComponentsOfCRS.html b/source/developer-guide/referencing/ComponentsOfCRS.html
index e92dede0..d5a49326 100644
--- a/source/developer-guide/referencing/ComponentsOfCRS.html
+++ b/source/developer-guide/referencing/ComponentsOfCRS.html
@@ -28,12 +28,12 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h2 id="ComponentsOfCRS">Components of a reference system by coordinates</h2>
+ <h2 id="ComponentsOfCRS">Coordinate reference systems</h2>
</header>
<p>
Spatial reference systems by coordinates provide necessary information for mapping numerical coordinate values
@@ -55,7 +55,105 @@
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>
+ <h3 id="ProjectedCRS">Map projections</h3>
+ <p>
+ Map projections represent a curved surface (the Earth surface) on a plane surface (a map or a computer screen).
+ Every rendering of geospatial data on a flat screen uses some kind of map projection, sometime implicitly.
+ Well-designed map projections provide some control over deformations:
+ one can preserve the angles, another projection can preserve the areas,
+ but none can preserve 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>
+ There is thousands of projected <abbr>CRS</abbr> in use around the world.
+ Many of them are published in the <a href="../../epsg.html"><abbr>EPSG</abbr> geodetic database</a>.
+ The easiest way to get a projected <abbr>CRS</abbr> with Apache <abbr>SIS</abbr> is to use its <abbr>EPSG</abbr> code.
+ For example the following code gets the definition of the <cite>JGD2000 / UTM zone 54N</cite> <abbr>CRS</abbr>
+ (for Japan from 138°E to 144°E):
+ </p>
+ <pre><code>CoordinateReferenceSystem crs = CRS.forCode("EPSG:3100");</code></pre>
+ <p>
+ Other ways to get a coordinate reference system will be given in a <a href="#GetCRS">next section</a>.
+ </p>
+
+ <h3 id="GeographicCRS">Geographic reference systems</h3>
+ <p>
+ All map projections are based on a geodetic (usually geographic) <abbr>CRS</abbr>.
+ A geodetic <abbr>CRS</abbr> is a coordinate reference system with latitude, longitude and sometime height axes.
+ There is many kinds of latitudes and longitudes,
+ but two common kinds supported by Apache <abbr>SIS</abbr> are <dfn>geodetic</dfn> and <dfn>geocentric</dfn> latitudes.
+ Those two angles differ slightly in the way they intersect the ellipsoid surface.
+ On Earth surface, the difference between those two kinds of latitude varies between 0 and about 20 km.
+ </p><p>
+ When peoples talk about latitudes and longitudes, they usually mean <em>geodetic</em> latitudes and longitudes.
+ A coordinate reference system using such latitudes and longitudes is said <dfn>geographic</dfn>
+ and is represented by the <code>GeographicCRS</code> interface.
+ Systems using the other kinds of latitude are represented by other <abbr>CRS</abbr> interfaces.
+ </p><p>
+ Theoretically, data expressed in a geographic <abbr>CRS</abbr> can never be rendered directly on a flat screen
+ (they could be rendered directly on a planetarium dome however).
+ In practice we allow data rendering in a geographic <abbr>CRS</abbr>,
+ but this process implicitly uses a <cite>Plate Carrée</cite> projection.
+ </p>
+
+ <h3 id="CompoundCRS">Vertical and temporal dimensions</h3>
+ <p style="color: red">TODO</p>
+
+ <h3 id="CoordinateSystem">Coordinate systems</h3>
+ <p>
+ A Coordinate System (<abbr>CS</abbr>) defines the set of axes that spans a given coordinate space.
+ Each axis defines an approximative direction (north, south, east, west, up, down, port, starboard, past, future, <i>etc.</i>),
+ units of measurement, minimal and maximal values, and what happen after reaching those extremum.
+ For example in longitude case, after +180° the coordinate values continue at −180°.
+ Axes having such behavior are flagged by the <code>RangeMeaning.WRAPAROUND</code> code.
+ </p>
+ <aside>
+ <h4>Generalizing to other types of axes</h4>
+ <p>
+ Wraparound can also exist in time axis. For example in climatological data defining normal temperatures,
+ after December the data sequence restarts to January; those months are associated to no particular year.
+ Apache <abbr>SIS</abbr> allows wraparound to happen on any axis, as long as it is flagged by <code>RangeMeaning</code> code.
+ It is possible to have many wraparound axes in the same coordinate system.
+ </p>
+ </aside>
+ <p>
+ Each Coordinate Reference System (<abbr>CRS</abbr>)
+ is associated with exactly one Coordinate System (<abbr>CS</abbr>).
+ Some properties that we can get from a coordinate system and its axes are shown below.
+ Axes are numbered from 0 to <code>cs.getDimension()-1</code> inclusive.
+ </p>
+
+<pre><code>CoordinateSystem cs = crs.getCoordinateSystem();
+CoordinateSystemAxis secondAxis = cs.getAxis(1); // For a geographic CRS, this is usually geodetic longitude.
+String abbreviation = secondAxis.getAbbreviation(); // For a longitude axis, this is usually "λ", "L" or "lon".
+AxisDirection direction = secondAxis.getDirection(); // For a longitude axis, this is usually EAST. Another occasional value is WEST.
+Unit<?> units = secondAxis.getUnit(); // For a longitude axis, this is usually Units.DEGREE.
+double minimum = secondAxis.getMinimumValue(); // For a longitude axis, this is usually −180°. Another common value is 0°.
+double maximum = secondAxis.getMaximumValue(); // For a longitude axis, this is usually +180°. Another common value is 360°.
+RangeMeaning atEnds = secondAxis.getRangeMeaning(); // For a longitude axis, this is WRAPAROUND.
+</code></pre>
+ <p>
+
+ In addition to axis definitions, another important coordinate system characteristic is their type
+ (<code>CartesianCS</code>, <code>SphericalCS</code>, <i>etc.</i>).
+ The <abbr>CS</abbr> type implies the set of mathematical rules for calculating geometric quantities like angles, distances and surfaces.
+ Usually the various <abbr>CS</abbr> subtypes do not define any new Java methods compared to the parent type,
+ but are nevertheless important for type safety.
+ For example many calculations or associations are legal only when all axes are perpendicular to each other.
+ In such case the coordinate system type is restricted to <code>CartesianCS</code> in method signatures.
+ </p><p>
+ Coordinate systems are mathematical concepts; they do <strong>not</strong> contain any information
+ about where on Earth is located the system origin.
+ Consequently coordinate systems alone are not sufficient for describing a location;
+ they must be combined with a <dfn>datum</dfn> (or <dfn>reference frame</dfn>).
+ Those combinations form the <dfn>coordinate reference systems</dfn> described in previous sections.
+ </p>
+
+
+
+
+ <h3 id="GeodeticDatum">Geodetic datum</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,
@@ -68,7 +166,7 @@
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>.
+ which is a fundamental component in coordinate reference systems of type <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.
@@ -98,8 +196,6 @@ double semiMinor = ellipsoid.<code class="GeoAPI">getSemiMinorAxis()</code>;
double ivf = ellipsoid.<code class="GeoAPI">getInverseFlattening()</code>; // = semiMajor / (semiMajor - semiMinor).
</code></pre>
-
- <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.
@@ -147,126 +243,6 @@ double ivf = ellipsoid.<code class="GeoAPI">getInverseFlattening()</code
has different coordinate values when using those different datums, even if the ellipsoid is identical in both cases.
Coordinate transformations between datums require some kind of database.
</p>
-
- <h3 id="CoordinateSystem">Coordinate systems</h3>
- <p>
- A Coordinate System (<abbr>CS</abbr>) defines the set of axes that spans a given coordinate space.
- Each axis defines an approximative direction (north, south, east, west, up, down, port, starboard, past, future, <i>etc.</i>),
- units of measurement, minimal and maximal values, and what happen after reaching those extremum.
- For example in longitude case, after +180° the coordinate values continue at −180°.
- But such loops may also exist in time axis. For example in climatological data defining normal temperatures,
- after December the data sequence restarts to January; those months are associated to no particular year.
- Axes having such behavior are associated to the <code>RangeMeaning.WRAPAROUND</code> code.
- </p><p>
- Some properties that we can get from a coordinate system and its axes are shown below.
- Axes are numbered from 0 to <code>cs.getDimension()-1</code> inclusive.
- </p>
-
-<pre><code>CoordinateSystem cs = crs.getCoordinateSystem();
-CoordinateSystemAxis secondAxis = cs.getAxis(1); // For a geographic CRS, this is usually geodetic longitude.
-String abbreviation = secondAxis.getAbbreviation(); // For a longitude axis, this is usually "λ", "L" or "lon".
-AxisDirection direction = secondAxis.getDirection(); // For a longitude axis, this is usually EAST. Another occasional value is WEST.
-Unit<?> units = secondAxis.getUnit(); // For a longitude axis, this is usually Units.DEGREE.
-double minimum = secondAxis.getMinimumValue(); // For a longitude axis, this is usually −180°. Another common value is 0°.
-double maximum = secondAxis.getMaximumValue(); // For a longitude axis, this is usually +180°. Another common value is 360°.
-RangeMeaning atEnds = secondAxis.getRangeMeaning(); // For a longitude axis, this is WRAPAROUND.
-</code></pre>
- <p>
-
- In addition to axis definitions, another important coordinate system characteristic is their type
- (<code>CartesianCS</code>, <code>SphericalCS</code>, <i>etc.</i>).
- The <abbr>CS</abbr> type implies the set of mathematical rules for calculating geometric quantities like angles, distances and surfaces.
- Usually the various <abbr>CS</abbr> subtypes do not define any new Java methods compared to the parent type,
- but are nevertheless important for type safety.
- For example many calculations or associations are legal only when all axes are perpendicular to each other.
- In such case the coordinate system type is restricted to <code>CartesianCS</code> in method signatures.
- </p><p>
- Coordinate systems are mathematical concepts; they do <strong>not</strong> contain any information
- about where on Earth is located the system origin.
- Consequently coordinate systems alone are not sufficient for describing a location;
- they must be combined with a <cite>datum</cite> (or <cite>reference frame</cite>).
- Those combinations form the <cite>coordinate reference systems</cite> described in next sections.
- </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 software products 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 software products,
- then <abbr>CRS</abbr> forced to <cite>longitude first</cite> axis order can be created by a call to the following method:
- </p>
-
-<pre><code>CoordinateReferenceSystem crs = …; // CRS obtained by any means.
-crs = AbstractCRS.castOrCopy(crs).forConvention(AxesConvention.RIGHT_HANDED)</code></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>
- There is many kinds of latitudes and longitudes. Two common kinds supported by Apache <abbr>SIS</abbr>
- are <cite>geodetic</cite> and <cite>geocentric</cite> latitudes.
- Those two angles differ slightly in the way they intersect the ellipsoid surface.
- On Earth surface, the difference between those two kinds of latitude varies between 0 and about 20 km.
- </p><p>
- When peoples talk about latitudes and longitudes, they usually mean <em>geodetic</em> latitudes and longitudes.
- A coordinate reference systems using such latitudes and longitudes is said <cite>geographic</cite>
- and is represented by the <code>GeographicCRS</code> interface.
- Systems using the other kinds of latitude are represented by other <abbr>CRS</abbr> interfaces.
- </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>
</section>
</body>
</html>
diff --git a/source/developer-guide/referencing/CoordinateOperationSteps.html b/source/developer-guide/referencing/CoordinateOperationSteps.html
new file mode 100644
index 00000000..6aa634b1
--- /dev/null
+++ b/source/developer-guide/referencing/CoordinateOperationSteps.html
@@ -0,0 +1,261 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+ <head>
+ <title>CoordinateOperationSteps</title>
+ <meta charset="UTF-8"/>
+ <link rel="stylesheet" type="text/css" href="../book.css"/>
+ </head>
+ <body>
+ <!--
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
+ -->
+ <h3 id="CoordinateOperationSteps">Chain of coordinate operation steps</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 the real operation executed by Apache <abbr>SIS</abbr> is divided in more steps.
+ </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">
+ <style>
+ ol, ul {padding-left:20px}
+ </style>
+ <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>
+ <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>
+ <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 conversion</b>
+ <ul>
+ <li>Scale factors (λ and φ) = 0</li>
+ <li>Shear factors (λ and φ) = π/180</li>
+ </ul>
+ </li><li><b>Ellipsoid (radians) to centric</b>
+ <ul>
+ <li>Eccentricity ≈ 0.08227</li>
+ </ul>
+ </li><li><b>Affine parametric transformation</b>
+ <ul>
+ <li>Scale factors ≈ 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><b>Centric to ellipsoid (radians)</b>
+ <ul>
+ <li>Eccentricity ≈ 0.08182</li>
+ </ul>
+ </li><li><b>Affine parametric conversion</b>
+ <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 of degrees) and
+ linear units relative to an ellipsoid of semi-major axis length of 1 (instead of 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">
+ <div style="padding-right:24px">
+ <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><samp class="wkt">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"]]</samp></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">
+ <div style="padding-right:24px">
+ <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 intent) 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><samp class="wkt">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>]]]</samp></pre>
+ </div>
+ </div>
+ </div>
+ <p>
+ The latter form is often useful for debugging.
+ If a coordinate operation seems to produce wrong results,
+ inspecting the Well Known Text like above should be the first thing to do.
+ The <a href="../../faq.html#transforms">Frequently Asked Questions page</a> gives more tips
+ about common causes of coordinate transformation errors.
+ </p>
+ </body>
+</html>
diff --git a/source/developer-guide/referencing/CoordinateOperations.html b/source/developer-guide/referencing/CoordinateOperations.html
index 2d79f5c2..9ee4dd92 100644
--- a/source/developer-guide/referencing/CoordinateOperations.html
+++ b/source/developer-guide/referencing/CoordinateOperations.html
@@ -20,7 +20,7 @@
under the License.
-->
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
<head>
<title>CoordinateOperations</title>
<meta charset="UTF-8"/>
@@ -28,8 +28,8 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
@@ -72,10 +72,10 @@
<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”)
+ <ul class="verbose">
+ <li>The <dfn>domain of validity</dfn>, 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 <dfn>positional accuracy</dfn>, 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>
@@ -96,7 +96,7 @@
<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>.
+ Furthermore its accuracy is usually 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>
@@ -156,8 +156,6 @@ public class MyApp {
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="https://www.ogc.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
@@ -225,16 +223,13 @@ double dy_dφ = jacobian.getElement(1,0);</code></pre>
</div>
<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>).
+ The first matrix column tells us that if we apply a displacement of 1° of latitude from the (<var>φ</var>, <var>λ</var>) position,
+ — in other words if we move at the (<var>φ</var> + 1, <var>λ</var>) geographic position —
+ then the projected coordinates would be displaced by (∂<var>x</var>, ∂<var>λ</var>) metres
+ — in other words they would become (<var>x</var> + ∂<var>x</var>, <var>y</var> + ∂<var>y</var>) —
+ if the map projection is approximated by an affine transform valid at the (<var>φ</var>, <var>λ</var>) position.
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.
+ if we apply a displacement of 1° of longitude on the source geographic coordinate under the same assumption.
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.
@@ -290,436 +285,12 @@ double dy_dφ = jacobian.getElement(1,0);</code></pre>
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>
- Geographic information systems often need to transform an envelope from one <abbr>CRS</abbr> to another.
- But a naive approach transforming the 4 corners is not sufficient.
- The figure below shows an envelope before a map projection and the geometric shape
- that we would get if all points (not only the corners) were projected.
- The resulting geometric shape is more complex than a rectangle because of the curvature caused by the map projection.
- Computing the envelope that contains the 4 corners of that shape is not enough,
- because the area in the bottom of the projected shape is lower than the two bottom corners.
- That surface would be outside the envelope.
- </p>
- <div class="row-of-boxes">
- <div>
- <div class="caption">Envelope before projection</div>
- <img style="border: solid 1px; margin-right: 15px" src="../../../static/book/images/GeographicArea.png" alt="Envelope in a geographic CRS"/>
- </div><div>
- <div class="caption">Geometric shape after projection</div>
- <img style="border: solid 1px; margin-left: 15px" src="../../../static/book/images/ConicArea.png" alt="Shape in a projected CRS"/>
- </div>
- </div>
- <p>
- A simple way to reduce the problem could be to sample a large number of points on each envelope border.
- For example we could sample 40 points on each border, transform them to the target <abbr>CRS</abbr>
- and compute an envelope containing all the transformed points.
- But even with 40 points, the point which is closest to the minimum in above figure can still be above that minimum.
- Consequently we still miss a small portion of the projected shape.
- It may be tempting to declare this error is negligible, but a single missing pixel can be enough for
- causing artifacts such as thin black lines in a mosaic or missing “piece of pie” in a projection over a pole.
- A workaround could be to arbitrarily increase the envelope size by some percentage,
- but a percentage too high will cause a larger amount of unnecessary data processing (e.g. more data to load from a file)
- while a percentage too low will leave some artifacts.
- </p><p>
- Map projection derivatives offer a more efficient way to resolve this problem.
- The figure below reproduces the same projected shape than above figure but with exaggerated deformations.
- The Apache <abbr>SIS</abbr> algorithm projects the 4 corners as in the naive approach,
- but opportunistically computes also their derivatives (the Jacobian matrices).
- Between two corners and using derivative information, there is only one possible cubic curve.
- We can describe that curve by the
-
- <i>f(<var>x</var>)</i> = <var>C</var>₀ + <var>C</var>₁<var>x</var> + <var>C</var>₂<var>x</var>² + <var>C</var>₃<var>x</var>³ equation
-
- with <var>C</var> coefficients computed from corner positions and derivatives.
- This approximation (shown by the red curve in above figure) does not match exactly the desired curve
- (shown by the blue shape in above figure) but is close.
- We do not use directly the cubic curve minimum,
- but instead we take the longitude λ (for above example) where this minimum is located.
- This is shown by the green dashed line in above figure.
- This position is easy to compute when the <var>C</var> coefficients are known.
- Assuming that the λ coordinate of the cubic curve minimum is close to the λ coordinates of the projected shape minimum,
- we can project the point on the envelope border at that location instead of projecting blindly 40 points on that border.
- </p>
- <div class="row-of-boxes">
- <div>
- <img src="../../../static/book/images/Approximation.png" alt="Cubic approximation of an envelope bounds"/>
- </div><div>
- 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>
- </div>
- </div>
- <p>
- In practice Apache <abbr>SIS</abbr> uses 8 points:
- the 4 corners plus one point at the center of each border of the envelope to project.
- The center points are added as a safety for map projections having symmetric deformations above and below equator.
- According our tests, using only those 8 points together with derivatives as described above
- gives more accurate results than “brute force” approach with 160 points on the 4 envelope borders.
- Saving 150 points seems small compared to computer performances.
- But above discussion used a two-dimensional envelope as an example.
- The same discussion applies to <var>n</var>-dimensional envelopes as well.
- Apache <abbr>SIS</abbr> can apply this algorithm on envelopes with any number of dimensions up to 64.
- The performance gain offered by this algorithm compared to “brute force” approach
- increases exponentially with the number of dimensions.
- </p><p>
- Apache <abbr>SIS</abbr> implements the algorithm described in this section
- by the static <code>Envelopes.transform(CoordinateOperation, Envelope)</code> method.
- An alternative <code>Envelopes.transform(MathTransform, Envelope)</code> method is also available,
- but should be used only when the <code>CoordinateOperation</code> is unknown.
- The reason is because <code>MathTransform</code> objects does not contain any information about coordinate system axes,
- which prevent the <code>Envelopes.transform(…)</code> method to handle special cases such as envelopes containing a pole.
+ The <a href="#JacobianUsage">annex</a> explains how derivatives are used by the Apache <abbr>SIS</abbr>
+ implementation of envelope and raster reprojections.
</p>
- <h4 id="DerivativeAndRaster">Transform derivatives applied to rasters</h4>
- <p>
- A raster can be projected by preparing an initially empty raster which will contain the resampled pixel values.
- Then for each pixel in the <em>destination</em> raster, we use the <em>inverse</em> of the map projection
- (<var>T</var>⁻¹) for computing the coordinates of the corresponding pixel in source raster.
- The transformed coordinates may not fall at the center of a source raster pixel,
- so source pixel values usually need to be interpolated.
- </p>
- <div style="display:flex; flex-direction:column; align-items:center">
- <div style="display:flex; justify-content:space-between; width:564px">
- <div class="caption">Source image</div>
- <div class="caption">Destination image</div>
- </div>
- <img src="../../../static/book/images/RasterProjection.png" alt="Raster reprojection"/>
- </div>
- <p>
- However applying the inverse transform on all pixel coordinates can be relatively slow.
- We can accelerate raster reprojections by pre-computing an <cite>interpolation grid</cite>.
- This grid contains the coordinate values of inverse transform <var>T</var>⁻¹ for only a few points.
- The coordinate values of other points are obtained by bilinear interpolations between interpolation grid points.
- Historically, this algorithm was implemented in the <code>WarpGrid</code> object of <cite>Java Advanced Imaging</cite> library.
- The performance gain is yet better if the same interpolation grid is reused for many rasters having their pixels at the same coordinates.
- </p><p>
- A difficulty in using interpolation grids is to determine how many points we need for keeping errors
- (defined as the difference between interpolated positions and actual positions computed by <var>T</var>⁻¹)
- below some threshold value (for example ¼ of pixel size).
- A “brute force” approach is to begin with a grid of size 3×3, then increase the number of points iteratively:
- </p>
- <div class="row-of-boxes">
- <div>
- <img src="../../../static/book/images/WarpGrid.png" alt="Warp grid"/>
- </div><div>
- 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>
- </div>
- </div>
- <p>
- We could stop dividing the grid when, after having computed new points,
- we verified that the differences between coordinates computed by <var>T</var>⁻¹ during last iteration
- and coordinates computed by bilinear interpolations for the same points are lower than the threshold value.
- Unfortunately this approach can only tell us <strong>after</strong> computing new points… that those new points were unnecessary.
- This is unfortunate considering that each iteration adds an amount of points approximately equal to
- 3 times the <em>sum</em> of the number of points of all previous iterations.
- </p><p>
- Map projection derivatives help to improve the speed of interpolation grid computations.
- Using the derivatives, we can estimate whether another iteration is necessary <strong>before</strong> to execute it.
- The basic idea is to check if the derivatives at two neighbor points define two tangent lines that are almost parallel.
- In such case, we assume that the transform between those two points is almost linear.
- In order to define numerically the meaning of “almost linear”,
- we compute the intersection of the two tangent lines as illustrated below (the blue arrows).
- Then we compute the distance between that intersection and the straight line connecting the two points
- (the dashed line in the figure below).
- </p>
- <p style="text-align:center"><img style="border: solid 1px" src="../../../static/book/images/IntersectionOfDerivatives.png" alt="Intersection of derivatives"/></p>
- <p>
- In “brute force” algorithm without derivatives, iteration stops when the distance between interpolated positions (blue dashed line)
- and actual projected positions (red curve) is less than the threshold value.
- This criteria requires to compute the projected positions before the decision can be made.
- But with an algorithm using derivatives, the projected positions (red curve) are replaced by the tangents intersection point.
- If the actual projected curve does not have too much deformations
- (which should be the case for pairs of neighbor points close enough),
- then the red curve stay between the blue dashed line and the tangents intersection point.
- By using that intersection point, we reduce greatly the number of points to transform
- (3× the sum of all previous iterations).
- </p>
-
- <h4 id="GetDerivative">Getting the derivative at a point</h4>
- <p>
- The algorithms discussed in previous section would be irrelevant if map projection derivatives were costly to compute.
- But analytic derivations of their formulas show that map projection and derivative formulas have many terms in common.
- Furthermore map projection formulas are simplified by Apache <abbr>SIS</abbr> implementation strategy,
- which takes out linear terms (delegated to affine transforms)
- so that <code>NormalizedProjection</code> subclasses can focus on the non-linear terms only.
- Map projection implementations in Apache <abbr>SIS</abbr> exploit those characteristics
- for computing Jacobian matrices (if required) together with projected points in a single operation,
- reusing many common terms between the two set of formulas.
- Example:</p>
-
-<pre><code>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);</code></pre>
-
- <p>
- If only the Jacobian matrix is desired (without the projected point),
- then the <code>MathTransform.derivative(DirectPosition)</code> method offers a more readable alternative.
- </p><p>
- Many operations on coordinate transforms can also be applied on transform derivatives:
- concatenation of a chain of transforms, inversion, taking a subset of the dimensions, <i>etc.</i>
- Inverse projection formulas are usually more complicated than forward projections formulas,
- but thankfully their derivatives do not need to be computed:
- the Jacobian matrix of an inverse transform is the inverse of the Jacobian matrix of the forward transform.
- Calculation of inverse projections can be implemented as below:
- </p>
-
-<pre><code>@Override
-public Matrix derivative(DirectPosition p) throws TransformException {
- Matrix jac = inverse().derivative(transform(p));
- return Matrices.inverse(jac);
-}</code></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><samp>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"]]</samp></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 intent) 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><samp>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>]]]</samp></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>
+ <xi:include href="CoordinateOperationSteps.html"/>
</section>
</body>
</html>
diff --git a/source/developer-guide/referencing/GetCRS.html b/source/developer-guide/referencing/GetCRS.html
index 6dee9d8c..abe279ed 100644
--- a/source/developer-guide/referencing/GetCRS.html
+++ b/source/developer-guide/referencing/GetCRS.html
@@ -28,23 +28,20 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
<h2 id="GetCRS">Fetching a spatial reference system</h2>
</header>
- <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>
+ <p style="color: red">TODO:</p>
+ <ul style="color: red">
+ <li>Using <code>CommonCRS</code></li>
+ <li>Looking <abbr>CRS</abbr> defined by authorities with <code>CRSAuthorityFactory</code></li>
+ <li>Reading definitions in GML or WKT format</li>
+ <li>Constructing programmatically using <code>CRSFactory</code></li>
+ </ul>
<h3 id="CRS_UserCode">Adding new <abbr>CRS</abbr> definitions</h3>
<p style="color: red">TODO</p>
diff --git a/source/developer-guide/referencing/index.html b/source/developer-guide/referencing/index.html
index 408a2943..9a64bf23 100644
--- a/source/developer-guide/referencing/index.html
+++ b/source/developer-guide/referencing/index.html
@@ -28,8 +28,8 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
@@ -37,9 +37,9 @@
</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> —
+ — an approach known as <dfn>spatial reference systems by identifiers</dfn> —
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>.
+ — an approach known as <dfn>spatial reference systems by coordinates</dfn>.
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
@@ -53,7 +53,7 @@
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>
+ <ul class="verbose">
<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>
@@ -62,74 +62,19 @@
<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,
+ Coordinates <dfn>conversions</dfn> or <dfn>transformations</dfn> 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>.
+ Those types will be discussed in <a href="#CoordinateOperations">another section</a>.
</p>
<xi:include href="ComponentsOfCRS.html"/>
<xi:include href="GetCRS.html"/>
+ <xi:include href="AxisOrder.html"/>
<xi:include href="CoordinateOperations.html"/>
</section>
</body>
diff --git a/source/developer-guide/storage/XML-ISO-19115.html b/source/developer-guide/storage/XML-ISO-19115.html
index a11e4e54..7b12e621 100644
--- a/source/developer-guide/storage/XML-ISO-19115.html
+++ b/source/developer-guide/storage/XML-ISO-19115.html
@@ -28,8 +28,8 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
diff --git a/source/developer-guide/storage/XML-ISO.html b/source/developer-guide/storage/XML-ISO.html
index 9f425de9..39b50be3 100644
--- a/source/developer-guide/storage/XML-ISO.html
+++ b/source/developer-guide/storage/XML-ISO.html
@@ -28,23 +28,13 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
<h2 id="XML-ISO">Representing objects in <abbr>XML</abbr></h2>
</header>
- <p>
- Objects defined by <abbr>OGC</abbr>/<abbr>ISO</abbr> standards must be able to communicate with remote machines via the Internet,
- using different software written in different languages.
- Some of the better known formats include <abbr>WKT</abbr> (<i>Well-Known Text</i>) and <abbr>WKB</abbr> (<i>Well-Known Binary</i>).
- But the most exhaustive and often referred format is <abbr>XML</abbr>,
- to the point where the representation of <abbr>ISO</abbr> objects in this format is itself sometimes
- the entire focus of an international standard.
- Thus are metadata classes described in <abbr>ISO</abbr> 19115-1 standard (an abstract specification),
- while the representation of these classes in <abbr>XML</abbr> is described in <abbr>ISO</abbr> 19115-3 and 19139 standards.
- </p>
<p>
Different <abbr>OGC</abbr>/<abbr>ISO</abbr> standards do not always use the same strategy to express objects in <abbr>XML</abbr>.
<abbr>ISO</abbr> 19115-3 standard in particular uses a more verbose approach than other standards,
@@ -95,34 +85,6 @@
<td><code>http://www.w3.org/1999/xlink</code></td>
</tr>
</table>
-
- <aside>
- <h2>Tools for reading and writing <abbr>XML</abbr> documents</h2>
- <p>
- Apache <abbr>SIS</abbr> uses different libraries to read and write different types of objects.
- The library used depends on the complexity of the object and on performance constraints.
- For example, <abbr title="Java Architecture for XML Binding">JAXB</abbr> annotations have the advantage of being close to code,
- which makes it easier to maintain mapping between Java and <abbr>XML</abbr>.
- On the other hand, <abbr title="Simple API for XML">SAX</abbr> is more efficient.
- In general, Apache <abbr>SIS</abbr> uses:
- </p>
- <ul>
- <li>
- <abbr>JAXB</abbr> for objects that do not occur very often in <abbr>XML</abbr> documents, but with complex structures and deep hierarchies.
- The metadata set in <abbr>ISO</abbr> 19115-3 standard is a typical example
- </li>
- <li>
- <abbr>SAX</abbr> for objects that are relatively simple, but which may exist in very large numbers.
- The set of points in a geometry is a typical example.
- </li>
- <li>
- <abbr title="Document Object Model">DOM</abbr> as an alternative to <abbr>JAXB</abbr>
- when the <abbr>XML</abbr> elements do not correspond exactly to Java attributes.
- <i>Features</i> are an example, as their structure is dynamic.
- </li>
- </ul>
- </aside>
-
<xi:include href="XML-ISO-19115.html"/>
</section>
</body>
diff --git a/source/developer-guide/storage/index.html b/source/developer-guide/storage/index.html
index f1a7ca71..5c5cff4c 100644
--- a/source/developer-guide/storage/index.html
+++ b/source/developer-guide/storage/index.html
@@ -28,12 +28,12 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
- <h2 id="Formats">Data storage formats</h2>
+ <h1 id="Formats">Data storage formats</h1>
</header>
<p>
Apache SIS can read and write spatial data and associated metadata in different formats.
diff --git a/source/developer-guide/utility/ComparisonModes.html b/source/developer-guide/utility/ComparisonModes.html
index 85cfc7be..9cb42962 100644
--- a/source/developer-guide/utility/ComparisonModes.html
+++ b/source/developer-guide/utility/ComparisonModes.html
@@ -28,8 +28,8 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
diff --git a/source/developer-guide/utility/Internationalization.html b/source/developer-guide/utility/Internationalization.html
index c4da1275..02699498 100644
--- a/source/developer-guide/utility/Internationalization.html
+++ b/source/developer-guide/utility/Internationalization.html
@@ -28,8 +28,8 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
@@ -71,7 +71,7 @@
This is the recommended language for logging messages to be read by system administrators.</li>
<li><code>getLocalizedMessage()</code> returns the message in a locale that depends on the context
in which the exception has been thrown. This is often the locale used by a particular <code>Format</code>
- or <code class="SIS">DataStore</code> instance, and can be presumed to be the locale on the client side.
+ or <code>DataStore</code> instance, and can be presumed to be the locale on the client side.
This is the recommended language to show in the user application.</li>
</ul>
@@ -118,14 +118,14 @@
<p>
All <abbr>SIS</abbr> methods receiving or returning the value of a <code>Locale</code> type accept the <code>Locale.ROOT</code> value.
This value is interpreted as specifying not to localize the text.
- The notion of a <cite>non-localized text</cite> is a little false, as it is always necessary to chose a formatting convention.
+ The notion of a <dfn>non-localized text</dfn> is a little false, as it is always necessary to chose a formatting convention.
This convention however, though very close to English, is usually slightly different.
For example:
</p>
<ul>
<li>
Identifiers are written as they appear in <abbr>UML</abbr> diagrams,
- such as <cite>blurredImage</cite> instead of <cite>Blurred image</cite>.
+ such as <var>blurredImage</var> instead of <var>Blurred image</var>.
</li>
<li>
Dates are written according to the <abbr>ISO</abbr> 8601 format,
diff --git a/source/developer-guide/utility/ObjectConverters.html b/source/developer-guide/utility/ObjectConverters.html
index 66895b93..de3a1a39 100644
--- a/source/developer-guide/utility/ObjectConverters.html
+++ b/source/developer-guide/utility/ObjectConverters.html
@@ -28,8 +28,8 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
@@ -58,7 +58,7 @@
<dd>A function is injective if no pair of <var>S</var> values can produce the same <var>T</var> value.
<div class="example"><p><b>Example:</b>
the <code>Integer</code> → <code>String</code> conversion performed by <code>Integer.toString()</code>
- is an <cite>injective</cite> function because if two <code>Integer</code> values are not equal,
+ is an <dfn>injective</dfn> function because if two <code>Integer</code> values are not equal,
then it is guaranteed that their conversions will result in different <code>String</code> values.
However the <code>String</code> → <code>Integer</code> conversion performed by <code>Integer.valueOf(String)</code>
is <strong>not</strong> an injective function
@@ -71,7 +71,7 @@
<dd>A function is surjective if each values of <var>T</var> can be created from at least one value of <var>S</var>.
<div class="example"><p><b>Example:</b>
the <code>String</code> → <code>Integer</code> conversion performed by <code>Integer.valueOf(String)</code>
- is a <cite>surjective</cite> function because every <code>Integer</code> value can be created from at least one <code>String</code> value.
+ is a <dfn>surjective</dfn> function because every <code>Integer</code> value can be created from at least one <code>String</code> value.
However the <code>Integer</code> → <code>String</code> conversion performed by <code>Integer.toString()</code>
is <strong>not</strong> a surjective function because it can not produce all possible <code>String</code> values.
For example there is no way to produce the "ABC" value with the <code>Integer.toString()</code> method.
@@ -81,9 +81,9 @@
<dt><dfn>Bijective</dfn></dt>
<dd>A function is bijective if there is a one-to-one relationship between <var>S</var> and <var>T</var> values.
<div class="example"><p><b>Note:</b>
- the <cite>bijective</cite> property is defined here for clarity, but actually does not have an explicit item
+ the <dfn>bijective</dfn> property is defined here for clarity, but actually does not have an explicit item
in Apache <abbr>SIS</abbr> <code>FunctionProperty</code> enumeration.
- It is not necessary since a function that is both <cite>injective</cite> and <cite>surjective</cite> is necessarily bijective.
+ It is not necessary since a function that is both <dfn>injective</dfn> and <dfn>surjective</dfn> is necessarily bijective.
</p></div>
</dd>
@@ -107,8 +107,8 @@
<p>
Above information may seem unnecessary when values are converted without taking in account the context in which the values appear.
But when the value to convert is part of a bigger object, then above information can affect the way the converted value will be used.
- For example conversion of a [<var>min</var> … <var>max</var>] range is straightforward when the converter is <cite>order preserving</cite>.
- But if the converter is <cite>order reversing</cite>, then the minimum and maximum values need to be interchanged.
+ For example conversion of a [<var>min</var> … <var>max</var>] range is straightforward when the converter is <dfn>order preserving</dfn>.
+ But if the converter is <dfn>order reversing</dfn>, then the minimum and maximum values need to be interchanged.
For example if the converter reverses the sign of values, then the converted range is [-<var>max</var> … -<var>min</var>].
If the converter is neither order preserving or order reversing, then range conversion is not allowed at all
(because it does not contain the same set of values) even if the minimum and maximum values could be converted individually.
diff --git a/source/developer-guide/utility/index.html b/source/developer-guide/utility/index.html
index 0d4d3ff7..d9aeca06 100644
--- a/source/developer-guide/utility/index.html
+++ b/source/developer-guide/utility/index.html
@@ -28,8 +28,8 @@
</head>
<body>
<!--
- Content below this point is copied in "/static/book/en/developer-guide.html" file
- by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+ Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
-->
<section>
<header>
diff --git a/static/book/book.css b/static/book/book.css
index b0ad6922..1d03454c 100644
--- a/static/book/book.css
+++ b/static/book/book.css
@@ -84,8 +84,10 @@ nav li.active > a {
*/
section > header > h1,
section > header > h2,
+section > header > h3,
section > h3,
section > h4,
+section > h5,
section > p,
section > nav > p,
section > pre,
@@ -95,7 +97,8 @@ section > details {
margin-right: 30px;
}
-li > p {
+li > p,
+section > ul {
margin-right: 30px;
}
@@ -114,6 +117,7 @@ dd > div.example {
main nav ul.toc,
section > ul,
+section > ol,
section > dl {
margin-left: 42px;
}
@@ -122,8 +126,8 @@ section > dl {
* Lists.
*/
ul.verbose li {
- margin-top: 4px;
- margin-bottom: 4px;
+ margin-top: 9px;
+ margin-bottom: 9px;
}
/*
@@ -278,6 +282,21 @@ table tr td.separator {
padding-bottom: 6px;
}
+/*
+ * Table with the first column in monospaced font, used for drawing trees.
+ * Because line-wrap is disabled, the table in HTML may need a `font-size`
+ * style element with a magic number using the `vw` unit.
+ */
+table.monospacedHeaderColumn {
+ white-space: nowrap;
+ line-height: 1;
+ border: none;
+}
+
+table.monospacedHeaderColumn tr > :nth-child(1) {
+ font-family: monospace;
+}
+
div.caption {
margin: 6px;
text-align: center;
diff --git a/static/book/toc.js b/static/book/toc.js
index dcb76062..069dfbfe 100644
--- a/static/book/toc.js
+++ b/static/book/toc.js
@@ -9,16 +9,19 @@ window.addEventListener('DOMContentLoaded', () => {
const observer = new IntersectionObserver(entries => {
entries.forEach(entry => {
const id = entry.target.getAttribute('id');
- if (entry.intersectionRatio > 0) {
- if (lastVisibleId !== null) {
- document.querySelector(`nav li a[href="#${lastVisibleId}"]`).parentElement.classList.remove('active');
- }
- lastVisibleId = id;
- var item = document.querySelector(`nav li a[href="#${id}"]`).parentElement;
- item.classList.add('active');
- const bounds = item.getBoundingClientRect();
- if (bounds.top < 0 || bounds.bottom > window.innerHeight - 2) {
- item.scrollIntoView();
+ var line = document.querySelector(`nav li a[href="#${id}"]`);
+ if (line !== null) {
+ if (entry.intersectionRatio > 0) {
+ if (lastVisibleId !== null) {
+ document.querySelector(`nav li a[href="#${lastVisibleId}"]`).parentElement.classList.remove('active');
+ }
+ lastVisibleId = id;
+ var item = line.parentElement;
+ item.classList.add('active');
+ const bounds = item.getBoundingClientRect();
+ if (bounds.top < 0 || bounds.bottom > window.innerHeight - 2) {
+ item.scrollIntoView();
+ }
}
}
});