geovista.common#

Provision common geovista infra-structure and utilities.

Notes#

Added in version 0.1.0.

Attributes#

BASE

Default base for wrapped longitude half-open interval, in degrees.

CENTRAL_MERIDIAN

Default central meridian.

COASTLINES_RESOLUTION

Default Natural Earth coastline resolution.

GV_CELL_IDS

Name of the geovista cell indices array.

GV_FIELD_CRS

The field array name of the OGC WKT of the mesh CRS.

GV_FIELD_GLOBE_EXAGGERATION_ABOVE

The field array name of the factor for heights above sea level of the mesh globe.

GV_FIELD_GLOBE_EXAGGERATION_BELOW

The field array name of the factor for depths below sea level of the mesh globe.

GV_FIELD_GLOBE_RADIUS

The field array name of the radius of the mesh globe, in metres.

GV_FIELD_GLOBE_RENDER_RADIUS

The field array name of the radius the mesh globe is drawn at.

GV_FIELD_NAME

The field array name of the mesh containing field, point and/or cell data.

GV_FIELD_RADIUS

The field array name of the mesh radius.

GV_FIELD_RESOLUTION

The field array name of the mesh resolution e.g., coastlines.

GV_FIELD_ZSCALE

The field array name of the mesh proportional multiplier for z-axis levels.

GV_MANIFOLD_CELL_IDS

Name of the geovista manifold cell indices/marker array.

GV_POINT_HEIGHT

Name of the point array of heights, in metres above mean sea level.

GV_POINT_IDS

Name of the geovista point indices array.

GV_POINT_ZLEVEL

Name of the point array of z-axis levels a point cloud carries in a planar CRS.

GV_REMESH_POINT_IDS

Name of the geovista remesh point indices/marker array.

JUPYTER_BACKEND

Default jupyter plotting backend for pyvista.

LRU_CACHE_SIZE

LRU cache size, which is auto-disabled for testing.

PERIOD

Default period for wrapped longitude half-open interval, in degrees.

RADIUS

Default radius of a spherical mesh.

REMESH_JOIN

Marker for remesh filter cell join point.

REMESH_SEAM

Marker for remesh filter western cell boundary point.

RETIRED_FIELDS

Every field that geovista reads, but no longer writes.

VTK_CELL_IDS

Name of the VTK cell indices array.

VTK_POINT_IDS

Name of the VTK point indices array.

Vector2DLike

Type alias for 2D vector components.

Vector3DLike

Type alias for 3D vector components.

VectorLike

Type alias for 2D or 3D vector components.

WRAP_ATOL

Absolute tolerance for longitudes close to 'wrap meridian'.

WRAP_RTOL

Relative tolerance for longitudes close to 'wrap meridian'.

ZLEVEL_SCALE

Proportional multiplier for z-axis levels/offsets.

ZTRANSFORM_FACTOR

The zlevel scaling to be applied when transforming to a projection.

Classes#

Preference

Enumeration of common mesh geometry preferences.

RetiredField

A field that geovista reads, but no longer writes.

StrEnumPlus

Convenience behaviour for a string enumeration.

Functions#

active_kernel()

Determine whether we are executing within an IPython kernel.

cast_UnstructuredGrid_to_PolyData(mesh, /, *[, clean])

Convert a UnstructuredGrid to a PolyData.

distance(mesh, /, *[, origin, mean])

Calculate the mean distance from the origin to the points of the mesh.

from_cartesian(mesh, /, *[, stacked, closed_interval, ...])

Convert cartesian xyz spherical mesh to geographic longitude and latitude.

get_modules(root, /, *[, base])

Find all submodule names relative to the root package.

nan_mask(data)

Replace any masked array values with NaNs.

point_cloud(mesh)

Determine whether the mesh is a point-cloud.

sanitize(*meshes[, extra, vtk, legacy])

Purge standard helper cell and point data index arrays.

sanitize_legacy(*meshes)

Translate and remove the retired fields of each mesh, in place.

