geovista.common

Provision common geovista infra-structure and utilities.

Notes

Added in version 0.1.0.

Module Contents

Classes

MixinStrEnum	Convenience behaviour mixin for a string enumeration.
Preference	Enumeration of common mesh geometry preferences.

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, rtol, ...])	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_data(*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[, radius, zlevel, zscale, stacked])	Convert geographic longitudes and latitudes to cartesian xyz points.
to_lonlat(xyz[, radians, radius, rtol, atol])	Convert cartesian xyz point on sphere to geographic longitude and latitude.
to_lonlats(xyz[, radians, radius, stacked, rtol, atol])	Convert cartesian xyz points on sphere to geographic longitudes and latitudes.
triangulated(surface)	Determine whether the provided mesh is triangulated.
vtk_warnings_off()	Disable vtk warning messages.
vtk_warnings_on()	Enable vtk warning messages.
wrap(lons[, base, period, rtol, atol, dtype])	Transform longitudes to be in the half-open interval [base, base + period).

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 CF serialized pyproj CRS.
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_POINT_IDS	Name of the geovista point indices array.
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.
VTK_CELL_IDS	Name of the VTK cell indices array.
VTK_POINT_IDS	Name of the VTK point indices array.
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.

class geovista.common.MixinStrEnum

Convenience behaviour mixin for a string enumeration.

Notes

Added in version 0.3.0.

classmethod valid(item)

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()

List enumeration member values.

Returns:

tuple of str

Tuple of all the valid preference enumeration member values.

Notes

Added in version 0.3.0.

class geovista.common.Preference(*args, **kwds)

Bases: MixinStrEnum, enum.Enum

Enumeration of common mesh geometry preferences.

Notes

Added in version 0.3.0.

CELL = 'cell'

POINT = 'point'

geovista.common.active_kernel()

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)

Convert a UnstructuredGrid to a PolyData.

Parameters:

meshUnstructuredGrid

The unstructured grid to be converted.

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)

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)

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)

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)

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)

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_data(*meshes)

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)

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, radius=None, zlevel=None, zscale=None, stacked=True)

Convert geographic longitudes and latitudes to cartesian xyz points.

Parameters:

lonsArrayLike

The longitude values (degrees) to be converted.

latsArrayLike

The latitude values (degrees) to be converted.

radiusfloat, optional

The radius of the sphere. Defaults to RADIUS.

zlevelfloat or ArrayLike, default=0.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 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, radius=None, rtol=None, atol=None)

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.

radiusfloat, optional

The radius of the sphere. Defaults to 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, radius=None, stacked=True, rtol=None, atol=None)

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.

radiusfloat or ArrayLike, optional

The radius of the sphere. If radius is not a scalar, then its shape must match the number of xyz points i.e., radii with shape (N,) for xyz points with shape (N, 3). Defaults to 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)

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.vtk_warnings_off()

Disable vtk warning messages.

Notes

Added in version 0.1.0.

geovista.common.vtk_warnings_on()

Enable vtk warning messages.

Notes

Added in version 0.1.0.

geovista.common.wrap(lons, base=None, period=None, rtol=None, atol=None, dtype=None)

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

Parameters:

lonsArrayLike

One or more longitude values to be wrapped in the interval.

basefloat, optional

The start limit of the half-open interval. Defaults to BASE.

periodfloat, optional

The end limit of the half-open interval expressed as a length from the base, in the same units. Defaults to PERIOD.

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.

dtypedata-type, default=float64

The resultant longitude dtype.

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

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 CF serialized pyproj CRS.

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.

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_POINT_IDS: str = 'gvOriginalPointIds'

Name of the geovista point indices array.

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

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

Marker for remesh filter cell join point.

geovista.common.REMESH_SEAM: int

Marker for remesh filter western cell boundary point.

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.

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.