sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1733449 - /sis/site/trunk/content/command-line.mdtext
Date Thu, 03 Mar 2016 11:42:32 GMT
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).



Mime
View raw message