sanitize_vtk(*meshes)

Purge standard VTK helper cell and point data index arrays.

set_jupyter_backend(*[, backend])

Configure the jupyter plotting backend for pyvista.

to_cartesian(lons, lats, *[, globe, zlevel, zscale, ...])

Convert geographic longitudes and latitudes to cartesian xyz points.

to_lonlat(xyz, /, *[, radians, globe, rtol, atol])

Convert cartesian xyz point on sphere to geographic longitude and latitude.

to_lonlats(xyz, /, *[, radians, globe, stacked, rtol, ...])

Convert cartesian xyz points on sphere to geographic longitudes and latitudes.

triangulated(surface)

Determine whether the provided mesh is triangulated.

vectors_to_cartesian(lons, lats, vectors, *[, globe, ...])

Transform geographic-oriented vector components uvw to cartesian xyz.

vtk_warnings_off()

Disable vtkLogger warning messages.

vtk_warnings_on()

Enable vtkLogger warning messages.

wrap(lons, *[, base, period, rtol, atol, dtype])

Transform longitudes to be in the half-open interval [base, base + period).

Module Contents#

class geovista.common.Preference[source]#

Bases: StrEnumPlus

Enumeration of common mesh geometry preferences.

Notes#

Added in version 0.3.0.

Initialize self. See help(type(self)) for accurate signature.

CELL = 'cell'#

Preference for cell geometry.

POINT = 'point'#

Preference for point geometry.

class geovista.common.RetiredField[source]#

A field that geovista reads, but no longer writes.

Notes

Added in version 0.6.0.

association: Literal['field', 'point', 'cell']#

Whether the field is field, point or cell data.

last_written: str#

The last release of geovista that wrote the field.

name: str#

The name of the field.

replacement: str#

What replaced the field.

translate: collections.abc.Callable[[pv], None]#

Write what replaced the field onto a mesh that has it, in place.

class geovista.common.StrEnumPlus[source]#

Bases: enum.StrEnum

Convenience behaviour for a string enumeration.

Notes#

Added in version 0.6.0.

Previously called MixinStrEnum.

Initialize self. See help(type(self)) for accurate signature.

classmethod valid(item)[source]#

Determine whether the provided item is a valid enumeration member.

Parameters:
itemstr or Preference

The candidate preference enumeration member.

Returns:
bool

Whether the preference enumeration member is valid.

Notes

Added in version 0.3.0.

classmethod values()[source]#

List enumeration member values.

Returns:
tuple of str

Tuple of all the valid preference enumeration member values.

Notes

Added in version 0.3.0.

geovista.common.active_kernel()[source]#

Determine whether we are executing within an IPython kernel.

Returns:
bool

Whether there is an active IPython kernel.

Notes

Added in version 0.1.0.

geovista.common.cast_UnstructuredGrid_to_PolyData(mesh, /, *, clean=False)[source]#

Convert a UnstructuredGrid to a PolyData.

Parameters:
meshDataSet

The unstructured grid to be converted. Any other kind of dataset raises TypeError.

cleanbool, default=False

Specify whether to merge duplicate points, remove unused points, and/or remove degenerate cells in the resultant mesh. See pyvista.PolyDataFilters.clean().

Returns:
PolyData

The resultant mesh.

Notes

Added in version 0.1.0.

geovista.common.distance(mesh, /, *, origin=None, mean=True)[source]#

Calculate the mean distance from the origin to the points of the mesh.

Note that given a spherical mesh the distance calculated is the radius.

Parameters:
meshPolyData

The surface that requires its distance to be calculated, relative to the origin.

originArrayLike, default=(0, 0, 0)

The (x, y, z) cartesian center of the spheroid mesh.

meanbool, default=True

Calculate the mean distance to the points of the mesh. Otherwise, calculate the distance to each point from the origin.

Returns:
float or ndarray

The mean distance to the provided mesh or each mesh point.

Notes

Added in version 0.1.0.

