sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1794727 [2/4] - in /sis/site/trunk: book/en/ book/en/annex/ book/en/coverage/ book/en/geometry/ book/en/introduction/ book/en/overview/ book/en/storage/ book/en/xml/ book/fr/ book/fr/overview/ book/fr/referencing/ book/fr/storage/ book/fr/...
Date Wed, 10 May 2017 14:38:19 GMT
Modified: sis/site/trunk/content/book/en/developer-guide.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/book/en/developer-guide.html?rev=1794727&r1=1794726&r2=1794727&view=diff
==============================================================================
--- sis/site/trunk/content/book/en/developer-guide.html [UTF-8] (original)
+++ sis/site/trunk/content/book/en/developer-guide.html [UTF-8] Wed May 10 14:38:19 2017
@@ -33,8 +33,15 @@ Partially translated by <i>Christina Hou
 <li><a href="#UML-annotation">Explicit mapping given by @UML annotations</a></li>
 <li><a href="#MappingToJDK">Implicit mapping to standard JDK</a></li>
 <li><a href="#GeoAPI-implementation">Implementations provided by Apache SIS</a></li></ul></li>
-<li><a href="#About">Conventions used in this guide</a><ul>
+<li><a href="#AboutBook">Conventions used in this guide</a><ul>
 <li><a href="#CodeColors">Code colors</a></li></ul></li></ul></li>
+<li><a href="#DataAccess">Geospatial data access</a></li>
+<li><a href="#Coverage">Data coverages</a></li>
+<li><a href="#Geometry">Geometries</a><ul>
+<li><a href="#GeometryBase">Base classes</a><ul>
+<li><a href="#DirectPosition">Direct points and positions</a></li>
+<li><a href="#Envelope">Envelopes</a><ul>
+<li><a href="#AntiMeridian">Envelopes that cross the antimeridian</a></li></ul></li></ul></li></ul></li>
 <li><a href="#Referencing">Spatial reference systems</a><ul>
 <li><a href="#ComponentsOfCRS">Components of a reference system by coordinates</a><ul>
 <li><a href="#Ellipsoid">Geoid et ellipsoid</a></li>
@@ -58,13 +65,12 @@ Partially translated by <i>Christina Hou
 <li><a href="#DerivativeAndEnvelope">Transform derivatives applied to envelopes</a></li>
 <li><a href="#DerivativeAndRaster">Transform derivatives applied to rasters</a></li>
 <li><a href="#GetDerivative">Getting the derivative at a point</a></li></ul></li>
-<li><a href="#CoordinateOperationSteps">Conceptual versus real chain of coordinate operations</a></li></ul></li></ul></li>
-<li><a href="#Geometry">Geometries</a><ul>
-<li><a href="#GeometryBase">Base classes</a><ul>
-<li><a href="#DirectPosition">Direct points and positions</a></li>
-<li><a href="#Envelope">Envelopes</a><ul>
-<li><a href="#AntiMeridian">Envelopes that cross the antimeridian</a></li></ul></li></ul></li></ul></li>
-<li><a href="#Coverage">Data coverages</a></li>
+<li><a href="#CoordinateOperationSteps">Conceptual versus real chain of coordinate operations</a></li></ul></li>
+<li><a href="#Formats">Date storage formats</a></li>
+<li><a href="#XML-ISO">Representing objects in XML</a><ul>
+<li><a href="#XML-ISO-19115">Representing metadata according to ISO 19115-3</a><ul>
+<li><a href="#gco-id">Identification of already-defined instances</a></li>
+<li><a href="#nilReason">Representing missing values</a></li></ul></li></ul></li></ul></li>
 <li><a href="#Utilities">Utility classes and methods</a><ul>
 <li><a href="#ComparisonModes">Comparison modes of objects</a></li>
 <li><a href="#ObjectConverters">Object converters</a></li>
@@ -74,10 +80,6 @@ Partially translated by <i>Christina Hou
 <li><a href="#Locale.ROOT">Locale.ROOT convention</a></li>
 <li><a href="#UnicodePoint">Treatment of characters</a><ul>
 <li><a href="#Whitespaces">Blank spaces interpretation</a></li></ul></li></ul></li></ul></li>
-<li><a href="#XML-ISO">Representing objects in XML</a><ul>
-<li><a href="#XML-ISO-19115">Representing metadata according to ISO 19115-3</a><ul>
-<li><a href="#gco-id">Identification of already-defined instances</a></li>
-<li><a href="#nilReason">Representing missing values</a></li></ul></li></ul></li>
 <li><a href="#Annexes">Annexes</a><ul>
 <li><a href="#ReduceDependency">Reduce direct dependency to Apache SIS</a><ul>
 <li><a href="#UML-annotation-indep">Mapping given by @UML annotations</a></li>
@@ -105,10 +107,11 @@ Partially translated by <i>Christina Hou
 
 
 
+
 <section>
 <header>
 <h1 id="Standards"><span class="section-number">1.</span> Standards and norms</h1>
-<nav><div class="chapter-links"><div class="next-chapter"><a href="#Referencing">Next chapter</a> ➡</div></div></nav>
+<nav><div class="chapter-links"><div class="next-chapter"><a href="#DataAccess">Next chapter</a> ➡</div></div></nav>
 </header>
 <nav>In this chapter:<ul class="toc">
 <li><a href="#ConceptualModels">Sources of conceptual models used by Apache SIS</a></li>
@@ -116,7 +119,7 @@ Partially translated by <i>Christina Hou
 <li><a href="#UML-annotation">Explicit mapping given by @UML annotations</a></li>
 <li><a href="#MappingToJDK">Implicit mapping to standard JDK</a></li>
 <li><a href="#GeoAPI-implementation">Implementations provided by Apache SIS</a></li></ul></li>
-<li><a href="#About">Conventions used in this guide</a><ul>
+<li><a href="#AboutBook">Conventions used in this guide</a><ul>
 <li><a href="#CodeColors">Code colors</a></li></ul></li></ul></nav>
 <p>
 A geospatial information community is a collection of systems or individuals capable of exchanging their geospatial data
@@ -540,12 +543,12 @@ Developers of client applications benefi
 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 title="Java DataBase Connectivity">JDBC</abbr></a> (<i>Java Database Connectivity</i>) interfaces of standard Java.
-Using the interfaces' <abbr title="Application Programming Interface">API</abbr>, developers can ignore the underlying implementation.
+Using the interfaces’ <abbr title="Application Programming Interface">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 title="Spatial Information System">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.
+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,
@@ -556,7 +559,7 @@ and simply get a null value until a new
 
 <details>
 <summary>More about the GeoAPI project</summary>
-<article>
+<article id="GeoAPI-history">
 <header>
 <h2>GeoAPI project history</h2>
 </header>
@@ -755,7 +758,7 @@ The final versions of Apache <abbr>SIS</
 <em>copy</em> of all interfaces in the <code class="GeoAPI">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 class="GeoAPI">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,
+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 class="GeoAPI">geoapi</code> standard module when the branches are merged to the trunk.
 </p></li>
 <li><p>
@@ -840,7 +843,7 @@ Some classes and methods have neither an
 They are either extensions of GeoAPI, or else types defined in other libraries, such as standard <abbr title="Java Development Kit">JDK</abbr>.
 In this last case, the mapping to <abbr>ISO</abbr> standards is implicit.
 The following table describes this mapping for <abbr>ISO</abbr> 19103 types.
-Java's primitive types are preferred when applicable,
+Java’s primitive types are preferred when applicable,
 but where necessary their wrappers are used in order to authorize null values.
 </p>
 <table>
@@ -998,8 +1001,8 @@ but GeoAPI often uses the <code class="G
 For example, it is useful on a server that simultaneously provides pages in multiple languages.
 By returning translations when objects are used rather than at the time of their creation,
 we allow the <abbr title="Spatial Information System">SIS</abbr> library to provide the same instances of <code class="GeoAPI">Metadata</code>
-or <code class="GeoAPI">Coverage</code> (for example) for the same data, regardless of the client's language.
-Translations may be made on the fly with the help of the application's <code>ResourceBundle</code>,
+or <code class="GeoAPI">Coverage</code> (for example) for the same data, regardless of the client’s language.
+Translations may be made on the fly with the help of the application’s <code>ResourceBundle</code>,
 or may be provided directly with the data (as in the case of <code class="GeoAPI">Metadata</code>).
 </p>
 <p>
