geovista.bridge

`geovista.bridge`#

Transform structured grids and unstructured meshes to PyVista format.

This module provides the Transform factory class for transforming rectilinear, curvilinear, and unstructured geospatial data into geolocated PyVista mesh instances.

Notes#

Added in version 0.1.0.

What is a Mesh?

Module Contents#

Classes#

Transform

Build a mesh from spatial points, connectivity, data and CRS metadata.

Attributes#

`BRIDGE_CLEAN`	Whether mesh cleaning performed by the bridge.
`NAME_CELLS`	Default array name for data on the mesh cells.
`NAME_POINTS`	Default array name for data on the mesh points.
`PathLike`	Type alias for an asset file path.
`RIO_SIEVE_SIZE`	The default size of the `rasterio.features.sieve()` filter.
`Shape`	Type alias for a tuple of integers.

class geovista.bridge.Transform(xs, ys, connectivity=None, start_index=None, crs=None, radius=None, zlevel=None, zscale=None, clean=None)[source]#

Build a mesh from spatial points, connectivity, data and CRS metadata.

Notes#

Added in version 0.1.0.

Build a mesh from spatial points, connectivity, data and CRS metadata.

Convenience factory to build multiple identical meshes but with different face or node data.

Parameters:

xsArrayLike: A 1-D array of x-values, in canonical crs units, defining the vertices of each face in the mesh.
ysArrayLike: A 1-D array of y-values, in canonical crs units, defining the vertices of each face in the mesh.
connectivityArrayLike or Shape, optional: Defines the topology of each face in the unstructured mesh in terms of indices into the provided xs and ys mesh geometry arrays. The connectivity is a 2-D (M, N) array, where M is the number of mesh faces, and N is the number of nodes per face. Alternatively, an (M, N) tuple defining the connectivity shape may be provided instead, given that the xs and ys define M*N points (at most) in the mesh geometry. If no connectivity is provided, and the xs and ys are 2-D, then their shape is used to determine the connectivity. Also, note that masked connectivity may be used to define a mesh consisting of different shaped faces.
start_indexint, default=0: Specify the base index of the provided connectivity in the closed interval [0, 1]. For example, if start_index=1, then the start_index will be subtracted from the connectivity to result in 0-based indices into the provided mesh geometry. If no start_index is provided, then it will be determined from the connectivity.
crsCRSLike, optional: The Coordinate Reference System of the provided xs and ys. May be anything accepted by pyproj.crs.CRS.from_user_input(). Defaults to EPSG:4326 i.e., WGS 84.
radiusfloat, optional: The radius of the mesh sphere. Defaults to RADIUS.
zlevelint, default=0: The z-axis level. Used in combination with the zscale to offset the radius by a proportional amount i.e., radius * zlevel * zscale.
zscalefloat, optional: The proportional multiplier for z-axis zlevel. Defaults to ZLEVEL_SCALE.
cleanbool, optional: Specify whether to merge duplicate points, remove unused points, and/or remove degenerate cells in the resultant mesh. See pyvista.PolyDataFilters.clean(). Defaults to BRIDGE_CLEAN.

Notes

Added in version 0.1.0.

classmethod from_1d(xs, ys, data=None, name=None, crs=None, rgb=False, radius=None, zlevel=None, zscale=None, clean=None)[source]#

Build a quad-faced mesh from contiguous 1-D x-values and y-values.

This allows the construction of a uniform or rectilinear quad-faced (M, N) mesh grid, where the mesh has M-faces in the y-axis, and N-faces in the x-axis, resulting in a mesh consisting of M*N faces.

The provided xs and ys will be projected from their crs to geographic longitude and latitude values.

Parameters:

xsArrayLike: A 1-D array of x-values, in canonical crs units, defining the contiguous face x-value boundaries of the mesh. Creating a mesh with N-faces in the crs x-axis requires a (N+1,) array. Alternatively, a (N, 2) contiguous bounds array may be provided.
ysArrayLike: A 1-D array of y-values, in canonical crs units, defining the contiguous face y-value boundaries of the mesh. Creating a mesh with M-faces in the crs y-axis requires a (M+1,) array. Alternatively, a (M, 2) contiguous bounds array may be provided.
dataArrayLike, optional: Data to be optionally attached to the mesh. The size of the data must match either the shape of the fully formed mesh points (M+1)*(N+1), or the number of mesh faces, M*N (but see the rgb parameter).
namestr, optional: The name of the optional data array to be attached to the mesh. If data is provided but with no name, defaults to either NAME_POINTS or NAME_CELLS.
crsCRSLike, optional: The Coordinate Reference System of the provided xs and ys. May be anything accepted by pyproj.crs.CRS.from_user_input(). Defaults to EPSG:4326 i.e., WGS 84.
rgbbool, default=False: Whether data is an RGB or RGBA image. When rgb=True, data is expected to have an extra dimension for the colour channels (length 3 or 4).
radiusfloat, optional: The radius of the sphere. Defaults to RADIUS.
zlevelint, default=0: The z-axis level. Used in combination with the zscale to offset the radius by a proportional amount i.e., radius * zlevel * zscale.
zscalefloat, optional: The proportional multiplier for z-axis zlevel. Defaults to ZLEVEL_SCALE.
cleanbool, optional: Specify whether to merge duplicate points, remove unused points, and/or remove degenerate cells in the resultant mesh. See pyvista.PolyDataFilters.clean(). Defaults to BRIDGE_CLEAN.

Returns:

PolyData: The quad-faced spherical mesh.

Notes

Added in version 0.1.0.

classmethod from_2d(xs, ys, data=None, name=None, crs=None, rgb=False, radius=None, zlevel=None, zscale=None, clean=None)[source]#

Build a quad-faced mesh from 2-D x-values and y-values.

This allows the construction of a uniform, rectilinear or curvilinear quad-faced (M, N) mesh grid, where the mesh has M-faces in the y-axis, and N-faces in the x-axis, resulting in a mesh consisting of M*N faces.

The provided xs and ys define the four vertices of each quad-face in the mesh for the native crs, which will then be projected to geographic longitude and latitude values.

Parameters:

xsArrayLike: A 2-D array of x-values, in canonical crs units, defining the face x-value boundaries of the mesh. Creating a (M, N) mesh requires a (M+1, N+1) x-axis array. Alternatively, a (M, N, 4) array may be provided.
ysArrayLike: A 2-D array of y-values, in canonical crs units, defining the face y-value boundaries of the mesh. Creating a (M, N) mesh requires a (M+1, N+1) y-axis array. Alternatively, a (M, N, 4) array may be provided.
dataArrayLike, optional: Data to be optionally attached to the mesh. The size of the data must match either the shape of the fully formed mesh points (M+1)*(N+1), or the number of mesh faces, M*N (but see the rgb parameter).
namestr, optional: The name of the optional data array to be attached to the mesh. If data is provided but with no name, defaults to either NAME_POINTS or NAME_CELLS.
crsCRSLike, optional: The Coordinate Reference System of the provided xs and ys. May be anything accepted by pyproj.crs.CRS.from_user_input(). Defaults to EPSG:4326 i.e., WGS 84.
rgbbool, default=False: Whether data is an RGB or RGBA image. When rgb=True, data is expected to have an extra dimension for the colour channels (length 3 or 4).
radiusfloat, optional: The radius of the sphere. Defaults to RADIUS.
zlevelint, default=0: The z-axis level. Used in combination with the zscale to offset the radius by a proportional amount i.e., radius * zlevel * zscale.
zscalefloat, optional: The proportional multiplier for z-axis zlevel. Defaults to ZLEVEL_SCALE.
cleanbool, optional: Specify whether to merge duplicate points, remove unused points, and/or remove degenerate cells in the resultant mesh. See pyvista.PolyDataFilters.clean(). Defaults to BRIDGE_CLEAN.

Returns:

PolyData: The quad-faced spherical mesh.

Notes

Added in version 0.1.0.

classmethod from_points(xs, ys, data=None, name=None, crs=None, radius=None, zlevel=None, zscale=None, clean=None)[source]#