geovista.common.from_cartesian(mesh, /, *, stacked=True, closed_interval=False, rtol=None, atol=None)[source]#

Convert cartesian xyz spherical mesh to geographic longitude and latitude.

Parameters:
meshPolyData

The mesh containing the cartesian (x, y, z) points to be converted to longitude and latitude coordinates.

stackedbool, default=True

Specify whether the resultant xy0 coordinates have shape (N, 3). Otherwise, they will have shape (3, N).

closed_intervalbool, default=False

Longitude values will be in the half-closed interval [-180, 180). However, if the mesh has a seam at the 180th meridian and closed_interval is True, then longitudes will be in the closed interval [-180, 180].

rtolfloat, optional

The relative tolerance for longitudes close to the ‘wrap meridian’ - see geovista.common.wrap() for more.

atolfloat, optional

The absolute tolerance for longitudes close to the ‘wrap meridian’ - see geovista.common.wrap() for more.

Returns:
ndarray

The longitude and latitude coordinates, in degrees.

Notes

Added in version 0.1.0.

geovista.common.get_modules(root, /, *, base=True)[source]#

Find all submodule names relative to the root package.

Recursively searches down from the root to find all child (leaf) modules.

The names of the modules will be relative to the root.

Parameters:
rootstr

The name (dot notation) of the top level package to search under. e.g., geovista.examples.

basebool, optional

Flag the top level root package, which will then remove the root prefix from all packages found and sort them alphabetically.

Returns:
list of str

The sorted list of child module names, relative to the root.

Notes

Added in version 0.5.0.

geovista.common.nan_mask(data)[source]#

Replace any masked array values with NaNs.

As a consequence of filling the mask with NaNs, non-float arrays will be cast to float.

Parameters:
dataArrayLike

The masked array to be filled with NaNs.

Returns:
ndarray

The data with masked values replaced with NaNs.

Notes

Added in version 0.1.0.

geovista.common.point_cloud(mesh)[source]#

Determine whether the mesh is a point-cloud.

Parameters:
meshPolyData

The mesh to be checked.

Returns:
bool

Whether the mesh is a point-cloud.

Notes

Added in version 0.2.0.

geovista.common.sanitize(*meshes, extra=None, vtk=True, legacy=True)[source]#

Purge standard helper cell and point data index arrays.

Parameters:
*meshesiterable of PolyData

One or more meshes to sanitize.

extrastr or list of str, optional

The name of additional data arrays to purge.

vtkbool | None, optional

Whether to sanitize VTK data arrays. Defaults to True.

legacybool, default=True

Whether to translate and remove retired fields, as sanitize_legacy() does.

Notes

Added in version 0.6.0.

geovista.common.sanitize_legacy(*meshes)[source]#

Translate and remove the retired fields of each mesh, in place.

Each field of RETIRED_FIELDS that a mesh has is translated into what replaced it, then removed, so that saving the mesh does not carry the field forward. A mesh with none is unchanged, and nothing warns.

Parameters:
*meshesiterable of DataSet

One or more meshes to sanitize.

Notes

Added in version 0.6.0.

geovista.common.sanitize_vtk(*meshes)[source]#

Purge standard VTK helper cell and point data index arrays.

Parameters:
*meshesiterable of PolyData

One or more meshes to sanitize.

Notes

Added in version 0.1.0.

geovista.common.set_jupyter_backend(*, backend=None)[source]#

Configure the jupyter plotting backend for pyvista.

Parameters:
backendstr, optional

The pyvista plotting backend. For further details see pyvista.set_jupyter_backend(). If None, defaults to JUPYTER_BACKEND.

Returns:
bool

Whether the jupyter backend was successfully configured.

Notes

Added in version 0.1.0.

geovista.common.to_cartesian(lons, lats, *, globe=None, zlevel=None, zscale=None, stacked=True)[source]#

Convert geographic longitudes and latitudes to cartesian xyz points.

A position is missing when its longitude or latitude is masked or NaN, and gives NaN in every component (positions spec §4.7). An infinite longitude or latitude is refused.

