geovista.bridge
#
Transform structured grids and unstructured meshes.
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.
Module Contents#
Classes#
Build a mesh from spatial points, connectivity, data and CRS metadata. 
Attributes#
Whether mesh cleaning performed by the bridge. 

Default array name for data on the mesh cells. 

Default array name for data on the mesh points. 

Type alias for an asset file path. 

The default size of the 

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:
 xs
ArrayLike
A 1D array of xvalues, in canonical crs units, defining the vertices of each face in the mesh.
 ys
ArrayLike
A 1D array of yvalues, in canonical crs units, defining the vertices of each face in the mesh.
 connectivity
ArrayLike
orShape
, 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, andN
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_index
int
, 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 0based indices into the provided mesh geometry. If no start_index is provided, then it will be determined from the connectivity.
 crs
CRSLike
, optional The Coordinate Reference System of the provided xs and ys. May be anything accepted by
pyproj.crs.CRS.from_user_input()
. Defaults toEPSG:4326
i.e.,WGS 84
. radius
float
, optional The radius of the mesh sphere. Defaults to
RADIUS
. zlevel
int
, default=0 The zaxis level. Used in combination with the zscale to offset the radius by a proportional amount i.e.,
radius * zlevel * zscale
. zscale
float
, optional The proportional multiplier for zaxis 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. Defaults to
BRIDGE_CLEAN
.
 xs
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 quadfaced mesh from contiguous 1D xvalues and yvalues.
This allows the construction of a uniform or rectilinear quadfaced (M, N) mesh grid, where the mesh has Mfaces in the yaxis, and Nfaces in the xaxis, 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:
 xs
ArrayLike
A 1D array of xvalues, in canonical crs units, defining the contiguous face xvalue boundaries of the mesh. Creating a mesh with Nfaces in the crs xaxis requires a (N+1,) array. Alternatively, a (N, 2) contiguous bounds array may be provided.
 ys
ArrayLike
A 1D array of yvalues, in canonical crs units, defining the contiguous face yvalue boundaries of the mesh. Creating a mesh with Mfaces in the crs yaxis requires a (M+1,) array. Alternatively, a (M, 2) contiguous bounds array may be provided.
 data
ArrayLike
, 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.
 name
str
, 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
orNAME_CELLS
. crs
CRSLike
, optional The Coordinate Reference System of the provided xs and ys. May be anything accepted by
pyproj.crs.CRS.from_user_input()
. Defaults toEPSG:4326
i.e.,WGS 84
. rgbbool, default=False
Whether the data is an
RGB
orRGBA
image. radius
float
, optional The radius of the sphere. Defaults to
RADIUS
. zlevel
int
, default=0 The zaxis level. Used in combination with the zscale to offset the radius by a proportional amount i.e.,
radius * zlevel * zscale
. zscale
float
, optional The proportional multiplier for zaxis 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. Defaults to
BRIDGE_CLEAN
.
 xs
 Returns:
PolyData
The quadfaced 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 quadfaced mesh from 2D xvalues and yvalues.
This allows the construction of a uniform, rectilinear or curvilinear quadfaced (M, N) mesh grid, where the mesh has Mfaces in the yaxis, and Nfaces in the xaxis, resulting in a mesh consisting of M*N faces.
The provided xs and ys define the four vertices of each quadface in the mesh for the native crs, which will then be projected to geographic longitude and latitude values.
 Parameters:
 xs
ArrayLike
A 2D array of xvalues, in canonical crs units, defining the face xvalue boundaries of the mesh. Creating a (M, N) mesh requires a (M+1, N+1) xaxis array. Alternatively, a (M, N, 4) array may be provided.
 ys
ArrayLike
A 2D array of yvalues, in canonical crs units, defining the face yvalue boundaries of the mesh. Creating a (M, N) mesh requires a (M+1, N+1) yaxis array. Alternatively, a (M, N, 4) array may be provided.
 data
ArrayLike
, 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.
 name
str
, 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
orNAME_CELLS
. crs
CRSLike
, optional The Coordinate Reference System of the provided xs and ys. May be anything accepted by
pyproj.crs.CRS.from_user_input()
. Defaults toEPSG:4326
i.e.,WGS 84
. rgbbool, default=False
Whether the data is an
RGB
orRGBA
image. radius
float
, optional The radius of the sphere. Defaults to
RADIUS
. zlevel
int
, default=0 The zaxis level. Used in combination with the zscale to offset the radius by a proportional amount i.e.,
radius * zlevel * zscale
. zscale
float
, optional The proportional multiplier for zaxis 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. Defaults to
BRIDGE_CLEAN
.
 xs
 Returns:
PolyData
The quadfaced 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 pointcloud mesh from xvalues, yvalues and zlevels.
Note that, any optional mesh data provided must be in the same order as the spatial points.
 Parameters:
 xs
ArrayLike
A 1D, 2D or 3D array of pointcloud xvalues, in canonical crs units. Must have the same shape as the ys.
 ys
ArrayLike
A 1D, 2D or 3D array of pointcloud yvalues, in canonical crs units. Must have the same shape as the xs.
 data
ArrayLike
, optional Data to be optionally attached to the mesh points.
 name
str
, 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
. crs
CRSLike
, optional The Coordinate Reference System of the provided xs and ys. May be anything accepted by
pyproj.crs.CRS.from_user_input()
. Defaults toEPSG:4326
i.e.,WGS 84
. radius
float
, optional The radius of the mesh pointcloud. Defaults to
RADIUS
. zlevel
int
orArrayLike
, default=0 The zaxis 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. zscale
float
, optional The proportional multiplier for zaxis zlevel. Defaults to
ZLEVEL_SCALE
. cleanbool, optional
Specify whether to merge duplicate points. Defaults to
BRIDGE_CLEAN
.
 xs
 Returns:
PolyData
The pointcloud 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 quadfaced mesh from the GeoTIFF.
Note that, the GeoTIFF data will be located on the
points
of the resultant mesh. Parameters:
 fname
PathLike
The file path to the GeoTIFF.
 name
str
, 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}"
. band
int
, optional The band index to read from the GeoTIFF. Note that, the band index is onebased. Defaults to the first band i.e.,
band=1
. rgbbool, default=False
Specify whether to read the GeoTIFF as an
RGB
orRGBA
image. Whenrgb=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. size
int
, 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.
 radius
float
, optional The radius of the mesh sphere. Defaults to
RADIUS
. zlevel
int
, default=0 The zaxis level. Used in combination with the zscale to offset the radius by a proportional amount i.e.,
radius * zlevel * zscale
. zscale
float
, optional The proportional multiplier for zaxis 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. Defaults to
BRIDGE_CLEAN
.
 fname
 Returns:
PolyData
The GeoTIFF spherical mesh.
Notes
Added in version 0.5.0.
Attention
Optional package dependency
rasterio
is required.Examples
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 theuint8
image data. Then, extract the mesh to remove cells with no masked points.>>> from geovista import Transform >>> from geovista.pantry import fetch_raster >>> fname = fetch_raster("bahamas_rgb.tif") >>> mesh = Transform.from_tiff(fname, rgb=True, sieve=True, extract=True) >>> mesh.plot(cpos="xz", lighting=False, rgb=True)
 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 1D xvalues and yvalues.
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, the connectivity must define a mesh comprised of faces based on the same primitive shape e.g., a mesh of triangles, or a mesh of quads etc. Support is not yet provided for mixed face meshes. Also, any optional mesh data provided must be in the same order as the mesh face connectivity.
 Parameters:
 xs
ArrayLike
A 1D array of xvalues, in canonical crs units, defining the vertices of each face in the mesh.
 ys
ArrayLike
A 1D array of yvalues, in canonical crs units, defining the vertices of each face in the mesh.
 connectivity
ArrayLike
orShape
, 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, andN
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. data
ArrayLike
, optional Data to be optionally attached to the mesh face or nodes.
 start_index
int
, 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 0based indices into the provided mesh geometry. If no start_index is provided, then it will be determined from the connectivity.
 name
str
, 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
orNAME_CELLS
. crs
CRSLike
, optional The Coordinate Reference System of the provided xs and ys. May be anything accepted by
pyproj.crs.CRS.from_user_input()
. Defaults toEPSG:4326
i.e.,WGS 84
. rgbbool, default=False
Whether the data is an
RGB
orRGBA
image. radius
float
, optional The radius of the mesh sphere. Defaults to
RADIUS
. zlevel
int
, default=0 The zaxis level. Used in combination with the zscale to offset the radius by a proportional amount i.e.,
radius * zlevel * zscale
. zscale
float
, optional The proportional multiplier for zaxis 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. Defaults to
BRIDGE_CLEAN
.
 xs
 Returns:
PolyData
The (M*N)faced spherical mesh.
Notes
Added in version 0.1.0.
 geovista.bridge.PathLike: TypeAlias#
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#
Type alias for a tuple of integers.