@@ 97,7 +99,7 @@ Partially translated by Christina Hou
1. Standards and norms

+

2. Utility classes and methods

+
2. Spatial reference systems
+

This chapter describes aspects of Apache SIS that apply to the entire library.
Most of these utilities are not specific to spatial information systems.

There are various opinions on how to implement Java standard's Objectâ.equals(Object) method.
According to some, it should be possible to compare different implementations of the same interface or base class.
But to follow this policy, each interface or base class's javadoc must define the algorithms that all implementations
shall use for their equals(Object) and hashCode() methods.
This approach is common in java.util.Collection and its child interfaces.
Transferring this approach to certain GeoAPI interfaces, however, would be a difficult task,
and would probably not be followed in many implementations.
Moreover, it comes at the expense of being able to take into account supplementary attributes in the child interfaces,
unless this possibility has been specified in the parent interface.
This constraint arises from the following points of the equals(Object) and hashCode() method contracts:
+For locating a point on Earth one can use identifiers like city name or postal address
+âÂ an approach known as spatial reference systems by identifiersÂ â
+or use numerical values valid in a given coordinate system like latitudes and longitudes
+âÂ an approach known as spatial reference systems by coordinates.
+Each reference system implies approximations like
+the choice of a figure of the Earth (geoid, ellipsoid, etc.) used as an approximation of Earth shape,
+the choice of geometric properties (angles, distances, etc.) 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 datum.
+
+A very common misbelief is that one can avoid this complexity by using a single coordinate reference system
+(typically WGS84) 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 SIS aims to represent coordinates on Earth with an accuracy of one centimetre or better.
+But the accuracy can be altered by various situations:

A.equals(B) implies B.equals(A) (symmetry);

A.equals(B) and B.equals(C) implies A.equals(C) (transitivity);

A.equals(B) implies A.hashCode() == B.hashCode().
+
Points should be inside the domain of validity as given by ReferenceSystemâ.getDomainOfValidity().
+
Distance measurements in a given map projection are true only is some special locations,
+named for instance âstandards parallelsâ.
+
Positional accuracy is altered after coordinate transformations.
+The new accuracy is described by CoordinateOperationâ.getCoordinateOperationAccuracy().
+
Finding the most appropriate coordinate transformation parameters require the use of a geodetic dataset like EPSG.
+Declaring those parameters within the CRS (for example with a TOWGS84 element) is often not sufficient.
+
+
+
âEarly bindingâ versus âlate bindingâ implementations
+
For example, these three constraints are violated if A (and eventually C) can contain attributes
which B ignores.
To bypass this problem, an alternative approach is to require that the objects compared by the
Objectâ.equals(Object) method be of the same class; in other words, A.getClass() == B.getClass().
This approach is sometimes regarded as contrary to the principles of object oriented programming.
In practice, for relatively complex applications, the important accorded to these principles depends on the context
in which the objects are compared:
if the objects are added to a HashSet or used as keys in a HashMap,
we would need a stricter adherence to the equals(Object) and hashCode() contract.
But if the developer is comparing the objects his or herself, for example to check that the relevant information has been changed,
then the constraints of symmetry, transitivity or coherence with the hash values may be of little interest.
More permissive comparisons may be desirable, sometimes going so far as to tolerate minor discrepancies in numerical values.


In order to allow developers a certain amount of flexibility, many classes in the SIS
library implement the org.apache.sis.util.LenientComparable interface,
which defines a equals(Object, ComparisonMode) method.
The principle modes of comparison are:
+Because of the WGS84 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 A to datum B can be done by first transforming
+from A to WGS84, then from WGS84 to B.
+With such approach, a coordinate transformations library would only need to associate each
+GeodeticDatum instance with the transformation parameters from that datum to WGS84.
+This approach was encouraged in version 1 of WKT format, since that format specified a
+TOWGS84[â¦] element (removed in WKT version 2) precisely for that purpose.
+This approach is known in EPSG guidance notes as âearly bindingâ implementations
+since information about coordinate transformations are associated early in geodetic object definitions,
+usually right at GeographicCRS creation time.
+While EPSG acknowledges that this approach is commonly used,
+this is not a recommended strategy for the following reasons:

STRICTÂ â The objects compared must share the same class and have exactly equal attributes,
including any possible public attributes specific to the implementation.


BY_CONTRACTÂ â The objects compared must implement the same GeoAPI (or other standard)
interface, but need not be of the same implementation class.
Only the attributes defined in the interface are compared;
all other attributes specific to the implementation â even if they are public â are ignored.


IGNORE_METADATAÂ â Like BY_CONTRACT,
but only compares attributes that influence the operations (numeric calculations or otherwise) performed by the object.
For example, in a geodesic datum, the longitude (in relation to Greenwich) of the original meridian
would be taken into account, while the name of the meridian would be ignored.


APPROXIMATIVEÂ â Like IGNORE_METADATA,
but tolerates minor discrepancies in numerical values.

