sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1753715 - /sis/site/trunk/content/faq.mdtext
Date Thu, 21 Jul 2016 17:28:35 GMT
Author: desruisseaux
Date: Thu Jul 21 17:28:35 2016
New Revision: 1753715

URL: http://svn.apache.org/viewvc?rev=1753715&view=rev
Log:
Edition to the FAQ.

Modified:
    sis/site/trunk/content/faq.mdtext

Modified: sis/site/trunk/content/faq.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/faq.mdtext?rev=1753715&r1=1753714&r2=1753715&view=diff
==============================================================================
--- sis/site/trunk/content/faq.mdtext (original)
+++ sis/site/trunk/content/faq.mdtext Thu Jul 21 17:28:35 2016
@@ -32,7 +32,7 @@ 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_.
-In order to make the example a little bit simpler, this code uses predefined systems given
by the `CommonCRS` convenience class.
+In order to make the example a little bit simpler, this code uses predefined constants given
by the `CommonCRS` convenience class.
 But more advanced applications will typically use EPSG codes instead.
 Note that all geographic coordinates below express latitude *before* longitude.
 
@@ -70,53 +70,54 @@ Note that all geographic coordinates bel
 
 The operation _methods_ (including, but not limited to, map projections) supported by Apache
SIS
 are listed in the [Coordinate Operation Methods](tables/CoordinateOperationMethods.html)
page.
-The amount of map projection _methods_ is relatively small,
+The amount of map projection methods is relatively small,
 but the amount of _projected CRS_ that we can build from them can be very large.
-For example with only three methods (namely _Cylindrical Mercator_, _Transverse Mercator_
and _Lambert Conic Conformal_)
+For example with only three family of methods (_Cylindrical Mercator_, _Transverse Mercator_
and _Lambert Conic Conformal_)
 used with different parameter values, we can cover thousands of projected CRS listed in the
EPSG geodetic dataset.
 
-For convenience, some pre-defined combinations of operation methods with parameter values
are assigned a code.
-A well-known source of codes is the EPSG geodetic dataset, but other authorities also exist.
-The predefined CRS known to Apache SIS is listed in the
+In order to use a map projection method, we need to know the value to assign to the projection
parameters.
+For convenience, thousands of projected CRS with pre-defined parameter values are are assigned
a unique identifier.
+A well-known source of such definitions is the EPSG geodetic dataset, but other authorities
also exist.
+The predefined CRS known to Apache SIS are listed in the
 [Coordinate Reference Systems](tables/CoordinateReferenceSystems.html) page.
 
 
 
 ### What is the axis order issue and how is it addressed?    {#axisOrder}
 
-The axis order is specified by the authority (typically a national agency) defining the _Coordinate
Reference System_ (CRS).
+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 pilots for centuries.
-However software developers tend to consistently use the (_x_,_y_) order for every kind of
CRS.
+However software developers tend to consistently use the (_x_, _y_) order for every kind
of CRS.
 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.
 