Parameters:
lonsArrayLike or pint.Quantity

The longitude values (degrees) to be converted. A pint quantity, from any registry, is read in degrees. Give lats as a quantity too.

latsArrayLike or pint.Quantity

The latitude values (degrees) to be converted. A pint quantity, from any registry, is read in degrees. Give lons as a quantity too.

globeGlobe, optional

The globe whose render radius the points lie at. Defaults to Globe(), whose render radius is RADIUS.

zlevelfloat or ArrayLike, default=0.0

The z-axis level. Used in combination with the zscale to offset the render radius by a proportional amount i.e., render_radius * zlevel * zscale. If zlevel is not a scalar, then its shape must match or broadcast with the shape of lons and lats.

zscalefloat, optional

The proportional multiplier for z-axis zlevel. Defaults to ZLEVEL_SCALE.

stackedbool, default=True

Specify whether the resultant xyz points have shape (N, 3). Otherwise, they will have shape (3, N).

Returns:
ndarray

The xyz spherical cartesian points.

Notes

Added in version 0.1.0.

geovista.common.to_lonlat(xyz, /, *, radians=False, globe=None, rtol=None, atol=None)[source]#

Convert cartesian xyz point on sphere to geographic longitude and latitude.

Parameters:
xyzArrayLike

The cartesian (x, y, z) point to be converted.

radiansbool, default=False

Convert resultant longitude and latitude values to radians. Default units are degrees.

globeGlobe, optional

The globe whose render radius the point lies at. Defaults to Globe(), whose render radius is RADIUS.

rtolfloat, optional

The relative tolerance for longitudes close to the ‘wrap meridian’ - see geovista.common.wrap() for more.

atolfloat, optional

The absolute tolerance for longitudes close to the ‘wrap meridian’ - see geovista.common.wrap() for more.

Returns:
ndarray

The longitude and latitude values.

Notes

Added in version 0.1.0.

geovista.common.to_lonlats(xyz, /, *, radians=False, globe=None, stacked=True, rtol=None, atol=None)[source]#

Convert cartesian xyz points on sphere to geographic longitudes and latitudes.

Parameters:
xyzArrayLike

The cartesian (x, y, z) points to be converted.

radiansbool, default=False

Convert resultant longitude and latitude values to radians. Default units are degrees.

globeGlobe, optional

The globe whose render radius the points lie at. Defaults to Globe(), whose render radius is RADIUS.

stackedbool, default=True

Default the resultant shape to be (N, 2), otherwise (2, N).

rtolfloat, optional

The relative tolerance for longitudes close to the ‘wrap meridian’ - see geovista.common.wrap() for more.

atolfloat, optional

The absolute tolerance for longitudes close to the ‘wrap meridian’ - see geovista.common.wrap() for more.

Returns:
ndarray

The longitude and latitude values.

Notes

Added in version 0.1.0.

geovista.common.triangulated(surface)[source]#

Determine whether the provided mesh is triangulated.

Parameters:
surfacePolyData

The surface mesh to check whether the geometry of all its cells are triangles.

Returns:
bool

Whether the surface is fully triangulated.

Notes

Added in version 0.1.0.

geovista.common.vectors_to_cartesian(lons, lats, vectors, *, globe=None, zlevel=None, zscale=None)[source]#

Transform geographic-oriented vector components uvw to cartesian xyz.

A position is missing when its longitude or latitude is masked or NaN, and gives NaN in every component of its vector (positions spec §4.7). An infinite longitude or latitude is refused.

Parameters:
lonsArrayLike or pint.Quantity

The longitude points of the vectors (in degrees). Must be the same shape as lats. A pint quantity, from any registry, is read in degrees. Give lats as a quantity too.

latsArrayLike or pint.Quantity

The latitude points of the vectors (in degrees). Must be the same shape as lons. A pint quantity, from any registry, is read in degrees. Give lons as a quantity too.

vectorsVector3DLike

