geovista.common#
Provision common geovista infra-structure and utilities.
Notes#
Added in version 0.1.0.
Attributes#
Default base for wrapped longitude half-open interval, in degrees. |
|
Default central meridian. |
|
Default Natural Earth coastline resolution. |
|
Name of the geovista cell indices array. |
|
The field array name of the OGC WKT of the mesh CRS. |
|
The field array name of the factor for heights above sea level of the mesh globe. |
|
The field array name of the factor for depths below sea level of the mesh globe. |
|
The field array name of the radius of the mesh globe, in metres. |
|
The field array name of the radius the mesh globe is drawn at. |
|
The field array name of the mesh containing field, point and/or cell data. |
|
The field array name of the mesh radius. |
|
The field array name of the mesh resolution e.g., coastlines. |
|
The field array name of the mesh proportional multiplier for z-axis levels. |
|
Name of the geovista manifold cell indices/marker array. |
|
Name of the point array of heights, in metres above mean sea level. |
|
Name of the geovista point indices array. |
|
Name of the point array of z-axis levels a point cloud carries in a planar CRS. |
|
Name of the geovista remesh point indices/marker array. |
|
Default jupyter plotting backend for pyvista. |
|
LRU cache size, which is auto-disabled for testing. |
|
Default period for wrapped longitude half-open interval, in degrees. |
|
Default radius of a spherical mesh. |
|
Marker for remesh filter cell join point. |
|
Marker for remesh filter western cell boundary point. |
|
Every field that geovista reads, but no longer writes. |
|
Name of the VTK cell indices array. |
|
Name of the VTK point indices array. |
|
Type alias for 2D vector components. |
|
Type alias for 3D vector components. |
|
Type alias for 2D or 3D vector components. |
|
Absolute tolerance for longitudes close to 'wrap meridian'. |
|
Relative tolerance for longitudes close to 'wrap meridian'. |
|
Proportional multiplier for z-axis levels/offsets. |
|
The zlevel scaling to be applied when transforming to a projection. |
Classes#
Enumeration of common mesh geometry preferences. |
|
A field that geovista reads, but no longer writes. |
|
Convenience behaviour for a string enumeration. |
Functions#
Determine whether we are executing within an |
|
|
Convert a |
|
Calculate the mean distance from the origin to the points of the mesh. |
|
Convert cartesian |
|
Find all submodule names relative to the root package. |
|
Replace any masked array values with NaNs. |
|
Determine whether the mesh is a point-cloud. |
|
Purge standard helper cell and point data index arrays. |
|
Translate and remove the retired fields of each mesh, in place. |
|
Purge standard VTK helper cell and point data index arrays. |
|
Configure the jupyter plotting backend for pyvista. |
|
Convert geographic longitudes and latitudes to cartesian |
|
Convert cartesian xyz point on sphere to geographic longitude and latitude. |
|
Convert cartesian xyz points on sphere to geographic longitudes and latitudes. |
|
Determine whether the provided mesh is triangulated. |
|
Transform geographic-oriented vector components |
Disable vtkLogger warning messages. |
|
Enable vtkLogger warning messages. |
|
|
Transform longitudes to be in the half-open interval |
Module Contents#
- class geovista.common.Preference[source]#
Bases:
StrEnumPlusEnumeration 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.
- 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.StrEnumConvenience 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:
- item
strorPreference The candidate preference enumeration member.
- item
- Returns:
boolWhether the preference enumeration member is valid.
Notes
Added in version 0.3.0.
- geovista.common.active_kernel()[source]#
Determine whether we are executing within an
IPythonkernel.- Returns:
boolWhether there is an active
IPythonkernel.
Notes
Added in version 0.1.0.
- geovista.common.cast_UnstructuredGrid_to_PolyData(mesh, /, *, clean=False)[source]#
Convert a
UnstructuredGridto aPolyData.- Parameters:
- mesh
DataSet The unstructured grid to be converted. Any other kind of dataset raises
TypeError.- clean
bool, default=False Specify whether to merge duplicate points, remove unused points, and/or remove degenerate cells in the resultant mesh. See
pyvista.PolyDataFilters.clean().
- mesh
- Returns:
PolyDataThe 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:
- mesh
PolyData The surface that requires its distance to be calculated, relative to the origin.
- origin
ArrayLike, default=(0, 0, 0) The (x, y, z) cartesian center of the spheroid mesh.
- mean
bool, default=True Calculate the mean distance to the points of the mesh. Otherwise, calculate the distance to each point from the origin.
- mesh
- Returns:
Notes
Added in version 0.1.0.
- geovista.common.from_cartesian(mesh, /, *, stacked=True, closed_interval=False, rtol=None, atol=None)[source]#
Convert cartesian
xyzspherical mesh to geographic longitude and latitude.- Parameters:
- mesh
PolyData The mesh containing the cartesian (x, y, z) points to be converted to longitude and latitude coordinates.
- stacked
bool, default=True Specify whether the resultant xy0 coordinates have shape (N, 3). Otherwise, they will have shape (3, N).
- closed_interval
bool, 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].- rtol
float, optional The relative tolerance for longitudes close to the ‘wrap meridian’ - see
geovista.common.wrap()for more.- atol
float, optional The absolute tolerance for longitudes close to the ‘wrap meridian’ - see
geovista.common.wrap()for more.
- mesh
- Returns:
ndarrayThe 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:
- Returns:
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:
- data
ArrayLike The masked array to be filled with NaNs.
- data
- Returns:
ndarrayThe 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.
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.
- extra
strorlistofstr, optional The name of additional data arrays to purge.
- vtk
bool|None, optional Whether to sanitize VTK data arrays. Defaults to
True.- legacy
bool, default=True Whether to translate and remove retired fields, as
sanitize_legacy()does.
- *meshesiterable of
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_FIELDSthat 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.Notes
Added in version 0.6.0.
- geovista.common.sanitize_vtk(*meshes)[source]#
Purge standard VTK helper cell and point data index arrays.
Notes
Added in version 0.1.0.
- geovista.common.set_jupyter_backend(*, backend=None)[source]#
Configure the jupyter plotting backend for pyvista.
- Parameters:
- backend
str, optional The pyvista plotting backend. For further details see
pyvista.set_jupyter_backend(). IfNone, defaults toJUPYTER_BACKEND.
- backend
- Returns:
boolWhether 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
xyzpoints.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:
- lons
ArrayLikeorpint.Quantity The longitude values (degrees) to be converted. A
pintquantity, from any registry, is read in degrees. Give lats as a quantity too.- lats
ArrayLikeorpint.Quantity The latitude values (degrees) to be converted. A
pintquantity, from any registry, is read in degrees. Give lons as a quantity too.- globe
Globe, optional The globe whose render radius the points lie at. Defaults to
Globe(), whose render radius isRADIUS.- zlevel
floatorArrayLike, 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.- zscale
float, optional The proportional multiplier for z-axis zlevel. Defaults to
ZLEVEL_SCALE.- stacked
bool, default=True Specify whether the resultant xyz points have shape (N, 3). Otherwise, they will have shape (3, N).
- lons
- Returns:
ndarrayThe
xyzspherical 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:
- xyz
ArrayLike The cartesian (x, y, z) point to be converted.
- radians
bool, default=False Convert resultant longitude and latitude values to radians. Default units are degrees.
- globe
Globe, optional The globe whose render radius the point lies at. Defaults to
Globe(), whose render radius isRADIUS.- rtol
float, optional The relative tolerance for longitudes close to the ‘wrap meridian’ - see
geovista.common.wrap()for more.- atol
float, optional The absolute tolerance for longitudes close to the ‘wrap meridian’ - see
geovista.common.wrap()for more.
- xyz
- Returns:
ndarrayThe 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:
- xyz
ArrayLike The cartesian (x, y, z) points to be converted.
- radians
bool, default=False Convert resultant longitude and latitude values to radians. Default units are degrees.
- globe
Globe, optional The globe whose render radius the points lie at. Defaults to
Globe(), whose render radius isRADIUS.- stacked
bool, default=True Default the resultant shape to be
(N, 2), otherwise(2, N).- rtol
float, optional The relative tolerance for longitudes close to the ‘wrap meridian’ - see
geovista.common.wrap()for more.- atol
float, optional The absolute tolerance for longitudes close to the ‘wrap meridian’ - see
geovista.common.wrap()for more.
- xyz
- Returns:
ndarrayThe longitude and latitude values.
Notes
Added in version 0.1.0.
- geovista.common.triangulated(surface)[source]#
Determine whether the provided mesh is triangulated.
- Parameters:
- surface
PolyData The surface mesh to check whether the geometry of all its cells are triangles.
- surface
- Returns:
boolWhether 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
uvwto cartesianxyz.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:
- lons
ArrayLikeorpint.Quantity The longitude points of the vectors (in degrees). Must be the same shape as lats. A
pintquantity, from any registry, is read in degrees. Give lats as a quantity too.- lats
ArrayLikeorpint.Quantity The latitude points of the vectors (in degrees). Must be the same shape as lons. A
pintquantity, from any registry, is read in degrees. Give lons as a quantity too.- vectors
Vector3DLike The eastward (
U), northward (V) and upward (W) vector components. All shapes must be the same as lons and lats.- globe
Globe, optional The globe whose render radius scales the vectors. Defaults to
Globe(), whose render radius isRADIUS.- zlevel
intorArrayLike, 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 fromfrom_points(). It will raise an error.- zscale
float, optional The proportional multiplier for z-axis zlevel. Defaults to
ZLEVEL_SCALE.
- lons
- Returns:
Vector3DLikeThe corresponding
xyzcartesian 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:
- lons
ArrayLikeorpint.Quantity One or more longitude values to be wrapped in the interval. A
pintquantity, from any registry, is read in degrees, so a plain base or period given with it is in degrees too.- base
floatorpint.Quantity, optional The start limit of the half-open interval. Defaults to
BASE. Apintquantity, from any registry, is read in degrees.- period
floatorpint.Quantity, optional The end limit of the half-open interval expressed as a length from the base, in the same units. Defaults to
PERIOD. Apintquantity, from any registry, is read in degrees.- rtol
float, 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 innumpy.isclose(). Defaults toWRAP_RTOL.- atol
float, 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 innumpy.isclose(). Defaults toWRAP_ATOL.- dtype
DTypeLike, 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 asfloat64and then converted, so an integer dtype truncates each wrapped longitude towards zero.
- lons
- Returns:
ndarrayThe 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.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_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.PERIOD: float = 360.0#
Default period for wrapped longitude half-open interval, in degrees.
- geovista.common.RETIRED_FIELDS: tuple[RetiredField, ...]#
Every field that geovista reads, but no longer writes.
See
sanitize_legacy(), which translates and removes them.
- 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’.