+
More than one transformation may exist from datum A to datum B,
+where each transformation is designed for a different geographic area.
+
Some operations are designed specifically for transformations from A to B
+and do not have the same accuracy than an operation using WGS84 as an intermediate step.
+
WGS84 itself has been updated many times,
+which makes it a kind of moving target (admittedly slowly) for coordinate transformations libraries.
+
Different systems could be used as the pivot system, for example the Galileo Reference Frame
+(GTRF) created for the European GPS competitor.

The default mode, used in all equals(Object) methods in SIS,
is STRICT. This mode is chosen for a safe operation â particularly with HashMapÂ â
without the need to rigorously define equals(Object) and hashCode() operations in every interface.
With this mode, the order of objects (A.equals(B) or B.equals(A)) is unimportant.
It is, however, the only mode that offers this guarantee.
In the expression A.equals(B), the BY_CONTRACT mode
(and so by extension all other modes that depend on it) only compares the properties known to A,
regardless of whether B knows more.





2.2. Internationalization

In an architecture where a program executed on a server provides its data to multiple clients,
the server's locale conventions are not necessarily the same as those of the clients.
Conventions may differ in language, but also in the way they write numeric values
(even between two countries that speak the same language) as well in time zone.
To produce messages that conform to the client's conventions, SIS uses
two approaches, distinguished by their level of granularity: at the level of the messages themselves,
or at the level of the objects that create the messages.
The approach used also determines whether it is possible to share the same instance of an object for all languages.



2.2.1. Distinct character sequences for each locale

Some classes are only designed to function according to one locale convention at a time.
This is of course true for the standard implementations of java.text.Format,
as they are entirely dedicated to the work of internationalization.
But it is also the case for other less obvious classes like javax.imageio.ImageReader/ImageWriter
and for Exception subclasses.
When one of these classes is implemented by SIS,
we identify it by implementing the org.apache.sis.util.Localized interface.
The getLocale() method of this interface can determine the locale conventions
by which the instance produces its message.


Some subclasses of Exception defined by SIS also implement the Localized interface.
For these exceptions, the error message may be produced according to two locale conventions,
for either the administrator or the client respectively:
getMessage() returns the exception message according to the system default conventions,
while getLocalizedMessage() returns the exception message according to the locale conventions specified
by getLocale().
This Locale will be determined by the Localized object that threw the exception.

Example:
Given an environment in which the default language is English and an AngleFormat object is created to
read angles according to French conventions.
If a ParseException is thrown when using this formatter, getMessage() returns the error message in English,
while getLocalizedMessage() returns the error message in French.
+the EPSG geodetic dataset defines about 50 transformations from NAD27 to NAD83.
+In an early binding approach, the same geographic CRS (namely âNAD27â) in the WKT 1
+format would need to be defined with a TOWGS84[8, 160, 176] element for coordinates in USA
+or with a TOWGS84[10, 158, 187] 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 TOWGS84[â¦] element associated to a CRS.
+But even when restricting CRS usage to the domain of validity of its single TOWGS84[â¦] element,
+those transformations are still approximative with a 10 metres accuracy in the USA case.
+More accurate transformations exist in the form of NADCON grid shift files,
+but those transformations are from NAD27 to NAD83 (which move together on the same continental plate),
+not to WGS84 (which move independently).
+The difference was often ignored when NAD83 and WGS84 were considered as practically equivalent,
+but that assumption is subject to more caution today.
The exceptions defined by SIS do not implement all of the Localized interface.
Only those most likely to be shown to the user are localized in this way.
ParseException are good candidates because they often occur due to an incorrect entry by the client.
By contrast, NullPointerException are generally caused by a programming error;
they may be localized in the system default language, but that is usually all.
+EPSG rather recommends the use of âlate bindingâ approach,
+in which coordinate transformation methods and parameters are defined for
+âA to Bâ pairs of systems (eventually completed with domain of validity)
+rather than associated to standalone datums.
+Apache SIS is a âlate bindingâ implementation,
+while some reminiscences of âearly bindingâ approach still exist in the form of the
+DefaultGeodeticDatumâ.getBursaWolfParameters() property.
+The later is used only if SIS fails to apply the late binding approach for given reference systems.
+
The utility class org.apache.sis.util.Exceptions provides convenience methods to get messages
according to the conventions of a given locale, when this information is available.
+The sisreferencing module provides a set of classes implementing
+different specializations of the ReferenceSystem 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 conversions or transformations are performed by another family of types,
+with CoordinateOperation as the root interface.
+Those types will be discussed in another section.

2.2.2. Single instance for all supported locales
+
2.1. Components of a reference system by coordinates
The API conventions defined by SIS or inherited by GeoAPI favour the use of the
InternationalString type when the value of a String type would likely be localized.
This approach allows us to defer the internationalization process to the time when a character sequence is requested,
rather than the time when the object that contains them is created.
This is particularly useful for immutable classes used for creating unique instances independently of locale conventions.
+Spatial reference systems by coordinates provide necessary information for mapping numerical coordinate values
+to realworld locations. In Apache SIS, most information is contained (directly or indirectly) in
+classes with a name ending in CRS, the abbreviation of Coordinate Reference System.
+Those objects contain:

Example:
SIS includes only one instance of the OperationMethod
type representing the Mercator projection, regardless of the client's language.
But its getName() method (indirectly) provides an instance of
InternationalString, so that toString(Locale.ENGLISH) returns Mercator projection
while toString(Locale.FRENCH) returns Projection de Mercator.

+
+
A datum, which specifies among other things which ellipsoid to use as an Earth shape approximation.
+
A description for each axis: name, direction, units of measurement, range of values.
+
Sometime a list of parameters, especially when using map projections.
+
When defining spatial objects independently of locale conventions, we reduce the risk of computational overload.
For example, it is easier to detect that two maps use the same cartographic projection if this last is represented by the
same instance of CoordinateOperation,
even if the projection has a different name depending on the country.
Moreover, certain types of CoordinateOperation may require coordinate transformation matrices,
so sharing a single instance becomes even more preferable in order to reduce memory consumption.
+Those systems are described by the ISO 19111 standard (Referencing by Coordinates),
+which replaces for most parts the older OGC 01009 standard (Coordinate Transformation Services).
+Those standards are completed by two other standards defining exchange formats:
+ISO 19136 and 19162 respectively for the
+Geographic Markup Language (GML) âÂ a XML format which is quite detailed but verboseÂ â
+and the WellKnown Text (WKT) âÂ a text format easier to read by humans.



2.2.3.Locale.ROOT convention

All SIS methods receiving or returning the value of a Locale type accept the Locale.ROOT value.
This value is interpreted as specifying not to localize the text.
The notion of a nonlocalized text is a little false, as it is always necessary to chose a formatting convention.
This convention however, though very close to English, is usually slightly different.
For example:



Identifiers are written as they appear in UML diagrams,
such as blurredImage instead of Blurred image.


Dates are written according to the ISO 8601 format,
which does not correspond to English conventions.


Numbers are written using their toString() methods, rather than using a java.text.NumberFormat.
As a result, there are differences in the number of significant digits,
use of exponential notation and the absence of thousands separators.






2.2.4. Treatment of characters

In Java, sequences of characters use UTF16 encoding.
There is a direct correspondence between the values of the char type and the great majority of characters,
which facilitates the use of sequences so long as these characters are sufficient.
However, certain Unicode characters cannot be represented by a single char.
These supplementary characters include certain ideograms,
but also road and geographical symbols in the 1F680 to 1F700 range.
Support for these supplementary characters requires slightly more complex interactions than the classic case,
where we may assume a direct correspondence.
Thus, instead of the loop on the left below, international applications must generally use the loop on the right:












Loop to Avoid
Recommended loop

for (int i=0; i<string.length(); i++) {
 char c = string.charAt(i);
 if (Character.isWhitespace(c)) {
 // A blank space was found.
 }
}


for (int i=0; i<string.length();) {
 int c = string.codePointAt(i);
 if (Character.isWhitespace(c)) {
 // A blank space was found.
 }
 i += Character.charCount(c);
}



SIS supports supplementary characters by using the loop on the right where necessary,
but the loop on the left is occasionally used when it is known that the characters searched for are not supplementary characters,
even if some may be present in the sequence in which we are searching.





2.2.4.1. Blank spaces interpretation

Standard Java provides two methods for determining whether a character is a blank space:
Characterâ.isWhitespace(â¦) and Characterâ.isSpaceChar(â¦).
These two methods differ in their interpretations of nonbreaking spaces, tabs and line breaks.
The first method conforms to the interpretation currently used in languages such as Java, C/C++ and XML,
which considers tabs and line breaks to be blank spaces, while nonbreaking spaces are read as not blank.
The second method â which conforms strictly to the Unicode definition â makes the opposite interpretation.


SIS uses each of these methods in different contexts.
isWhitespace(â¦) is used to separate the elements of a list (numbers, dates, words, etc.),
while isSpaceChar(â¦) is used to ignore blank spaces inside a single element.


Example:
Take a list of numbers represented according to French conventions.
Each number may contain nonbreaking spaces as thousands separators,
while the different numbers in the list may be separated by ordinary spaces, tabs or line breaks.
When analyzing a number, we want to consider the nonbreaking spaces as being part of the number,
whereas a tab or a line break most likely indicates a separation between this number and the next.
We would thus use isSpaceChar(â¦).
Conversely, when separating the numbers in the list, we want to consider tabs and line breaks as separators,
but not nonbreaking spaces.
We would thus use isWhitespace(â¦).
The role of ordinary spaces, to which either case might apply, should be decided beforehand.


In practice, this distinction is reflected in the use of isSpaceChar(â¦) in the implementations of java.text.Format,
or the use of isWhitespace(â¦) in nearly all the rest of the SIS library.





3. Spatial reference systems




For locating a point on Earth one can use identifiers like city name or postal address
âÂ an approach known as spatial reference systems by identifiersÂ â
or use numerical values valid in a given coordinate system
âÂ an approach known as spatial reference systems by coordinates.
Each system implies approximations as:



Choice of a figure of the Earth (geoid, ellipsoid, etc.) used as an approximation of Earth shape.

