Banded contour example (#1305)

* banded contour example

* changelog + registry

* change changelog ref

* review comments

* organise tags

* add triangulate tag

changelog/1305.documentation.rst

@@ -0,0 +1 @@
+Added a gallery example using :meth:`pyvista.PolyDataFilters.contour_banded`. (:user:`HGWright`)

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 = "2025.01.4"
+DATA_VERSION: str = "2025.01.5"
 """The ``geovista-data`` repository version for :mod:`geovista` resources."""
 
 GEOVISTA_CACHEDIR: str = "GEOVISTA_CACHEDIR"

src/geovista/cache/registry.txt

@@ -37,6 +37,7 @@ rasters/fuji_dem.tif.bz2 2e51a278e62304d671e15be8f6cdbea0cb7d477643b97b95c4d4706
 rasters/japan_map.png.bz2 7b39023b5d26e79475d2dba92269593d5ce46c14ed5859079c79d1fa0ec0987f
 tests/images/examples.test__clouds.png a650d7717324453f86e9f03b55009a79d23ff124fee58791bfe0d558fdfc1f98
 tests/images/examples.test__clouds_robin.png 73a0f6d6267f7f248643bc733e3b2699af47b711286e449171310e9fb2024f90
+tests/images/examples.test__contour.banded_contour.png 7f2ecf50e0fb9b104a1ddf57cfddb3d19724f37b96d1a052aabb053b4df68735
 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

src/geovista/examples/contour/README.rst

@@ -0,0 +1,4 @@
+.. _gv-examples-contour:
+
+Contour
+=======

src/geovista/examples/contour/__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/contour/banded_contour.py

@@ -0,0 +1,95 @@
+#!/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.
+
+"""
+Banded Contour
+--------------
+
+This example demonstrates how to use banded contours.
+
+📋 Summary
+^^^^^^^^^^
+Uses an unstructured Met Office LFRic C48 cubed-sphere mesh of surface altitude
+data.
+
+First triangulate the mesh as this is the preferred geometry when using the contour
+filter.
+
+Then we threshold the surface altitude by height such that all sea-level cells
+are removed from the mesh.
+
+The remaining land-based cells of the mesh are contoured and rendered using a
+qualitative colormap (``Set3``) containing 12 unique colours. We use the
+``contour_banded`` filter to generate 13 contours and the associated banded contour
+edges.
+
+A Natural Earth base layer is also rendered along with the Natural Earth coastlines.
+
+.. tags::
+
+    component: coastlines, component: texture,
+    domain: orography,
+    filter: cast, filter: contour, filter: threshold, filter: triangulate,
+    sample: unstructured,
+    style: colormap
+
+----
+
+"""  # noqa: D205,D212,D400
+
+from __future__ import annotations
+
+import geovista
+from geovista.common import cast_UnstructuredGrid_to_PolyData as cast
+from geovista.pantry.meshes import lfric_orog
+import geovista.theme
+
+
+def main() -> None:
+    """Plot banded contours of surface altitude with a qualitative colormap.
+
+    Notes
+    -----
+    .. versionadded:: 0.6.0
+
+    """
+    # Load the sample mesh.
+    mesh = lfric_orog()
+
+    # Triangulate the mesh prior to contouring.
+    mesh.triangulate(inplace=True)
+
+    # Remove only those cells where all their vertices have a surface altitude
+    # below the specified height threshold.
+    height = 1e-1
+    mesh = cast(mesh.threshold(height, preference="point"))
+
+    # Generate the filled contours and contour edges between bands.
+    n_contours = 13
+    contours, edges = mesh.contour_banded(n_contours)
+
+    p = geovista.GeoPlotter()
+
+    sargs = {"title": "Surface Altitude / m", "fmt": "%.0f"}
+    p.add_mesh(contours, cmap="Set3", n_colors=n_contours - 1, scalar_bar_args=sargs)
+    p.add_mesh(edges, color="black", zlevel=1)
+
+    p.add_base_layer(texture=geovista.natural_earth_1())
+    p.add_coastlines()
+
+    # Render the scene using super-sample anti-aliasing.
+    p.enable_anti_aliasing(aa_type="ssaa")
+
+    # Define a specific camera position.
+    p.view_vector(vector=(0, 1, 0.5))
+    p.camera.zoom(1.2)
+
+    p.add_axes()
+    p.show()
+
+
+if __name__ == "__main__":
+    main()