Author: desruisseaux
Date: Thu Mar 3 11:42:31 2016
New Revision: 1733449
URL: http://svn.apache.org/viewvc?rev=1733449&view=rev
Log:
Documentation fixes.
Modified:
sis/site/trunk/content/command-line.mdtext
Modified: sis/site/trunk/content/command-line.mdtext
URL:
http://svn.apache.org/viewvc/sis/site/trunk/content/command-line.mdtext?rev=1733449&r1=1733448&r2=1733449&view=diff
==============================================================================
--- sis/site/trunk/content/command-line.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/command-line.mdtext [UTF-8] Thu Mar 3 11:42:31 2016
@@ -16,7 +16,7 @@ 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 a data
file.
+A command-line interface is provided for extracting information from data
files or authority codes.
[TOC]
@@ -43,16 +43,16 @@ Example:
:::bash
export PATH=$PWD/apache-sis-0.6/bin:$PATH
-The remaining of this page assumes that `bin` is on the search path.
-If not, just prepend the `sis` command by its path (e.g.
`./apache-sis-0.6/bin/sis`).
+The remaining of this page assumes that the `bin` directory is on the search
path.
+If not, the same examples can still be executed by replacing the `sis` command
by `./apache-sis-0.6/bin/sis`.
Optional dependencies {#dependencies}
----------------------------------------
-Every JAR files present in the `lib` sub-directory will be included on the
classpath during the execution of `sis` command.
-By default, the `lib` directory contains only the SIS archive. However users
can add other JAR files in that directory for
-the following optional dependencies:
+Every JAR files present in the `lib` sub-directory will be included on the
classpath during `sis` command execution.
+By default, the `lib` directory contains only the `sis.jar` file.
+ However users can add other JAR files in that directory for the following
optional dependencies:
* **Derby driver —**
needed only if Apache SIS can not locate a JavaDB driver in the JDK
installation directory.
@@ -68,7 +68,7 @@ the following optional dependencies:
Usage {#usage}
=================
-Invoking `sis` without argument show a summary of available commands and all
options.
+Invoking `sis` without argument shows a summary of available commands and all
options.
For executing a command, the syntax is:
:::bash
@@ -81,7 +81,7 @@ Available commands are:
<tr><td><code>about</code></td> <td>Show information about Apache SIS
and system configuration.</td></tr>
<tr><td><code>mime-type</code></td> <td>Show MIME type for the given
file.</td></tr>
<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
information for the given file or code.</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>
</table>
@@ -119,7 +119,7 @@ SIS can read Coordinate Reference System
* _Well Known Text_ (WKT) format version 1 and 2
* _Geographic Markup Language_ (GML) version 3.2
-The easiest way is see a CRS definition is to use an EPSG code.
+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.
Appache SIS provides a [list of supported
codes](book/tables/CoordinateReferenceSystems.html), which can be queried from
the command line.
For example the following command prints the definition of the _"JGD2011 /
Japan Plane Rectangular CS VIII"_ Coordinate Reference System:
@@ -162,11 +162,12 @@ For an output using the legacy WKT 1 for
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.
-If an output closer to the WKT 2 recommendations is desired, one can add the
`--format wkt2` option to the above command.
+If an output closer to WKT 2 recommendations is desired, one can add the
`--format wkt2` option to the above command.
+The result will be slightly more verbose.
Apache SIS can also read and write CRS definitions in the _Geographic Markup
Language_ (GML) format.
For GML output, one can add the `--format xml` option to the above command.
-Note that the result is quite verbose.
+The result will be much more verbose than WKT outputs.
@@ -174,16 +175,22 @@ Extracting EPSG identifier from a Coordi
------------------------------------------------------------------------------
Because the EPSG geodetic dataset is so commonly used,
-it is very common to define a CRS by only its EPSG code instead than its full
definition.
-Such codes can be written as “`EPSG:4326`” or “`urn:ogc:def:crs:EPSG::4326`”
for instance.
-In a _Well Known Text_ (WKT) string, the code appears at the bottom of the
definition
-in an element like `ID["EPSG", 4326]` or `AUTHORITY["EPSG", "4326"]`.
-However in many case the code is missing.
-But Apache SIS can find it by comparing a given CRS against the definitions in
the EPSG database.
-
-The following example read a WKT for the _“NTF (Paris) / Lambert zone II”_
Coordinate Reference System,
-but in which the `ID["EPSG", 27572]` has been intentionally omitted.
-Furthermore, the _“NTF (Paris) / Lambert zone II”_ name has been replaced by
_“NTF (Paris) / zone to be discovered by the demo”_
+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)
+
+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"]`.
+However in many cases the code is missing.
+Sometime Apache SIS can find a missing code by comparing a given CRS against
the definitions in the EPSG database.
+
+The following example reads a WKT for the _“NTF (Paris) / Lambert zone II”_
Coordinate Reference System,
+but in which the `ID["EPSG", 27572]` element has been intentionally omitted.
+Furthermore, the _“NTF (Paris) / Lambert zone II”_ name has been replaced by
_“NTF (Paris) / zone to be discovered by the demo”_ name.
Executing the following command:
:::bash
@@ -215,7 +222,7 @@ produces an output like below:
Apache SIS can perform such analysis because it “understands” the CRS
definition.
This analysis capability can be tested by altering the CRS definition.
-The following example asks the identifier of a CRS which is normally defined
as below:
+The next example asks the identifier of a CRS which is normally defined as
below:
:::text
ProjectedCRS["WGS 84 / Mercator 41",
@@ -244,8 +251,10 @@ produces an output like below:
:::text
urn:ogc:def:crs:EPSG:8.9:3994 | WGS 84 / Mercator 41
-Apache SIS has been able to detect that the second CRS is numerically
equivalent to the first one,
-and return the identifier for the CRS that we should use.
+In above example, Apache SIS used the fact that a
+_“Mercator (variant A)”_ projection with a _“Scale factor at natural origin”_
parameter value of 0.755799… on the WGS84 datum is numerically equivalent to a
+_“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.
@@ -313,5 +322,6 @@ Performance consideration {#performan
===========================================
If there is a large amount of files to process, invoking the above command
many time may be inefficient
-since it would restart a new JVM on every invocation. For such cases, it is
more efficient to loop inside
-a small Java program using the [SIS API](apidocs/index.html).
+since it would restart a new JVM on every invocation.
+If the operation requires the EPSG dataset, booting the Derby database also
has a significant cost.
+For such cases, it is more efficient to loop inside a small Java program using
the [SIS API](apidocs/index.html).