Choice of geometric properties (angles, distances, etc.) to be preserved when a map is shown on plane surface.

Lost of precision when a coordinates is transformed from one referencing system to another system.


Unless otherwise specified, Apache SIS aims to represent coordinates on Earth with an accuracy of one centimetre or better.
But the accuracy can be altered by various situations:



Points should be inside the domain of validity as given by ReferenceSystemâ.getDomainOfValidity().

Distance measurements in a given map projection are true only is some special locations,
named for instance âstandards parallelsâ.

Positional accuracy is reduced after coordinate transformations. The new accuracy is described by
CoordinateOperationâ.getCoordinateOperationAccuracy().


The sisreferencing module provides a set of classes implementing
different specializations of the ReferenceSystem 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.
Those operations are performed by another family of types, with CoordinateOperation as the root interface.
Those types will be discussed in another section,
but we mention here two subtypes related to the coordinate accuracy topic:




Coordinate conversions are fully determined by mathematic formulas.
Those conversions would have an infinite precision if it was not for the unavoidable rounding errors
inherent to floatingpoint calculations.

Example: map projections.


Coordinate transformations are defined empirically.
They usually have a few meters error which is not caused by limitation in computer accuracy.
Those errors exist because transformations are only approximations of a more complex reality.


Example: datum changes from
North American Datum 1927 (NAD27) to
North American Datum 1983 (NAD83),
even if the map projection method (e.g. Lambert Conformal or Transverse Mercator) does not change.







3.1. Components of a reference system by coordinates

Spatial reference systems by coordinates provide necessary information for mapping numerical coordinate values
to realworld locations. In Apache SIS, most information is contained (directly or indirectly) in
classes with a name ending in CRS, the abbreviation of Coordinate Reference System.
Those objects contain:



A datum, which specifies among other things which ellipsoid to use as an Earth shape approximation.

A description for each axis: name, direction, units of measurement, range of values.

Sometime a list of parameters. A wellknown example is when the CRS uses a map projection.


Those systems are described by the ISO 19111 standard (Referencing by Coordinates),
which replaces for most parts the older OGC 01009 standard (Coordinate Transformation Services).
Those standards are completed by two other standards defining exchange formats:
ISO 19136 and 19162 respectively for the
Geographic Markup Language (GML) âÂ a XML format which is quite detailed but verboseÂ â
and the WellKnown Text (WKT) âÂ a text format easier to read by humans.



3.1.1. Geoid et ellipsoid
+
2.1.1. Geoid et ellipsoid
Since the real topographic surface is difficult to represent mathematically, it is not used directly.
A slightly more convenient surface is the geoid,
@@ 1480,13 +1251,17 @@ Some of them provide a very good approxi
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.

Example:
At the beginning of XX^{th} century in USA, the Michigan state used an ellipsoid based on the
âClarke 1866â ellipsoid but with axis lengths expanded by 800 feet.
+
+
Example:
+the EPSG geodetic dataset defines among others the âWGS 84â, âClarke 1866â, âClarke 1880â,
+âGRS 1980â and âGRS 1980 Authalic Sphereâ (a sphere of same surface than the GRS 1980 ellipsoid).
+Ellipsoids may be used in various places of the world or may be defined for a very specific region.
+For example in USA at the beginning of XX^{th} 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.
The WGS84 ubiquity tends to reduce the need for Transformation operations with recent data,
but does not eliminate it.
@@ 1528,67 +1302,11 @@ Furthermore many borders were legally de
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.



âEarly bindingâ versus âlate bindingâ implementations


Because of the WGS84 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 A to datum B can be done by first transforming
from A to WGS84, then from WGS84 to B.
With such approach, a coordinate transformations library would only need to associate each
GeodeticDatum instance with the transformation parameters from that datum to WGS84.
This approach was encouraged in version 1 of WKT format, since that format specified a
TOWGS84[â¦] element (removed in WKT version 2) precisely for that purpose.
This approach is known in EPSG guidance notes as âearly bindingâ implementations
since information about coordinate transformations are associated early in geodetic object definitions,
usually right at GeographicCRS creation time.
While EPSG acknowledges that this approach is commonly used,
this is not a recommended strategy for the following reasons:



More than one transformation may exist from datum A to datum B,
where each transformation is designed for a different geographic area.

Some operations are designed specifically for transformations from A to B
and do not have the same accuracy than an operation using WGS84 as an intermediate step.

WGS84 itself has been updated many times,
which makes it a kind of moving target (admittedly slowly) for coordinate transformations libraries.

Different systems could be used as the pivot system, for example the Galileo Reference Frame
(GTRF) created for the European GPS competitor.


Example:
the EPSG geodetic dataset defines about 50 transformations from NAD27 to NAD83.
In an early binding approach, the same geographic CRS (namely âNAD27â) in the WKT 1
format would need to be defined with a TOWGS84[8, 160, 176] element for coordinates in USA
or with a TOWGS84[10, 158, 187] 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 TOWGS84[â¦] element associated to a CRS.
But even when restricting CRS usage to the domain of validity of its single TOWGS84[â¦] element,
those transformations are still approximative with a 10 metres accuracy in the USA case.
More accurate transformations exist in the form of NADCON grid shift files,
but those transformations are from NAD27 to NAD83 (which move together on the same continental plate),
not to WGS84 (which move independently).
The difference was often ignored when NAD83 and WGS84 were considered as practically equivalent,
but that assumption is subject to more caution today.