The eastward (U), northward (V) and upward (W) vector components. All shapes must be the same as lons and lats.

globeGlobe, optional

The globe whose render radius scales the vectors. Defaults to Globe(), whose render radius is RADIUS.

zlevelint or ArrayLike, default=0.0

The z-axis level. Used in combination with the zscale to offset the render radius by a proportional amount i.e., render_radius * zlevel * zscale. NOTE : non-scalar zlevel is not actually supported, since it is planned to drop support for this from from_points(). It will raise an error.

zscalefloat, optional

The proportional multiplier for z-axis zlevel. Defaults to ZLEVEL_SCALE.

Returns:
Vector3DLike

The corresponding xyz cartesian vector components.

Notes

Added in version 0.6.0.

geovista.common.vtk_warnings_off()[source]#

Disable vtkLogger warning messages.

Notes

Added in version 0.1.0.

geovista.common.vtk_warnings_on()[source]#

Enable vtkLogger warning messages.

Notes

Added in version 0.1.0.

geovista.common.wrap(lons, *, base=None, period=None, rtol=None, atol=None, dtype=None)[source]#

Transform longitudes to be in the half-open interval [base, base + period).

Parameters:
lonsArrayLike or pint.Quantity

One or more longitude values to be wrapped in the interval. A pint quantity, from any registry, is read in degrees, so a plain base or period given with it is in degrees too.

basefloat or pint.Quantity, optional

The start limit of the half-open interval. Defaults to BASE. A pint quantity, from any registry, is read in degrees.

periodfloat or pint.Quantity, optional

The end limit of the half-open interval expressed as a length from the base, in the same units. Defaults to PERIOD. A pint quantity, from any registry, is read in degrees.

rtolfloat, optional

The relative tolerance for longitudes close to the ‘wrap meridian’ - that is base + period - to be considered equal to the wrap meridian. Necessary to prevent cell smearing. See rtol in numpy.isclose(). Defaults to WRAP_RTOL.

atolfloat, optional

The absolute tolerance for longitudes close to the ‘wrap meridian’ - that is base + period - to be considered equal to the wrap meridian. Necessary to prevent cell smearing. See atol in numpy.isclose(). Defaults to WRAP_ATOL.

dtypeDTypeLike, optional

The data-type of the wrapped longitudes. Defaults to float64. The longitudes are wrapped in the dtype when it is floating point. Otherwise they are wrapped as float64 and then converted, so an integer dtype truncates each wrapped longitude towards zero.

Returns:
ndarray

The transformed longitude values.

Notes

Added in version 0.1.0.

Examples

>>> from geovista.common import wrap
>>> import numpy as np
>>> wrap([179.0, 179.999, 180.0, 181.0])
array([ 179., -180., -180., -179.])
>>> wrap([179, 180, 181], period=90)
array([ -91., -180., -179.])
>>> wrap([179, 180, 181], base=0, period=90)
array([89.,  0.,  1.])
geovista.common.BASE: float = -180.0#

Default base for wrapped longitude half-open interval, in degrees.

geovista.common.CENTRAL_MERIDIAN: float = 0.0#

Default central meridian.

geovista.common.COASTLINES_RESOLUTION: str = '10m'#

Default Natural Earth coastline resolution.

geovista.common.GV_CELL_IDS: str = 'gvOriginalCellIds'#

Name of the geovista cell indices array.

geovista.common.GV_FIELD_CRS: str = 'gvCRS'#

The field array name of the OGC WKT of the mesh CRS.

A WKT holding a non-ASCII character or a backslash is escaped, and the array then has a second element naming the codec, see geovista.crs.to_wkt().

geovista.common.GV_FIELD_GLOBE_EXAGGERATION_ABOVE: str = 'gvGlobeExaggerationAbove'#

The field array name of the factor for heights above sea level of the mesh globe.

See geovista.globe.Globe.

geovista.common.GV_FIELD_GLOBE_EXAGGERATION_BELOW: str = 'gvGlobeExaggerationBelow'#

