geovista.common

Provision common geovista infra-structure and utilities.

ノート

Added in version 0.1.0.

属性

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_MANIFOLD_CELL_IDS	Name of the geovista manifold cell indices/marker array.
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.
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.
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])	Purge standard helper cell and point data index arrays.
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, *[, radius, zlevel, zscale, ...])	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, ...])	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, *[, radius, ...])	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).

モジュール内容

class geovista.common.Preference

Bases: StrEnumPlus

Enumeration of common mesh geometry preferences.

ノート

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.StrEnumPlus

Bases: enum.StrEnum

Convenience behaviour for a string enumeration.

ノート

Added in version 0.6.0.

Previously called MixinStrEnum.

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

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.

ノート

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.

ノート

Added in version 0.3.0.

geovista.common.active_kernel()

Determine whether we are executing within an IPython kernel.

Returns:

bool

Whether there is an active IPython kernel.

ノート

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.

ノート

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.

ノート

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.

ノート

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.

ノート

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.

ノート

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.

ノート

Added in version 0.2.0.

geovista.common.sanitize(*meshes, extra=None, vtk=True)

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.

ノート

Added in version 0.6.0.

geovista.common.sanitize_vtk(*meshes)

Purge standard VTK helper cell and point data index arrays.

Parameters:

*meshesiterable of PolyData

One or more meshes to sanitize.

ノート

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.

ノート

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.

ノート

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.

ノート

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.

ノート

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.

ノート

Added in version 0.1.0.

geovista.common.vectors_to_cartesian(lons, lats, vectors, *, radius=None, zlevel=None, zscale=None)

Transform geographic-oriented vector components uvw to cartesian xyz.

Parameters:

lonsArrayLike

The longitude points of the vectors (in degrees). Must be the same shape as lats.

latsArrayLike

The latitude points of the vectors (in degrees). Must be the same shape as lons.

vectorsVector3DLike

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

radiusfloat, optional

The radius of the sphere. Defaults to RADIUS.

zlevelint 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. 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.

ノート

Added in version 0.6.0.

geovista.common.vtk_warnings_off()

Disable vtkLogger warning messages.

ノート

Added in version 0.1.0.

geovista.common.vtk_warnings_on()

Enable vtkLogger warning messages.

ノート

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.

ノート

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 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_MANIFOLD_CELL_IDS: str = 'gvManifoldCellIds'

Name of the geovista manifold cell indices/marker array.

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 = 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.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.