EPSG rather recommends the use of âlate bindingâ approach,
in which coordinate transformation methods and parameters are defined for
âA to Bâ pairs of systems (eventually completed with domain of validity)
rather than associated to standalone datums.
Apache SIS is a âlate bindingâ implementation,
while some reminiscences of âearly bindingâ approach still exist in the form of the
DefaultGeodeticDatumâ.getBursaWolfParameters() property.
The later is used only if SIS fails to apply the late binding approach for given reference systems.



3.1.3. Coordinate systems
+
2.1.3. Coordinate systems
TODO

3.1.3.1. Axis order
+
2.1.3.1. Axis order
The axis order is specified by the authority (typically a national agency) defining the Coordinate Reference System (CRS).
The order depends on the CRS type and the country defining the CRS.
@@ 1631,13 +1349,13 @@ To avoid ambiguities, users are encourag
The WKT format will be presented in more details in the next sections.

3.1.4. Geographic reference systems
+
2.1.4. Geographic reference systems
TODO

3.1.4.1.WellKnown Text format
+
2.1.4.1.WellKnown Text format
TODO

3.1.5. Map projections
+
2.1.5. Map projections
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.
@@ 1647,35 +1365,35 @@ while countries elongated along the Nort
TODO

3.1.5.1.WellKnown Text format
+
2.1.5.1.WellKnown Text format
TODO

3.1.6. Vertical and temporal dimensions
+
2.1.6. Vertical and temporal dimensions
TODO

3.1.6.1.WellKnown Text format
+
2.1.6.1.WellKnown Text format
TODO

3.2. Fetching a spatial reference system
+
2.2. Fetching a spatial reference system
TODO

3.2.1. Looking CRS defined by authorities
+
2.2.1. Looking CRS defined by authorities
TODO

3.2.2. Reading definitions in GML or WKT format
+
2.2.2. Reading definitions in GML or WKT format
TODO

3.2.3. Constructing programmatically
+
2.2.3. Constructing programmatically
TODO

3.2.4. Adding new CRS definitions
+
2.2.4. Adding new CRS definitions
TODO

3.3. Coordinate operations
+
2.3. Coordinate operations
Given a source coordinate reference system (CRS) in which existing coordinate values are expressed,
and a target coordinate reference system in which coordinate values are desired,
@@ 1712,21 +1430,45 @@ Among the information provided by The domain of validity, either as a textual description (e.g. âCanada â onshore and offshoreâ)
or with the coordinates of a geographic bounding box.
The positional accuracy, which may be anything from 1 centimetre to a few kilometres.

The coordinate operation subtype. If the coordinate operation is an instance of Transformation,
then it may be one among many possibilities depending on the area of interest, and its accuracy is limited by
âreal worldâ constraints (not only rounding errors).
If the coordinate operation is rather an instance of Conversion, then it does not have those limitations.
+
The coordinate operation subtype. Among them, two subtypes provide the same functionalities but with a significant conceptual difference:
+
+
+Coordinate conversions are fully determined by mathematical formulas.
+Those conversions would have an infinite precision if it was not for the unavoidable rounding errors
+inherent to floatingpoint calculations.
+Map projections are in this category.
+
+Coordinate transformations 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 NAD27 to NAD83
+are in this category.
+
+
+
The actual mathematical work is performed by an object obtained by a call to cop.getMathTransform().
The CoordinateOperation and MathTransform types are separated because the later is a kind of âblack boxâ,
which may be implemented in a very different way than what the coordinate operation said.
+If the coordinate operation is an instance of Transformation,
+then the instance selected by SIS 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 Conversion.
+Consequently verifying the domain of validity and the positional accuracy declared in the transformation metadata is of particular importance.
+
+
+
2.3.1. Executing an operation on coordinate values
+
+The CoordinateOperation object introduced in above section provides highlevel informations
+(source and target CRS, domain of validity, positional accuracy, operation parameters, etc).
+The actual mathematical work is performed by a separated object obtained by a call to CoordinateOperationâ.getMathTransform().
+At the difference of CoordinateOperation instances, MathTransform instances do not carry any metadata.
+They are kind of black box which know nothing about the source and target CRS
+(actually the same MathTransform can be used for different pairs of CRS if the mathematical work is the same), domain or accuracy.
+Furthermore MathTransform may be implemented in a very different way than what CoordinateOperation 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, etc.)
are implemented by MathTransform as affine transforms and concatenated for efficiency.
+are implemented by MathTransform as affine transforms and concatenated for efficiency,
+even if CoordinateOperation reports them as a chain of Mercator and other operations.
+The âconceptual versus real chain of coordinate operationsâ section explains the differences in more details.