The field array name of the factor for depths below sea level of the mesh globe.

See geovista.globe.Globe.

geovista.common.GV_FIELD_GLOBE_RADIUS: str = 'gvGlobeRadius'#

The field array name of the radius of the mesh globe, in metres.

See geovista.globe.Globe.

geovista.common.GV_FIELD_GLOBE_RENDER_RADIUS: str = 'gvGlobeRenderRadius'#

The field array name of the radius the mesh globe is drawn at.

See geovista.globe.Globe.

geovista.common.GV_FIELD_NAME: str = 'gvName'#

The field array name of the mesh containing field, point and/or cell data.

geovista.common.GV_FIELD_RADIUS: str = 'gvRadius'#

The field array name of the mesh radius.

Retired, and last written by release 0.5.3, since 0.6 records the globe of a mesh in its place. See RETIRED_FIELDS.

geovista.common.GV_FIELD_RESOLUTION: str = 'gvResolution'#

The field array name of the mesh resolution e.g., coastlines.

geovista.common.GV_FIELD_ZSCALE: str = 'gvZScale'#

The field array name of the mesh proportional multiplier for z-axis levels.

geovista.common.GV_MANIFOLD_CELL_IDS: str = 'gvManifoldCellIds'#

Name of the geovista manifold cell indices/marker array.

geovista.common.GV_POINT_HEIGHT: str = 'gvHeight'#

Name of the point array of heights, in metres above mean sea level.

A float64 array of one height for each point, NaN where a height is missing. See geovista.accessor.GeoVistaAccessor.height, which reads it.

geovista.common.GV_POINT_IDS: str = 'gvOriginalPointIds'#

Name of the geovista point indices array.

geovista.common.GV_POINT_ZLEVEL: str = 'gvZLevel'#

Name of the point array of z-axis levels a point cloud carries in a planar CRS.

geovista.common.GV_REMESH_POINT_IDS: str = 'gvRemeshPointIds'#

Name of the geovista remesh point indices/marker array.

geovista.common.JUPYTER_BACKEND: str = 'trame'#

Default jupyter plotting backend for pyvista.

geovista.common.LRU_CACHE_SIZE: int = 0#

LRU cache size, which is auto-disabled for testing.

geovista.common.PERIOD: float = 360.0#

Default period for wrapped longitude half-open interval, in degrees.

geovista.common.RADIUS: float = 1.0#

Default radius of a spherical mesh.

geovista.common.REMESH_JOIN: int = -3#

Marker for remesh filter cell join point.

geovista.common.REMESH_SEAM: int = -1#

Marker for remesh filter western cell boundary point.

geovista.common.RETIRED_FIELDS: tuple[RetiredField, ...]#

Every field that geovista reads, but no longer writes.

See sanitize_legacy(), which translates and removes them.

geovista.common.VTK_CELL_IDS: str = 'vtkOriginalCellIds'#

Name of the VTK cell indices array.

geovista.common.VTK_POINT_IDS: str = 'vtkOriginalPointIds'#

Name of the VTK point indices array.

type geovista.common.Vector2DLike = tuple[ArrayLike, ArrayLike]#

Type alias for 2D vector components.

type geovista.common.Vector3DLike = tuple[ArrayLike, ArrayLike, ArrayLike]#

Type alias for 3D vector components.

type geovista.common.VectorLike = Vector2DLike | Vector3DLike#

Type alias for 2D or 3D vector components.

geovista.common.WRAP_ATOL: float = 1e-08#

Absolute tolerance for longitudes close to ‘wrap meridian’.

geovista.common.WRAP_RTOL: float = 1e-05#

Relative tolerance for longitudes close to ‘wrap meridian’.

geovista.common.ZLEVEL_SCALE: float = 0.0001#

Proportional multiplier for z-axis levels/offsets.

geovista.common.ZTRANSFORM_FACTOR: int = 3#

The zlevel scaling to be applied when transforming to a projection.