sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1753710 - /sis/site/trunk/content/faq.mdtext
Date Thu, 21 Jul 2016 16:24:40 GMT
Author: desruisseaux
Date: Thu Jul 21 16:24:40 2016
New Revision: 1753710

Ported more FAQ from Geotk.


Modified: sis/site/trunk/content/faq.mdtext
--- sis/site/trunk/content/faq.mdtext (original)
+++ sis/site/trunk/content/faq.mdtext Thu Jul 21 16:24:40 2016
@@ -26,6 +26,9 @@ This page lists some Frequently Asked Qu
 Referencing    {#referencing}
+Getting started    {#referencing-intro}
 ### How do I transform a coordinate?    {#transform-point}
 The following Java code projects a geographic coordinate from the _World Geodetic System
1984_ (WGS84) to _WGS 84 / UTM zone 33N_.
@@ -43,7 +46,7 @@ Note that all geographic coordinates bel
     import org.apache.sis.referencing.CommonCRS;
     import org.apache.sis.geometry.DirectPosition2D;
-    public final class Test {
+    public class MyApp {
         public static void main(String[] args) throws FactoryException, TransformException
             CoordinateReferenceSystem sourceCRS = CommonCRS.WGS84.geographic();
             CoordinateReferenceSystem targetCRS = CommonCRS.WGS84.UTM(40, 14);  // Get whatever
zone is valid for 14°E.
@@ -83,7 +86,7 @@ The predefined CRS known to Apache SIS i
 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.
-In the case of geographic CRS, the (_latitude_, _longitude_) axis order is widely used by
geographers and pilotes for centuries.
+In the case of geographic CRS, the (_latitude_, _longitude_) axis order is widely used by
geographers and pilots for centuries.
 However software developers tend to consistently use the (_x_,_y_) order for every kind of
 Those different practices resulted in contradictory definitions of axis order for almost
every CRS of kind `GeographicCRS`,
 for some `ProjectedCRS` in the South hemisphere (South Africa, Australia, _etc._) and for
some polar projections among others.
@@ -99,23 +102,27 @@ and should contain an explicit `ORDER[â
 Many softwares still use the old (_x_,_y_) axis order, because it is easier to implement.
 Apache SIS defaults to axis order _as defined by the authority_ (except when parsing a WKT
1 definition),
-but allows to change axis order to (<var>x</var>,<var>y</var>) order
after CRS creation.
+but allows to change axis order to (_x_,_y_) order after CRS creation.
 This change can be done with the following code:
-    CoordinateReferenceSystem crs = …;   // CRS obtained by any mean.
+    CoordinateReferenceSystem crs = …;             // CRS obtained by any means.
     crs = AbstractCRS.castOrCopy(crs).forConvention(AxesConvention.RIGHT_HANDED)
 For any CRS identified by an EPSG code, the official axis order can be checked on the
 official EPSG registry at [](
 (not to be confused with other sites having "epsg" in their name,
 but actually unrelated to the organization in charge of EPSG definition and maintenance):
-Click on the _"Retrieve by code"_ link and enter the numerical code.
+click on the _"Retrieve by code"_ link and enter the numerical code.
 Then click on the _"View"_ link on the right side,
 and click on the _"+"_ symbol of the left side of _"Axes"_.
+Coordinate Reference Systems    {#crs}
 ### How do I instantiate a Universal Transverse Mercator (UTM) projection?    {#UTM}
 If the UTM zone is unknown, an easy way is to use the `UTM` method in one of the `CommonCRS`
pre-defined constants.
@@ -125,12 +132,12 @@ See the [above Java code example](#trans
 If the UTM zone is know, one way is to use the "EPSG" or "AUTO" authority factory.
 The EPSG code of some UTM projections can be determined as below, where _zone_ is a number
from 1 to 60 inclusive (unless otherwise specified):
-    * WGS 84 (northern hemisphere): 32600 + _zone_
-    * WGS 84 (southern hemisphere): 32700 + _zone_
-    * WGS 72 (northern hemisphere): 32200 + _zone_
-    * WGS 72 (southern hemisphere): 32300 + _zone_
-    * NAD 83 (northern hemisphere): 26900 + _zone_ (zone 1 to 23 only)
-    * NAD 27 (northern hemisphere): 26700 + _zone_ (zone 1 to 22 only)
+  * WGS 84 (northern hemisphere): 32600 + _zone_
+  * WGS 84 (southern hemisphere): 32700 + _zone_
+  * WGS 72 (northern hemisphere): 32200 + _zone_
+  * WGS 72 (southern hemisphere): 32300 + _zone_
+  * NAD 83 (northern hemisphere): 26900 + _zone_ (zone 1 to 23 only)
+  * NAD 27 (northern hemisphere): 26700 + _zone_ (zone 1 to 22 only)
 Note that the above list is incomplete. See the EPSG database for additional UTM definitions
 (WGS 72BE, SIRGAS 2000, SIRGAS 1995, SAD 69, ETRS 89, _etc._, most of them defined only for
a few zones).
@@ -147,6 +154,232 @@ then build a `DefaultProjectedCRS` insta
+### How do I instantiate a Google projection?    {#google}
+The Google projection is a Mercator projection that pretends to be defined on the WGS84 datum,
+but actually ignores the ellipsoidal nature of that datum and uses the simpler spherical
formulas instead.
+Since version 6.15 of the EPSG geodetic dataset, the preferred way to get that projection
is to invoke `CRS.forCode("EPSG:3857")`.
+Note that the use of that projection is **not** recommended, unless needed for compatibility
with other data.
+The EPSG:3857 definition uses a map projection method named "Popular Visualisation Pseudo
+The EPSG geodetic dataset provides also some other map projections that use spherical formulas
despite the ellipsoidal nature of the ellipsoid.
+Those methods have "(Spherical)" in their name, for example "Mercator (Spherical)"
+(which differs from "Popular Visualisation Pseudo Mercator" by the use of a more appropriate
sphere radius).
+Those projection methods can be used in Well Known Text (WKT) definitions.
+If there is a need to use spherical formulas with a projection that does not have a "(Spherical)"
+this can be done with explicit declarations of "semi_major" and "semi_minor" parameter values
in the WKT definition.
+Those parameters are usually inferred from the datum, but Apache SIS allows explicit declarations
to override the inferred values.
+### How can I identify the projection kind of a CRS?    {#projectionKind}
+The "kind of projection" (Mercator, Lambert Conformal, _etc._) is called _Operation Method_
in ISO 19111 terminology.
+One approach is to check the value of `OperationMethod.getName()` and compare them against
the OGC or EPSG names
+listed in the [Coordinate Operation Methods](tables/CoordinateOperationMethods.html) page.
+### How do I get the EPSG code of an existing CRS?    {#lookupEPSG}
+The _identifier_ of a Coordinate Reference System (CRS) object can be obtained by the `getIdentifiers()`
+which usually return a collection of zero or one element.
+If the CRS has been created from a Well Known Text (WKT) parsing
+and the WKT ends with an `AUTHORITY["EPSG", "xxxx"]` (WKT 1) or `ID["EPSG", xxxx]` (WKT 2)
+then the identifier (an EPSG numerical code in this example) is the _xxxx_ value in that
+If the CRS has been created from the EPSG geodetic dataset (for example by a call to `CRS.forCode("EPSG:xxxx")`),
+then the identifier is that _xxxx_ code.
+If the CRS has been created in another way, then the collection returned by the `getIdentifiers()`
+may or may not be empty depending if the program that created the CRS took the responsibility
of providing identifiers.
+If the collection of identifiers is empty, the most effective fix is to make sure that the
+contains an `AUTHORITY` or `ID` element (assuming that the CRS was parsed from a WKT).
+If this is not possible, then the `org.apache.sis.referencing.IdentifiedObjects` class contains
+some convenience methods which may help. Example:
+    :::java
+    CoordinateReferenceSystem myCRS = …;
+    Integer identifier = IdentifiedObjects.lookupEPSG(myCRS);
+    if (identifier != null) {
+        System.out.println("The EPSG code has been found: " + identifier);
+    }
+The above call will scan the EPSG database for a CRS equals (ignoring metadata) to the given
+*Note that this scan is sensitive to axis order.*
+Most geographic CRS in the EPSG database are declared with (_latitude_, _longitude_) axis
+Consequently if the given CRS has (_longitude_, _latitude_) axis order, then the scan is
likely to find no match.
+### How do I get the "urn:ogc:def:crs:…" URN of an existing CRS?    {#lookupURN}
+OGC defines URN for CRS identifiers, for example "urn:ogc:def:crs:epsg:7.1:4326" where "7.1"
is the version of the EPSG database used.
+URN may or may not be present in the set of identifiers returned by `crs.getIdentifiers()`.
+In many cases (especially if the CRS was parsed from a Well Known Text), only simple identifiers
like "EPSG:4326" are provided.
+An easy way to build the full URN is to use the code below:
+    :::java
+    CoordinateReferenceSystem myCRS = …;
+    String urn = IdentifiedObjects.lookupURN(myCRS);
+The above call may scan the EPSG database for finding the information if it was not explicitely
provided in the given CRS.
+### Can I rely on IdentifiedObjects.lookupEPSG(…) to work correctly as the inverse of
CRS.forCode(…)?   {#lookupReliability}
+For CRS created from the EPSG geodetic dataset, usually yes.
+Note however that `IdentifiedObjects.getIdentifier(…)` is cheaper and insensitive to
the details of CRS definition,
+since it never query the database. But it works only if the CRS declares explicitly its code,
+which is the case for CRS created from the EPSG database or parsed from a Well Known Text
(WKT) having an `AUTHORITY` or `ID` element.
+The `lookupEPSG(…)` method on the other hand is robust to erroneous code declaration,
+since it always compares the CRS with the database content.
+But it fails if there is slight mismatch (for example rounding errors in projection parameters)
+between the supplied CRS and the CRS found in the database.
+### How can I determine if two CRS are "functionally" equal?    {#equalsIgnoreMetadata}
+Two Coordinate Reference Systems may not be considered equal if they are associated to different
+(name, identifiers, scope, domain of validity, remarks), even though they represent the same
logical CRS.
+In order to test if two CRS are functionally equivalent, use `Utilities.equalsIgnoreMetadata(Object,
+### Are CRS objects safe for use as keys in HashMap?    {#crsHashCode}
+Yes, every classes defined in the ``, `cs` and `datum` packages
+define properly their `equals(Object)` and `hashCode()` methods.
+The Apache SIS library itself uses CRS objects in `HashMap`-like containers for caching purpose.
+Coordinate transformations    {#transforms}
+### My transformed coordinates are totally wrong!    {#axisOrderInTransforms}
+This is most frequently caused by ordinate values given in the wrong order.
+Developers tend to assume a (_x_, _y_) or (_longitude_, _latitude_) axis order.
+But geographers and pilots are using (_latitude_, _longitude_) axis order for centuries,
+and the EPSG geodetic dataset defines geographic coordinate reference systems that way.
+If a coordinate transformation seems to produce totally wrong values,
+the first thing to do should be to print the source and target coordinate reference systems:
+    :::java
+    System.out.println(sourceCRS);
+    System.out.println(targetCRS);
+Attention should be paid to the order of `AXIS` elements.
+In the example below, the coordinate reference system clearly uses (_latitude_, _longitude_)
axis order:
+    :::text
+    GeodeticCRS["WGS 84",
+      Datum["World Geodetic System 1984",
+        Ellipsoid["WGS 84", 6378137.0, 298.257223563]],
+      CS[ellipsoidal, 2],
+        Axis["Geodetic latitude (Lat)", north],
+        Axis["Geodetic longitude (Lon)", east],
+        Unit["degree", 0.017453292519943295]]
+If (_longitude_, _latitude_) axis order is really wanted, Apache SIS can be forced to that
order [as described above](#axisOrder).
+### I have correct axis order but my transformed coordinates are still wrong.   {#projectionName}
+Make sure that the right projection is used. Some projection names are confusing.
+For example _"Oblique Mercator"_ and _"Hotine Oblique Mercator"_ (in EPSG naming) are two
different projections.
+But _"Oblique Mercator"_ (not Hotine) in EPSG naming is also called _"Hotine Oblique Mercator
Azimuth Center"_ by ESRI,
+while _"Hotine Oblique Mercator"_ (EPSG naming) is called _"Hotine Oblique Mercator Azimuth
Natural Origin"_ by ESRI.
+The _"Oblique Stereographic"_ projection (EPSG name) is called _"Double Stereographic"_ by
+ESRI also defines a _"Stereographic"_ projection, which is actually an oblique projection
like the former but using different formulas.
+### I just used the WKT of a well-known authority and my transformed coordinates are still
wrong!    {#parameterUnits}
+The Well Known Text (WKT) specification has been interpreted in different ways by different
+One subtle issue is the angular units of prime meridian and projection parameter values.
+The WKT 1 specification clary states: _"If the `PRIMEM` clause occurs inside a `GEOGCS`,
+then the longitude units will match those of the geographic coordinate system"_ (source:
OGC 01-009).
+However ESRI and GDAL among others unconditionally use decimal degrees, ignoring this part
of the WKT specification.
+This problem can be identified by WKT inspection as in the following example:
+    :::text
+    PROJCS["Lambert II étendu",
+      GEOGCS["Nouvelle Triangulation Française",
+        …,
+        PRIMEM["Paris", 2.337229167],
+        UNIT["grad", 0.01570796326794897]]
+      PROJECTION["Lambert_Conformal_Conic_1SP"],
+      PARAMETER["latitude_of_origin", 46.8],
+      …]
+The Paris prime meridian is located at approximatively 2.597 gradians from Greenwich, which
is 2.337 degrees.
+From this fact, we can see that the above WKT uses decimal degrees despite its `UNIT["grad"]`
+This mismatch applies also to the parameter value, which declare 46.8° in the above example
while the official value is 52 gradians.
+By default, Apache SIS interprets those angular values as gradians when parsing such WKT,
resulting in a large error.
+In order to get the intended result, there is a choice:
+  * Replace `UNIT["grad", 0.01570796326794897]` by `UNIT["degree", 0.017453292519943295]`,
+    which ensure that Apache SIS, GDAL and ESRI understand that WKT in the same way.
+  * Or ask explicitely Apache SIS to parse the WKT using the ESRI or GDAL conventions, by
specifying the
+    `Convention.WKT1_COMMON_UNITS` enumeration value to `WKTFormat` in the ``
+Note that the GeoPackage standard explicitely requires OGC 01-009 compliant WKT
+and the new WKT 2 standard also follows the OGC 01-009 interpretation.
+The default Apache SIS behavior is consistent with those two standards.
+### I verified all the above and still have an error of about one kilometer.    {#BursaWolf}
+Coordinate Reference Systems (CRS) approximate the Earth’s shape by an ellipsoid.
+Different ellipsoids (actually different _datum_) are used in different countries of the
world and at different time in history.
+When transforming coordinates between two CRS using the same datum, no Bursa-Wolf parameters
are needed.
+But when the transformation involves a change of datum, the referencing module needs some
information about how to perform that datum shift.
+There is many way to specify how to perform a datum shift, and most of them are only approximation.
+The Bursa-Wolf method is one of them, not the only one. However it is one of the most frequently
used method.
+The Bursa-Wolf parameters can specified inside a `TOWGS84` element in version 1 of Well Known
Text (WKT) format,
+or in a `BOUNDCRS` element in version 2 of WKT format.
+If the CRS are parsed from a WKT string, make sure that the string contains the appropriate
+### I get slightly different results depending on the environment I’m running in.  
+The results of coordinates converted when running in a web application container (JBoss,
+may be a few meters off compared to coordinates converted in an IDE (NetBeans, Eclipse, _etc._).
+The results depend on whatever an EPSG factory is available on the classpath, **regardless
how the CRS were created**,
+because the EPSG factory specifies explicitly the coordinate operation to apply for some
pairs of CRS.
+In such case, the coordinate operation specified by EPSG has precedence over the Burwa-Wolf
+(the `TOWGS84` element in version 1 of Well Known Text format).
+A connection to the EPSG database may have been established for one environment
+(typically the JEE one) and not the other (typically the IDE one) because only the former
has JDBC driver.
+The recommended way to uniformize the results is to add in the second environment (IDE)
+the same JDBC driver than the first environment (JEE).
+It should be one of the following: JavaDB (a.k.a. Derby), HSQL or PostgreSQL.
+Make sure that the [connection parameters to the EPSG database](epsg.html) are also the same.
+### Can I always expect a transform from an arbitrary CRS to WGS84 to succeed?    {#toWGS84}
+For 2D horizontal CRS created from the EPSG database, calls to `CRS.findOperation(…)`
should generally succeed.
+For 3D CRS having any kind of height different than ellipsoid height, or for a 2D CRS of
type `EngineeringCRS`, it may fail.
+Note however that even if the call to `CRS.findOperation(…)` succeed, the call to `MathTransform.transform(…)`
may fail
+or produce `NaN` or infinity values if the coordinate to transform is far from the projection
area of validity.
 Metadata    {#metadata}

View raw message