3.3.1. Executing an operation on coordinate values
The following Java code performs a map projection from geographic coordinates on the World Geodetic System 1984 (WGS84) datum
coordinates in the WGS 84 / UTM zone 33N coordinate reference system.
@@ 1763,45 +1505,99 @@ Note that all geographic coordinates bel
}

3.3.2. Partial derivatives of coordinate operations
+
2.3.2. Partial derivatives of coordinate operations
TODO
+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,
+OGC 01009, now considered obsolete but still useful.
+Let P be a map projection converting degrees of latitude and longitude (Ï,Â Î»)
+into projected coordinates (x,Â y) in metres.
+The formula below represents the map projection result as a column matrix
+(reason will become clearer soon):
TODO
+Remaining equations in this section will abridge
+âx(Î»,Â Ï) as âx and
+ây(Î»,Â Ï) as ây,
+but reader should keep in mind that each of those derivative values depends on the (Î»,Â Ï) coordinate given at Jacobian matrix calculation time.
+The first matrix column tells us that if we apply a small displacement of âÏ degrees of latitude from the (Ï,Â Î») position,
+âÂ in other words if we move at the (ÏÂ +Â âÏ, Î») geographic positionÂ â
+then the projected coordinate will be displaced by (âx, âÎ») metres
+âÂ in other words it will become (xÂ +Â âx, yÂ +Â âÎ»).
+Similarly the last matrix column gives us the displacement that happen on the projected coordinate
+if we apply a small displacement of âÎ» 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, P_{1} and P_{2},
+for emphasing that the result change for every points.
+In that figure, vectors U et V stand for the first and second column respectively
+in the Jacobian matrices.
@@ 1815,10 +1611,10 @@ Note that all geographic coordinates bel
âxâÎ»
+âxâÏ
âyâÎ»
+âyâÏ
@@ 1829,10 +1625,10 @@ Note that all geographic coordinates bel
âxâÏ
+âxâÎ»
âyâÏ
+âyâÎ»
@@ 1846,7 +1642,7 @@ Note that all geographic coordinates bel
TODO

3.3.2.1. Transform derivatives applied to envelopes
+
2.3.2.1. Transform derivatives applied to envelopes
TODO
@@ 1882,7 +1678,7 @@ The same cubic line can have two minimum

