Author: desruisseaux
Date: Tue May 24 01:11:38 2016
New Revision: 1745294
URL: http://svn.apache.org/viewvc?rev=1745294&view=rev
Log:
Add instructions in "command-line" page about coordinate transformations.
Added:
sis/site/trunk/content/examples/coordinates/
sis/site/trunk/content/examples/coordinates/AmericanCities.csv (with
props)
sis/site/trunk/content/examples/coordinates/CanadianCities.csv (with
props)
sis/site/trunk/content/examples/crs/
sis/site/trunk/content/examples/crs/EquivalentDefinition.wkt
- copied unchanged from r1745293,
sis/site/trunk/content/examples/EquivalentDefinition.wkt
sis/site/trunk/content/examples/crs/MissingIdentifier.wkt
- copied unchanged from r1745293,
sis/site/trunk/content/examples/MissingIdentifier.wkt
sis/site/trunk/content/examples/crs/WrongAxisOrder.wkt
- copied unchanged from r1745293,
sis/site/trunk/content/examples/WrongAxisOrder.wkt
Removed:
sis/site/trunk/content/examples/EquivalentDefinition.wkt
sis/site/trunk/content/examples/MissingIdentifier.wkt
sis/site/trunk/content/examples/WrongAxisOrder.wkt
Modified:
sis/site/trunk/content/command-line.mdtext
sis/site/trunk/content/index.mdtext
Modified: sis/site/trunk/content/command-line.mdtext
URL:
http://svn.apache.org/viewvc/sis/site/trunk/content/command-line.mdtext?rev=1745294&r1=1745293&r2=1745294&view=diff
==============================================================================
--- sis/site/trunk/content/command-line.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/command-line.mdtext [UTF-8] Tue May 24 01:11:38 2016
@@ -16,7 +16,13 @@ Notice: Licensed to the Apache Software
specific language governing permissions and limitations
under the License.
-A command-line interface is provided for extracting information from data
files or authority codes.
+A command-line interface is provided for extracting information from data
files or authority codes,
+and for performing coordinate operations.
+That command-line tool is provided for allowing users to experiment some
Apache SIS functionalities
+without writing Java code.
+For each example, key Java methods are listed for allowing users to reproduce
the functionality
+in their own application.
+
[TOC]
@@ -84,22 +90,25 @@ Available commands are:
<tr><td><code>metadata</code></td> <td>Show metadata information for the
given file.</td></tr>
<tr><td><code>crs</code></td> <td>Show Coordinate Reference System
(CRS) information for the given file or code.</td></tr>
<tr><td><code>identifier</code></td> <td>Show identifiers for metadata and
referencing systems in the given file.</td></tr>
+ <tr><td><code>transform</code></td> <td>Convert or transform coordinates
from given source CRS to target CRS.</td></tr>
</table>
-The set of legal options and the expected number of file arguments depends on
the command being executed.
+The set of legal options and the expected number of file arguments depend on
the command being executed.
However all commands support the `--help` option, which lists the options
available for that command.
Available options will be from the following list:
<table>
- <tr><td><code>--format</code></td> <td>The output format:
<code>xml</code>, <code>wkt</code>, <code>wkt1</code> or
<code>text</code>.</td></tr>
- <tr><td><code>--locale</code></td> <td>The locale to use for the command
output.</td></tr>
- <tr><td><code>--timezone</code></td> <td>The timezone for the dates to be
formatted.</td></tr>
- <tr><td><code>--encoding</code></td> <td>The encoding to use for the command
output.</td></tr>
- <tr><td><code>--colors</code></td> <td>Whether colorized output shall be
enabled.</td></tr>
- <tr><td><code>--brief</code></td> <td>Whether the output should contains
only brief information.</td></tr>
- <tr><td><code>--verbose</code></td> <td>Whether the output should contains
more detailed information.</td></tr>
- <tr><td><code>--debug</code></td> <td>Prints full stack trace in case of
failure.</td></tr>
- <tr><td><code>--help</code></td> <td>Lists the options available for a
specific command.</td></tr>
+ <tr><td><code>--sourceCRS</code></td> <td>The Coordinate Reference System of
input data.</td></tr>
+ <tr><td><code>--targetCRS</code></td> <td>The Coordinate Reference System of
output data.</td></tr>
+ <tr><td><code>--format</code></td> <td>The output format:
<code>xml</code>, <code>wkt</code>, <code>wkt1</code> or
<code>text</code>.</td></tr>
+ <tr><td><code>--locale</code></td> <td>The locale to use for the command
output.</td></tr>
+ <tr><td><code>--timezone</code></td> <td>The timezone for the dates to be
formatted.</td></tr>
+ <tr><td><code>--encoding</code></td> <td>The encoding to use for the
command output.</td></tr>
+ <tr><td><code>--colors</code></td> <td>Whether colorized output shall be
enabled.</td></tr>
+ <tr><td><code>--brief</code></td> <td>Whether the output should contains
only brief information.</td></tr>
+ <tr><td><code>--verbose</code></td> <td>Whether the output should contains
more detailed information.</td></tr>
+ <tr><td><code>--debug</code></td> <td>Prints full stack trace in case of
failure.</td></tr>
+ <tr><td><code>--help</code></td> <td>Lists the options available for a
specific command.</td></tr>
</table>
The `--locale`, `--timezone` and `--encoding` options apply to the command
output sent to the standard output stream,
@@ -111,14 +120,24 @@ The reason is that command output may be
Examples {#examples}
=======================
-Extracting ISO 19111 Coordinate Reference System (CRS) {#crs}
-----------------------------------------------------------------
+The following examples first show how to get a Coordinate Reference System
(CRS) from different kinds of definitions.
+CRS contain necessary information for locating points on Earth.
+Those information include the geodetic datum, the map projection (if any), the
axes and their units of measurement.
+When two such CRS are known (the _source_ and the _target_), it is possible to
convert or transform points between those CRS.
+However the coordinate operation depends not only on the source and target
CRS, but also on the _area of interest_ as shown
+by the example transforming city coordinates in USA and in Canada.
+Then another example show how to get a wider set of metadata, with the CRS as
only one specific element of those metadata.
+
+
+
+Getting ISO 19111 Coordinate Reference Systems (CRS) {#crs}
+--------------------------------------------------------------
-SIS can read Coordinate Reference System (CRS) definitions from various
sources:
+Apache SIS can read Coordinate Reference System (CRS) definitions from various
sources:
- * Code from the EPSG geodetic dataset
- * _Well Known Text_ (WKT) format version 1 and 2
- * _Geographic Markup Language_ (GML) version 3.2
+ * Codes from the EPSG geodetic dataset
+ * Texts in _Well Known Text_ (WKT) format version 1 and 2
+ * XML files conform to _Geographic Markup Language_ (GML) schema version 3.2
The easiest way to see a CRS definition is to use an EPSG code.
The [EPSG geodetic dataset](http://www.epsg.org/) is a widely-used source of
definitions for thousands of Coordinate Reference Systems.
@@ -160,7 +179,7 @@ documented in [download](downloads.html#
The above output is compatible with version 2 of _Well Known Text_ (WKT)
format.
However some applications are restricted to WKT version 1.
-For an output using the legacy WKT 1 format, one can add the `--format wkt1`
option to the above command.
+For an output using the legacy WKT 1 format, one can add the `--format wkt1`
option to the above command-line.
The “WKT 2” specification allows some flexibility in keyword names and in the
way to specify units of measurement.
By default, the command-line uses this flexibility for producing less verbose
but still legal WKT 2 output.
@@ -171,19 +190,29 @@ Apache SIS can also read and write CRS d
For GML output, one can add the `--format xml` option to the above command.
The result will be much more verbose than WKT outputs.
+Java methods for accessing functionalities shown in above examples are:
+
+ * Convenience static methods in `org.apache.sis.referencing` package:
+ + `CRS.forCode(String)`
+ + `CRS.fromWKT(String)`
+ + `CRS.fromXML(String)`
+ * Classes in other packages (less convenient but give more control):
+ + `org.apache.sis.io.wkt.WKTFormat` — control WKT version, syntax
highlighting, _etc._
+ + `org.apache.sis.xml.MarshallerPool` — control GML version, link
resolutions, _etc._
-Extracting EPSG identifier from a Coordinate Reference System {#identifier}
-------------------------------------------------------------------------------
+
+Getting a verified EPSG identifier from a Coordinate Reference System
{#identifier}
+--------------------------------------------------------------------------------------
Because the EPSG geodetic dataset is so commonly used,
a very common practice is to specify a CRS using only its EPSG code instead
than its full definition.
Such codes can be written in different ways. For example all the following
strings are for the same code:
- * `EPSG:4326`
- * `urn:ogc:def:crs:EPSG::4326`
- * `http://www.opengis.net/def/crs/epsg/0/4326` (not yet supported on the
command-line)
- * `http://www.opengis.net/gml/srs/epsg.xml#4326` (not yet supported on
the command-line)
+ * `"EPSG:4326"`
+ * `"urn:ogc:def:crs:EPSG::4326"`
+ * `"http://www.opengis.net/def/crs/epsg/0/4326"` (not yet supported on the
command-line)
+ * `"http://www.opengis.net/gml/srs/epsg.xml#4326"` (not yet supported on
the command-line)
In a _Well Known Text_ (WKT) string, the code can appear at the bottom of the
definition
in an optional element like `ID["EPSG", 4326]` or `AUTHORITY["EPSG", "4326"]`.
@@ -196,23 +225,23 @@ Furthermore, the _“NTF (Paris) / Lambe
Executing the following command:
:::bash
- sis identifier http://sis.staging.apache.org/examples/MissingIdentifier.wkt
+ sis identifier http://sis.apache.org/examples/crs/MissingIdentifier.wkt
produces an output like below:
:::text
urn:ogc:def:crs:EPSG:8.9:27572 | NTF (Paris) / Lambert zone II
-As we can see, SIS has been able to find back the identifier code and the
actual CRS name.
+As we can see, Apache SIS has been able to find back the identifier code and
the actual CRS name.
Sometime a WKT declares wrongly an EPSG code.
The most frequent case is a WKT that defines a Coordinate Reference System
with (_longitude_, _latitude_) axes,
but declare an EPSG code for a CRS with (_latitude_, _longitude_) axes.
-Apache SIS can detect such mismatch.
+Apache SIS can detect such mismatches.
For example executing the following command:
:::bash
- sis identifier http://sis.staging.apache.org/examples/WrongAxisOrder.wkt
+ sis identifier http://sis.apache.org/examples/crs/WrongAxisOrder.wkt
produces an output like below:
@@ -246,7 +275,7 @@ However in this example, we will provide
Executing the following command:
:::bash
- sis identifier
http://sis.staging.apache.org/examples/EquivalentDefinition.wkt
+ sis identifier http://sis.apache.org/examples/crs/EquivalentDefinition.wkt
produces an output like below:
@@ -258,6 +287,87 @@ _“Mercator (variant A)”_ projection
_“Mercator (variant B)”_ projection with a _“Latitude of 1st standard
parallel”_ parameter value of 41° on the same datum.
This recognition allowed SIS to return the EPSG:3994 code even if it stands
for a CRS defined as a _“Mercator (variant B)”_ projection rather than variant
A.
+Java methods for accessing functionalities shown in above example are:
+
+ * Convenience static method in `org.apache.sis.referencing` package:
+ + `IdentifiedObjects.lookupURN(IdentifiedObject, Citation)`
+ * Class in other package (less convenient but give more control):
+ + `org.apache.sis.referencing.factory.IdentifiedObjectFinder`
+
+
+
+Performing coordinate conversions or transformations {#coordinateOperation}
+------------------------------------------------------------------------------
+
+Coordinates represented in a given CRS can be transformed into coordinates
represented in another CRS.
+The coordinate transformations depend mostly on the _source_ and _target_ CRS,
but the _area of interest_
+can also have an influence; while optional, that area should be specified when
it is known.
+
+The following example transform coordinates from the North American Datum 1927
(EPSG:4267) to WGS84 (EPSG:4326).
+The example is run twice: once for cities in USA, then once for cities in
Canada:
+(Note: the application may log warnings to the console. Those warnings can be
ignored)
+
+ :::bash
+ wget http://sis.apache.org/examples/coordinates/AmericanCities.csv
+ wget http://sis.apache.org/examples/coordinates/CanadianCities.csv
+ sis transform --sourceCRS EPSG:4267 --targetCRS EPSG:4326
AmericanCities.csv
+ sis transform --sourceCRS EPSG:4267 --targetCRS EPSG:4326
CanadianCities.csv
+
+The first execution should print the following header, followed by transformed
coordinate values.
+Note the operation code (EPSG:1173), domain of validity (United State) and
accuracy.
+
+ :::text
+ # Source: NAD27 (EPSG:4267)
+ # Destination: WGS 84 (EPSG:4326)
+ # Operations: NAD27 to WGS 84 (4) (EPSG:1173)
+ # Domain: United States (USA) - onshore
+ # Accuracy: 10.0 metres
+
+The second execution should print the following header, followed by
transformed coordinate values.
+Note that the operation code (EPSG:1172), domain of validity (Canada) and
accuracy are not the same
+than in previous example.
+
+ :::text
+ # Source: NAD27 (EPSG:4267)
+ # Destination: WGS 84 (EPSG:4326)
+ # Operations: NAD27 to WGS 84 (3) (EPSG:1172)
+ # Domain: Canada - onshore and offshore
+ # Accuracy: 20.0 metres
+
+The difference between those two operations become more visible by adding the
`--verbose` option
+to the above `sis transform` commands.
+This option shows the coordinate operation in Well Known Text (WKT) or
pseudo-WKT format.
+When transforming coordinates in USA, the operation contains the following
parameter values:
+
+ :::text
+ Method["Geocentric translations (geog2D domain)"],
+ Parameter["X-axis translation", -8.0, Unit["metre", 1]],
+ Parameter["Y-axis translation", 160.0, Unit["metre", 1]],
+ Parameter["Z-axis translation", 176.0, Unit["metre", 1]]
+
+But when transforming coordinates in Canada, the operation rather contains the
following parameter values:
+
+ :::text
+ Method["Geocentric translations (geog2D domain)"],
+ Parameter["X-axis translation", -10.0, Unit["metre", 1]],
+ Parameter["Y-axis translation", 158.0, Unit["metre", 1]],
+ Parameter["Z-axis translation", 187.0, Unit["metre", 1]],
+
+As seen in the above examples, the parameter values differ slightly with the
geographic area of the coordinates to transform.
+Those parameters could also be different if _datum shift grids_ are available.
For example in USA:
+
+ :::text
+ Method["NADCON"],
+ Parameter["Latitude difference file", "conus.las"],
+ Parameter["Longitude difference file", "conus.los"],
+
+Java methods for accessing functionalities shown in above examples are:
+
+ * Convenience static method in `org.apache.sis.referencing` package:
+ + `CRS.findOperation(CoordinateReferenceSystem, CoordinateReferenceSystem,
GeographicBoundingBox)`
+ * Class in other package (less convenient but give more control):
+ + `org.apache.sis.referencing.operation.DefaultCoordinateOperationFactory`
+
Extracting ISO 19115 Metadata {#metadata}
@@ -318,6 +428,14 @@ The following example show the metadata
Adding the `--format xml` option to the above command will format the same
metadata in a XML document.
The output is not shown in this page because of its verbosity.
+Java methods for accessing functionalities shown in above examples are:
+
+ * Convenience static methods in `org.apache.sis.xml` package:
+ + `XML.marshal(…)`
+ + `XML.unmarshal(…)`
+ * Class in other package (less convenient but give more control):
+ + `org.apache.sis.xml.MarshallerPool`
+
Performance consideration {#performance}
Added: sis/site/trunk/content/examples/coordinates/AmericanCities.csv
URL:
http://svn.apache.org/viewvc/sis/site/trunk/content/examples/coordinates/AmericanCities.csv?rev=1745294&view=auto
==============================================================================
--- sis/site/trunk/content/examples/coordinates/AmericanCities.csv (added)
+++ sis/site/trunk/content/examples/coordinates/AmericanCities.csv [UTF-8] Tue
May 24 01:11:38 2016
@@ -0,0 +1,27 @@
+#
+# Coordinates of some cities in USA. The coordinates are given
+# with only 3 significant digits, which implies an uncertainty
+# of more than 100 metres. With such uncertainty, it does not
+# matter if the geodetic datum is WGS84, NAD83 or NAD27 since
+# the error is greater than the difference between those datums.
+#
+# Axis order is latitude first, then longitude. Units are degrees.
+#
+
+# San-Francisco
+37.783, -122.417
+
+# New-York
+40.713, -74.006
+
+# Los Angeles
+34.050, -118.250
+
+# Houston
+29.763, -95.383
+
+# Chicago
+41.837, -87.685
+
+# Miami
+25.775, -80.209
Propchange: sis/site/trunk/content/examples/coordinates/AmericanCities.csv
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: sis/site/trunk/content/examples/coordinates/AmericanCities.csv
------------------------------------------------------------------------------
svn:mime-type = text/plain;charset=UTF-8
Added: sis/site/trunk/content/examples/coordinates/CanadianCities.csv
URL:
http://svn.apache.org/viewvc/sis/site/trunk/content/examples/coordinates/CanadianCities.csv?rev=1745294&view=auto
==============================================================================
--- sis/site/trunk/content/examples/coordinates/CanadianCities.csv (added)
+++ sis/site/trunk/content/examples/coordinates/CanadianCities.csv [UTF-8] Tue
May 24 01:11:38 2016
@@ -0,0 +1,27 @@
+#
+# Coordinates of some cities in Canada. The coordinates are given
+# with only 3 significant digits, which implies an uncertainty of
+# more than 100 metres. With such uncertainty, it does not matter
+# if the geodetic datum is WGS84, NAD83 or NAD27 since the error
+# is greater than the difference between those datums.
+#
+# Axis order is latitude first, then longitude. Units are degrees.
+#
+
+# Vancouver
+49.250, -123.100
+
+# Toronto
+43.700, -79.400
+
+# Montreal
+45.500, -73.567
+
+# Regina
+50.455, -104.607
+
+# Saskatoon
+52.133, -106.683
+
+# St. John's
+47.568, -52.707
Propchange: sis/site/trunk/content/examples/coordinates/CanadianCities.csv
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: sis/site/trunk/content/examples/coordinates/CanadianCities.csv
------------------------------------------------------------------------------
svn:mime-type = text/plain;charset=UTF-8
Modified: sis/site/trunk/content/index.mdtext
URL:
http://svn.apache.org/viewvc/sis/site/trunk/content/index.mdtext?rev=1745294&r1=1745293&r2=1745294&view=diff
==============================================================================
--- sis/site/trunk/content/index.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/index.mdtext [UTF-8] Tue May 24 01:11:38 2016
@@ -47,10 +47,14 @@ The latest SIS release is 0.7, released
Apache SIS requires a Java 6 Runtime Environment.
The EPSG geodetic dataset (optional but recommended) can be [installed
separately](epsg.html).
+Apache SIS is a Java library for use by other applications.
+Leveraging the full SIS capabilities or getting the best performance require
that users write their own applications on top of SIS.
+However a command-line tool is provided for allowing users to experiment some
SIS functionalities before writing code.
+
* [Downloads](downloads.html) as a `zip` files, or as Maven dependencies.
* Developer guide ([English](book/en/developer-guide.html) |
[French](book/fr/developer-guide.html)) — note that this is work in progress.
* [Online Javadoc](apidocs/index.html) for API documentation.
- * [Command-line interface](command-line.html) for an overview of a
command-line tool.
+ * [Command-line interface](command-line.html) for an overview of the
command-line tool.
* [SIS Wiki][wiki] for "drawing board" and roadmap.
* [Recommended code patterns](code-patterns.html) for writing more robust
applications.