@@ -1065,7 +1068,7 @@ However such instantiations should be do
 
 <section>
 <header>
-<h2 id="About"><span class="section-number">1.3.</span> Conventions used in this guide</h2>
+<h2 id="AboutBook"><span class="section-number">1.3.</span> Conventions used in this guide</h2>
 </header>
 <p>
 Standards sometimes favour the application of certain generic terms to particular contexts,
@@ -1076,9 +1079,9 @@ But the functions to which they are appl
 For example, <abbr>ISO</abbr> 19123 applies these terms to <code class="OGC">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
+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.
+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 title="Spatial Information System">SIS</abbr> library prefers as much as possible to use terms in the sense of <abbr title="Open Geospatial Consortium">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,
@@ -1121,1900 +1124,1924 @@ Text in gray boxes are for information p
 
 <section>
 <header>
-<h1 id="Referencing"><span class="section-number">2.</span> Spatial reference systems</h1>
-<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Standards">Previous chapter</a></div><div class="next-chapter"><a href="#Geometry">Next chapter</a> ➡</div></div></nav>
+<h1 id="DataAccess"><span class="section-number">2.</span> Geospatial data access</h1>
+<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Standards">Previous chapter</a></div><div class="next-chapter"><a href="#Coverage">Next chapter</a> ➡</div></div></nav>
 </header>
-<nav>In this chapter:<ul class="toc">
-<li><a href="#ComponentsOfCRS">Components of a reference system by coordinates</a><ul>
-<li><a href="#Ellipsoid">Geoid et ellipsoid</a></li>
-<li><a href="#GeodeticDatum">Geodetic datum</a></li>
-<li><a href="#CoordinateSystem">Coordinate systems</a><ul>
-<li><a href="#AxisOrder">Axis order</a></li></ul></li>
-<li><a href="#GeographicCRS">Geographic reference systems</a><ul>
-<li><a href="#GeographicWKT">Well-Known Text format</a></li></ul></li>
-<li><a href="#ProjectedCRS">Map projections</a><ul>
-<li><a href="#ProjectedWKT">Well-Known Text format</a></li></ul></li>
-<li><a href="#CompoundCRS">Vertical and temporal dimensions</a><ul>
-<li><a href="#CompoundWKT">Well-Known Text format</a></li></ul></li></ul></li>
-<li><a href="#GetCRS">Fetching a spatial reference system</a><ul>
-<li><a href="#CRSAuthorityFactory">Looking CRS defined by authorities</a></li>
-<li><a href="#CRSParsing">Reading definitions in GML or WKT format</a></li>
-<li><a href="#CRSFactory">Constructing programmatically</a></li>
-<li><a href="#CRS_UserCode">Adding new CRS definitions</a></li></ul></li>
-<li><a href="#CoordinateOperations">Coordinate operations</a><ul>
-<li><a href="#MathTransform">Executing an operation on coordinate values</a></li>
-<li><a href="#TransformDerivative">Partial derivatives of coordinate operations</a><ul>
-<li><a href="#DerivativeAndEnvelope">Transform derivatives applied to envelopes</a></li>
-<li><a href="#DerivativeAndRaster">Transform derivatives applied to rasters</a></li>
-<li><a href="#GetDerivative">Getting the derivative at a point</a></li></ul></li>
-<li><a href="#CoordinateOperationSteps">Conceptual versus real chain of coordinate operations</a></li></ul></li></ul></nav>
+<nav>In this chapter:<ul class="toc"/></nav>
 <p>
-For locating a point on Earth one can use identifiers like city name or postal address
-— an approach known as <cite>spatial reference systems by identifiers</cite> —
-or use numerical values valid in a given coordinate system like latitudes and longitudes
-— an approach known as <cite>spatial reference systems by coordinates</cite>.
-Each reference system implies approximations like
-the choice of a figure of the Earth (geoid, ellipsoid, <i>etc.</i>) used as an approximation of Earth shape,
-the choice of geometric properties (angles, distances, <i>etc.</i>) to be preserved when a map is shown on plane surface, and
-a lost of precision when coordinates are transformed to systems using a different <a href="#GeodeticDatum">datum</a>.
-</p><p>
-A very common misbelief is that one can avoid this complexity by using a single coordinate reference system
-(typically <abbr title="World Geodetic System 1984">WGS84</abbr>) as a universal system for all data.
-The next chapters will explain why the reality is not so simple.
-Whether a universal reference system can suit an application needs or not depends on the desired positional accuracy
-and the kind of calculations to be performed with the data.
-Unless otherwise specified, Apache <abbr title="Spatial Information System">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:
+<span style="color: red">TODO</span>
 </p>
-<ul>
-<li>Points should be inside the domain of validity as given by <code class="GeoAPI">ReferenceSystem​.getDomainOfValidity()</code>.</li>
-<li>Distance measurements in a given map projection are true only is some special locations,
-named for instance “standards parallels”.</li>
-<li>Positional accuracy is altered after coordinate transformations.
-The new accuracy is described by <code class="GeoAPI">CoordinateOperation​.getCoordinateOperationAccuracy()</code>.</li>
-<li>Finding the most appropriate coordinate transformation parameters require the use of a geodetic dataset like <abbr>EPSG</abbr>.
-Declaring those parameters within the <abbr title="Coordinate Reference System">CRS</abbr> (for example with a <code class="OGC">TOWGS84</code> element) is often not sufficient.</li>
-</ul>
-<article>
+</section>
+
+
+<section>
 <header>
-<h2>“Early binding” versus “late binding” implementations</h2>
+<h1 id="Coverage"><span class="section-number">3.</span> Data coverages</h1>
+<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#DataAccess">Previous chapter</a></div><div class="next-chapter"><a href="#Geometry">Next chapter</a> ➡</div></div></nav>
 </header>
+<nav>In this chapter:<ul class="toc"/></nav>
 <p>
-Because of the <abbr title="World Geodetic System 1984">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 class="GeoAPI">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 class="GeoAPI">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:
+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 title="International Organization for Standardization">ISO</abbr> 19123 standard that describes them, “Coverage Geometry and Functions”,
+nicely summarizes the two essential elements of coverages:
 </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>
+<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 title="Spatial Information System">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 <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 title="Coordinate Reference System">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.
+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>
-<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 title="Spatial Information System">SIS</abbr> is a “late binding” implementation,
-while some reminiscences of “early binding” approach still exist in the form of the
-<code class="SIS">DefaultGeodeticDatum​.getBursaWolfParameters()</code> property.
-The later is used only if <abbr>SIS</abbr> fails to apply the late binding approach for given reference systems.
+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 class="SIS">GridGeometry</code> class.
 </p>
-</article>
+</li>
+</ul>
 <p>
-The <code class="SIS">sis-referencing</code> module provides a set of classes implementing
-different specializations of the <code class="GeoAPI">ReferenceSystem</code> interface, together with required components.
-Those implementations store spatial reference system descriptions, together with metadata like their domain of validity.
-However those objects do not perform any operation on coordinate values.
-Coordinates <cite>conversions</cite> or <cite>transformations</cite> are performed by another family of types,
-with <code class="GeoAPI">CoordinateOperation</code> as the root interface.
-Those types will be discussed in <a href="#CoordinateOperation">another section</a>.
+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 class="OGC">CV_DiscreteCoverage</code> type.
+</p>
+<aside>
+<h2>SIS’s <code class="SIS">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 title="Spatial Information System">SIS</abbr> by the <code class="SIS">Range</code> and <code class="SIS">NumberRange</code>
+classes respectively.
+The <code class="SIS">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 title="International Organization for Standardization">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 class="SIS">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 class="SIS">Range</code>,
+as well as other information such as <i>transfer function</i> (described later).
+</p>
+</aside>
+</section>
 
 
+<section>
+<header>
+<h1 id="Geometry"><span class="section-number">4.</span> Geometries</h1>
+<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Coverage">Previous chapter</a></div><div class="next-chapter"><a href="#Referencing">Next chapter</a> ➡</div></div></nav>
+</header>
+<nav>In this chapter:<ul class="toc">
+<li><a href="#GeometryBase">Base classes</a><ul>
+<li><a href="#DirectPosition">Direct points and positions</a></li>
+<li><a href="#Envelope">Envelopes</a><ul>
+<li><a href="#AntiMeridian">Envelopes that cross the antimeridian</a></li></ul></li></ul></li></ul></nav>
+<p>
+This chapter introduces a few aspects of <abbr title="International Organization for Standardization">ISO</abbr> 19107 standard (<i>Spatial schema</i>)
+and the Apache <abbr title="Spatial Information System">SIS</abbr> classes that implement them.
+</p>
 
 
 
 
 <section>
 <header>