2.3.3. Conceptual versus real chain of coordinate operations
+
+Coordinate operations may include many steps, each with their own set of parameters.
+For example transformations from one datum (e.g. NAD27) to another datum (e.g. WGS84)
+can be approximated by an affine transform (translation, rotation and scale) applied on the geocentric coordinates.
+This implies that the coordinates must be converted from geographic to geocentric domain before the affine transform,
+then back to geographic domain after the affine transform.
+The result is a threesteps process illustrated in the âConceptual chain of operationsâ column of the example below.
+However because that operation chain is very common, the EPSG geodetic dataset provides a shortcut
+named âGeocentric translation in geographic domainâ.
+Using this operation, the conversion steps between geographic and geocentric CRS are implicit.
+Consequently the datum shifts as specified by EPSG appears as if it was a single operation,
+but this is not the real operation executed by Apache SIS.
+
+
+
Example:
+transformation of geographic coordinates from NAD27 to WGS84 in Canada
+can be approximated by the EPSG:1172 coordinate operation.
+This single EPSG operation is actually a chain of three operations in which two steps are implicit.
+The operation as specified by EPSG 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 SIS 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 (latitude, longitude) coordinates in degrees.
+
+
+
+Operation specified by EPSG:
+
+
Geocentric translation in geographic domain
+
+
Xaxis translation = 10 m
+
Yaxis translation = 158 m
+
Zaxis translation = 187 m
+
+
+
+Conversions between geographic and geocentric domains are implicit.
+The semimajor and semiminor axis lengths required for those conversions
+are inferred from the source and target datum.
+
+
+Conceptual chain of operations:
+
+
Geographic to geocentric conversion
+
+
Source semimajor = 6378206.4 m
+
Source semiminor = 6356583.8 m
+
+
Geocentric translation
+
+
Xaxis translation = 10 m
+
Yaxis translation = 158 m
+
Zaxis translation = 187 m
+
+
Geocentric to geographic conversion
+
+
Target semimajor = 6378137.0 m
+
Target semiminor â 6356752.3 m
+
+
+
+Axis order and units are implicitly defined by the source and target CRS.
+It is implementation responsibility to perform any needed unit conversions and/or axis swapping.
+
+
+Operations actually performed by Apache SIS:
+
+
Affine parametric conversion
+
+
Scale factors (Î» and Ï) = 0
+
Shear factors (Î» and Ï) = Ï/180
+
+
Ellipsoid (radians domain) to centric conversion
+
+
Eccentricity â 0.08227
+
+
Affine parametric transformation
+
+
Scale factors (X, Y and Z) â 1.00001088
+
Xaxis translation â 1.568â E6
+
Yaxis translation â 24.772â E6
+
Zaxis translation â 29.319â E6
+
+
Centric to ellipsoid (radians domain) conversion
+
+
Eccentricity â 0.08182
+
+
Affine parametric conversion
+
+
Scale factors (Î» and Ï) = 0
+
Shear factors (Î» and Ï) = 180/Ï
+
+
+
+
+
+
+The operation chain actually performed by Apache SIS 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 SIS steps work on righthanded coordinate systems
+(as opposed to the lefthanded coordinate system when latitude is before longitude),
+with angular units in radians (instead than degrees) and
+linear units relative to an ellipsoid of semimajor 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 SIS uses affine parametric conversions for this purpose,
+which allow to combine axes swapping and unit conversions in a single step
+(see affine transform for more information).
+The reason why Apache SIS splits conceptual operations in such finegrained 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 geocentric to ellipsoid conversion)
+immediately followed by a conversion from degrees to radians (e.g. before a map projection).
+Another example is the Affine parametric transformation step above,
+which combines both the geocentric translation step
+and a scale factor implied by the ellipsoid change.
+
+
+
+All those operation chains can be viewed in Well Known Text (WKT) or pseudoWKT format.
+The simplest operation chain, as specified by the authority, is given directly by the
+String representation of the CoordinateOperation instance.
+This WKT 2 representation contains not only a description of operations with their parameter values,
+but also additional information about the context in which the operation applies (the source and target CRS)
+together with some metadata like the accuracy and domain of validity.
+Some operation steps and parameters may be omitted if they can be inferred from the context.
+
+
+
+
+
Example:
+the WKT 2 representation on the right is for the same coordinate operation than the one used in previous example.
+This representation can be obtained by a call to System.outâ.println(cop)
+where cop is a CoordinateOperation instance.
+Some characteristics of this representation are:
+
+
+
The SourceCRS and TargetCRS elements determine axis order and units.
+For this reason, axis swapping and unit conversions do not need to be represented in this WKT.
+
The âGeocentric translation in geographic domainâ operation implies conversions between geographic and geocentric coordinate reference systems.
+Ellipsoid semiaxis lengths are inferred from above SourceCRS and TargetCRS elements,
+so they do not need to be specified in this WKT.
+
The operation accuracy (20 metres) is much greater than the numerical floatingpoint precision.
+This kind of metadata could hardly be guessed from the mathematical function alone.
+
+
+
+
CoordinateOperation["NAD27 to WGS 84 (3)",
+ SourceCRS[full CRS definition required here but omitted for brevity],
+ TargetCRS[full CRS definition required here but omitted for brevity],
+ Method["Geocentric translations (geog2D domain)"],
+ Parameter["Xaxis translation", 10.0, Unit["metre", 1]],
+ Parameter["Yaxis translation", 158.0, Unit["metre", 1]],
+ Parameter["Zaxis translation", 187.0, Unit["metre", 1]],
+ OperationAccuracy[20.0],
+ Area["Canada  onshore and offshore"],
+ BBox[40.04, 141.01, 86.46, 47.74],
+ Id["EPSG", 1172, "8.9"]]
+
+
+
+
+An operation chain closer to what Apache SIS really performs is given by the
+String representation of the MathTransform instance.
+In this WKT 1 representation, contextual information and metadata are lost;
+a MathTransform is like a mathematical function with no knowledge about the meaning of the coordinates on which it operates.
+Since contextual information are lost, implicit operations and parameters become explicit.
+This representation is useful for debugging since any axis swapping operation (for example) become visible.
+Apache SIS constructs this representation from the data structure in memory,
+but convert them in a more convenient form for human, for example by converting radians to degrees.
+
+
+
+
+
Example:
+the WKT 1 representation on the right is for the same coordinate operation than the one used in previous example.
+This representation can be obtained by a call to System.outâ.println(copâ.getMathTransform())
+where cop is a CoordinateOperation instance.
+Some characteristics of this representation are:
+
+
+
Since there is not anymore (on intend) any information about source and target CRS,
+axis swapping (if needed) and unit conversions must be performed explicitly.
+This is the task of the first and last affine operations in this WKT.
+
The âGeocentric translationâ operation is not anymore applied in the geographic domain, but in the geocentric domain.
+Consequently conversions between geographic and geocentric coordinate reference systems must be made explicit.
+Those explicit steps are also necessary for specifying the ellipsoid semiaxis lengths,
+since they can not anymore by inferred for source and target CRS.
+
Conversions between geographic and geocentric coordinates are threedimensional.
+Consequently operations for increasing and reducing the number of dimensions are inserted.
+By default the ellipsoidal height before conversion is set to zero.
+Finally, the raw operation chain can be view by a call to AbstractMathTransformâ.toString(Convention.INTERNAL).
+This pseudoWKT representation shows exactly what Apache SIS does,
+but is rarely used because difficult to read.
+It may occasionally be useful for advanced debugging.
+
+
+
+
+
3. Geometries

5. Data coverages