Build a point-cloud mesh from x-values, y-values and z-levels.

Note that, any optional mesh data provided must be in the same order as the spatial points.

Parameters:

xsArrayLike: A 1-D, 2-D or 3-D array of point-cloud x-values, in canonical crs units. Must have the same shape as the ys.
ysArrayLike: A 1-D, 2-D or 3-D array of point-cloud y-values, in canonical crs units. Must have the same shape as the xs.
dataArrayLike, optional: Data to be optionally attached to the mesh points defined by xs and ys.
namestr, optional: The name of the optional data array to be attached to the mesh. If data is provided but with no name, defaults to NAME_POINTS.
crsCRSLike, optional: The Coordinate Reference System of the provided xs and ys. May be anything accepted by pyproj.crs.CRS.from_user_input(). Defaults to EPSG:4326 i.e., WGS 84.
radiusfloat, optional: The radius of the mesh point-cloud. Defaults to RADIUS.
zlevelint or ArrayLike, default=0: The z-axis level. Used in combination with the zscale to offset the radius by a proportional amount i.e., radius * zlevel * zscale. If zlevel is not a scalar, then its shape must match or broadcast with the shape of the xs and ys.
zscalefloat, optional: The proportional multiplier for z-axis zlevel. Defaults to ZLEVEL_SCALE.
cleanbool, optional: Specify whether to merge duplicate points. See pyvista.PolyDataFilters.clean(). Defaults to BRIDGE_CLEAN.

Returns:

PolyData: The point-cloud spherical mesh.

Notes

Added in version 0.2.0.

classmethod from_tiff(fname, name=None, band=1, rgb=False, sieve=False, size=None, extract=False, radius=None, zlevel=None, zscale=None, clean=None)[source]#

Build a quad-faced mesh from the GeoTIFF.

Note that, the GeoTIFF data will be located on the points of the resultant mesh.

Parameters:

fnamePathLike: The file path to the GeoTIFF.
namestr, optional: The name of the GeoTIFF data array to be attached to the mesh. Defaults to NAME_POINTS. Note that, {units} may be used as a placeholder for the units of the data array e.g., "Elevation / {units}".
bandint, optional: The band index to read from the GeoTIFF. Note that, the band index is one-based. Defaults to the first band i.e., band=1.
rgbbool, default=False: Specify whether to read the GeoTIFF as an RGB or RGBA image. When rgb=True, the band index is ignored.
sievebool, default=False: Specify whether to sieve the GeoTIFF mask to remove small connected regions. See rasterio.features.sieve() for more information.
sizeint, optional: The size of the sieve filter. Defaults to RIO_SIEVE_SIZE.
extractbool, default=False: Specify whether to extract cells from the mesh with no masked points.
radiusfloat, optional: The radius of the mesh sphere. Defaults to RADIUS.
zlevelint, default=0: The z-axis level. Used in combination with the zscale to offset the radius by a proportional amount i.e., radius * zlevel * zscale.
zscalefloat, optional: The proportional multiplier for z-axis zlevel. Defaults to ZLEVEL_SCALE.
cleanbool, optional: Specify whether to merge duplicate points, remove unused points, and/or remove degenerate cells in the resultant mesh. See pyvista.PolyDataFilters.clean(). Defaults to BRIDGE_CLEAN.

Returns:

PolyData: The GeoTIFF spherical mesh.

Notes

Added in version 0.5.0.

Attention

Optional package dependency rasterio is required.

Examples

>>> from geovista import GeoPlotter, Transform
>>> from geovista.pantry import fetch_raster
>>> from geovista.pantry.textures import natural_earth_1

Render the GeoTIFF RGB image as a geolocated mesh.

First, rasterio.features.sieve() the GeoTIFF image to remove several unwanted masked regions within the interior of the image, due to a lack of dynamic range in the uint8 image data. Then, extract the mesh to remove cells with no masked points.

>>> fname = fetch_raster("bahamas_rgb.tif")
>>> mesh = Transform.from_tiff(fname, rgb=True, sieve=True, extract=True)

Now render the result:

>>> plotter = GeoPlotter()
>>> _ = plotter.add_mesh(mesh, rgb=True)
>>> plotter.view_poi()
>>> _ = plotter.add_base_layer(texture=natural_earth_1(), zlevel=0)
>>> _ = plotter.add_coastlines(color="white")
>>> plotter.show()

Static Scene

../../../../../_images/index-1_00_00.png

Interactive Scene

classmethod from_unstructured(xs, ys, connectivity=None, data=None, start_index=None, name=None, crs=None, rgb=None, radius=None, zlevel=None, zscale=None, clean=None)[source]#

Build a mesh from unstructured 1-D x-values and y-values.

The connectivity defines the topology of faces within the unstructured mesh. This is represented in terms of indices into the provided xs and ys mesh geometry.

Note that any optional mesh data provided must be in the same order as the mesh face connectivity, or in the same order as the points described by xs & ys (data can be on points or on cells).

Parameters:

xsArrayLike: A 1-D array of x-values, in canonical crs units, defining the vertices of each face in the mesh.
ysArrayLike: A 1-D array of y-values, in canonical crs units, defining the vertices of each face in the mesh.
connectivityArrayLike or Shape, optional: Defines the topology of each face in the unstructured mesh in terms of indices into the provided xs and ys mesh geometry arrays. The connectivity is a 2-D (M, N) array, where M is the number of mesh faces, and N is the number of nodes per face. Alternatively, an (M, N) tuple defining the connectivity shape may be provided instead, given that the xs and ys define M*N points (at most) in the mesh geometry. If no connectivity is provided, and the xs and ys are 2-D, then their shape is used to determine the connectivity. Also, note that masked connectivity may be used to define a mesh consisting of different shaped faces.
dataArrayLike, optional: Data to be optionally attached to the mesh face or nodes.
start_indexint, default=0: Specify the base index of the provided connectivity in the closed interval [0, 1]. For example, if start_index=1, then the start_index will be subtracted from the connectivity to result in 0-based indices into the provided mesh geometry. If no start_index is provided, then it will be determined from the connectivity.
namestr, optional: The name of the optional data array to be attached to the mesh. If data is provided but with no name, defaults to either NAME_POINTS or NAME_CELLS.
crsCRSLike, optional: The Coordinate Reference System of the provided xs and ys. May be anything accepted by pyproj.crs.CRS.from_user_input(). Defaults to EPSG:4326 i.e., WGS 84.
rgbbool, default=False: Whether data is an RGB or RGBA image. When rgb=True, data is expected to have an extra dimension for the colour channels (length 3 or 4).
radiusfloat, optional: The radius of the mesh sphere. Defaults to RADIUS.
zlevelint, default=0: The z-axis level. Used in combination with the zscale to offset the radius by a proportional amount i.e., radius * zlevel * zscale.
zscalefloat, optional: The proportional multiplier for z-axis zlevel. Defaults to ZLEVEL_SCALE.
cleanbool, optional: Specify whether to merge duplicate points, remove unused points, and/or remove degenerate cells in the resultant mesh. See pyvista.PolyDataFilters.clean(). Defaults to BRIDGE_CLEAN.

Returns:

PolyData: The (M*N)-faced spherical mesh.

Notes

Added in version 0.1.0.

geovista.bridge.BRIDGE_CLEAN: bool = False#: Whether mesh cleaning performed by the bridge.

geovista.bridge.NAME_CELLS: str = 'cell_data'#: Default array name for data on the mesh cells.

geovista.bridge.NAME_POINTS: str = 'point_data'#: Default array name for data on the mesh points.

geovista.bridge.PathLike: TypeAlias = str | PurePath#: Type alias for an asset file path.

geovista.bridge.RIO_SIEVE_SIZE: int = 800#: The default size of the rasterio.features.sieve() filter.

geovista.bridge.Shape: TypeAlias = tuple[int]#: Type alias for a tuple of integers.

geovista.bridge

On this page

geovista.bridge#

Notes#

Module Contents#

Classes#

Attributes#

Notes#

`geovista.bridge`#