-<h2 id="ComponentsOfCRS"><span class="section-number">2.1.</span> Components of a reference system by coordinates</h2>
+<h2 id="GeometryBase"><span class="section-number">4.1.</span> Base classes</h2>
 </header>
 <p>
-Spatial reference systems by coordinates provide necessary information for mapping numerical coordinate values
-to real-world locations. In Apache <abbr title="Spatial Information System">SIS</abbr>, most information is contained (directly or indirectly) in
-classes with a name ending in <abbr title="Coordinate Reference System">CRS</abbr>, the abbreviation of <i>Coordinate Reference System</i>.
-Those objects contain:
+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 title="International Organization for Standardization">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 class="GeoAPI">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>
-<ul>
-<li>A <i>datum</i>, which specifies among other things which ellipsoid to use as an Earth shape approximation.</li>
-<li>A description for each axis: name, direction, units of measurement, range of values.</li>
-<li>Sometime a list of parameters, especially when using map projections.</li>
-</ul>
 <p>
-Those systems are described by the <abbr title="International Organization for Standardization">ISO</abbr> 19111 standard (<i>Referencing by Coordinates</i>),
-which replaces for most parts the older <abbr>OGC 01-009</abbr> standard (<i>Coordinate Transformation Services</i>).
-Those standards are completed by two other standards defining exchange formats:
-<abbr>ISO</abbr> 19136 and 19162 respectively for the
-<cite>Geographic Markup Language</cite> (<abbr>GML</abbr>) — a <abbr>XML</abbr> format which is quite detailed but verbose —
-and the <cite>Well-Known Text</cite> (<abbr>WKT</abbr>) — a text format easier to read by humans.
+All geometries are specializations of <code class="GeoAPI">TransfiniteSet</code>.
+The parent class of those geometries is called <code class="OGC">GM_Object</code> in <abbr>ISO</abbr> 19107 standard.
+GeoAPI interfaces use the <code class="GeoAPI">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="Ellipsoid"><span class="section-number">2.1.1.</span> Geoid et ellipsoid</h3>
-<p>
-Since the real topographic surface is difficult to represent mathematically, it is not used directly.
-A slightly more convenient surface is the geoid,
-a surface where the gravitational field has the same value everywhere (an equipotential surface).
-This surface is perpendicular to the direction of a plumb line at all points.
-The geoid surface would be equivalent to the mean sea level if all oceans where at rest,
-without winds or permanent currents like the Gulf Stream.
-</p><p>
-While much smoother than topographic surface, the geoid surface still have hollows and bumps
-caused by the uneven distribution of mass inside Earth.
-For more convenient mathematical operations, the geoid surface is approximated by an ellipsoid.
-This “figure of Earth” is represented in GeoAPI by the <code class="GeoAPI">Ellipsoid</code> interface,
-a fundamental component in coordinate reference systems of kind <code class="GeoAPI">GeographicCRS</code> and <code class="GeoAPI">ProjectedCRS</code>.
-Tenth of ellipsoids are commonly used for datum definitions.
-Some of them provide a very good approximation for a particular geographic area
-at the expense of the rest of the world for which the datum was not designed.
-Other datums are compromises applicable to the whole world.
-</p>
-<div class="example">
-<p><b>Example:</b>
-the <abbr>EPSG</abbr> geodetic dataset defines among others the “<abbr>WGS</abbr> 84”, “Clarke 1866”, “Clarke 1880”,
-“<abbr>GRS</abbr> 1980” and “<abbr>GRS</abbr> 1980 Authalic Sphere” (a sphere of same surface than the <abbr>GRS</abbr> 1980 ellipsoid).
-Ellipsoids may be used in various places of the world or may be defined for a very specific region.
-For example in <abbr>USA</abbr> at the beginning of XX<sup>th</sup> century,
-the Michigan state used an ellipsoid based on the “Clarke 1866” ellipsoid but with axis lengths expanded by 800 feet.
-This modification aimed to take in account the average state height above mean sea level.</p>
-</div>
 
-<h3 id="GeodeticDatum"><span class="section-number">2.1.2.</span> Geodetic datum</h3>
+
+<h3 id="DirectPosition"><span class="section-number">4.1.1.</span> Direct points and positions</h3>
 <p>