+
4. Data coverages
+
@@ 2199,8 +2219,369 @@ as well as other information such as
+
5. Utility classes and methods
+
+
+
+
+This chapter describes aspects of Apache SIS that apply to the entire library.
+Most of these utilities are not specific to spatial information systems.
+
+
+
5.1. Comparison modes of objects
+
+There are various opinions on how to implement Java standardâs Objectâ.equals(Object) method.
+According to some, it should be possible to compare different implementations of the same interface or base class.
+But to follow this policy, each interface or base classâs javadoc must define the algorithms that all implementations
+shall use for their equals(Object) and hashCode() methods.
+This approach is common in java.util.Collection and its child interfaces.
+Transferring this approach to certain GeoAPI interfaces, however, would be a difficult task,
+and would probably not be followed in many implementations.
+Moreover, it comes at the expense of being able to take into account supplementary attributes in the child interfaces,
+unless this possibility has been specified in the parent interface.
+This constraint arises from the following points of the equals(Object) and hashCode() method contracts:
+
+
+
A.equals(B) implies B.equals(A) (symmetry);
+
A.equals(B) and B.equals(C) implies A.equals(C) (transitivity);
+
A.equals(B) implies A.hashCode() == B.hashCode().
+
+
+For example, these three constraints are violated if A (and eventually C) can contain attributes
+which B ignores.
+To bypass this problem, an alternative approach is to require that the objects compared by the
+Objectâ.equals(Object) method be of the same class; in other words, A.getClass() == B.getClass().
+This approach is sometimes regarded as contrary to the principles of object oriented programming.
+In practice, for relatively complex applications, the important accorded to these principles depends on the context
+in which the objects are compared:
+if the objects are added to a HashSet or used as keys in a HashMap,
+we would need a stricter adherence to the equals(Object) and hashCode() contract.
+But if the developer is comparing the objects his or herself, for example to check that the relevant information has been changed,
+then the constraints of symmetry, transitivity or coherence with the hash values may be of little interest.
+More permissive comparisons may be desirable, sometimes going so far as to tolerate minor discrepancies in numerical values.
+
+
+In order to allow developers a certain amount of flexibility, many classes in the SIS
+library implement the org.apache.sis.util.LenientComparable interface,
+which defines a equals(Object, ComparisonMode) method.
+The principle modes of comparison are:
+
+
+
+STRICTÂ â The objects compared must share the same class and have exactly equal attributes,
+including any possible public attributes specific to the implementation.
+
+
+BY_CONTRACTÂ â The objects compared must implement the same GeoAPI (or other standard)
+interface, but need not be of the same implementation class.
+Only the attributes defined in the interface are compared;
+all other attributes specific to the implementation â even if they are public â are ignored.
+
+
+IGNORE_METADATAÂ â Like BY_CONTRACT,
+but only compares attributes that influence the operations (numeric calculations or otherwise) performed by the object.
+For example, in a geodesic datum, the longitude (in relation to Greenwich) of the original meridian
+would be taken into account, while the name of the meridian would be ignored.
+
+
+APPROXIMATIVEÂ â Like IGNORE_METADATA,
+but tolerates minor discrepancies in numerical values.
+
+
+
+The default mode, used in all equals(Object) methods in SIS,
+is STRICT. This mode is chosen for a safe operation â particularly with HashMapÂ â
+without the need to rigorously define equals(Object) and hashCode() operations in every interface.
+With this mode, the order of objects (A.equals(B) or B.equals(A)) is unimportant.
+It is, however, the only mode that offers this guarantee.
+In the expression A.equals(B), the BY_CONTRACT mode
+(and so by extension all other modes that depend on it) only compares the properties known to A,
+regardless of whether B knows more.
+
+
+
+
+
5.2. Object converters
+
+There is sometime a need to convert instances from a source Java type to a target Java type
+while those types are unknown at compile time.
+Various projects (Apache Common Convert, Spring, etc.)
+have created their own interface for performing object conversions between types known only at runtime.
+Details vary, but such interfaces typically look like below:
+
+
interface ObjectConverter<S,T> { // Some projects use only "Converter" as interface name.
+ T apply(S object); // Another method name commonly found in other projects is "convert".
+}
+
+Like other projects, Apache SIS also defines its own ObjectConverter interface.
+The main difference between SIS converter interface and the interfaces found in other projects
+is that SIS converters provide some information about their mathematical properties.
+An Apache SIS converter can have zero, one or many of the following properties:
+
+
+
Injective
+
A function is injective if no pair of S values can produce the same T value.
+
Example:
+the Integer â String conversion performed by Integerâ.toString()
+is an injective function because if two Integer values are not equal,
+then it is guaranteed that their conversions will result in different String values.
+However the String â Integer conversion performed by Integerâ.valueOf(String)
+is not an injective function
+because many distinct String values can be converted to the same Integer value.
+For example converting the "42", "+42" and "0042" character strings all result in the same 42 integer value.
+
+
+
+
Surjective
+
A function is surjective if each values of T can be created from at least one value of S.
+
Example:
+the String â Integer conversion performed by Integerâ.valueOf(String)
+is a surjective function because every Integer value can be created from at least one String value.
+However the Integer â String conversion performed by Integerâ.toString()
+is not a surjective function because it can not produce all possible String values.
+For example there is no way to produce the "ABC" value with the Integerâ.toString() method.
+