This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch asf-staging
in repository https://gitbox.apache.org/repos/asf/sis-site.git
commit d41a542c4deb37979c3c44d5527b39767048382b
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Wed Feb 12 12:18:26 2025 +0100
Refresh the "How to" pages with the fix for wrong Maven coordinates and the
addition of "How to add custom CRS".
---
howto.html | 1 +
howto/compound_crs.html | 2 +-
howto/crs_equality.html | 2 +-
howto/custom_crs.html | 166 +++++++++++++++++++++++++++++++++
howto/envelopes_in_different_crs.html | 2 +-
howto/geodetic_paths.html | 4 +-
howto/index.xml | 11 ++-
howto/instantiate_utm_projection.html | 2 +-
howto/lookup_crs_urn.html | 2 +-
howto/parse_and_format_mgrs_codes.html | 4 +-
howto/transform_coordinates.html | 2 +-
howto/transform_envelopes.html | 2 +-
12 files changed, 185 insertions(+), 15 deletions(-)
diff --git a/howto.html b/howto.html
index 238f8b0c..bfb9f155 100644
--- a/howto.html
+++ b/howto.html
@@ -72,6 +72,7 @@ The examples are grouped in the following sections:</p>
<li><a href="./howto/envelopes_in_different_crs.html">Union or intersection of
envelopes in different reference systems</a></li>
<li><a href="./howto/crs_equality.html">Determine if two reference systems are
functionally equal</a></li>
<li><a href="./howto/geodetic_paths.html">Compute geodetic distances and
paths</a></li>
+<li><a href="./howto/custom_crs.html">Extend with custom Coordinate Reference
Systems</a></li>
</ul>
<h1 id="metadata">Metadata </h1>
<ul>
diff --git a/howto/compound_crs.html b/howto/compound_crs.html
index 20cbd9b3..07135f58 100644
--- a/howto/compound_crs.html
+++ b/howto/compound_crs.html
@@ -58,7 +58,7 @@ Apache SIS accepts both, illustrated below.</p>
</thead>
<tbody>
<tr>
-<td><code>org.apache.sis.storage:sis-referencing</code></td>
+<td><code>org.apache.sis.core:sis-referencing</code></td>
<td><code>org.apache.sis.referencing</code></td>
</tr>
</tbody>
diff --git a/howto/crs_equality.html b/howto/crs_equality.html
index d32dce43..d8a60bfb 100644
--- a/howto/crs_equality.html
+++ b/howto/crs_equality.html
@@ -58,7 +58,7 @@ is to request the coordinate operation between them, and
check if that operation
</thead>
<tbody>
<tr>
-<td><code>org.apache.sis.storage:sis-referencing</code></td>
+<td><code>org.apache.sis.core:sis-referencing</code></td>
<td><code>org.apache.sis.referencing</code></td>
</tr>
</tbody>
diff --git a/howto/custom_crs.html b/howto/custom_crs.html
new file mode 100644
index 00000000..fccfde92
--- /dev/null
+++ b/howto/custom_crs.html
@@ -0,0 +1,166 @@
+<!DOCTYPE html>
+<html lang="en">
+
+ <head>
+ <title>Apache SIS - Extend with custom Coordinate Reference Systems</title>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <link rel="stylesheet" type="text/css" media="screen" href="../sis.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="../syntax.css">
+ </head>
+ <body>
+ <div class="topbar">
+ <a class="topbar-brand" href="../index.html">Apache SIS™</a>
+ <ul class="topbar-items">
+ <li>
+ <a href="https://www.apache.org/events/current-event.html";>
+ <img class="apache-con"
src="https://www.apache.org/events/current-event-234x60.png"; alt="ApacheCon"/>
+ </a>
+ </li>
+ </ul>
+ </div>
+ <div class="main-section">
+ <nav class="left-bar">
+ <ul class="nav-pills">
+ <li><a class="nav-link inactive " href="../index.html">Home</a></li>
+ <li><a class="nav-link inactive "
href="../about.html">About</a></li>
+ <li><a class="nav-link inactive "
href="../downloads.html">Downloads</a></li>
+ <li><a class="nav-link active " href="../howto.html">How
to…</a></li>
+ <li><a class="nav-link inactive "
href="../standards.html">Standards</a></li>
+ <li><a class="nav-link inactive " href="../formats.html">Data
formats</a></li>
+ <li><a class="nav-link inactive " href="../epsg.html">EPSG
Database</a></li>
+ <li><a class="nav-link inactive " href="../javafx.html">Application
(demo)</a></li>
+ <li><a class="nav-link inactive "
href="../documentation.html">Documentation</a></li>
+ </ul>
+ </nav>
+ <div class="main-content">
+ <main class="container">
+ <article>
+ <img src="../images/logo.png" class="sis-logo" align="left"/>
+ <p class="page-title">Extend with custom Coordinate Reference
Systems</p>
+
+ <p>An application can associate its own authority codes to custom Coordinate
Reference System (CRS) definitions.
+Such custom CRS definitions can be written in Well-Known Text (WKT) format in
any text file,
+and declared to Apache SIS using the service provider mechanism.
+After those steps, custom Coordinate Reference Systems can be created
+in the same way as for EPSG definitions, with calls to
<code>CRS.forCode(String)</code>.</p>
+<h1 id="direct-dependencies">Direct dependencies</h1>
+<table>
+<thead>
+<tr>
+<th>Maven coordinates</th>
+<th>Module info</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>org.apache.sis.core:sis-metadata</code></td>
+<td><code>org.apache.sis.metadata</code></td>
+</tr>
+<tr>
+<td><code>org.apache.sis.core:sis-referencing</code></td>
+<td><code>org.apache.sis.referencing</code></td>
+</tr>
+</tbody>
+</table>
+<h1 id="example-of-crs-definitions">Example of CRS definitions</h1>
+<p>The first step is to choose an authority name.
+This page uses “MyOrg”, but applications should replace by their
own names.
+Then, the additional CRS definitions can be written in WKT format in a text
file.
+The file can contain as many definitions as desired.
+Each CRS definition must end with an <code>ID[authority, code]</code> element
where <em>authority</em>
+is the chosen authority name, and <em>code</em> is an arbitrary code managed
by that authority.
+The codes are often numerical, but not necessarily:
+alphanumeric codes between quotes are also accepted.
+Example:</p>
+<pre tabindex="0"><code class="language-wkt"
data-lang="wkt">ProjectedCRS["North Pole Azimuthal Equidistant",
+ BaseGeodCRS["WGS 1984",
+ Datum["World Geodetic System 1984",
+ Ellipsoid["WGS 1984", 6378137, 298.257223563]],
+ AngleUnit["Degree", 0.0174532925199433]],
+ Conversion["North Pole Azimuthal Equidistant",
+ Method["Azimuthal Equidistant (Spherical)"],
+ Parameter["Latitude of natural origin", 90]],
+ CS[Cartesian, 2],
+ Axis["Easting (E)", east],
+ Axis["Northing (N)", north],
+ Unit["metre", 1],
+ Id["MyOrg", 102016]]
+
+ProjectedCRS["North Pole Stereographic",
+ ...
+ Id["MyOrg", 102018]]
+</code></pre><h2 id="more-compact-definitions-non-standard">More compact
definitions (non-standard)</h2>
+<p>A file with many CRS definitions may contain a lot of redundancy.
+For example, the <code>BaseGeodCRS</code> and <code>CS</code> elements are
often repeated verbatim in many <code>ProjectedCRS</code> definitions.
+Apache SIS has a non-standard mechanism for declaring WKT fragments are
reusing them in many CRS definitions.
+The fragment can be declared with a <code>SET</code> directive, and reused by
prefixing the fragment name with <code>$</code>:
+Example for the same CRS than above:</p>
+<pre tabindex="0"><code class="language-wkt" data-lang="wkt">SET WGS84_BASE =
+ BaseGeodCRS["WGS 1984",
+ Datum["World Geodetic System 1984",
+ Ellipsoid["WGS 1984", 6378137, 298.257223563]],
+ AngleUnit["Degree", 0.0174532925199433]]
+
+SET CARTESIAN_CS =
+ CS[Cartesian, 2],
+ Axis["Easting (E)", east],
+ Axis["Northing (N)", north],
+ Unit["metre", 1]
+
+ProjectedCRS["North Pole Azimuthal Equidistant",
+ $WGS84_BASE,
+ Conversion["North Pole Azimuthal Equidistant",
+ Method["Azimuthal Equidistant (Spherical)"],
+ Parameter["Latitude of natural origin", 90]],
+ $CARTESIAN_CS,
+ Id["MyOrg", 102016]]
+</code></pre><p>The above examples are available with more explanations in a
<a
href="https://sis.apache.org/apidocs/org.apache.sis.referencing/org/apache/sis/io/wkt/doc-files/ESRI.txt";>text
file</a>.</p>
+<h1 id="java-code">Java code</h1>
+<p>The application needs to load the CRS definitions file in a Java code like
below
+(see the <a
href="https://sis.apache.org/apidocs/org.apache.sis.referencing/org/apache/sis/io/wkt/WKTDictionary.html";>Javadoc</a>
for more information).
+Replace “MyOrg” by the chosen authority name and
“MyCRS.txt” by the text file
+containing CRS definitions in WKT format:</p>
+<div class="highlight"><pre tabindex="0" class="chroma"><code
class="language-java" data-lang="java"><span class="line"><span
class="cl"><span class="kn">package</span><span class="w"> </span><span
class="nn">org.myorg</span><span class="p">;</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span class="w">
+</span></span></span><span class="line"><span class="cl"><span
class="w"></span><span class="kn">import</span><span class="w"> </span><span
class="nn">java.io.BufferedReader</span><span class="p">;</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span
class="w"></span><span class="kn">import</span><span class="w"> </span><span
class="nn">java.io.IOException</span><span class="p">;</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span
class="w"></span><span class="kn">import</span><span class="w"> </span><span
class="nn">java.nio.file.Files</span><span class="p">;</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span
class="w"></span><span class="kn">import</span><span class="w"> </span><span
class="nn">java.nio.file.Path</span><span class="p">;</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span
class="w"></span><span class="kn">import</span><span class="w"> </span><span
class="nn">org.apache.sis.io.wkt.WKTDictionary</span><span
class="p">;</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span
class="w"></span><span class="kn">import</span><span class="w"> </span><span
class="nn">org.apache.sis.metadata.iso.citation.DefaultCitation</span><span
class="p">;</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span
class="w"></span><span class="kn">import</span><span class="w"> </span><span
class="nn">org.opengis.referencing.crs.CRSAuthorityFactory</span><span
class="p">;</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span
class="w"></span><span class="kn">import</span><span class="w"> </span><span
class="nn">org.opengis.util.FactoryException</span><span
class="p">;</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span class="w">
+</span></span></span><span class="line"><span class="cl"><span
class="w"></span><span class="kd">public</span><span class="w"> </span><span
class="kd">class</span> <span class="nc">MyCRS</span><span class="w">
</span><span class="kd">extends</span><span class="w"> </span><span
class="n">WKTDictionary</span><span class="w"> </span><span
class="kd">implements</span><span class="w"> </span><span
class="n">CRSAuthorityFactory</span><span class="w"> </span><span
class="p">{</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span class="w">
</span><span class="n">MyCRS</span><span class="p">()</span><span class="w">
</span><span class="kd">throws</span><span class="w"> </span><span
class="n">IOException</span><span class="p">,</span><span class="w">
</span><span class="n">FactoryException</span><span class="w"> </span><span
class="p">{</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span class="w">
</span><span class="kd">super</span><span class="p">(</span><span
class="k">new</span><span class="w"> </span><span
class="n">DefaultCitation</span><span class="p">(</span><span
class="s">"MyOrg"</span><span class="p">));</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span class="w">
</span><span class="k">try</span><span class="w"> </span><span
class="p">(</span><span class="n">BufferedReader</span><span class="w">
</span><span class="n">source</span><span class="w"> </span><span
class="o">=</span><span class="w"> </span><span class="n">Files</span><span
class="p">.</span><span class="na">newBufferedReader</span><span
class="p">(</span><span class="n">Path</span><span class="p">.</span> [...]
+</span></span></span><span class="line"><span class="cl"><span class="w">
</span><span class="n">load</span><span class="p">(</span><span
class="n">source</span><span class="p">);</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span class="w">
</span><span class="p">}</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span class="w">
</span><span class="p">}</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span
class="w"></span><span class="p">}</span><span class="w">
+</span></span></span></code></pre></div><p>Finally, applications need to
declare above class as a services in their <code>module-info.java</code>:</p>
+<div class="highlight"><pre tabindex="0" class="chroma"><code
class="language-java" data-lang="java"><span class="line"><span
class="cl"><span class="n">module</span><span class="w"> </span><span
class="n">org</span><span class="p">.</span><span class="na">myorg</span><span
class="w"> </span><span class="p">{</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span class="w">
</span><span class="n">requires</span><span class="w"> </span><span
class="n">org</span><span class="p">.</span><span class="na">apache</span><span
class="p">.</span><span class="na">sis</span><span class="p">.</span><span
class="na">referencing</span><span class="p">;</span><span class="w">
+</span></span></span><span class="line"><span class="cl"><span class="w">
</span><span class="n">provides</span><span class="w"> </span><span
class="n">org</span><span class="p">.</span><span
class="na">opengis</span><span class="p">.</span><span
class="na">referencing</span><span class="p">.</span><span
class="na">crs</span><span class="p">.</span><span
class="na">CRSAuthorityFactory</span><span class="w"> </span><span
class="n">with</span><span class="w"> </span><span class="n">org< [...]
+</span></span></span><span class="line"><span class="cl"><span
class="w"></span><span class="p">}</span><span class="w">
+</span></span></span></code></pre></div><p>Alternatively, non-modular
applications can register in <code>META-INF/services/</code> instead.</p>
+<h1 id="usage">Usage</h1>
+<p>After all above steps have been completed, the
<code>org.apache.sis.referencing.CRS</code> class should recognize the custom
authority codes.
+For example, a call to <code>CRS.forCode("MyOrg:102016")</code>
should return the <code>ProjectedCRS</code> defined in above example.</p>
+
+
+ </article>
+ </main>
+ <footer>
+ <div class="container">
+ <p>Copyright © 2013-2025 The Apache Software Foundation,
Licensed under the
+ <a href="https://www.apache.org/licenses/LICENSE-2.0";>Apache
License, Version 2.0</a>.<br/>
+ Apache SIS, Apache, the Apache feather logo are trademarks of The
Apache Software Foundation.</p>
+ </div>
+ </footer>
+ </div>
+ </div>
+ </body>
+</html>
diff --git a/howto/envelopes_in_different_crs.html
b/howto/envelopes_in_different_crs.html
index 42cc2b5a..5bdbe604 100644
--- a/howto/envelopes_in_different_crs.html
+++ b/howto/envelopes_in_different_crs.html
@@ -55,7 +55,7 @@ Apache <abbr title="Spatial Information System">SIS</abbr>
can handle this task
</thead>
<tbody>
<tr>
-<td><code>org.apache.sis.storage:sis-referencing</code></td>
+<td><code>org.apache.sis.core:sis-referencing</code></td>
<td><code>org.apache.sis.referencing</code></td>
</tr>
</tbody>
diff --git a/howto/geodetic_paths.html b/howto/geodetic_paths.html
index ae933607..af3a8ca7 100644
--- a/howto/geodetic_paths.html
+++ b/howto/geodetic_paths.html
@@ -49,14 +49,12 @@ with the property that the azimuths at the two curve
extremities are preserved.<
<tr>
<th>Maven coordinates</th>
<th>Module info</th>
-<th>Remarks</th>
</tr>
</thead>
<tbody>
<tr>
-<td><code>org.apache.sis.storage:sis-referencing</code></td>
+<td><code>org.apache.sis.core:sis-referencing</code></td>
<td><code>org.apache.sis.referencing</code></td>
-<td></td>
</tr>
</tbody>
</table>
diff --git a/howto/index.xml b/howto/index.xml
index 8bf104a2..1243444f 100644
--- a/howto/index.xml
+++ b/howto/index.xml
@@ -19,7 +19,7 @@
<link>https://sis.apache.org/howto/geodetic_paths.html</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
<guid>https://sis.apache.org/howto/geodetic_paths.html</guid>
- <description>The following example computes the geodetic distance
between given positions. The geodetic distance is the shortest distance on
Earth ellipsoid. Apache SIS can also compute the path as a Béziers curve, with
the property that the azimuths at the two curve extremities are
preserved.
Direct dependencies Maven coordinates Module info Remarks
org.apache.sis.storage:sis-referencing org.apache.sis.referencing Code example
Note that all geographic coordinates below express [...]
+ <description>The following example computes the geodetic distance
between given positions. The geodetic distance is the shortest distance on
Earth ellipsoid. Apache SIS can also compute the path as a Béziers curve, with
the property that the azimuths at the two curve extremities are
preserved.
Direct dependencies Maven coordinates Module info
org.apache.sis.core:sis-referencing org.apache.sis.referencing Code example
Note that all geographic coordinates below express latitude b [...]
</item>
<item>
<title>Determine if two CRS are functionally equal</title>
@@ -28,6 +28,13 @@
<guid>https://sis.apache.org/howto/crs_equality.html</guid>
<description>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,
Utilities.equalsIgnoreMetadata(myFirstCRS, mySecondCRS) can be used.
In
some cases, equalsIgnoreMetadata(…) may fail to see that two reference
systems are equal. It may happen for example when tw [...]
</item>
+ <item>
+ <title>Extend with custom Coordinate Reference Systems</title>
+ <link>https://sis.apache.org/howto/custom_crs.html</link>
+ <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
+ <guid>https://sis.apache.org/howto/custom_crs.html</guid>
+ <description>An application can associate its own authority codes to
custom Coordinate Reference System (CRS) definitions. Such custom CRS
definitions can be written in Well-Known Text (WKT) format in any text file,
and declared to Apache SIS using the service provider mechanism. After those
steps, custom Coordinate Reference Systems can be created in the same way as
for EPSG definitions, with calls to CRS.forCode(String).
Direct
dependencies Maven coordinates Module info org.a [...]
+ </item>
<item>
<title>From data lake to data cube</title>
<link>https://sis.apache.org/howto/datalake_to_datacube.html</link>
@@ -96,7 +103,7 @@
<link>https://sis.apache.org/howto/parse_and_format_mgrs_codes.html</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
<guid>https://sis.apache.org/howto/parse_and_format_mgrs_codes.html</guid>
- <description>The following example converts geographic coordinates to
Military Grid Reference System (MGRS) codes and conversely. MGRS codes can be
seen as a kind of GeoHash but with better properties. Apache SIS supports also
GeoHash if desired, in a way similar to this example.
Direct dependencies
Maven coordinates Module info Remarks org.apache.sis.storage:sis-referencing
org.apache.sis.referencing Code example Note that all geographic coordinates
below express latitude befo [...]
+ <description>The following example converts geographic coordinates to
Military Grid Reference System (MGRS) codes and conversely. MGRS codes can be
seen as a kind of GeoHash but with better properties. Apache SIS supports also
GeoHash if desired, in a way similar to this example.
Direct dependencies
Maven coordinates Module info org.apache.sis.core:sis-referencing
org.apache.sis.referencing Code example Note that all geographic coordinates
below express latitude before longitud [...]
</item>
<item>
<title>Read raster from a GeoTIFF file</title>
diff --git a/howto/instantiate_utm_projection.html
b/howto/instantiate_utm_projection.html
index 647a1c68..9338062e 100644
--- a/howto/instantiate_utm_projection.html
+++ b/howto/instantiate_utm_projection.html
@@ -71,7 +71,7 @@ The EPSG code of some UTM projections can be determined as
below, where <em>zone
</thead>
<tbody>
<tr>
-<td><code>org.apache.sis.storage:sis-referencing</code></td>
+<td><code>org.apache.sis.core:sis-referencing</code></td>
<td><code>org.apache.sis.referencing</code></td>
<td></td>
</tr>
diff --git a/howto/lookup_crs_urn.html b/howto/lookup_crs_urn.html
index abb198c1..108ca78f 100644
--- a/howto/lookup_crs_urn.html
+++ b/howto/lookup_crs_urn.html
@@ -67,7 +67,7 @@ Consequently if the given <abbr title="Coordinate Reference
System">CRS</abbr> h
</thead>
<tbody>
<tr>
-<td><code>org.apache.sis.storage:sis-referencing</code></td>
+<td><code>org.apache.sis.core:sis-referencing</code></td>
<td><code>org.apache.sis.referencing</code></td>
<td></td>
</tr>
diff --git a/howto/parse_and_format_mgrs_codes.html
b/howto/parse_and_format_mgrs_codes.html
index b53c3f80..ecb6e7a4 100644
--- a/howto/parse_and_format_mgrs_codes.html
+++ b/howto/parse_and_format_mgrs_codes.html
@@ -49,14 +49,12 @@ Apache SIS supports also GeoHash if desired, in a way
similar to this example.</
<tr>
<th>Maven coordinates</th>
<th>Module info</th>
-<th>Remarks</th>
</tr>
</thead>
<tbody>
<tr>
-<td><code>org.apache.sis.storage:sis-referencing</code></td>
+<td><code>org.apache.sis.core:sis-referencing</code></td>
<td><code>org.apache.sis.referencing</code></td>
-<td></td>
</tr>
</tbody>
</table>
diff --git a/howto/transform_coordinates.html b/howto/transform_coordinates.html
index f259f862..1bf12325 100644
--- a/howto/transform_coordinates.html
+++ b/howto/transform_coordinates.html
@@ -55,7 +55,7 @@ Unexpected results are often caused by wrong axis order.</p>
</thead>
<tbody>
<tr>
-<td><code>org.apache.sis.storage:sis-referencing</code></td>
+<td><code>org.apache.sis.core:sis-referencing</code></td>
<td><code>org.apache.sis.referencing</code></td>
<td></td>
</tr>
diff --git a/howto/transform_envelopes.html b/howto/transform_envelopes.html
index 1bb43b23..17cec885 100644
--- a/howto/transform_envelopes.html
+++ b/howto/transform_envelopes.html
@@ -60,7 +60,7 @@ the same Apache <abbr title="Spatial Information
System">SIS</abbr> methods can
</thead>
<tbody>
<tr>
-<td><code>org.apache.sis.storage:sis-referencing</code></td>
+<td><code>org.apache.sis.core:sis-referencing</code></td>
<td><code>org.apache.sis.referencing</code></td>
</tr>
</tbody>
![https://www.apache.org/events/current-event-234x60.png"](https://www.apache.org/events/current-event-234x60.png"){kind=link}