-For defining a geodetic system in a country, a national authority selects an ellipsoid matching closely the country surface.
-Differences between that ellipsoid and the geoid’s hollows and bumps are usually less than 100 metres.
-Parameters that relate an <code class="GeoAPI">Ellipsoid</code> to the Earth surface (for example the position of ellipsoid center)
-are represented by instances of <code class="GeoAPI">GeodeticDatum</code>.
-Many <code class="GeoAPI">GeodeticDatum</code> definitions can use the same <code class="GeoAPI">Ellipsoid</code>,
-but with different orientations or center positions.
-</p><p>
-Before the satellite era, geodetic measurements were performed exclusively from Earth surface.
-Consequently, two islands or continents not in range of sight from each other were not geodetically related.
-So the <cite>North American Datum 1983</cite> (<abbr>NAD83</abbr>) and the <cite>European Datum 1950</cite> (<abbr>ED50</abbr>)
-are independent: their ellipsoids have different sizes and are centered at a different positions.
-The same geographic coordinate will map different locations on Earth depending on whether the coordinate
-uses one reference system or the other.
-</p><p>
-The <abbr title="Global Positioning System">GPS</abbr> invention implied the creation of a
-world geodetic system named <abbr title="World Geodetic System 1984">WGS84</abbr>.
-The ellipsoid is then unique and centered at the Earth gravity center.
-<abbr>GPS</abbr> provides at any moment the receptor absolute position on that world geodetic system.
-But since <abbr>WGS84</abbr> is a world-wide system, it may differs significantly from local systems.
-For example the difference between <abbr>WGS84</abbr> and the European system <abbr>ED50</abbr> is about 150 metres,
-and the average difference between <abbr>WGS84</abbr> and the <cite>Réunion 1947</cite> system is 1.5 kilometres.
-Consequently we shall not blindly use <abbr>GPS</abbr> coordinates on a map,
-as transformations to the local system may be required.
-Those transformations are represented in GeoAPI by instances of the <code class="GeoAPI">Transformation</code> interface.
-</p><p>
-The <abbr>WGS84</abbr> ubiquity tends to reduce the need for <code class="GeoAPI">Transformation</code> operations with recent data,
-but does not eliminate it.
-The Earth moves under the effect of plate tectonic and new systems are defined every years for taking that fact in account.
-For example while <abbr>NAD83</abbr> was originally defined as practically equivalent to <abbr>WGS84</abbr>,
-there is now (as of 2016) a 1.5 metres difference.
-The <cite>Japanese Geodetic Datum 2000</cite> was also defined as practically equivalent to <abbr>WGS84</abbr>,
-but the <cite>Japanese Geodetic Datum 2011</cite> now differs.
-Even the <abbr>WGS84</abbr> datum, which was a terrestrial model realization at a specific time,
-got revisions because of improvements in instruments accuracy.
-Today, at least six <abbr>WGS84</abbr> versions exist.
-Furthermore many borders were legally defined in legacy datums, for example <abbr>NAD27</abbr> in <abbr>USA</abbr>.
-Updating data to the new datum would imply transforming some straight lines or simple geometric shapes
-into more irregular shapes, if the shapes are large enough.
-</p>
-
-<h3 id="CoordinateSystem"><span class="section-number">2.1.3.</span> Coordinate systems</h3>
-<p style="color: red">TODO</p>
-
-<h4 id="AxisOrder"><span class="section-number">2.1.3.1.</span> Axis order</h4>
-<p>
-The axis order is specified by the authority (typically a national agency) defining the <cite>Coordinate Reference System</cite> (<abbr title="Coordinate Reference System">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 class="GeoAPI">GeographicCRS</code>,
-for some <code class="GeoAPI">ProjectedCRS</code> in the South hemisphere (South Africa, Australia, <i>etc.</i>) and for some polar projections among others.
-</p><p>
-Recent <abbr title="Open Geospatial Consortium">OGC</abbr> standards mandate the use of axis order as defined by the authority.
-Oldest <abbr>OGC</abbr> standards used the (<var>x</var>, <var>y</var>) axis order instead, ignoring any authority specification.
-Many softwares still use the old (<var>x</var>, <var>y</var>) axis order,
-maybe because such uniformization makes <abbr>CRS</abbr> implementation and usage <em>apparently</em> easier.
-Apache <abbr title="Spatial Information System">SIS</abbr> supports both conventions with the following approach:
-by default, <abbr>SIS</abbr> creates <abbr>CRS</abbr> with axis order <em>as defined by the authority</em>.
-Those <abbr>CRS</abbr> are created by calls to the <code>CRS.forCode(String)</code> method
-and the actual axis order can be verified after the <abbr>CRS</abbr> creation with <code>System.out​.println(crs)</code>.
-But if (<var>x</var>, <var>y</var>) axis order is wanted for compatibility with older <abbr>OGC</abbr> specifications or other softwares,
-then <abbr>CRS</abbr> forced to <cite>longitude first</cite> axis order can be created by a call to the following method:
-</p>
-
-<pre><code class="GeoAPI">CoordinateReferenceSystem</code> crs = …;               <code class="comment">// CRS obtained by any means.
-</code>crs = AbstractCRS.castOrCopy(crs).forConvention(AxesConvention.RIGHT_HANDED)</pre>
-
-<p>
-Among the legacy <abbr>OGC</abbr> standards that used the non-conform axis order,
-an influent one is version 1 of the <cite>Well Known Text</cite> (<abbr>WKT</abbr>) format specification.
-According that widely-used format, <abbr>WKT</abbr> 1 definitions without explicit <code>AXIS[…]</code> elements
-shall default to (<var>longitude</var>, <var>latitude</var>) or (<var>x</var>, <var>y</var>) axis order.
-In version 2 of <abbr>WKT</abbr> format, <code>AXIS[…]</code> elements are no longer optional
-and should contain an explicit <code>ORDER[…]</code> sub-element for making the intended order yet more obvious.
-But if <code>AXIS[…]</code> elements are nevertheless missing in a <abbr>WKT</abbr> 2 definition,
-Apache <abbr>SIS</abbr> defaults to (<var>latitude</var>, <var>longitude</var>) order.
-So in summary:
-</p>
-<ul>
-<li>Default <abbr>WKT</abbr> 1 axis order of geographic <abbr>CRS</abbr> is (<var>longitude</var>, <var>latitude</var>) as mandated by <abbr>OGC</abbr> 01-009 specification.</li>
-<li>Default <abbr>WKT</abbr> 2 axis order of geographic <abbr>CRS</abbr> is (<var>latitude</var>, <var>longitude</var>),
-but this is <abbr>SIS</abbr>-specific as <abbr title="International Organization for Standardization">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.
+<abbr title="International Organization for Standardization">ISO</abbr> 19107 defines two types of structures to represent a point:
+<code class="OGC">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 class="OGC">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>
-
-<h3 id="GeographicCRS"><span class="section-number">2.1.4.</span> Geographic reference systems</h3>
-<p style="color: red">TODO</p>
-
-<h4 id="GeographicWKT"><span class="section-number">2.1.4.1.</span> <i>Well-Known Text</i> format</h4>
-<p style="color: red">TODO</p>
-
-<h3 id="ProjectedCRS"><span class="section-number">2.1.5.</span> 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.
+In order to allow the <abbr title="Application Programming Interface">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 class="OGC">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 class="GeoAPI">Position</code> as the parent interface of <code class="GeoAPI">DirectPosition</code> and <code class="GeoAPI">Point</code>.
+In practice, the great majority of Apache <abbr title="Spatial Information System">SIS</abbr>’s <abbr>API</abbr> works on <code class="GeoAPI">DirectPosition</code>s,
+or occasionally on <code class="GeoAPI">Position</code>s when it seems useful to also allow geometric points.
 </p>
-<p style="color: red">TODO</p>
-
-<h4 id="ProjectedWKT"><span class="section-number">2.1.5.1.</span> <i>Well-Known Text</i> format</h4>
-<p style="color: red">TODO</p>
-
-<h3 id="CompoundCRS"><span class="section-number">2.1.6.</span> Vertical and temporal dimensions</h3>
-<p style="color: red">TODO</p>
-
-<h4 id="CompoundWKT"><span class="section-number">2.1.6.1.</span> <i>Well-Known Text</i> format</h4>
-<p style="color: red">TODO</p>
-</section>
-
 
-<section>
-<header>
-<h2 id="GetCRS"><span class="section-number">2.2.</span> Fetching a spatial reference system</h2>
-</header>
-<p style="color: red">TODO</p>
-
-<h3 id="CRSAuthorityFactory"><span class="section-number">2.2.1.</span> Looking <abbr title="Coordinate Reference System">CRS</abbr> defined by authorities</h3>
-<p style="color: red">TODO</p>
-
-<h3 id="CRSParsing"><span class="section-number">2.2.2.</span> Reading definitions in GML or WKT format</h3>
-<p style="color: red">TODO</p>
 
-<h3 id="CRSFactory"><span class="section-number">2.2.3.</span> Constructing programmatically</h3>
-<p style="color: red">TODO</p>
-
-<h3 id="CRS_UserCode"><span class="section-number">2.2.4.</span> Adding new <abbr title="Coordinate Reference System">CRS</abbr> definitions</h3>
-<p style="color: red">TODO</p>
-</section>
 
-
-<section>
-<header>
-<h2 id="CoordinateOperations"><span class="section-number">2.3.</span> Coordinate operations</h2>
-</header>
+<h3 id="Envelope"><span class="section-number">4.1.2.</span> Envelopes</h3>
 <p>
-Given a <em>source</em> coordinate reference system (<abbr title="Coordinate Reference System">CRS</abbr>) in which existing coordinate values are expressed,
-and a <em>target</em> coordinate reference system in which coordinate values are desired,
-Apache <abbr title="Spatial Information System">SIS</abbr> can provide a <em>coordinate operation</em> performing the conversion or transformation work.
-The search for coordinate operations may use a third argument, optional but recommended,
-which is the geographic area of the data to transform.
-That later argument is recommended because coordinate operations are often valid only in a some geographic area
-(typically a particular country or state), and many transformations may exist
-for the same pair of source and target <abbr>CRS</abbr> but different domain of validity.
-Different coordinate operations may also be different compromises between accuracy and their domain of validity,
-and specifying a smaller area of interest may allow Apache <abbr>SIS</abbr> to select a more accurate operation.
+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>).
+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.
+Nevertheless, we speak of envelopes as rectangles, cubes or hyper-cubes (depending on the number of dimensions)
+in order to facilitate discussion, while bearing in mind their non-geometric nature.
 </p>
 <div class="example"><p><b>Example:</b>
-the <abbr>EPSG</abbr> geodetic dataset (as of version 7.9) defines 77 coordinate operations from the
-<cite>North American Datum 1927</cite> (EPSG:4267) coordinate reference system to the
-<cite>World Geodetic System 1984</cite> (EPSG:4326) <abbr>CRS</abbr>.
-There is one operation valid only for coordinate transformations in Québec,
-another operation valid for coordinate transformations in Texas west of 100°W,
-another operation for the same state but east of 100°W, <i>etc</i>.
-If the user did not specified any geographic area of interest,
-then Apache <abbr>SIS</abbr> defaults on the coordinate operation which is valid in the largest area.
-In this example, the “largest area” criterion results in the selection of a coordinate operation valid for Canada,
-not <abbr>USA</abbr>.</p>
-</div>
+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.
+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,
+and then recalculating its envelope.
+</p></div>
 <p>
-The easiest way to obtain a coordinate operation from above-cited information
-is to use the <code class="SIS">org.apache.sis.referencing.CRS</code> convenience class:
+An envelope might be represented by two positions corresponding to two opposite corners of a rectangle,
+cube or hyper-cube.
+For the first corner, we often take the one whose ordinates all have the maximal value (<code class="OGC">upperCorner</code>).
+When displayed using a conventional system of coordinates (with <var>y</var> axis values running upwards),
+these two positions appear respectively in the lower left corner and the upper right corner of a rectangle.
+Care must be taken with different coordinate systems, however, which may vary the positions of these corners on the screen.
+The expressions <i>lower corner</i> and <i>upper corner</i> should thus be understood in the mathematical rather than the visual sense.
 </p>
 
