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.

ノート#

Added in version 0.1.0.

What is a Mesh?

属性#

`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.
`NAME_VECTORS`	Default array name for mesh vectors.
`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.

Classes#

Transform

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

モジュール内容#

class geovista.bridge.Transform(xs, ys, /, *, connectivity=None, start_index=None, crs=None, radius=None, zlevel=None, zscale=None, clean=None)[ソース]#

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

ノート#

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 1D array of x-values, in canonical crs units, defining the vertices of each face in the mesh.
ysArrayLike: A 1D 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 2D (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 2D, 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.

ノート

Added in version 0.1.0.

__call__(*, data=None, name=None)[ソース]#

Build the mesh and attach the provided data to faces or nodes.

Parameters:

dataArrayLike, optional: Data to be optionally attached to the mesh face or nodes.
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.

Returns:

PolyData: The spherical mesh.

ノート

..versionadded:: 0.1.0

classmethod from_1d(xs, ys, /, *, data=None, name=None, crs=None, rgb=False, radius=None, zlevel=None, zscale=None, clean=None)[ソース]#

Build a quad-faced mesh from contiguous 1D 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 1D 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 1D 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.

ノート

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)[ソース]#

Build a quad-faced mesh from 2D 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 2D 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 2D 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.

ノート

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, vectors=None, vectors_crs=None, vectors_name=None)[ソース]#

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

Note that optional mesh data or vectors must be in the same order as the spatial points.

Parameters:

xsArrayLike: A 1D, 2D or 3D array of point-cloud x-values, in canonical crs units. Must have the same shape as the ys.
ysArrayLike: A 1D, 2D or 3D 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.
vectorsVectorLike, optional: A tuple of 2 or 3 arrays of the same shape as xs and ys. These give eastward (U), northward (V) and optionally upward (W) vector components, which are converted to an [N, 3] array of 3D vectors and attached to the resultant mesh, see vectors_name. This can be used to generate glyphs (such as arrows) and streamlines.
vectors_crsCRSLike, optional: The Coordinate Reference System of the provided vectors. May be anything accepted by pyproj.crs.CRS.from_user_input(). Defaults to the same as crs. Note that vectors_crs only specifies horizontal orientation of the vectors. Their magnitudes are always spatial distance, and the vertical component is always radial (i.e., "upwards").
vectors_namestr, optional: The name of the vectors array to be attached to the mesh. If vectors is provided but with no vectors_name, defaults to NAME_VECTORS.

Returns:

PolyData: The point-cloud mesh with optional vectors attached.

ノート

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)[ソース]#

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, default=1: The band index to read from the GeoTIFF. Note that the band index is one-based.
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.

ノート

Added in version 0.5.0.

注意

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:

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

Static Scene

../../../../../_images/index-b7343bf723387d45_00_00.png

Interactive Scene

classmethod from_unstructured(xs, ys, /, *, connectivity=None, data=None, start_index=None, name=None, crs=None, rgb=False, radius=None, zlevel=None, zscale=None, clean=None)[ソース]#

Build a mesh from unstructured 1D 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 and ys (data can only be attached to points or cells).

Parameters:

xsArrayLike: A 1D array of x-values, in canonical crs units, defining the vertices of each face in the mesh.
ysArrayLike: A 1D 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 2D (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 2D, 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.

ノート

Added in version 0.1.0.

classmethod to_structured_grid(xs, ys, zs, /, *, data=None, name=None, crs=None, radius=None, zlevel=None, zscale=None)[ソース]#

Build a structured grid from contiguous 1D spatial coordinates.

The 3D structured grid consists of cubic voxel cells which are constructed from the 1D spatial coordinates defining the bounds of the cells in each dimension.

Parameters:

xsArrayLike: The 1D array of x-values, in canonical crs units, defining the x-axis cell bounds of the grid.
ysArrayLike: The 1D array of y-values, in canonical crs units, defining the y-axis cell bounds of the grid.
zsArrayLike: The 1D array of z-values, in canonical crs units, defining the z-axis cell bounds of the grid.
dataArrayLike | None, optional: Data to be optionally attached to the structured grid cells or points. Note that the expected data dimensionality is (Z, Y, X) order.
namestr | None, optional: The name of the optional data array to be attached to the grid. 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 spatial coordinates. May be anything accepted by pyproj.crs.CRS.from_user_input(). Defaults to EPSG:4326 i.e., WGS 84.
radiusfloat | None, optional: The radius of the grid 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.

Returns:

StructuredGrid: The spherical structured grid.

ノート

Added in version 0.6.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.NAME_VECTORS: str = 'vector_data'#: Default array name for mesh vectors.

type geovista.bridge.PathLike = str | pathlib.Path#: Type alias for an asset file path.

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

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

geovista.bridge

On this page

geovista.bridge#

ノート#

属性#

Classes#

モジュール内容#

ノート#