iris.experimental.geovista#

Experimental module for using some GeoVista operations with Iris cubes.

iris.experimental.geovista.cube_to_polydata(cube, **kwargs)[source]#

Create a pyvista.PolyData object from a Cube.

The resulting PolyData object can be plotted using a geovista.geoplotter.GeoPlotter.

Uses geovista.bridge.Transform to parse the cube’s information - one of: from_1d() / from_2d() / from_unstructured().

Parameters:

cube (Cube) – The Cube containing the spatial information and data for creating the class:~pyvista.PolyData.
**kwargs (dict, optional) – Additional keyword arguments to be passed to the relevant Transform method (e.g zlevel).

Returns:

The PolyData object representing the cube’s spatial information and data.

Return type:

PolyData

Raises:

NotImplementedError – If a Cube with too many dimensions is passed. Only the horizontal data can be represented, meaning a 2D Cube, or 1D Cube if the horizontal space is described by MeshCoords.

Examples

>>> from iris.experimental.geovista import cube_to_polydata

Converting a standard 2-dimensional Cube with 1-dimensional coordinates:

>>> print(cube.summary(shorten=True))
air_temperature / (K)               (latitude: 73; longitude: 96)
>>> print(cube_to_polydata(cube))
PolyData (...
  N Cells:    7008
  N Points:   7178
  N Strips:   0
  X Bounds:   -9.992e-01, 9.992e-01
  Y Bounds:   -9.992e-01, 9.992e-01
  Z Bounds:   -1.000e+00, 1.000e+00
  N Arrays:   4

Configure the conversion by passing additional keyword arguments:

>>> print(cube_to_polydata(cube, radius=2))
PolyData (...
  N Cells:    7008
  N Points:   7178
  N Strips:   0
  X Bounds:   -1.998e+00, 1.998e+00
  Y Bounds:   -1.998e+00, 1.998e+00
  Z Bounds:   -2.000e+00, 2.000e+00
  N Arrays:   4

Converting a Cube that has a mesh describing its horizontal space:

>>> print(cube_mesh.summary(shorten=True))
synthetic / (1)                     (-- : 96)
>>> print(cube_to_polydata(cube_mesh))
PolyData (...
  N Cells:    96
  N Points:   98
  N Strips:   0
  X Bounds:   -1.000e+00, 1.000e+00
  Y Bounds:   -1.000e+00, 1.000e+00
  Z Bounds:   -1.000e+00, 1.000e+00
  N Arrays:   4

Remember to reduce the dimensionality of your Cube to just be the horizontal space:

>>> print(cube_w_time.summary(shorten=True))
air_temperature / (K)               (time: 240; latitude: 37; longitude: 49)
>>> print(cube_to_polydata(cube_w_time[0, :, :]))
PolyData (...
  N Cells:    1813
  N Points:   1900
  N Strips:   0
  X Bounds:   -6.961e-01, 6.961e-01
  Y Bounds:   -9.686e-01, -3.411e-01
  Z Bounds:   2.483e-01, 8.714e-01
  N Arrays:   4

iris.experimental.geovista.extract_unstructured_region(cube, polydata, region, **kwargs)[source]#

Index a Cube with a mesh to a specific region.

Uses geovista.geodesic.BBox.enclosed() to identify the cube indices that are within the specified region (region being a BBox class).

Parameters:

cube (Cube) – The cube to be indexed (must have a mesh).
polydata (pyvista.PolyData) – A PolyData representing the same horizontal space as cube. The region extraction is first applied to polydata, with the resulting indices then applied to cube. In many cases polydata can be created by applying cube_to_polydata() to cube.
region (geovista.geodesic.BBox) – A BBox representing the region to be extracted.
**kwargs (dict, optional) – Additional keyword arguments to be passed to the geovista.geodesic.BBox.enclosed() method (e.g preference).

Returns:

The region extracted cube.

Return type:

Cube

Raises:

ValueError – If polydata and the mesh on cube do not have the same shape.

Examples

The parameters of extract_unstructured_region() have been designed with flexibility and reuse in mind. This is demonstrated below.

>>> from geovista import BBox
>>> from iris.experimental.geovista import cube_to_polydata, extract_unstructured_region
>>> print(cube_w_mesh.shape)
(72, 96)
>>> # The mesh dimension represents the horizontal space of the cube.
>>> print(cube_w_mesh.shape[cube_w_mesh.mesh_dim()])
96
>>> cube_polydata = cube_to_polydata(cube_w_mesh[0, :])
>>> extracted_cube = extract_unstructured_region(
...     cube=cube_w_mesh,
...     polydata=cube_polydata,
...     region=BBox(lons=[0, 70, 70, 0], lats=[-25, -25, 45, 45]),
... )
>>> print(extracted_cube.shape)
(72, 11)

Now reuse the same cube and polydata to extract a different region:

>>> new_region = BBox(lons=[0, 35, 35, 0], lats=[-25, -25, 45, 45])
>>> extracted_cube = extract_unstructured_region(
...     cube=cube_w_mesh,
...     polydata=cube_polydata,
...     region=new_region,
... )
>>> print(extracted_cube.shape)
(72, 6)

Now apply the same region extraction to a different cube that has the same horizontal shape:

>>> print(other_cube_w_mesh.shape)
(20, 96)
>>> extracted_cube = extract_unstructured_region(
...     cube=other_cube_w_mesh,
...     polydata=cube_polydata,
...     region=new_region,
... )
>>> print(extracted_cube.shape)
(20, 6)

Arbitrary keywords can be passed down to geovista.geodesic.BBox.enclosed() (outside in this example):

>>> extracted_cube = extract_unstructured_region(
...     cube=other_cube_w_mesh,
...     polydata=cube_polydata,
...     region=new_region,
...     outside=True,
... )
>>> print(extracted_cube.shape)
(20, 90)