-<pre><code class="GeoAPI">CoordinateOperation</code> cop = CRS.findOperation(sourceCRS, targetCRS, areaOfInterest);</pre>
 
+
+<h4 id="AntiMeridian"><span class="section-number">4.1.2.1.</span> Envelopes that cross the antimeridian</h4>
 <p>
-Among the information provided by <code class="GeoAPI">CoordinateOperation</code> object, the following are of special interest:
+Minimums and maximums are the values most often assigned to <code class="OGC">lowerCorner</code>
+and <code class="OGC">upperCorner</code>.
+But the situation becomes complicated when an envelope crosses the antimeridian (-180° or 180° longitude).
+For example, an envelope 10° in size may begin at 175° longitude and end at -175°.
+In this case, the longitude value assigned to <code class="OGC">lowerCorner</code> is greater than that assigned to <code class="OGC">upperCorner</code>.
+Apache <abbr title="Spatial Information System">SIS</abbr> therefore uses a slightly different definition of these two corners:
 </p>
 <ul>
-<li>The <cite>domain of validity</cite>, either as a textual description (e.g. “Canada – onshore and offshore”)
-or with the coordinates of a geographic bounding box.</li>
-<li>The <cite>positional accuracy</cite>, which may be anything from 1 centimetre to a few kilometres.</li>
-<li>The coordinate operation subtype. Among them, two sub-types provide the same functionalities but with a significant conceptual difference:
-<ul class="verbose">
-<li>
-Coordinate <strong>conversions</strong> are fully determined by mathematical formulas.
-Those conversions would have an infinite precision if it was not for the unavoidable rounding errors
-inherent to floating-point calculations.
-Map projections are in this category.
-</li><li>
-Coordinate <strong>transformations</strong> are defined empirically.
-They often have errors of a few metres which are not caused by limitation in computer accuracy.
-Those errors exist because transformations are only approximations of a more complex reality.
-Datum shifts from <abbr title="North American Datum 1927">NAD27</abbr> to <abbr title="North American Datum 1983">NAD83</abbr>
-are in this category.
+<li><b><code class="SIS">lowerCorner</code>:</b>
+the starting point, if we move along the inside of the envelope in the direction of ascending values.
 </li>
-</ul>
+<li><b><code class="SIS">upperCorner</code>:</b>
+the end-point, if we move along the inside of the envelope in the direction of ascending values.
 </li>
 </ul>
 <p>
-If the coordinate operation is an instance of <code class="GeoAPI">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 class="GeoAPI">Conversion</code>.
-Consequently verifying the domain of validity and the positional accuracy declared in the transformation metadata is of particular importance.
+If the envelope does not cross the antimeridian, these two definitions are equivalent to the selection of minimal and
+maximal values respectively. This is the case in the green rectangle in the figure below.
+When the envelope crosses the antimeridian, the <code class="SIS">lowerCorner</code> and the
+<code class="SIS">upperCorner</code> appear again at the bottom and top of the rectangle
+(assuming a standard system of coordinates), so their names remain appropriate from a visual standpoint.
+However, the left and right positions are switched.
+This case is illustrated by the red rectangle in the figure below.
 </p>
-
-<h3 id="MathTransform"><span class="section-number">2.3.1.</span> Executing an operation on coordinate values</h3>
-<p>
-The <code class="GeoAPI">CoordinateOperation</code> object introduced in above section provides high-level informations
-(source and target <abbr title="Coordinate Reference System">CRS</abbr>, domain of validity, positional accuracy, operation parameters, <i>etc</i>).
-The actual mathematical work is performed by a separated object obtained by a call to <code class="GeoAPI">CoordinateOperation​.getMathTransform()</code>.
-At the difference of <code class="GeoAPI">CoordinateOperation</code> instances, <code class="GeoAPI">MathTransform</code> instances do not carry any metadata.
-They are kind of black box which know nothing about the source and target <abbr>CRS</abbr>
-(actually the same <code class="GeoAPI">MathTransform</code> can be used for different pairs of <abbr>CRS</abbr> if the mathematical work is the same), domain or accuracy.
-Furthermore <code class="GeoAPI">MathTransform</code> may be implemented in a very different way than what <code class="GeoAPI">CoordinateOperation</code> said.
-In particular many conceptually different coordinate operations (e.g. longitude rotations,
-change of units of measurement, conversions between two Mercator projections on the same datum, <i>etc.</i>)
-are implemented by <code class="GeoAPI">MathTransform</code> as <a href="#AffineTransform">affine transforms</a> and concatenated for efficiency,
-even if <code class="GeoAPI">CoordinateOperation</code> reports them as a chain of Mercator and other operations.
-The “<a href="#CoordinateOperationSteps">conceptual versus real chain of coordinate operations</a>” section explains the differences in more details.
+<p style="text-align:center">
+<img alt="Envelope example with and without anti-meridian spanning." src="../../apidocs/org/apache/sis/geometry/doc-files/AntiMeridian.png"/>
 </p>
 <p>
-The following Java code performs a map projection from geographic coordinates on the <cite>World Geodetic System 1984</cite> (<abbr title="World Geodetic System 1984">WGS84</abbr>) datum
-coordinates in the <cite>WGS 84 / UTM zone 33N</cite> coordinate reference system.
-In order to make the example a little bit simpler, this code uses predefined constants given by the <code>CommonCRS</code> convenience class.
-But more advanced applications will typically use <abbr>EPSG</abbr> codes instead.
-Note that all geographic coordinates below express latitude before longitude.
+The notions of inclusion and intersection, however, interpreted slightly differently in these two cases.
+In the usual case where we do not cross the antimeridian, the green rectangle covers a region of inclusion.
+The regions excluded from this rectangle continue on to infinity in all directions.
+In other words, the region of inclusion is not repeated every 360°.
+But in the case of the red rectangle, the information provided by the envelope actually covers a region of exclusion
+between the two edges of the rectangle. The region of inclusion extends to infinity to the left and right.
+We could stipulate that all longitudes below -180° or above 180° are considered excluded,
+but this would be an arbitrary decision that would not be an exact counterpart to the usual case (green rectangle).
+A developer may wish to use these values, for example, in a mosaic where the map of the world is repeated several times
+horizontally and each repetition is considered distinct.
+If developers wish to perform operations as though the regions of inclusion or exclusion were repeated every 360°,
+they themselves will have to bring the longitudinal values between -180° and 180° in advance.
+All the <code class="SIS">add(…)</code>, <code class="SIS">contains(…)</code>,
+<code class="SIS">intersect(…)</code>, etc. functions of all the envelopes defined in the
+<code class="SIS">org.apache.sis.geometry</code> package perform their calculations according to this convention.
 </p>
-
-<pre><b>import</b> org.opengis.geometry.<code class="GeoAPI">DirectPosition</code>;
-<b>import</b> org.opengis.referencing.crs.<code class="GeoAPI">CoordinateReferenceSystem</code>;
-<b>import</b> org.opengis.referencing.operation.<code class="GeoAPI">CoordinateOperation</code>;
-<b>import</b> org.opengis.referencing.operation.<code class="GeoAPI">TransformException</code>;
-<b>import</b> org.opengis.util.<code class="GeoAPI">FactoryException</code>;
-<b>import</b> org.apache.sis.referencing.CRS;
-<b>import</b> org.apache.sis.referencing.CommonCRS;
-<b>import</b> org.apache.sis.geometry.DirectPosition2D;
-
-<b>public</b> <b>class</b> MyApp {
-    <b>public</b> <b>static</b> <b>void</b> main(String[] args) <b>throws</b> <code class="GeoAPI">FactoryException</code>, <code class="GeoAPI">TransformException</code> {
-        <code class="GeoAPI">CoordinateReferenceSystem</code> sourceCRS = CommonCRS.WGS84.geographic();
-        <code class="GeoAPI">CoordinateReferenceSystem</code> targetCRS = CommonCRS.WGS84.UTM(40, 14);  <code class="comment">// Get whatever zone is valid for 14°E.
-</code>        <code class="GeoAPI">CoordinateOperation</code> operation = CRS.findOperation(sourceCRS, targetCRS, <b>null</b>);
-
-        <code class="comment">// The above lines are costly and should be performed only once before to project many points.
-</code>        <code class="comment">// In this example, the operation that we got is valid for coordinates in geographic area from
-</code>        <code class="comment">// 12°E to 18°E (UTM zone 33) and 0°N to 84°N.
-</code>
-        <code class="GeoAPI">DirectPosition</code> ptSrc = <b>new</b> DirectPosition2D(40, 14);           <code class="comment">// 40°N 14°E
-</code>        <code class="GeoAPI">DirectPosition</code> ptDst = operation.getMathTransform().transform(ptSrc, <b>null</b>);
-
-        System.out.println(<i>"Source: "</i> + ptSrc);
-        System.out.println(<i>"Target: "</i> + ptDst);
-    }
-}</pre>
-
-
-<h3 id="TransformDerivative"><span class="section-number">2.3.2.</span> Partial derivatives of coordinate operations</h3>
+<aside>
+<h5>Generalizing to other types of axes</h5>
 <p>
