Add a gallery example for regional manifold extraction

changelog/1284.documentation.rst

@@ -0,0 +1,2 @@
+Added a gallery example for region manifold extraction using :func:`geovista.geodesic.wedge`.
+Closes :issue:`1285`. (:user:`ESadek-MO`)

src/geovista/cache/__init__.py

@@ -44,7 +44,7 @@
 BASE_URL: str = "https://github.com/bjlittle/geovista-data/raw/{version}/assets/"
 """Base URL for :mod:`geovista` resources."""
 
-DATA_VERSION: str = "2024.10.2"
+DATA_VERSION: str = "2025.01.3"
 """The ``geovista-data`` repository version for :mod:`geovista` resources."""
 
 GEOVISTA_CACHEDIR: str = "GEOVISTA_CACHEDIR"

src/geovista/cache/registry.txt

@@ -39,6 +39,7 @@ tests/images/examples.test__clouds.png a650d7717324453f86e9f03b55009a79d23ff124f
 tests/images/examples.test__clouds_robin.png 73a0f6d6267f7f248643bc733e3b2699af47b711286e449171310e9fb2024f90
 tests/images/examples.test__curvilinear.from_2d__orca_moll.png 39e693dccfbefe67f1ed438341342f1c6b5fa11f24b3d46c4706d8514c043d45
 tests/images/examples.test__curvilinear.from_2d__orca.png 492868315f090aad25278660ffd97df31e7158f5c142962e8e23e16773199ade
+tests/images/examples.test__extraction.wedge_manifold.png 1678ce568e440ac226c620db9d489884fe3f4b59f8b2c5faa29dcb23e8fa7ff3
 tests/images/examples.test__point_cloud.from_points__orca_cloud_eqc.png e41921a712d335061b7507b9fa0880d93a52d7391cb4c586f163d911b54e8362
 tests/images/examples.test__point_cloud.from_points__orca_cloud.png 8f723740ca12bfc9c02a29806a777e985d2a3a64a187e39e8a78c1d5ad1a29ff
 tests/images/examples.test__rectilinear.from_1d__oisst_eqc.png b4e1d6b0984dbde1b7123b62eb8643206b83a399df90d32d877bf42089863350

src/geovista/examples/extraction/README.rst

@@ -0,0 +1,2 @@
+Region Manifold Extraction
+==========================

src/geovista/examples/extraction/__init__.py

@@ -0,0 +1,24 @@
+# Copyright (c) 2021, GeoVista Contributors.
+#
+# This file is part of GeoVista and is distributed under the 3-Clause BSD license.
+# See the LICENSE file in the package root directory for licensing details.
+
+"""The examples showcase various geovista features and capabilities.
+
+Each example is importable and runnable as a standalone script from the command
+line.
+
+Note that, the examples are installed as part of the geovista package
+and can be easily accessed through the geovista command line interface
+(CLI) entry-point.
+
+.. code: bash
+
+  # For further details refer to the geovista examples (CLI) help.
+  geovista examples --help
+
+Notes
+-----
+.. versionadded:: 0.6.0
+
+"""

src/geovista/examples/extraction/wedge_manifold.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+# Copyright (c) 2021, GeoVista Contributors.
+#
+# This file is part of GeoVista and is distributed under the 3-Clause BSD license.
+# See the LICENSE file in the package root directory for licensing details.
+
+"""
+Wedge Extraction
+----------------
+
+This example demonstrates how to extract a region from a mesh using a geodesic manifold.
+
+📋 Summary
+^^^^^^^^^^
+Creates a mesh from 1-D latitude and longitude unstructured points and
+connectivity.
+
+Isolates wedges of this mesh and plots them onto natural earth base layer
+texture.
+
+It uses an unstructured Met Office LFRic C48 cubed-sphere of surface altitude
+data.
+
+The resulting mesh contains quad cells and is constructed from CF UGRID
+unstructured cell points and connectivity.
+
+.. tags::
+
+    component: coastlines,
+    component: manifold,
+    component: texture,
+    domain: orography,
+    load: unstructured
+
+----
+
+"""  # noqa: D205,D212,D400
+
+from __future__ import annotations
+
+import geovista as gv
+from geovista.geodesic import wedge
+from geovista.pantry.data import lfric_orog
+import geovista.theme
+
+
+def main() -> None:
+    """Extract and plot 3 wedge regions, each using different enclosure methods.
+
+    Notes
+    -----
+    .. versionadded:: 0.6.0
+
+    """
+    # Load the sample data.
+    sample = lfric_orog()
+
+    # Create the mesh from the sample data.
+    mesh = gv.Transform.from_unstructured(
+        sample.lons,
+        sample.lats,
+        connectivity=sample.connectivity,
+        data=sample.data,
+        name=sample.name,
+    )
+
+    # Calculate the sample data range.
+    clim = mesh.get_data_range()
+
+    # Create 3 different wedge geodesic bounding-box manifolds.
+    bbox_1 = wedge(-25, 25)
+    bbox_2 = wedge(65, 115)
+    bbox_3 = wedge(155, 205)
+
+    # Extract the underlying sample mesh within each manifold using a different
+    # preference which defines the criterion of sample mesh cell enclosure.
+    region_1 = bbox_1.enclosed(mesh, preference="cell")
+    region_2 = bbox_2.enclosed(mesh, preference="point")
+    region_3 = bbox_3.enclosed(mesh, preference="center")
+
+    p = gv.GeoPlotter()
+    sargs = {"title": f"{sample.name} / {sample.units}", "fmt": "%.1f"}
+
+    # Add the 3 extracted regions.
+    p.add_mesh(region_1, clim=clim, scalar_bar_args=sargs)
+    p.add_mesh(region_2, clim=clim, scalar_bar_args=sargs)
+    p.add_mesh(region_3, clim=clim, scalar_bar_args=sargs)
+
+    # Add the surface boundary of each wedge region.
+    p.add_mesh(bbox_1.boundary(mesh), color="red", line_width=3)
+    p.add_mesh(bbox_2.boundary(mesh), color="purple", line_width=3)
+    p.add_mesh(bbox_3.boundary(mesh), color="orange", line_width=3)
+
+    # Add coastlines and a texture mapped base layer.
+    p.add_base_layer(texture=gv.natural_earth_hypsometric())
+    p.add_coastlines(resolution="10m")
+
+    # Define a specific camera position.
+    p.view_vector(vector=(1, 1, 1))
+    p.camera.zoom(1.2)
+
+    p.show_axes()
+    p.show()
+
+
+if __name__ == "__main__":
+    main()