This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/sis-site.git
commit 1a25795a572d662138160e11f197702f63d3df98
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Tue Apr 18 16:41:51 2023 +0200
Add two more examples in the referencing section.
---
content/howto/_index.md | 2 +
content/howto/geodetic_paths.md | 68 +++++++++++++++++++++++++
content/howto/parse_and_format_mgrs_codes.md | 75 ++++++++++++++++++++++++++++
3 files changed, 145 insertions(+)
diff --git a/content/howto/_index.md b/content/howto/_index.md
index 35b52100..8d717856 100644
--- a/content/howto/_index.md
+++ b/content/howto/_index.md
@@ -28,8 +28,10 @@ The examples are grouped in the following sections:
* [Get the EPSG code or URN of an existing reference
system](howto/lookup_crs_urn.html)
* [Transform points between two reference
systems](howto/transform_coordinates.html)
* [Transform envelopes between two reference
systems](howto/transform_envelopes.html)
+* [Parse and format MGRS codes](howto/parse_and_format_mgrs_codes.html)
* [Union or intersection of envelopes in different reference
systems](howto/envelopes_in_different_crs.html)
* [Determine if two reference systems are functionally
equal](howto/crs_equality.html)
+* [Compute geodetic distances and paths](howto/geodetic_paths.html)
# Metadata {#metadata}
diff --git a/content/howto/geodetic_paths.md b/content/howto/geodetic_paths.md
new file mode 100644
index 00000000..353b9063
--- /dev/null
+++ b/content/howto/geodetic_paths.md
@@ -0,0 +1,68 @@
+---
+title: Compute geodetic distances and paths
+---
+
+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 latitude *before* longitude.
+
+{{< highlight java >}}
+import java.awt.Shape;
+import org.apache.sis.referencing.CommonCRS;
+import org.apache.sis.referencing.GeodeticCalculator;
+
+public class GeodeticPaths {
+ /**
+ * Demo entry point.
+ *
+ * @param args ignored.
+ */
+ public static void main(String[] args) {
+ var calculator =
GeodeticCalculator.create(CommonCRS.WGS84.geographic());
+ calculator.setStartGeographicPoint(40, 5);
+ calculator.setEndGeographicPoint(42, 3);
+ System.out.printf("Result of geodetic calculation: %s%n", calculator);
+
+ double d;
+ d = calculator.getRhumblineLength();
+ d -= calculator.getGeodesicDistance();
+ System.out.printf("The rhumbline is %1.2f %s longer%n", d,
calculator.getDistanceUnit());
+
+ Shape path = calculator.createGeodesicPath2D(100);
+ System.out.printf("Java2D shape class for approximating this path:
%s%n", path.getClass());
+ }
+}
+{{< / highlight >}}
+
+
+# Output
+
+The output depends on the locale.
+Below is an example:
+
+```
+Result of geodetic calculation:
+Coordinate reference system: WGS 84
+┌─────────────┬─────────────────┬────────────────┬────────────┐
+│ │ Latitude │ Longitude │ Azimuth │
+│ Start point │ 40°00′00.0000″N │ 5°00′00.0000″E │ -36°29′45″ │
+│ End point │ 42°00′00.0000″N │ 3°00′00.0000″E │ -37°48′29″ │
+└─────────────┴─────────────────┴────────────────┴────────────┘
+Geodesic distance: 278,632.68 m
+
+The rhumbline is 6.09 m longer
+Java2D shape class for approximating this path: class
java.awt.geom.QuadCurve2D$Double
+```
diff --git a/content/howto/parse_and_format_mgrs_codes.md
b/content/howto/parse_and_format_mgrs_codes.md
new file mode 100644
index 00000000..60dece71
--- /dev/null
+++ b/content/howto/parse_and_format_mgrs_codes.md
@@ -0,0 +1,75 @@
+---
+title: Parse and format MGRS codes
+---
+
+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 *before* longitude.
+
+{{< highlight java >}}
+import org.apache.sis.geometry.DirectPosition2D;
+import org.apache.sis.referencing.CommonCRS;
+import org.apache.sis.referencing.gazetteer.MilitaryGridReferenceSystem;
+import org.opengis.referencing.gazetteer.Location;
+import org.opengis.referencing.operation.TransformException;
+
+public class MGRS {
+ /**
+ * Demo entry point.
+ *
+ * @param args ignored.
+ * @throws TransformException if an error occurred when encoding or
decoding a position.
+ */
+ public static void main(String[] args) throws TransformException {
+ var rs = new MilitaryGridReferenceSystem();
+ var point = new DirectPosition2D(CommonCRS.WGS84.geographic(), 40, 5);
+ var coder = rs.createCoder();
+ var code = coder.encode(point);
+ System.out.printf("MGRS code of %s is %s%n", point, code);
+
+ coder.setPrecision(1000); // Limit to a precision of 1 km.
+ code = coder.encode(point);
+ System.out.printf("Same code reduced to 1 km precision: %s%n", code);
+
+ Location reverse = coder.decode(code);
+ System.out.printf("Back to geographic coordinates: %s%n", reverse);
+ }
+}
+{{< / highlight >}}
+
+
+# Output
+
+The output depends on the locale.
+Below is an example:
+
+```
+MGRS code of POINT(40 5) is 31TFE7072529672
+Same code reduced to 1 km precision: 31TFE7029
+Back to geographic coordinates:
+┌─────────────────────────────────────────────────────────────────┐
+│ Location type: Grid coordinate │
+│ Geographic identifier: 31TFE7029 │
+│ West bound: 670,000 m — 4°59′28″E │
+│ Representative value: 670,500 m — 4°59′51″E │
+│ East bound: 671,000 m — 5°00′12″E │
+│ South bound: 4,429,656 m — 40°00′00″N │
+│ Representative value: 4,429,828 m — 40°00′05″N │
+│ North bound: 4,430,000 m — 40°00′12″N │
+│ Coordinate reference system: WGS 84 / UTM zone 31N │
+│ Administrator: North Atlantic Treaty Organization │
+└─────────────────────────────────────────────────────────────────┘
+```
