sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1816133 - in /sis/site/trunk/content: GDAL.mdtext epsg.mdtext index.mdtext release-management.mdtext
Date Thu, 23 Nov 2017 11:09:09 GMT
Author: desruisseaux
Date: Thu Nov 23 11:09:08 2017
New Revision: 1816133

URL: http://svn.apache.org/viewvc?rev=1816133&view=rev
Log:
Add a note about bridge to GDAL.

Added:
    sis/site/trunk/content/GDAL.mdtext   (with props)
Modified:
    sis/site/trunk/content/epsg.mdtext
    sis/site/trunk/content/index.mdtext
    sis/site/trunk/content/release-management.mdtext

Added: sis/site/trunk/content/GDAL.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/GDAL.mdtext?rev=1816133&view=auto
==============================================================================
--- sis/site/trunk/content/GDAL.mdtext (added)
+++ sis/site/trunk/content/GDAL.mdtext [UTF-8] Thu Nov 23 11:09:08 2017
@@ -0,0 +1,91 @@
+Title:  Bridge with GDAL
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+        or more contributor license agreements.  See the NOTICE file
+        distributed with this work for additional information
+        regarding copyright ownership.  The ASF licenses this file
+        to you under the Apache License, Version 2.0 (the
+        "License"); you may not use this file except in compliance
+        with the License.  You may obtain a copy of the License at
+        .
+          http://www.apache.org/licenses/LICENSE-2.0
+        .
+        Unless required by applicable law or agreed to in writing,
+        software distributed under the License is distributed on an
+        "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+        KIND, either express or implied.  See the License for the
+        specific language governing permissions and limitations
+        under the License.
+
+
+
+While Apache SIS provides its own map projection engine, some applications may want to also
use the Proj.4 library.
+It may be for using map projection methods not yet supported by Apache SIS, or for getting
the exact same numerical
+results than Proj.4. The two libraries can coexist and can be used through the same API,
+provided that following prerequisites are meet.
+
+
+Prerequisites    {#prerequisites}
+=================================
+Proj.4 needs to be pre-installed; there is no copy embedded in Apache SIS.
+Proj.4 can be installed by package managers on most Linux distributions,
+or with tools like MacPorts on MacOS.
+In addition, the `sis-gdal` module must be on the classpath.
+Maven projects can use the following dependency in their `pom.xml` file:
+
+    :::xml
+    <dependencies>
+      <dependency>
+        <groupId>org.apache.sis.storage</groupId>
+        <artifactId>sis-gdal</artifactId>
+        <version>0.8</version>
+      </dependency>
+    </dependencies>
+
+Current Apache SIS version supports only Linux and MacOS platforms.
+A future version will add Windows support.
+
+
+Usage    {#usage}
+=================
+For instantiating a coordinate reference system (CRS) backed by Proj.4:
+
+    :::java
+    CoordinateReferenceSystem crs = CRS.forCode("Proj4::+init=epsg:4326");
+
+Everything after "PROJ4::" is forwarded as-is to the Proj.4 library.
+Note that despite the "epsg" part in above definition string, CRS created by above method
call is **not**
+conform to EPSG:4326 authoritative definition. It should rather be understood as a Proj.4-specific
code.
+Proj.4 definitions may differ from authoritative definitions in axis order, axis directions
or units of measurement.
+To get the authoritative definition, use `CRS.forCode("EPSG::4326")` instead.
+
+For creating a coordinate operation backed by Proj.4, there is nothing special to do;
+we can invoke the same method regardless if the CRS are backed by Proj.4 or Apache SIS.
+The following code will create a transform backed by Proj.4 if *both* `sourceCRS` and `targetCRS`
+were created with `CRS.forCode("Proj4::…")` calls.
+
+    :::java
+    CoordinateOperation  op = CRS.findOperation(sourceCRS, targetCRS, null);
+    MathTransform        mt = op.getMathTransform();
+    DirectPosition sourcePt = new DirectPosition2D(x, y);
+    DirectPosition targetPt = mt.transform(sourcePt, null);
+
+To verify if a `MathTransform` instance is implemented by Proj.4 or by Apache SIS,
+one can look at the _Well Known Text_ (WKT) representation as given by `System.out.println(mt)`.
+If the transform is backed by Apache SIS, the output may show any of the parameters listed
+in the [coordinate operation methods table](tables/CoordinateOperationMethods.html).
+But if the transform is backed by Proj.4, then the transform will always be described
+by the `"pj_transform"` method with exactly two parameters: `"srcdefn"` and `"dstdefn"`:
+
+    :::text
+    PARAM_MT["pj_transform",
+      PARAMETER["srcdefn", "+proj=…"],
+      PARAMETER["dstdefn", "+proj=…"]]
+
+See the [Javadoc](apidocs/org/apache/sis/storage/gdal/package-summary.html) for more information.
+
+
+Limitations    {#limitations}
+=============================
+Current Apache SIS version can create CRS backed by Proj.4 only when SIS can map Proj.4 parameters
to EPSG parameters.
+For example the Proj.4 `+x_0=` parameter is often (but not always) mapped to EPSG _False
easting_ parameter.
+Future SIS versions may relax the requirement for such mapping.

Propchange: sis/site/trunk/content/GDAL.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: sis/site/trunk/content/GDAL.mdtext
------------------------------------------------------------------------------
    svn:mime-type = text/plain;charset=UTF-8

Modified: sis/site/trunk/content/epsg.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/epsg.mdtext?rev=1816133&r1=1816132&r2=1816133&view=diff
==============================================================================
--- sis/site/trunk/content/epsg.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/epsg.mdtext [UTF-8] Thu Nov 23 11:09:08 2017
@@ -116,7 +116,7 @@ if that database is specified by JNDI):
       <dependency>
         <groupId>org.apache.sis.non-free</groupId>
         <artifactId>sis-epsg</artifactId>
-        <version>${sis.version}</version>
+        <version>0.8</version>
         <scope>runtime</scope>
       </dependency>
 
@@ -149,7 +149,7 @@ This dependency can be declared as below
       <dependency>
         <groupId>org.apache.sis.non-free</groupId>
         <artifactId>sis-embedded-data</artifactId>
-        <version>${sis.version}</version>
+        <version>0.8</version>
         <scope>runtime</scope>
       </dependency>
     </dependencies>

Modified: sis/site/trunk/content/index.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/index.mdtext?rev=1816133&r1=1816132&r2=1816133&view=diff
==============================================================================
--- sis/site/trunk/content/index.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/index.mdtext [UTF-8] Thu Nov 23 11:09:08 2017
@@ -38,6 +38,7 @@ Some Apache SIS features are:
       See the list of [supported coordinate reference systems](tables/CoordinateReferenceSystems.html).
     * Mercator, Transverse Mercator, Lambert Conic Conformal, stereographic and more map
projections.
       See the list of [supported operation methods](tables/CoordinateOperationMethods.html).
+    * [Bridge to Proj.4](gdal.html) as a complement to Apache SIS own referencing engine.
   * Referencing by identifiers (ISO 19112:2003)
     * Geohashes (a simple encoding of geographic coordinates into short strings of letters
and digits).
     * Military Grid Reference System (MGRS), also used for some civilian uses.

Modified: sis/site/trunk/content/release-management.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/release-management.mdtext?rev=1816133&r1=1816132&r2=1816133&view=diff
==============================================================================
--- sis/site/trunk/content/release-management.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/release-management.mdtext [UTF-8] Thu Nov 23 11:09:08 2017
@@ -141,6 +141,7 @@ Add a new `<release>` block for the new
 Update the version numbers from the old one to `$NEW_VERSION` in the following files.
 
   * `content/index.mdtext`
+  * `content/gdal.mdtext`
   * `content/downloads.mdtext` (need also to update `$NEW_VERSION-SNAPSHOT` to the next snapshot
version)
   * `content/command-line.mdtext`
   * `content/epsg.mdtext` (be aware that the version number may sometime be behind the SIS
version number)



Mime
View raw message