sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1814366 [1/4] - in /sis/site/trunk/book: en/ en/annex/ en/annexes/ en/annexes/design/ en/annexes/geoapi/ en/annexes/tests/ en/introduction/ fr/ fr/annex/ fr/annexes/ fr/annexes/design/ fr/annexes/geoapi/ fr/annexes/tests/ fr/introduction/
Date Sun, 05 Nov 2017 18:04:33 GMT
Author: desruisseaux
Date: Sun Nov  5 18:04:32 2017
New Revision: 1814366

URL: http://svn.apache.org/viewvc?rev=1814366&view=rev
Log:
Move more of GeoAPI discussion in annex.

Added:
    sis/site/trunk/book/en/annexes/
      - copied from r1814365, sis/site/trunk/book/en/annex/
    sis/site/trunk/book/en/annexes/design/
    sis/site/trunk/book/en/annexes/design/AffineTransform.html
      - copied, changed from r1814233, sis/site/trunk/book/en/annex/DesignNotes.html
    sis/site/trunk/book/en/annexes/design/MatrixLibrary.html
      - copied, changed from r1814233, sis/site/trunk/book/en/annex/DesignNotes.html
    sis/site/trunk/book/en/annexes/design/index.html
      - copied, changed from r1814233, sis/site/trunk/book/en/annex/Annexes.html
    sis/site/trunk/book/en/annexes/geoapi/
    sis/site/trunk/book/en/annexes/geoapi/DefinitionProcess.html
      - copied, changed from r1814233, sis/site/trunk/book/en/introduction/GeoAPI.html
    sis/site/trunk/book/en/annexes/geoapi/Modules.html
      - copied, changed from r1814233, sis/site/trunk/book/en/introduction/GeoAPI.html
    sis/site/trunk/book/en/annexes/geoapi/ReduceDependency.html
      - copied, changed from r1814233, sis/site/trunk/book/en/annex/ReduceDependency.html
    sis/site/trunk/book/en/annexes/geoapi/index.html
      - copied, changed from r1814233, sis/site/trunk/book/en/annex/Annexes.html
    sis/site/trunk/book/en/annexes/tests/
    sis/site/trunk/book/en/annexes/tests/GeoApiConformance.html
      - copied, changed from r1814233, sis/site/trunk/book/en/annex/Tests.html
    sis/site/trunk/book/en/annexes/tests/index.html
      - copied, changed from r1814233, sis/site/trunk/book/en/annex/Annexes.html
    sis/site/trunk/book/fr/annexes/
      - copied from r1814365, sis/site/trunk/book/fr/annex/
    sis/site/trunk/book/fr/annexes/design/
    sis/site/trunk/book/fr/annexes/design/AffineTransform.html
      - copied, changed from r1814233, sis/site/trunk/book/fr/annex/DesignNotes.html
    sis/site/trunk/book/fr/annexes/design/MatrixLibrary.html
      - copied, changed from r1814233, sis/site/trunk/book/fr/annex/DesignNotes.html
    sis/site/trunk/book/fr/annexes/design/index.html
      - copied, changed from r1814233, sis/site/trunk/book/fr/annex/Annexes.html
    sis/site/trunk/book/fr/annexes/geoapi/
    sis/site/trunk/book/fr/annexes/geoapi/DefinitionProcess.html
      - copied, changed from r1814233, sis/site/trunk/book/fr/introduction/GeoAPI.html
    sis/site/trunk/book/fr/annexes/geoapi/Modules.html
      - copied, changed from r1814233, sis/site/trunk/book/fr/introduction/GeoAPI.html
    sis/site/trunk/book/fr/annexes/geoapi/ReduceDependency.html
      - copied, changed from r1814233, sis/site/trunk/book/fr/annex/ReduceDependency.html
    sis/site/trunk/book/fr/annexes/geoapi/index.html
      - copied, changed from r1814233, sis/site/trunk/book/fr/annex/Annexes.html
    sis/site/trunk/book/fr/annexes/tests/
    sis/site/trunk/book/fr/annexes/tests/GeoApiConformance.html
      - copied, changed from r1814233, sis/site/trunk/book/fr/annex/Tests.html
    sis/site/trunk/book/fr/annexes/tests/index.html
      - copied, changed from r1814233, sis/site/trunk/book/fr/annex/Annexes.html
Removed:
    sis/site/trunk/book/en/annex/
    sis/site/trunk/book/en/annexes/Annexes.html
    sis/site/trunk/book/en/annexes/DesignNotes.html
    sis/site/trunk/book/en/annexes/ReduceDependency.html
    sis/site/trunk/book/en/annexes/Tests.html
    sis/site/trunk/book/fr/annex/
    sis/site/trunk/book/fr/annexes/Annexes.html
    sis/site/trunk/book/fr/annexes/DesignNotes.html
    sis/site/trunk/book/fr/annexes/ReduceDependency.html
    sis/site/trunk/book/fr/annexes/Tests.html
Modified:
    sis/site/trunk/book/en/index.html
    sis/site/trunk/book/en/introduction/ConceptualModels.html
    sis/site/trunk/book/en/introduction/GeoAPI.html
    sis/site/trunk/book/fr/index.html
    sis/site/trunk/book/fr/introduction/ConceptualModels.html
    sis/site/trunk/book/fr/introduction/GeoAPI.html