+For any CRS identified by an EPSG code, the official axis order can be checked on the
+official EPSG registry at [http://www.epsg-registry.org](http://www.epsg-registry.org)
+(not to be confused with other sites having "epsg" in their name,
+but actually unrelated to the organization in charge of EPSG definitions):
+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"_.
+
 Recent OGC standards mandate the use of axis order as defined by the authority.
-Oldest OGC standards used the (_x_,_y_) axis order instead, ignoring any authority specification.
+Oldest OGC standards used the (_x_, _y_) axis order instead, ignoring any authority specification.
 Among the legacy OGC standards that used the non-conform axis order,
 an influent one is version 1 of the _Well Known Text_ (WKT) format specification.
 According that widely-used format, WKT definitions without explicit `AXIS[…]` elements
-shall default to (_longitude_, _latitude_) or (_x_,_y_) axis order.
-In version 2 of WKT format, `AXIS[…]` elements are no longer optional
+shall default to (_longitude_, _latitude_) or (_x_, _y_) axis order.
+In version 2 of the WKT format, `AXIS[…]` elements are no longer optional
 and should contain an explicit `ORDER[…]` sub-element for making the intended order
yet more obvious.
 
-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 (_x_,_y_) order after CRS creation.
+Many softwares still use the old (_x_, _y_) axis order, sometime because it is easier to
implement.
+But Apache SIS rather defaults to axis order _as defined by the authority_ (except when parsing
a WKT 1 definition),
+but allows changing axis order to the (_x_, _y_) order after CRS creation.
 This change can be done with the following code:
 
     :::java
     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 [http://www.epsg-registry.org](http://www.epsg-registry.org)
-(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.
-Then click on the _"View"_ link on the right side,
-and click on the _"+"_ symbol of the left side of _"Axes"_.
-
 
 
 
@@ -125,7 +126,7 @@ 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.
+If the UTM zone is unknown, an easy way is to invoke the `UTM(…)` method on one of the
`CommonCRS` pre-defined constants.
 That method receives in argument a geographic coordinate in (_latitude_, _longitude_) order
and computes the UTM zone from it.
 See the [above Java code example](#transform-point).
 
@@ -144,32 +145,27 @@ Note that the above list is incomplete.
 Once the EPSG code of the UTM projection has been determined, the CRS can be obtained as
in the example below:
 
     :::java
-    int code = 32600 + zone;
+    int code = 32600 + zone;    // For WGS84 northern hemisphere
     CoordinateReferenceSystem crs = CRS.forCode("EPSG:" + code);
 
-If no EPSG code is available for the desired projection, a more powerful (but also more difficult)
-way is to instantiate directly a `MathTransform` using the parameters documented in the
-[Coordinate Operation Methods](tables/CoordinateOperationMethods.html#9807) page,
-then build a `DefaultProjectedCRS` instance using it.
-
 
 
 ### 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")`.
+Since version 6.15 of 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
Mercator".
+The EPSG:3857 definition uses a map projection method named _"Popular Visualisation Pseudo
Mercator"_.
 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 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)"
counterpart,
-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.
+this can be done with explicit declarations of `"semi_major"` and `"semi_minor"` parameter
values in the WKT definition.
+Those parameter values are usually inferred from the datum, but Apache SIS allows explicit
declarations to override the inferred values.
 
 
 
@@ -186,17 +182,20 @@ listed in the [Coordinate Operation Meth
 The _identifier_ of a Coordinate Reference System (CRS) object can be obtained by the `getIdentifiers()`
method,
 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)
element,
+and the WKT ends with an `AUTHORITY["EPSG", "xxxx"]` (WKT version 1) or `ID["EPSG", xxxx]`
(WKT version 2) element,
 then the identifier (an EPSG numerical code in this example) is the _xxxx_ value in that
element.
 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.
+then the identifier is the _xxxx_ code given to that method.
 If the CRS has been created in another way, then the collection returned by the `getIdentifiers()`
method
 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
WKT
 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:
+If this is not possible, then the `org.​apache.​sis.​referencing.​IdentifiedObjects`
class contains some convenience methods which may help.
+In the following example, the call to `lookupEPSG(…)` will scan the EPSG database for
a CRS equals
+(ignoring metadata) to the given one. *Note that this scan is sensitive to axis order.*
+Most geographic CRS in the EPSG database are declared with (_latitude_, _longitude_) axis
order.
+Consequently if the given CRS has (_longitude_, _latitude_) axis order, then the scan is
likely to find no match.
 
     :::java
     CoordinateReferenceSystem myCRS = …;
@@ -205,26 +204,21 @@ some convenience methods which may help.
         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
one.
-*Note that this scan is sensitive to axis order.*
-Most geographic CRS in the EPSG database are declared with (_latitude_, _longitude_) axis
order.
-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.
+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:
+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.
+That example may scan the EPSG database for finding the information if it was not explicitely
provided in the given CRS.
 
     :::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}
@@ -235,7 +229,7 @@ since it never query the database. But i
 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)
+But it may fail if there is slight mismatch (for example rounding errors in projection parameters)
 between the supplied CRS and the CRS found in the database.
 
 
@@ -244,7 +238,7 @@ between the supplied CRS and the CRS fou
 
 Two Coordinate Reference Systems may not be considered equal if they are associated to different
metadata
 (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,
Object)`.
+In order to test if two CRS are functionally equivalent, use `Utilities.equalsIgnoreMetadata(myFirstCRS,
mySecondCRS)`.
 
 
 
@@ -264,16 +258,16 @@ Coordinate transformations    {#transfor
 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.
+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:
+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:
+In the example below, the Coordinate Reference System clearly uses (_latitude_, _longitude_)
axis order:
 
     :::text
     GeodeticCRS["WGS 84",
@@ -307,17 +301,15 @@ One subtle issue is the angular units of
 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:
+This problem can be identified by WKT inspection as in the following extract:
 
     :::text
     PROJCS["Lambert II étendu",
-      GEOGCS["Nouvelle Triangulation Française",
-        …,
+      GEOGCS["Nouvelle Triangulation Française", …,
         PRIMEM["Paris", 2.337229167],
         UNIT["grad", 0.01570796326794897]]
       PROJECTION["Lambert_Conformal_Conic_1SP"],
-      PARAMETER["latitude_of_origin", 46.8],
-      …]
+      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"]`
declaration.
@@ -329,7 +321,7 @@ In order to get the intended result, the
     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 `org.apache.sis.io.wkt`
package.
+    `Convention.​WKT1_COMMON_UNITS` enumeration value to `WKTFormat` in the `org.​apache.​sis.​io.​wkt`
package.
 
 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.
@@ -345,9 +337,9 @@ When transforming coordinates between tw
 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.
+The Bursa-Wolf method is one of them, not the only one. However it is one of the most frequently
used methods.
+The Bursa-Wolf parameters can be specified inside a `TOWGS84` element with version 1 of Well
Known Text (WKT) format,
+or in a `BOUNDCRS` element with version 2 of WKT format.
 If the CRS are parsed from a WKT string, make sure that the string contains the appropriate
element.
 
 
@@ -355,9 +347,9 @@ If the CRS are parsed from a WKT string,
 
 ### I get slightly different results depending on the environment I’m running in.  
 {#slightDifferences}
 
-The results of coordinates converted when running in a web application container (JBoss,
_etc._)
-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**,
+The results of coordinate transformations when running in a web application container (JBoss,
_etc._)
+may be a few meters off compared to coordinates transformations in an IDE (NetBeans, Eclipse,
_etc._).
+The results depend on whether 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
parameters
 (the `TOWGS84` element in version 1 of Well Known Text format).
@@ -365,7 +357,7 @@ In such case, the coordinate operation s
 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).
+the same JDBC driver than the one available in 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.
 
@@ -374,9 +366,9 @@ Make sure that the [connection parameter
 ### 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.
+For 3D CRS having any kind of height different than ellipsoidal 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.
+or produce `NaN` or infinity values if the coordinate to transform is far from the domain
of validity.
 
 
 



Mime
View raw message