-Previous section shows how to project a coordinate from one reference system to another one.
-There is another, less known, operation which does not compute the projected coordinates of a given point,
-but instead the derivative of the projection function at that point.
-This operation was defined in an older Open Geospatial specification,
-<a href="http://www.opengeospatial.org/standards/ct">OGC 01-009</a>, now considered obsolete but still useful.
-Let <var>P</var> be a map projection converting degrees of latitude and longitude (<var>φ</var>, <var>λ</var>)
-into projected coordinates (<var>x</var>, <var>y</var>) in metres.
-The formula below represents the map projection result as a column matrix
-(reason will become clearer soon):
+This section specifically relates to longitude, as it is the most usual example of a cyclic axis.
+However, in Apache <abbr title="Spatial Information System">SIS</abbr> envelopes, there is no explicit mention of longitude, or of its 360° cycle.
+The characteristics of the range of values of each axis (its extremum, units, type of cycle, etc.)
+are attributes of <code class="GeoAPI">CoordinateSystemAxis</code> objects,
+indirectly associated with envelopes via the coordinate reference system.
+Apache <abbr>SIS</abbr> inspects these attributes to determine the way in which it must perform these operations.
+Thus, any axis associated with the code <code class="GeoAPI">RangeMeaning.WRAPAROUND</code> benefit from
+the same treatment as does longitude.
+For example, this could be a time axis for climatological data (one “year” represents the average temperature in all the
+months of January, followed by the average of all the months of February, etc.)
+This generalization also applies to longitude axes defined by a range of 0° to 360° rather than -180° to 180°.
 </p>
-
-<table class="hidden">
-<tr>
-<th>Equation</th>
-<th>Java code</th>
-</tr>
-<tr>
-<td style="vertical-align:middle; min-width:350px; padding-right:60px">
-<math xmlns="http://www.w3.org/1998/Math/MathML" alttext="MathML capable browser required" display="block">
-<mi>P</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo>
-<mo>=</mo>
-<mfenced close="]" open="[">
-<mtable>
-<mtr><mtd><mi>x</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo></mtd></mtr>
-<mtr><mtd><mi>y</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo></mtd></mtr>
-</mtable>
-</mfenced>
-</math>
-</td>
-<td style="vertical-align:middle; min-width:500px; padding-left:60px">
-
-<pre style="margin:0"><code class="GeoAPI">DirectPosition</code> geographic = <b>new</b> DirectPosition2D(<var>φ</var>, <var>λ</var>);
-<code class="GeoAPI">DirectPosition</code> projected = <var><b>P</b></var>.transform(geographic, <b>null</b>);
-<b>double</b> <var>x</var> = projected.getOrdinate(0);
-<b>double</b> <var>y</var> = projected.getOrdinate(1);</pre>
-
-</td>
-</tr>
-</table>
-
-<p>The map projection partial derivate at this point can be represented by a Jacobian matrix:</p>
-
-<table class="hidden">
-<tr>
-<th>Equation</th>
-<th>Java code</th>
-</tr>
-<tr>
-<td style="vertical-align:middle; min-width:350px; padding-right:60px">
-<math xmlns="http://www.w3.org/1998/Math/MathML" alttext="MathML capable browser required" display="block">
-<msup><mi>P</mi><mo>′</mo></msup><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo>
-<mo>=</mo>
-<msub><mi>JAC</mi><mrow><mi>P</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo></mrow></msub>
-<mo>=</mo>
-<mfenced close="]" open="[">
-<mtable>
-<mtr>
-<mtd><mfrac><mrow><mo>∂</mo><mi>x</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo></mrow><mrow><mo>∂</mo><mi>φ</mi></mrow></mfrac></mtd>
-<mtd><mfrac><mrow><mo>∂</mo><mi>x</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo></mrow><mrow><mo>∂</mo><mi>λ</mi></mrow></mfrac></mtd>
-</mtr>
-<mtr>
-<mtd><mfrac><mrow><mo>∂</mo><mi>y</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo></mrow><mrow><mo>∂</mo><mi>φ</mi></mrow></mfrac></mtd>
-<mtd><mfrac><mrow><mo>∂</mo><mi>y</mi><mo>(</mo><mi>φ</mi><mo>,</mo><mi>λ</mi><mo>)</mo></mrow><mrow><mo>∂</mo><mi>λ</mi></mrow></mfrac></mtd>
-</mtr>
-</mtable>
-</mfenced>
-</math>
-</td>
-<td style="vertical-align:middle; min-width:500px; padding-left:60px">
-
-<pre style="margin:0"><code class="GeoAPI">DirectPosition</code> geographic = <b>new</b> DirectPosition2D(<var>φ</var>, <var>λ</var>);
-<code class="GeoAPI">Matrix</code> jacobian = <var><b>P</b></var>.derivative(geographic);
-<b>double</b> dx_dλ = jacobian.getElement(0,1);
-<b>double</b> dy_dφ = jacobian.getElement(1,0);</pre>
-
-</td>
-</tr>
-</table>
-
+</aside>
 <p>
-Remaining equations in this section will abridge
-∂<var>x</var>(<var>λ</var>, <var>φ</var>) as ∂<var>x</var> and
-∂<var>y</var>(<var>λ</var>, <var>φ</var>) as ∂<var>y</var>,
-but reader should keep in mind that each of those derivative values depends on the (<var>λ</var>, <var>φ</var>) coordinate given at Jacobian matrix calculation time.
-The first matrix column tells us that if we apply a small displacement of ∂<var>φ</var> degrees of latitude from the (<var>φ</var>, <var>λ</var>) position,
-— in other words if we move at the (<var>φ</var> + ∂<var>φ</var>, <var>λ</var>) geographic position —
-then the projected coordinate will be displaced by (∂<var>x</var>, ∂<var>λ</var>) metres
-— in other words it will become (<var>x</var> + ∂<var>x</var>, <var>y</var> + ∂<var>λ</var>).
-Similarly the last matrix column gives us the displacement that happen on the projected coordinate
-if we apply a small displacement of ∂<var>λ</var> degrees of longitude on the source geographic coordinate.
-We can visualize such displacements in a figure like below.
-This figure shows the derivative at two points, <var>P</var><sub>1</sub> and <var>P</var><sub>2</sub>,
-for emphasing that the result change for every points.
-In that figure, vectors <var>U</var> et <var>V</var> stand for the first and second column respectively
-in the Jacobian matrices.
+In order for functions such as <code class="SIS">add(…)</code> to work correctly,
+all objects involved must use the same coordinate reference system, including the same range of values.
+Thus an envelope that expresses longitudes in the range [-180 … +180]° is not compatible with an envelope that expresses
+longitudes in the range [0 … 360]°.
+The conversions, if necessary, are up to the user
+(the <code class="SIS">Envelopes</code> class provides convenience methods to do this).
+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 class="SIS">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.
 </p>