Copied: sis/site/trunk/book/en/annexes/design/AffineTransform.html (from r1814233, sis/site/trunk/book/en/annex/DesignNotes.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/annexes/design/AffineTransform.html?p2=sis/site/trunk/book/en/annexes/design/AffineTransform.html&p1=sis/site/trunk/book/en/annex/DesignNotes.html&r1=1814233&r2=1814366&rev=1814366&view=diff
==============================================================================
--- sis/site/trunk/book/en/annex/DesignNotes.html [UTF-8] (original)
+++ sis/site/trunk/book/en/annexes/design/AffineTransform.html [UTF-8] Sun Nov  5 18:04:32 2017
@@ -24,7 +24,7 @@
   <head>
     <title>DesignNotes</title>
     <meta charset="UTF-8"/>
-    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
+    <link rel="stylesheet" type="text/css" href="../../../../content/book/book.css"/>
   </head>
   <body>
     <!--
@@ -33,12 +33,8 @@
     -->
     <section>
       <header>
-        <h2 id="DesignNotes">Design notes</h2>
+        <h2 id="AffineTransform">Affine transform</h2>
       </header>
-      <p>Following chapters explain the rational behind some implementation choices done in Apache <abbr>SIS</abbr>.</p>
-
-
-      <h3 id="AffineTransform">Affine transform</h3>
       <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.
@@ -80,11 +76,11 @@
           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="../../math/PixelToGeographicTerms.html"/>
+          <xi:include href="../../../math/PixelToGeographicTerms.html"/>
         </p><p>
           Above equations can be represented in matrix form as below:
         </p><p>
-        <xi:include href="../../math/PixelToGeographic.html"/>
+        <xi:include href="../../../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
@@ -107,13 +103,13 @@
           <th>Initial conversion</th><th></th>
           <th>Concatenated operation</th>
         </tr><tr>
-          <td style="vertical-align: middle"><xi:include href="../../math/AxisSwapping2D.html"/></td>
+          <td style="vertical-align: middle"><xi:include href="../../../math/AxisSwapping2D.html"/></td>
           <td style="vertical-align: middle; padding-left: 15px; padding-right: 15px">×</td>
-          <td style="vertical-align: middle"><xi:include href="../../math/InverseAxisY.html"/></td>
+          <td style="vertical-align: middle"><xi:include href="../../../math/InverseAxisY.html"/></td>
           <td style="vertical-align: middle; padding-left: 15px; padding-right: 15px">×</td>
-          <td style="vertical-align: middle"><xi:include href="../../math/PixelToGeographicSameAxisDirections.html"/></td>
+          <td style="vertical-align: middle"><xi:include href="../../../math/PixelToGeographicSameAxisDirections.html"/></td>
           <td style="vertical-align: middle; padding-left: 15px; padding-right: 15px">=</td>
-          <td style="vertical-align: middle"><xi:include href="../../math/PixelToGeographicReverseOrderAndY.html"/></td>
+          <td style="vertical-align: middle"><xi:include href="../../../math/PixelToGeographicReverseOrderAndY.html"/></td>
         </tr></table>
         <p>
           A key principle is that there is no need to write Java code dedicated to above kinds of axis changes.
@@ -125,7 +121,7 @@
         </p>
       </div>
 
-      <h4 id="AffineTransformAPI">Integration with graphical libraries</h4>
+      <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>.
@@ -163,122 +159,6 @@ if (mt instanceof AffineTransform) {
         The above cast is not guaranteed to succeed,
         even when the <code>MathTransform</code> meets the requirements allowing Java2D usage.
       </p>
-
-
-      <h3 id="MatrixLibrary">Specificities of a matrix library for <abbr>GIS</abbr></h3>
-      <p>
-        <abbr>GIS</abbr> make an extensive usage of matrices for displaying maps or for transforming coordinates.
-        There is many excellent open source or commercial matrix libraries available.
-        However, <abbr>GIS</abbr> have some specific needs that differ a little bit from the goals of many existent libraries.
-        Matrix operations like those described in the <a href="#AffineTransform">affine transform chapter</a>
-        appear in almost all coordinate operations applied by Apache <abbr>SIS</abbr>.
-        But the analysis of those operations reveal some patterns:
-      </p>
-      <ul>
-        <li><p>Those matrices are almost always of small size, rarely more than 5 rows and 5 columns.</p></li>
-        <li><p>“Heavy” matrix operations (matrix inversions or multiplications) do not happen in performance-critical code.
-            In almost every cases, those heavy operations are executed only once, for example when a data file is read
-            or in preparation steps before to transform coordinates.
-            Those heavy operations rarely happen in the loop that apply the coordinate operation
-            after we finished to prepare it.</p></li>
-        <li><p>In a sequence of matrix multiplications or inversions, rounding errors accumulate and grow fast.
-            If the sequence of matrix operations is long enough,
-            rounding errors can become indistinguishable from real operations like datum shifts.
-            This ambiguity can happen because the matrix representation of some datum shifts has small values,
-            with scale factors of a few parts per million and rotation terms of a few arc-seconds.</p></li>
-        <li><p>It is quite common that two affine transforms cancel each other when they are concatenated, i.e.
-            that matrix multiplications result in some or all scale factors equal to 1 and some or all translation terms equal to 0.
-            However because of rounding errors the results are rarely exact, but are rather some values like 0,9999…97 instead of 1.
-            The usual workaround is to compare floating point numbers with some tolerance threshold.
-            Unfortunately it is difficult to choose a threshold that catch a wide range of rounding errors
-            without wrongly considering legitimate datum shifts as rounding errors (see previous point).</p></li>
-      </ul>
-      <p>
-        As a consequence of above points, accuracy of a matrix library is more important than performance for a <abbr>GIS</abbr> like Apache <abbr>SIS</abbr>.
-        Paradoxically, a good way to improve performance is to invest more CPU time for more accurate matrix operations
-        when <em>preparing</em> (not <em>executing</em>) the coordinate operation,
-        because it increases the chances to correctly detect which operations cancel each other.
-        This investment can save execution time at the place where it matters most:
-        in the code looping over millions of coordinates to transform.
-      </p><p>
-        However matrix libraries are often designed for high performances with large matrices, sometime containing thousands of rows and columns.
-        Those libraries can efficiently resolve systems of linear equations with hundreds of unknown variables.
-        Those libraries resolve difficult problems, but not of the same kind than the problems that Apache <abbr>SIS</abbr> needs to solve.
-        For that reason, and also for another reason described in next paragraphs, Apache <abbr>SIS</abbr> uses its own matrix implementation.
-        This implementation addresses the accuracy issue by using “double-double” arithmetic
-        (a technic for simulating the accuracy of approximatively 120 bits wide floating point numbers)
-        at the cost of performance in a phase (transform <em>preparation</em>) where performance is not considered critical.
-      </p>
-
-      <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.
-        Depending on whether we have more lines than columns:
-      </p>
-      <ul>
-        <li>From Apache <abbr>SIS</abbr> library perspective, a non-square matrix is a coordinate operation that adds or removes a dimension.</li>
-        <li>From linear algebra libraries perspective, a non-square matrix is an under-determined or over-determined system of equations.</li>
-      </ul>
-      <p>
-        To illustrate the issues caused by direct use of libraries designed for linear algebra,
-        consider a (<var>φ₁</var>, <var>λ₁</var>, <var>h</var>) → (<var>φ₂</var>, <var>λ₂</var>) conversion
-        from three-dimensional points to two-dimensional points on a surface.
-        The <var>φ</var> terms are latitudes, the <var>λ</var> terms are longitudes and
-        (<var>φ₂</var>, <var>λ₂</var>) may be different than (<var>φ₁</var>, <var>λ₁</var>) if <var>h</var> axis is not perpendicular to the surface.
-      </p><p>
-        <xi:include href="../../math/Geographic3Dto2D.html"/>
-      </p><p>
-        For linear algebra libraries, the above non-square matrix represents an under-determined system of equations and may be considered unresolvable.
-        Indeed the above coordinate operation can not be inverted as a (<var>φ₂</var>, <var>λ₂</var>) → (<var>φ₁</var>, <var>λ₁</var>, <var>h</var>)
-        operation because we do not know which value to assign to <var>h</var>.
-        Ignoring <var>h</var> implies that we can not assign values to (<var>φ₁</var>, <var>λ₁</var>) neither since those values may depend on <var>h</var>.
-        However in <abbr>GIS</abbr> case, the ellipsoidal <var>h</var> axis is perpendicular to the ellipsoid surface
-        on which the <em>geodetic</em> latitudes and longitudes (<var>φ</var>, <var>λ</var>) are represented
-        (note that this statement is not true for <em>geocentric</em> latitudes and longitudes).
-        This perpendicularity makes <var>φ₁</var> and <var>λ₁</var> independent of <var>h</var>.
-        In such cases, we can can still do some processing.
-      </p><p>
-        Apache <abbr>SIS</abbr> proceeds by checking if <var>h</var> values are independent of <var>φ</var> and <var>λ</var> values.
-        We identify such cases by checking which matrix coefficients are zero.
-        If <abbr>SIS</abbr> can identify independent dimensions, it can temporarily exclude those dimensions
-        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.
-        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
-        that the matrix represents a coordinate operation; this is not something that can be done with arbitrary matrices.
-      </p><p>
-        The above-described approach allows Apache <abbr>SIS</abbr> to resolve some under-determined equation systems commonly found in <abbr>GIS</abbr>.
-        In our example using <code>NaN</code> as the default value, the <var>h</var> ordinate stay unknown – we do not create information from nothing –
-        but at least the (<var>φ</var>, <var>λ</var>) coordinates are preserved.
-        The opposite problem, those of over-determined equation systems, is more subtile.
-        An approach commonly applied by linear algebra libraries is to resolve over-determined systems by the least squares method.
-        Such method applied to our example would compute a (<var>φ₂</var>, <var>λ₂</var>, <var>h</var>) → (<var>φ₁</var>, <var>λ₁</var>) operation
-        that seems the best compromise for various <var>φ₂</var>, <var>λ₂</var> and <var>h</var> values,
-        while being (except special cases) an exact solution for no-one.
-        Furthermore linear combinations between those three variables may be an issue because of heterogenous units of measurement,
-        for instance with <var>h</var> in metres and (<var>φ</var>, <var>λ</var>) in degrees.
-        Apache <abbr>SIS</abbr> rather proceeds in the same way than for under-determined systems:
-        by requiring that some dimensions are independent from other dimensions, otherwise the matrix is considered non-invertible.
-        Consequently in over-determined systems case, <abbr>SIS</abbr> may refuse to perform some matrix inversions that linear algebra libraries can do,
-        but in case of success the resulting coordinate operation is guaranteed to be exact (ignoring rounding errors).
-      </p>
-
-      <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>
-      <ul>
-        <li>Lightweight objects for small matrices, especially the 3×3 ones.</li>
-        <li>Improved accuracy with “double-double” arithmetic, accepting performance cost in codes where performance is not critical.</li>
-        <li>Special handling of non-square matrices on the assumption that those matrices represent coordinate operations.</li>
-      </ul>
-      <p>
-        This library is provided in the <code>org.apache.sis.matrix</code> package of the <code>sis-referencing</code> module.
-      </p>
     </section>
   </body>
 </html>

Copied: sis/site/trunk/book/en/annexes/design/MatrixLibrary.html (from r1814233, sis/site/trunk/book/en/annex/DesignNotes.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/annexes/design/MatrixLibrary.html?p2=sis/site/trunk/book/en/annexes/design/MatrixLibrary.html&p1=sis/site/trunk/book/en/annex/DesignNotes.html&r1=1814233&r2=1814366&rev=1814366&view=diff
==============================================================================
--- sis/site/trunk/book/en/annex/DesignNotes.html [UTF-8] (original)
+++ sis/site/trunk/book/en/annexes/design/MatrixLibrary.html [UTF-8] Sun Nov  5 18:04:32 2017
@@ -24,7 +24,7 @@
   <head>
     <title>DesignNotes</title>
     <meta charset="UTF-8"/>
-    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
+    <link rel="stylesheet" type="text/css" href="../../../../content/book/book.css"/>
   </head>
   <body>
     <!--
@@ -33,139 +33,8 @@
     -->
     <section>
       <header>
-        <h2 id="DesignNotes">Design notes</h2>
+        <h2 id="MatrixLibrary">Specificities of a matrix library for <abbr>GIS</abbr></h2>
       </header>
-      <p>Following chapters explain the rational behind some implementation choices done in Apache <abbr>SIS</abbr>.</p>
-
-
-      <h3 id="AffineTransform">Affine transform</h3>
-      <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="../../math/PixelToGeographicTerms.html"/>
-        </p><p>
-          Above equations can be represented in matrix form as below:
-        </p><p>
-        <xi:include href="../../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>
-        <table class="hidden"><tr>
-          <th>Change 2</th><th></th>
-          <th>Change 1</th><th></th>
-          <th>Initial conversion</th><th></th>
-          <th>Concatenated operation</th>
-        </tr><tr>
-          <td style="vertical-align: middle"><xi:include href="../../math/AxisSwapping2D.html"/></td>
-          <td style="vertical-align: middle; padding-left: 15px; padding-right: 15px">×</td>
-          <td style="vertical-align: middle"><xi:include href="../../math/InverseAxisY.html"/></td>
-          <td style="vertical-align: middle; padding-left: 15px; padding-right: 15px">×</td>
-          <td style="vertical-align: middle"><xi:include href="../../math/PixelToGeographicSameAxisDirections.html"/></td>
-          <td style="vertical-align: middle; padding-left: 15px; padding-right: 15px">=</td>
-          <td style="vertical-align: middle"><xi:include href="../../math/PixelToGeographicReverseOrderAndY.html"/></td>
-        </tr></table>
-        <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>
-
-      <h4 id="AffineTransformAPI">Integration with graphical libraries</h4>
-      <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>.
-        Each library defines its own <abbr>API</abbr>. Some examples are listed below:
-      </p>
-      <table>
-        <caption>Affine transform implementations in graphical libraries</caption>
-        <tr><th>Library</th>                                  <th>Transform implementation</th>                          <th>Dimensions</th></tr>
-        <tr><td>Java2D</td>                                   <td><code>java.awt.geom.AffineTransform</code></td>        <td>2</td></tr>
-        <tr><td>Java3D</td>                                   <td><code>javax.media.j3d.Transform3D</code></td>          <td>3</td></tr>
-        <tr><td>JavaFX</td>                                   <td><code>javafx.scene.transform.Affine</code></td>        <td>2 or 3</td></tr>
-        <tr><td>Java Advanced Imaging (<abbr>JAI</abbr>)</td> <td><code>javax.media.jai.PerspectiveTransform</code></td> <td>2</td></tr>
-        <tr><td>Android</td>                                  <td><code>android.graphics.Matrix</code></td>              <td>2</td></tr>
-      </table>
-      <p>
-        However in many cases, affine or perspective transforms are the only kind of coordinate operations supported by the graphical library.
-        Apache <abbr>SIS</abbr> needs to handle a wider range of operations, in which affine transforms are only special cases.
-        In particular most map projections and datum shifts can not be represented by affine transforms.
-        <abbr>SIS</abbr> also needs to support arbitrary number of dimensions,
-        while above-cited <abbr>API</abbr> restrict the use to a fixed number of dimensions.
-        For those reasons <abbr>SIS</abbr> can not use directly the above-cited <abbr>API</abbr>.
-        Instead, <abbr>SIS</abbr> uses the more abstract <code>org.opengis.referencing.transform.MathTransform</code> interface.
-        But in the special case where the transform is actually affine, <abbr>SIS</abbr> may try to use an existing implementation,
-        in particular Java2D. The following Java code can be used in situations where the Java2D object is desired:
-      </p>
-
-<pre><code>MathTransform mt = ...;    // Any math transform created by Apache SIS.
-if (mt instanceof AffineTransform) {
-    AffineTransform at = (AffineTransform) mt;
-    // Use Java2D API from here.
-}</code></pre>
-
-      <p>
-        Apache <abbr>SIS</abbr> uses Java2D on a <em>best effort</em> basis only.
-        The above cast is not guaranteed to succeed,
-        even when the <code>MathTransform</code> meets the requirements allowing Java2D usage.
-      </p>
-
-
-      <h3 id="MatrixLibrary">Specificities of a matrix library for <abbr>GIS</abbr></h3>
       <p>
         <abbr>GIS</abbr> make an extensive usage of matrices for displaying maps or for transforming coordinates.
         There is many excellent open source or commercial matrix libraries available.
@@ -210,7 +79,7 @@ if (mt instanceof AffineTransform) {
         at the cost of performance in a phase (transform <em>preparation</em>) where performance is not considered critical.
       </p>
 
-      <h4 id="NonSquareMatrix">What to do with non-square matrices (and why)</h4>
+      <h3 id="NonSquareMatrix">What to do with non-square matrices (and why)</h3>
       <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.
@@ -227,7 +96,7 @@ if (mt instanceof AffineTransform) {
         The <var>φ</var> terms are latitudes, the <var>λ</var> terms are longitudes and
         (<var>φ₂</var>, <var>λ₂</var>) may be different than (<var>φ₁</var>, <var>λ₁</var>) if <var>h</var> axis is not perpendicular to the surface.
       </p><p>
-        <xi:include href="../../math/Geographic3Dto2D.html"/>
+        <xi:include href="../../../math/Geographic3Dto2D.html"/>
       </p><p>
         For linear algebra libraries, the above non-square matrix represents an under-determined system of equations and may be considered unresolvable.
         Indeed the above coordinate operation can not be inverted as a (<var>φ₂</var>, <var>λ₂</var>) → (<var>φ₁</var>, <var>λ₁</var>, <var>h</var>)
@@ -267,7 +136,7 @@ if (mt instanceof AffineTransform) {
         but in case of success the resulting coordinate operation is guaranteed to be exact (ignoring rounding errors).
       </p>
 
-      <h4 id="MatrixLibrarySummary">Apache <abbr>SIS</abbr> matrix library</h4>
+      <h3 id="MatrixLibrarySummary">Apache <abbr>SIS</abbr> matrix library</h3>
       <p>
         In summary, Apache <abbr>SIS</abbr> provides its own matrix library for the following reasons:
       </p>

Copied: sis/site/trunk/book/en/annexes/design/index.html (from r1814233, sis/site/trunk/book/en/annex/Annexes.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/annexes/design/index.html?p2=sis/site/trunk/book/en/annexes/design/index.html&p1=sis/site/trunk/book/en/annex/Annexes.html&r1=1814233&r2=1814366&rev=1814366&view=diff
==============================================================================
--- sis/site/trunk/book/en/annex/Annexes.html [UTF-8] (original)
+++ sis/site/trunk/book/en/annexes/design/index.html [UTF-8] Sun Nov  5 18:04:32 2017
@@ -24,7 +24,7 @@
   <head>
     <title>Annexes</title>
     <meta charset="UTF-8"/>
-    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
+    <link rel="stylesheet" type="text/css" href="../../../../content/book/book.css"/>
   </head>
   <body>
     <!--
@@ -33,12 +33,12 @@
     -->
     <section>
       <header>
-        <h1 id="Annexes">Annexes</h1>
+        <h1 id="DesignNotes">Design notes</h1>
       </header>
+      <p>Following sections explain the rational behind some implementation choices done in Apache <abbr>SIS</abbr>.</p>
 
-      <xi:include href="ReduceDependency.html"/>
-      <xi:include href="Tests.html"/>
-      <xi:include href="DesignNotes.html"/>
+      <xi:include href="AffineTransform.html"/>
+      <xi:include href="MatrixLibrary.html"/>
     </section>
   </body>
 </html>

Copied: sis/site/trunk/book/en/annexes/geoapi/DefinitionProcess.html (from r1814233, sis/site/trunk/book/en/introduction/GeoAPI.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/annexes/geoapi/DefinitionProcess.html?p2=sis/site/trunk/book/en/annexes/geoapi/DefinitionProcess.html&p1=sis/site/trunk/book/en/introduction/GeoAPI.html&r1=1814233&r2=1814366&rev=1814366&view=diff
==============================================================================
--- sis/site/trunk/book/en/introduction/GeoAPI.html [UTF-8] (original)
+++ sis/site/trunk/book/en/annexes/geoapi/DefinitionProcess.html [UTF-8] Sun Nov  5 18:04:32 2017
@@ -24,277 +24,127 @@
   <head>
     <title>GeoAPI</title>
     <meta charset="UTF-8"/>
-    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
+    <link rel="stylesheet" type="text/css" href="../../../../content/book/book.css"/>
   </head>
   <body>
     <!--
-      Content below this point is copied in "../../content/book/en/developer-guide.html"
+      Content below this point is copied in "(…)/content/book/en/developer-guide.html"
       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>
+        <h2 id="SpecificationToInterfaces">From <abbr>OGC</abbr> specifications to Java interfaces</h2>
       </header>
       <p>
-        The <a href="http://www.geoapi.org">GeoAPI</a> project offers a set of Java interfaces for geospatial applications.
-        In a series of <code>org.opengis.*</code> packages, GeoAPI defines structures representing metadata,
-        coordinate reference systems and operations that perform cartographic projections.
-        In a part that is not yet standardized — called <i>pending</i> — GeoAPI defines structures that represent geo-referenced images,
-        geometries, filters that can be applied to queries, and other features.
-        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 naming conventions.
-        These interfaces benefit both client applications and libraries:
+        GeoAPI interfaces are sometime generated from other files provided by <abbr>OGC</abbr>, like <abbr>XSD</abbr> files.
+        But there is always a manual revision, and often modifications compared to automatically generated Java files.
+        It would have been possible to automatically generate Java interfaces from <abbr>OGC</abbr> standards using existing tools.
+        For example one of the most commonly-used approaches is to transform <a href="http://schemas.opengis.net/gml/3.3/"><abbr>XSD</abbr> schemas</a>
+        into Java interfaces using command line utility <code>xjc</code>.
+        As this utility is included in most Java distributions (it is one of the <a href="http://jaxb.java.net"><abbr>JAXB</abbr></a> tools),
+        this approach is favoured by many projects found on the Internet.
+        Other approaches use tools integrated into the Eclipse Development Environment,
+        which is based on <abbr>UML</abbr> schemas rather than <abbr>XSD</abbr> ones.
+        A similar approach was attempted in the early days of the GeoAPI project, but was quickly abandoned.
+        We favor a manual approach for the following reasons:
       </p>
       <ul>
-        <li><p>
-          Developers of client applications benefit from the greater knowledge base available on the Internet
-          (due to the many publications related to <abbr>OGC</abbr> standards), as well as increased interoperability.
-          Interoperability is facilitated by a better separation between applications that <em>call</em> GeoAPI functions,
-          and libraries that <em>implement</em> GeoAPI.
-          The separation is similar to that offered by the <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/"><abbr>JDBC</abbr></a> (<i>Java Database Connectivity</i>) interfaces of standard Java.
-          Using the interfaces’ <abbr>API</abbr>, developers can ignore the underlying implementation.
-          For example, they can perform cartographic projections with the help of the <a href="http://www.geoapi.org/geoapi-proj4/index.html">Proj.4</a> library, or the Apache <abbr>SIS</abbr> library,
-          without having to change their programs when they change libraries.
-        </p></li>
-        <li><p>
-          The developers of libraries inherit the expertise of the specifications’ authors, via the models that represent interfaces.
-          GeoAPI also provides a framework within which developers can prioritize the implementation of the features they most need,
-          while leaving the remaining features as extension points for future developments.
-          For example, clients can call a GeoAPI function even if it is not yet supported by the library,
-          and simply get a null value until a new version of the library returns a relevant value.
-        </p></li>
-      </ul>
-
-
-      <details>
-        <summary>More about the GeoAPI project</summary>
-        <article id="GeoAPI-history">
-          <header>
-            <h2>GeoAPI project history</h2>
-          </header>
+        <li>
           <p>
-            In 2001, the Open GIS Consortium (the former name of the Open Geospatial Consortium) published
-            <a href="http://www.opengeospatial.org/standards/ct"><abbr>OGC</abbr> implementation specification 01-009:
-            <cite>Coordinate Transformation Services</cite></a>.
-            This specification, developed by the Computer Aided Development Corporation (Cadcorp),
-            was accompanied by <abbr>COM</abbr>, <abbr>CORBA</abbr>, and Java interfaces.
-            At this time, the wave of web services had not yet eclipsed classical programming interfaces.
-            The interfaces of the <abbr>OGC</abbr> did anticipate a networked world,
-            but invested rather — in the case of Java — in <abbr>RMI</abbr> (<i>Remote Method Invocation</i>) technology.
-            As the GeoAPI project did not yet exist, we retroactively designate these historical interfaces “<a href="http://www.geoapi.org/0.1/index.html">GeoAPI 0.1</a>”.
-            These interfaces already used the package name <code>org.opengis</code>, which would be adopted by GeoAPI.
-          </p><p>
-            In 2002, developers of free projects launched a
-            <a href="http://web.archive.org/web/20030509104308/http://digitalearth.org/story/2002/10/10/55046/206">call for the creation of a geospatial <abbr>API</abbr></a>.
-            The initial proposal attracted the interest of at least five free projects.
-            The project was created using <a href="http://sourceforge.net/projects/geoapi/">SourceForge</a>,
-            which has since hosted the source code in a <a href="http://www.geoapi.org/source-repository.html">Subversion repository</a>.
-            It was then that the project assumed the name “GeoAPI”, and used the interfaces of the <abbr>OGC</abbr> specification 01-009 as a starting point.
-          </p><p>
-            A few months later, the <abbr>OGC</abbr> launched the <a href="http://www.opengeospatial.org/standards/go"><abbr>GO</abbr>-1: <i>Geographic Objects</i></a> project,
-            which pursued goals similar to those of GeoAPI.
-            In the meantime, the <abbr>OGC</abbr> abandonned some of their specifications in favor of <abbr>ISO</abbr> standards.
-            GeoAPI and <abbr>GO-1</abbr> worked jointly to rework the GeoAPI interfaces and base them on the new <abbr>ISO</abbr> norms.
-            Their first interation, <a href="http://www.geoapi.org/1.0/index.html">GeoAPI 1.0</a>,
-            served as a starting point for the first draft of the <abbr>OGC</abbr> specification 03-064 by the <abbr>GO</abbr>-1 working group.
-            The final version of this specification became an <abbr>OGC</abbr> standard in 2005,
-            and <a href="http://www.geoapi.org/2.0/index.html">GeoAPI 2.0</a> was published at that time.
-          </p><p>
-            The <abbr>GO</abbr>-1 project was largely supported by a company called <i>Polexis</i>.
-            Its acquisition by <i>Sys Technology</i>, and the change in priorities under the new owners,
-            brought a halt to the <abbr>GO</abbr>-1 project, which in turn slowed development on GeoAPI.
-            In order to resume development, a new working group entitled “GeoAPI 3.0” was created at the <abbr>OGC</abbr>.
-            This group took a narrower focus compared to GeoAPI 2.0, concentrating on the most stable interfaces, and putting the others
-            — such as geometries — in a module entitled “<a href="http://www.geoapi.org/geoapi-pending/index.html">pending</a>”, for future consideration.
-            <a href="http://www.geoapi.org/3.0/index.html">GeoAPI 3.0</a> became an <a href="http://www.opengeospatial.org/standards/geoapi"><abbr>OGC</abbr> standard</a> in 2011.
-            This version was the first to be deployed in the <a href="http://search.maven.org/#search|ga|1|geoapi">Maven central repository</a>.
+            Some <abbr>XSD</abbr> schemas are much more verbose than the original <abbr>UML</abbr> schemas.
+            Converting from <abbr>XSD</abbr> schemas introduces — at least in the case of metadata —
+            almost double the number of interfaces actually defined by the standard, without adding any new features.
+            <abbr>XSD</abbr> schemas also define attributes specific to <abbr>XML</abbr> documents (<code class="OGC">id</code>,
+            <code class="OGC">uuid</code>, <code>xlink:href</code>, <i>etc.</i>), that do not exist in the original <abbr>UML</abbr> diagrams,
+            and which we do not necessarily wish to expose in a Java <abbr>API</abbr>.
+            Converting from <abbr>UML</abbr> schemas avoids this problem, but tools capable of performing this operation are less common.
           </p>
-        </article>
-      </details>
-
-      <p>GeoAPI interfaces are sometime generated from other files provided by <abbr>OGC</abbr>, like <abbr>XSD</abbr> files.
-        But there is always a manual revision, and often modifications compared to automatically generated Java files.
-        Deviations from the standards are documented in each affected class and method.
-        Each mention of a deviation is also collected on a <a href="http://www.geoapi.org/3.0/javadoc/departures.html">single page</a> in order to provide an overview.
-        Since these deviations blur the relationships between the standards and certain Java interfaces,
-        the correspondence between these languages is explained by <code>@UML</code> annotations and property files described in the following section.
-      </p>
-
-      <details>
-        <summary>More about the reasons for manual definition of Java interfaces</summary>
-        <article id="SpecificationToInterfaces">
-          <header>
-            <h2>From <abbr>OGC</abbr> specifications to Java interfaces</h2>
-          </header>
+          <div class="example"><p><b>Example:</b>
+            <abbr>XSD</abbr> metadata schemas insert a <code>&lt;gmd:CI_Citation&gt;</code> element
+            inside a <code class="OGC">&lt;gmd:citation&gt;</code>,
+            a <code>&lt;gmd:CI_OnlineResource&gt;</code> element inside a <code class="OGC">&lt;gmd:onlineResource&gt;</code>,
+            and so on for the hundreds of classes defined by <abbr>ISO</abbr> 19115 standard.
+            This redundancy is certainly not necessary in a Java program.
+          </p></div>
+        </li>
+        <li>
           <p>
-            It is possible to automatically generate Java interfaces <abbr>OGC</abbr> standards using existing tools.
-            One of the most commonly-used approaches is to transform <a href="http://schemas.opengis.net/gml/3.3/"><abbr>XSD</abbr> schemas</a>
-            into Java interfaces using command line utility <code>xjc</code>.
-            As this utility is included in most Java distributions (it is one of the <a href="http://jaxb.java.net"><abbr>JAXB</abbr></a> tools),
-            this approach is favoured by many projects found on the Internet.
-            Other approaches use tools integrated into the Eclipse Development Environment,
-            which is based on <abbr>UML</abbr> schemas rather than <abbr>XSD</abbr> ones.
-          </p><p>
-            A similar approach was attempted in the early days of the GeoAPI project, but was quickly abandoned.
-            We favor a manual approach for the following reasons:
+            <abbr>OGC</abbr> standards use different naming conventions than Java.
+            In particular, the names of almost all <abbr>OGC</abbr> classes begin with a two-letter prefix,
+            such as <code>MD_Identifier</code>.
+            This prefixes fulfill the same role as package names in Java.
+            GeoAPI adapts this practice by using interface names without prefixes and placing these interfaces in packages corresponding to the prefixes,
+            but with more descriptive names.
+            Occasionally we also change the names; for example, to avoid acronyms, or to conform to an established convention such as JavaBeans.
           </p>
-          <ul>
-            <li>
-              <p>
-                Some <abbr>XSD</abbr> schemas are much more verbose than the original <abbr>UML</abbr> schemas.
-                Converting from <abbr>XSD</abbr> schemas introduces — at least in the case of metadata —
-                almost double the number of interfaces actually defined by the standard, without adding any new features.
-                <abbr>XSD</abbr> schemas also define attributes specific to <abbr>XML</abbr> documents (<code class="OGC">id</code>,
-                <code class="OGC">uuid</code>, <code>xlink:href</code>, <i>etc.</i>), that do not exist in the original <abbr>UML</abbr> diagrams,
-                and which we do not necessarily wish to expose in a Java <abbr>API</abbr>.
-                Converting from <abbr>UML</abbr> schemas avoids this problem, but tools capable of performing this operation are less common.
-              </p>
-              <div class="example"><p><b>Example:</b>
-                <abbr>XSD</abbr> metadata schemas insert a <code>&lt;gmd:CI_Citation&gt;</code> element
-                inside a <code class="OGC">&lt;gmd:citation&gt;</code>,
-                a <code>&lt;gmd:CI_OnlineResource&gt;</code> element inside a <code class="OGC">&lt;gmd:onlineResource&gt;</code>,
-                and so on for the hundreds of classes defined by <abbr>ISO</abbr> 19115 standard.
-                This redundancy is certainly not necessary in a Java program.
-              </p></div>
-            </li>
-            <li>
-              <p>
-                <abbr>OGC</abbr> standards use different naming conventions than Java.
-                In particular, the names of almost all <abbr>OGC</abbr> classes begin with a two-letter prefix,
-                such as <code>MD_Identifier</code>.
-                This prefixes fulfill the same role as package names in Java.
-                GeoAPI adapts this practice by using interface names without prefixes and placing these interfaces in packages corresponding to the prefixes,
-                but with more descriptive names.
-                Occasionally we also change the names; for example, to avoid acronyms, or to conform to an established convention such as JavaBeans.
-              </p>
-              <div class="example"><p><b>Example:</b>
-                The <abbr>OGC</abbr> class <code>MD_Identifier</code> becomes the
-                <code>Identifier</code> interface in the <code>org.opengis.metadata</code> package.
-                The <abbr>OGC</abbr> class <code>SC_CRS</code> becomes the <code>CoordinateReferenceSystem</code> interface,
-                and the <code class="OGC">usesDatum</code> association becomes a <code class="GeoAPI">getDatum()</code> method,
-                rather than the “<code>getUsesDatum()</code>” that would result from an automatic conversion tool.
-                We do not allow programs to blindly apply rules that ignore the conventions of the community whose schemas we translate.
-              </p></div>
-            </li>
-            <li>
-              <p>
-                The standards may contain structures that do not have a direct equivalent in Java,
-                such as unions similar to what we would find in C/C++.
-                The strategy used to obtain an equivalent feature in Java depends on the context:
-                multiple inheritance of interfaces, modification of the hierarchy, or simply omitting the union.
-                These decisions are made case-by-case based on a needs analysis.
-              </p>
-              <div class="example"><p><b>Example:</b>
-                <abbr>ISO</abbr> 19111 standard defines different types of coordinate systems, such as spherical, cylindrical, polar or Cartesian.
-                It then defines several <em>subsets</em> of these types of coordinate systems systems.
-                These subsets, represented by unions, serve to specify that a class may only be associated with a particular type of coordinate system.
-                For example, a union of types may be associated with an image, named <code>CS_ImageCS</code>,
-                which can only contain <code>CS_CartesianCS</code> and <code>CS_AffineCS</code>.
-                In this case, we get the desired effect in Java through a modification of the hierarchy of classes:
-                we define the <code>CartesianCS</code> interface as a specialization of <code>AffineCS</code>,
-                which is semantically correct.
-                But it is not possible to apply a similar strategy to other unions without violating the semantics.
-              </p></div>
-            </li>
-            <li>
-              <p>
-                Several specifications overlap.
-                GeoAPI performs the work of integration by replacing some duplicate structures with references to equivalent structures from the standards that best represent them.
-              </p>
-              <div class="example"><p><b>Example:</b>
-                <abbr>ISO</abbr> 19115:2003 standard, which defines metadata structures,
-                also attempts to describe a few structures representing coordinate reference systems (<abbr title="Coordinate Reference System">CRS</abbr>).
-                Yet these are also the focus of another standard: <abbr>ISO</abbr> 19111.
-                At the same time, <abbr>ISO</abbr> 19111:2007 states in section 3 that it reuses all of the elements of
-                <abbr>ISO</abbr> 19115:2003 except <code>MD_CRS</code> and its components.
-                GeoAPI interfaces reduce the redundancy by applying the exclusion recommended by <abbr>ISO</abbr> 19111 to the entire project.
-              </p></div>
-            </li>
-            <li>
-              <p>
-                The complexity of some standards have increased for historical reasons rather than technical ones, related to the standardization process.
-                GeoAPI reduces the technical debt by designing interfaces with each element in its proper place,
-                regardless of the chronological order in which the standards were published.
-              </p>
-              <div class="example"><p><b>Example:</b>
-                <abbr>ISO</abbr> 19115-2 standard is an extension of <abbr>ISO</abbr> 19115-1 standard, adding image metadata structures.
-                These metadata were defined in a separate standard because they were not yet ready when the first part of the standard was published.
-                As it was not possible for administrative reasons to add attributes to already-published classes,
-                the new attributes were added in a sub-class bearing almost the same name.
-                Thus, <abbr>ISO</abbr> 19115-2 defines the class <code>MI_Band</code>,
-                which extends the class <code>MD_Band</code> from <abbr>ISO</abbr> 19115-1 by adding attributes that would have appeared
-                directly in the parent class if there were ready on time.
-                In GeoAPI, we have chosen to “repair” these anomalies by fusing these two classes into a single interface.
-              </p></div>
-            </li>
-          </ul>
-        </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>.
-      </p>
-
-      <details>
-        <summary>More about GeoAPI modules</summary>
-        <article id="GeoAPI-modules">
-          <h2>GeoAPI modules</h2>
+          <div class="example"><p><b>Example:</b>
+            The <abbr>OGC</abbr> class <code>MD_Identifier</code> becomes the
+            <code>Identifier</code> interface in the <code>org.opengis.metadata</code> package.
+            The <abbr>OGC</abbr> class <code>SC_CRS</code> becomes the <code>CoordinateReferenceSystem</code> interface,
+            and the <code class="OGC">usesDatum</code> association becomes a <code class="GeoAPI">getDatum()</code> method,
+            rather than the “<code>getUsesDatum()</code>” that would result from an automatic conversion tool.
+            We do not allow programs to blindly apply rules that ignore the conventions of the community whose schemas we translate.
+          </p></div>
+        </li>
+        <li>
           <p>
-            The GeoAPI project consists of a standardized part (<code>geoapi</code>)
-            and an experimental part (<code>geoapi-pending</code>).
-            As these two parts are mutually exclusive, users must take care not to mix them in the same project.
-            This separation is guaranteed for all projects that depend only on the Maven central repository
-            (including the final versions of Apache <abbr>SIS</abbr>),
-            as the <code>geoapi-pending</code> module is never deployed on this central repository.
-            By contrast, certain <abbr>SIS</abbr> development branches may depend on <code>geoapi-pending</code>.
+            The standards may contain structures that do not have a direct equivalent in Java,
+            such as unions similar to what we would find in C/C++.
+            The strategy used to obtain an equivalent feature in Java depends on the context:
+            multiple inheritance of interfaces, modification of the hierarchy, or simply omitting the union.
+            These decisions are made case-by-case based on a needs analysis.
           </p>
+          <div class="example"><p><b>Example:</b>
+            <abbr>ISO</abbr> 19111 standard defines different types of coordinate systems, such as spherical, cylindrical, polar or Cartesian.
+            It then defines several <em>subsets</em> of these types of coordinate systems systems.
+            These subsets, represented by unions, serve to specify that a class may only be associated with a particular type of coordinate system.
+            For example, a union of types may be associated with an image, named <code>CS_ImageCS</code>,
+            which can only contain <code>CS_CartesianCS</code> and <code>CS_AffineCS</code>.
+            In this case, we get the desired effect in Java through a modification of the hierarchy of classes:
+            we define the <code>CartesianCS</code> interface as a specialization of <code>AffineCS</code>,
+            which is semantically correct.
+            But it is not possible to apply a similar strategy to other unions without violating the semantics.
+          </p></div>
+        </li>
+        <li>
           <p>
-            GeoAPI modules are:
+            Several specifications overlap.
+            GeoAPI performs the work of integration by replacing some duplicate structures with references to equivalent structures from the standards that best represent them.
           </p>
-          <ul>
-            <li><p>
-              <b><code>geoapi</code></b> — includes interfaces covered by the
-              <a href="http://www.opengeospatial.org/standards/geoapi">GeoAPI standard of the <abbr>OGC</abbr></a>.
-              The final versions of Apache <abbr>SIS</abbr> depend on this module.
-            </p></li>
-            <li><p>
-              <b><code>geoapi-pending</code></b> — contains a
-              <em>copy</em> of all interfaces in the <code>geoapi</code> module
-              (not a dependence) with additions that have not yet been approved as an <abbr>OGC</abbr> standard.
-              Some additions appear in interfaces normally defined by the <code>geoapi</code> module, hence the need to copy them.
-              Apache <abbr>SIS</abbr>’s development branches <code>jdk7</code> and <code>jdk8</code> depend on this module,
-              but this dependence becomes a dependence on the <code>geoapi</code> standard module when the branches are merged to the trunk.
-            </p></li>
-            <li><p>
-              <b><code>geoapi-conformance</code></b> — includes a JUnit test suite that developers may use to test their implementations.
-            </p></li>
-            <li><p>
-              <b><code>geoapi-examples</code></b> — includes examples of relatively simple implementations.
-              These examples are placed in the public domain in order to encourage users to copy and adapt them to their needs if
-              Apache <abbr>SIS</abbr> services are unsuitable.
-            </p></li>
-            <li><p>
-              <b><code>geoapi-proj4</code></b> — contains a partial implementation of <code>org.opengis.referencing</code>
-              packages as adaptors based on the C/C++ Proj.4 library.
-              This module may be used as an alternative to the <code>sis-referencing</code> module for certain functions.
-            </p></li>
-            <li><p>
-              <b><code>geoapi-netcdf</code></b> — contains a partial implementation of <code>org.opengis.referencing</code>
-              and <code>org.opengis.coverage</code> packages as adaptors based on the <abbr>UCAR</abbr> <abbr>netCDF</abbr> library.
-              The series of tests in this module was developed in such a way as to be reusable for other projects.
-              Apache <abbr>SIS</abbr> uses them to test its own <code>sis-netcdf</code> module.
-            </p></li>
-            <li><p>
-              <b><code>geoapi-openoffice</code></b> — contains an add-in for the OpenOffice.org office suite.
-            </p></li>
-          </ul>
-        </article>
-      </details>
+          <div class="example"><p><b>Example:</b>
+            <abbr>ISO</abbr> 19115:2003 standard, which defines metadata structures,
+            also attempts to describe a few structures representing coordinate reference systems (<abbr title="Coordinate Reference System">CRS</abbr>).
+            Yet these are also the focus of another standard: <abbr>ISO</abbr> 19111.
+            At the same time, <abbr>ISO</abbr> 19111:2007 states in section 3 that it reuses all of the elements of
+            <abbr>ISO</abbr> 19115:2003 except <code>MD_CRS</code> and its components.
+            GeoAPI interfaces reduce the redundancy by applying the exclusion recommended by <abbr>ISO</abbr> 19111 to the entire project.
+          </p></div>
+        </li>
+        <li>
+          <p>
+            The complexity of some standards have increased for historical reasons rather than technical ones, related to the standardization process.
+            GeoAPI reduces the technical debt by designing interfaces with each element in its proper place,
+            regardless of the chronological order in which the standards were published.
+          </p>
+          <div class="example"><p><b>Example:</b>
+            <abbr>ISO</abbr> 19115-2 standard is an extension of <abbr>ISO</abbr> 19115-1 standard, adding image metadata structures.
+            These metadata were defined in a separate standard because they were not yet ready when the first part of the standard was published.
+            As it was not possible for administrative reasons to add attributes to already-published classes,
+            the new attributes were added in a sub-class bearing almost the same name.
+            Thus, <abbr>ISO</abbr> 19115-2 defines the class <code>MI_Band</code>,
+            which extends the class <code>MD_Band</code> from <abbr>ISO</abbr> 19115-1 by adding attributes that would have appeared
+            directly in the parent class if there were ready on time.
+            In GeoAPI, we have chosen to “repair” these anomalies by fusing these two classes into a single interface.
+          </p></div>
+        </li>
+      </ul>
+      <p>
+        Deviations from the standards are documented in each affected class and method.
+        Each mention of a deviation is also collected on a <a href="http://www.geoapi.org/3.0/javadoc/departures.html">single page</a> in order to provide an overview.
+        Since these deviations blur the relationships between the standards and certain Java interfaces,
+        the correspondence between these languages is explained by <code>@UML</code> annotations and property files described in the following section.
+      </p>
 
 
 
@@ -528,50 +378,6 @@ System.out.println("Standard name of typ
 MediumName usbKey = MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">USB_KEY</code>"); // There is no constraint on this value.
 assert MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">CD_ROM</code>")  == cdRom  : "valueOf must return existing constants.";
 assert MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">USB_KEY</code>") == usbKey : "valueOf must cache the previously requested values.";</code></pre>
-
-
-
-      <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>CRSFactory.createXXX(…)</code> or <code>new DefaultXXX(…)</code>
-        is almost the same except that <code>Factory</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>



Mime
View raw message