-
-<table class="hidden"><tr>
-<td><img alt="Example of a map projection derivative" src="../images/Derivatives.png" style="border: solid 1px"/></td>
-<td style="padding-left: 30px; vertical-align: middle">
-<p>where vectors are related to the matrix by:</p>
-<math xmlns="http://www.w3.org/1998/Math/MathML" alttext="MathML capable browser required" display="block">
-<mtable><mtr>
-<mtd>
-<mover><mi>U</mi><mo>→</mo></mover><mo>=</mo>
-<mfenced close="]" open="[">
-<mtable>
-<mtr>
-<mtd><mfrac><mrow><mo>∂</mo><mi>x</mi></mrow><mrow><mo>∂</mo><mi>φ</mi></mrow></mfrac></mtd>
-</mtr>
-<mtr>
-<mtd><mfrac><mrow><mo>∂</mo><mi>y</mi></mrow><mrow><mo>∂</mo><mi>φ</mi></mrow></mfrac></mtd>
-</mtr>
-</mtable>
-</mfenced>
-</mtd>
-<mtd><mtext>et</mtext></mtd>
-<mtd>
-<mover><mi>V</mi><mo>→</mo></mover><mo>=</mo>
-<mfenced close="]" open="[">
-<mtable>
-<mtr>
-<mtd><mfrac><mrow><mo>∂</mo><mi>x</mi></mrow><mrow><mo>∂</mo><mi>λ</mi></mrow></mfrac></mtd>
-</mtr>
-<mtr>
-<mtd><mfrac><mrow><mo>∂</mo><mi>y</mi></mrow><mrow><mo>∂</mo><mi>λ</mi></mrow></mfrac></mtd>
-</mtr>
-</mtable>
-</mfenced>
-</mtd>
-</mtr></mtable>
-</math>
-</td>
-</tr></table>
-
+<aside>
+<h5>The special case of [+0 … -0] range</h5>
 <p>
-Above figure shows one usage of map projection derivatives:
-they provide the direction of parallels and meridians at a given location in a map projection.
-One can use that information for determining if axes have been swapped or their direction reversed.
-But the usefulness of map projection derivatives goes further.
+Java (or more generally, IEEE Standard 754) defines two values distinct from zero:
+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 title="Spatial Information System">SIS</abbr> envelopes, they may actually return opposite results for axes using <code class="GeoAPI">RangeMeaning.WRAPAROUND</code>.
+An envelope whose range is [0 … 0], [-0 … -0] or [-0 … +0] would normally be considered an empty envelope,
+but the [+0 … -0] range would in fact be considered to include the entire set of values all around the world.
+This behaviour conforms to the definition of <code class="SIS">lowerCorner</code> and <code class="SIS">upperCorner</code>,
+which considers +0 as the starting point, and -0 as the end-point after cycling through all possible values.
+Such behaviour only occurs for the pair of values +0 and -0, and only in that order.
+For all other real values, if the condition <code>lower</code> <code>==</code> <code>upper</code> is true,
+then it is guaranteed that the envelope is empty.
 </p>
+</aside>
+</section>
+</section>
 
-<h4 id="DerivativeAndEnvelope"><span class="section-number">2.3.2.1.</span> Transform derivatives applied to envelopes</h4>
-<p>
-<span style="color: red">TODO</span>
-</p>
-<table class="hidden">
-<tr>
-<th>Envelope before projection</th>
-<th>Geometric shape after projection</th>
-</tr>
-<tr>
-<td><img alt="Envelope in a geographic CRS" src="../images/GeographicArea.png" style="border: solid 1px; margin-right: 15px"/></td>
-<td><img alt="Shape in a projected CRS" src="../images/ConicArea.png" style="border: solid 1px; margin-left:  15px"/></td>
-</tr>
-</table>
+
+<section>
+<header>
+<h1 id="Referencing"><span class="section-number">5.</span> Spatial reference systems</h1>
+<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Geometry">Previous chapter</a></div><div class="next-chapter"><a href="#Utilities">Next chapter</a> ➡</div></div></nav>
+</header>
+<nav>In this chapter:<ul class="toc">
+<li><a href="#ComponentsOfCRS">Components of a reference system by coordinates</a><ul>
+<li><a href="#Ellipsoid">Geoid et ellipsoid</a></li>
+<li><a href="#GeodeticDatum">Geodetic datum</a></li>
+<li><a href="#CoordinateSystem">Coordinate systems</a><ul>
+<li><a href="#AxisOrder">Axis order</a></li></ul></li>
+<li><a href="#GeographicCRS">Geographic reference systems</a><ul>
+<li><a href="#GeographicWKT">Well-Known Text format</a></li></ul></li>
+<li><a href="#ProjectedCRS">Map projections</a><ul>
+<li><a href="#ProjectedWKT">Well-Known Text format</a></li></ul></li>
+<li><a href="#CompoundCRS">Vertical and temporal dimensions</a><ul>
+<li><a href="#CompoundWKT">Well-Known Text format</a></li></ul></li></ul></li>
+<li><a href="#GetCRS">Fetching a spatial reference system</a><ul>
+<li><a href="#CRSAuthorityFactory">Looking CRS defined by authorities</a></li>
+<li><a href="#CRSParsing">Reading definitions in GML or WKT format</a></li>
+<li><a href="#CRSFactory">Constructing programmatically</a></li>
+<li><a href="#CRS_UserCode">Adding new CRS definitions</a></li></ul></li>
+<li><a href="#CoordinateOperations">Coordinate operations</a><ul>
+<li><a href="#MathTransform">Executing an operation on coordinate values</a></li>
+<li><a href="#TransformDerivative">Partial derivatives of coordinate operations</a><ul>
+<li><a href="#DerivativeAndEnvelope">Transform derivatives applied to envelopes</a></li>
+<li><a href="#DerivativeAndRaster">Transform derivatives applied to rasters</a></li>
+<li><a href="#GetDerivative">Getting the derivative at a point</a></li></ul></li>
+<li><a href="#CoordinateOperationSteps">Conceptual versus real chain of coordinate operations</a></li></ul></li>
+<li><a href="#Formats">Date storage formats</a></li>
+<li><a href="#XML-ISO">Representing objects in XML</a><ul>
+<li><a href="#XML-ISO-19115">Representing metadata according to ISO 19115-3</a><ul>
+<li><a href="#gco-id">Identification of already-defined instances</a></li>
+<li><a href="#nilReason">Representing missing values</a></li></ul></li></ul></li></ul></nav>
 <p>
-<span style="color: red">TODO</span>
+For locating a point on Earth one can use identifiers like city name or postal address
+— an approach known as <cite>spatial reference systems by identifiers</cite> —
+or use numerical values valid in a given coordinate system like latitudes and longitudes
+— an approach known as <cite>spatial reference systems by coordinates</cite>.
+Each reference system implies approximations like
+the choice of a figure of the Earth (geoid, ellipsoid, <i>etc.</i>) used as an approximation of Earth shape,
+the choice of geometric properties (angles, distances, <i>etc.</i>) to be preserved when a map is shown on plane surface, and
+a lost of precision when coordinates are transformed to systems using a different <a href="#GeodeticDatum">datum</a>.
+</p><p>
+A very common misbelief is that one can avoid this complexity by using a single coordinate reference system
+(typically <abbr title="World Geodetic System 1984">WGS84</abbr>) as a universal system for all data.
+The next chapters will explain why the reality is not so simple.
+Whether a universal reference system can suit an application needs or not depends on the desired positional accuracy
+and the kind of calculations to be performed with the data.
+Unless otherwise specified, Apache <abbr title="Spatial Information System">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>
-<table class="hidden"><tr><td>
-<img alt="Cubic approximation of an envelope bounds" src="../images/Approximation.png"/>
-</td><td style="padding-left: 60px">
-Legend:
 <ul>
-<li><b>Blue:</b> the geometric shape of the envelope after projection.
-This is the shape from which to get a new envelope.</li>
-<li><b>Red</b> (with hash): The
-<var>y</var> = <var>C</var>₀ + <var>C</var>₁λ + <var>C</var>₂λ² + <var>C</var>₃λ³ approximation.</li>
-<li><b>Green</b> (dashed line): Position λ<sub>m</sub> of approximation minimum, obtained by resolving
-0 = <var>C</var>₁ + 2<var>C</var>₂λ<sub>m</sub> + 3<var>C</var>₃λ<sub>m</sub>².
-The same cubic line can have two minimums.</li>
+<li>Points should be inside the domain of validity as given by <code class="GeoAPI">ReferenceSystem​.getDomainOfValidity()</code>.</li>
+<li>Distance measurements in a given map projection are true only is some special locations,
+named for instance “standards parallels”.</li>
+<li>Positional accuracy is altered after coordinate transformations.
+The new accuracy is described by <code class="GeoAPI">CoordinateOperation​.getCoordinateOperationAccuracy()</code>.</li>
+<li>Finding the most appropriate coordinate transformation parameters require the use of a geodetic dataset like <abbr>EPSG</abbr>.
+Declaring those parameters within the <abbr title="Coordinate Reference System">CRS</abbr> (for example with a <code class="OGC">TOWGS84</code> element) is often not sufficient.</li>
 </ul>
-</td></tr></table>
-<p>
-<span style="color: red">TODO</span>
-</p>
-
-
-<h4 id="DerivativeAndRaster"><span class="section-number">2.3.2.2.</span> Transform derivatives applied to rasters</h4>
-<p>
-<span style="color: red">TODO</span>
-</p>
-<table class="hidden">
-<tr>
-<th style="text-align: left">Source image</th>
-<th style="text-align: right">Destination image</th>
-</tr>
-<tr>
-<td colspan="2"><img alt="Intersection of derivatives" src="../images/RasterProjection.png"/></td>
-</tr>
-</table>
+<article>
+<header>
+<h2>“Early binding” versus “late binding” implementations</h2>
+</header>
 <p>
-<span style="color: red">TODO</span>
+Because of the <abbr title="World Geodetic System 1984">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 class="GeoAPI">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 class="GeoAPI">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>
-<table class="hidden"><tr>
-<td><img alt="Intersection of derivatives" src="../images/WarpGrid.png"/></td>
-<td style="padding-left: 60px">
-Legend:
 <ul>
-<li><b>Blue dots:</b>  first  iteration (9 points).</li>
-<li><b>Green dots:</b> second iteration (25 points, including 16 news).</li>
-<li><b>Red dots:</b>   third  iteration (81 points, including 56 news).</li>
-</ul>
-Continuing…
-<ul>
-<li>Forth iteration:  289 points, including  208 news.</li>
-<li>Fifth iteration: 1089 points, including  800 news.</li>
-<li>Sixth iteration: 4225 points, including 3136 news.</li>
-<li>…</li>
+<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>
-</td></tr></table>
+<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 title="Coordinate Reference System">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>
-<span style="color: red">TODO</span>
+<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 title="Spatial Information System">SIS</abbr> is a “late binding” implementation,
+while some reminiscences of “early binding” approach still exist in the form of the
+<code class="SIS">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>
-<p style="text-align:center"><img alt="Intersection of derivatives" src="../images/IntersectionOfDerivatives.png" style="border: solid 1px"/></p>
+</article>
 <p>
-<span style="color: red">TODO</span>
+The <code class="SIS">sis-referencing</code> module provides a set of classes implementing
+different specializations of the <code class="GeoAPI">ReferenceSystem</code> interface, together with required components.
+Those implementations store spatial reference system descriptions, together with metadata like their domain of validity.
+However those objects do not perform any operation on coordinate values.
+Coordinates <cite>conversions</cite> or <cite>transformations</cite> are performed by another family of types,
+with <code class="GeoAPI">CoordinateOperation</code> as the root interface.
+Those types will be discussed in <a href="#CoordinateOperation">another section</a>.
 </p>
 
-<h4 id="GetDerivative"><span class="section-number">2.3.2.3.</span> Getting the derivative at a point</h4>
-<p>
-<span style="color: red">TODO</span>
-Example:</p>
 
-<pre><code class="SIS">AbstractMathTransform</code> projection = ...;         <code class="comment">// An Apache SIS map projection.
-</code><b>double</b>[] sourcePoint = {longitude, latitude};   <code class="comment">// The geographic coordinate to project.
-</code><b>double</b>[] targetPoint = <b>new</b> <b>double</b>[2];           <code class="comment">// Where to store the projection result.
-</code><code class="GeoAPI">Matrix</code>   derivative  = projection.<code class="SIS">transform</code>(sourcePoint, 0, targetPoint, 0, <b>true</b>);</pre>
 
-<p>
-<span style="color: red">TODO</span>
-</p>
 
-<pre>@Override
-<b>public</b> <code class="GeoAPI">Matrix</code> derivative(<code class="GeoAPI">DirectPosition</code> p) <b>throws</b> <code class="GeoAPI">TransformException</code> {
-    <code class="GeoAPI">Matrix</code> jac = inverse().derivative(transform(p));
-    <b>return</b> Matrices.inverse(jac);
-}</pre>
 
 
-<h3 id="CoordinateOperationSteps"><span class="section-number">2.3.3.</span> Conceptual versus real chain of coordinate operations</h3>
+<section>
+<header>
+<h2 id="ComponentsOfCRS"><span class="section-number">5.1.</span> Components of a reference system by coordinates</h2>
+</header>
 <p>
-Coordinate operations may include many steps, each with their own set of parameters.
-For example transformations from one datum (e.g. <abbr title="North American Datum 1927">NAD27</abbr>) to another datum (e.g. <abbr title="World Geodetic System 1984">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 title="Coordinate Reference System">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 title="Spatial Information System">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.
+Spatial reference systems by coordinates provide necessary information for mapping numerical coordinate values
+to real-world locations. In Apache <abbr title="Spatial Information System">SIS</abbr>, most information is contained (directly or indirectly) in
+classes with a name ending in <abbr title="Coordinate Reference System">CRS</abbr>, the abbreviation of <i>Coordinate Reference System</i>.
+Those objects contain:
 </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>
+<li>A <i>datum</i>, which specifies among other things which ellipsoid to use as an Earth shape approximation.</li>
+<li>A description for each axis: name, direction, units of measurement, range of values.</li>
+<li>Sometime a list of parameters, especially when using map projections.</li>
 </ul>
-</li>
-</ol>
-</div>
+<p>
+Those systems are described by the <abbr title="International Organization for Standardization">ISO</abbr> 19111 standard (<i>Referencing by Coordinates</i>),
+which replaces for most parts the older <abbr>OGC 01-009</abbr> standard (<i>Coordinate Transformation Services</i>).
+Those standards are completed by two other standards defining exchange formats:
+<abbr>ISO</abbr> 19136 and 19162 respectively for the
+<cite>Geographic Markup Language</cite> (<abbr>GML</abbr>) — a <abbr>XML</abbr> format which is quite detailed but verbose —
+and the <cite>Well-Known Text</cite> (<abbr>WKT</abbr>) — a text format easier to read by humans.
+</p>
+
+<h3 id="Ellipsoid"><span class="section-number">5.1.1.</span> Geoid et ellipsoid</h3>
+<p>
+Since the real topographic surface is difficult to represent mathematically, it is not used directly.
+A slightly more convenient surface is the geoid,
+a surface where the gravitational field has the same value everywhere (an equipotential surface).
+This surface is perpendicular to the direction of a plumb line at all points.
+The geoid surface would be equivalent to the mean sea level if all oceans where at rest,
+without winds or permanent currents like the Gulf Stream.
+</p><p>
+While much smoother than topographic surface, the geoid surface still have hollows and bumps
+caused by the uneven distribution of mass inside Earth.
+For more convenient mathematical operations, the geoid surface is approximated by an ellipsoid.
+This “figure of Earth” is represented in GeoAPI by the <code class="GeoAPI">Ellipsoid</code> interface,
+a fundamental component in coordinate reference systems of kind <code class="GeoAPI">GeographicCRS</code> and <code class="GeoAPI">ProjectedCRS</code>.
+Tenth of ellipsoids are commonly used for datum definitions.
+Some of them provide a very good approximation for a particular geographic area
+at the expense of the rest of the world for which the datum was not designed.
+Other datums are compromises applicable to the whole world.
+</p>
+<div class="example">
+<p><b>Example:</b>
+the <abbr>EPSG</abbr> geodetic dataset defines among others the “<abbr>WGS</abbr> 84”, “Clarke 1866”, “Clarke 1880”,
+“<abbr>GRS</abbr> 1980” and “<abbr>GRS</abbr> 1980 Authalic Sphere” (a sphere of same surface than the <abbr>GRS</abbr> 1980 ellipsoid).
+Ellipsoids may be used in various places of the world or may be defined for a very specific region.
+For example in <abbr>USA</abbr> at the beginning of XX<sup>th</sup> century,
+the Michigan state used an ellipsoid based on the “Clarke 1866” ellipsoid but with axis lengths expanded by 800 feet.
+This modification aimed to take in account the average state height above mean sea level.</p>
 </div>
+
+<h3 id="GeodeticDatum"><span class="section-number">5.1.2.</span> Geodetic datum</h3>
 <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.
+For defining a geodetic system in a country, a national authority selects an ellipsoid matching closely the country surface.
+Differences between that ellipsoid and the geoid’s hollows and bumps are usually less than 100 metres.
+Parameters that relate an <code class="GeoAPI">Ellipsoid</code> to the Earth surface (for example the position of ellipsoid center)

[... 2366 lines stripped ...]


Mime
View raw message