:py:mod:`geovista.common` ========================= .. py:module:: geovista.common .. autoapi-nested-parse:: Provision common geovista infra-structure and utilities. Notes ----- .. versionadded:: 0.1.0 .. !! processed by numpydoc !! Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: geovista.common.MixinStrEnum geovista.common.Preference Functions ~~~~~~~~~ .. autoapisummary:: geovista.common.active_kernel geovista.common.cast_UnstructuredGrid_to_PolyData geovista.common.distance geovista.common.from_cartesian geovista.common.get_modules geovista.common.nan_mask geovista.common.point_cloud geovista.common.sanitize_data geovista.common.set_jupyter_backend geovista.common.to_cartesian geovista.common.to_lonlat geovista.common.to_lonlats geovista.common.triangulated geovista.common.vtk_warnings_off geovista.common.vtk_warnings_on geovista.common.wrap Attributes ~~~~~~~~~~ .. autoapisummary:: geovista.common.BASE geovista.common.CENTRAL_MERIDIAN geovista.common.COASTLINES_RESOLUTION geovista.common.GV_CELL_IDS geovista.common.GV_FIELD_CRS geovista.common.GV_FIELD_NAME geovista.common.GV_FIELD_RADIUS geovista.common.GV_FIELD_RESOLUTION geovista.common.GV_FIELD_ZSCALE geovista.common.GV_POINT_IDS geovista.common.GV_REMESH_POINT_IDS geovista.common.JUPYTER_BACKEND geovista.common.LRU_CACHE_SIZE geovista.common.PERIOD geovista.common.RADIUS geovista.common.REMESH_JOIN geovista.common.REMESH_SEAM geovista.common.VTK_CELL_IDS geovista.common.VTK_POINT_IDS geovista.common.WRAP_ATOL geovista.common.WRAP_RTOL geovista.common.ZLEVEL_SCALE geovista.common.ZTRANSFORM_FACTOR .. py:class:: MixinStrEnum Convenience behaviour mixin for a string enumeration. .. rubric:: Notes .. versionadded:: 0.3.0 .. !! processed by numpydoc !! .. py:method:: valid(item) :classmethod: Determine whether the provided item is a valid enumeration member. :Parameters: **item** : :class:`python:str` or :obj:`Preference ` The candidate preference enumeration member. :Returns: :class:`python:bool` Whether the preference enumeration member is valid. .. rubric:: Notes .. versionadded:: 0.3.0 .. !! processed by numpydoc !! .. py:method:: values() :classmethod: List enumeration member values. :Returns: :class:`python:tuple` of :class:`python:str` Tuple of all the valid preference enumeration member values. .. rubric:: Notes .. versionadded:: 0.3.0 .. !! processed by numpydoc !! .. py:class:: Preference(*args, **kwds) Bases: :py:obj:`MixinStrEnum`, :py:obj:`enum.Enum` Enumeration of common mesh geometry preferences. .. rubric:: Notes .. versionadded:: 0.3.0 .. !! processed by numpydoc !! .. py:attribute:: CELL :value: 'cell' .. py:attribute:: POINT :value: 'point' .. py:function:: active_kernel() Determine whether we are executing within an ``IPython`` kernel. :Returns: :class:`python:bool` Whether there is an active ``IPython`` kernel. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:function:: cast_UnstructuredGrid_to_PolyData(mesh, clean = False) Convert a :class:`~pyvista.UnstructuredGrid` to a :class:`~pyvista.PolyData`. :Parameters: **mesh** : :class:`~pyvista.UnstructuredGrid` The unstructured grid to be converted. **clean** : :class:`python:bool`, default=False Specify whether to merge duplicate points, remove unused points, and/or remove degenerate cells in the resultant mesh. See :meth:`pyvista.PolyDataFilters.clean`. :Returns: :class:`~pyvista.PolyData` The resultant mesh. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:function:: 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: **mesh** : :class:`~pyvista.PolyData` The surface that requires its distance to be calculated, relative to the `origin`. **origin** : :data:`~numpy.typing.ArrayLike`, default=(0, 0, 0) The (x, y, z) cartesian center of the spheroid mesh. **mean** : :class:`python:bool`, default=True Calculate the mean distance to the points of the `mesh`. Otherwise, calculate the distance to each point from the `origin`. :Returns: :class:`python:float` or :class:`~numpy.ndarray` The mean distance to the provided mesh or each mesh point. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:function:: from_cartesian(mesh, stacked = True, closed_interval = False, rtol = None, atol = None) Convert cartesian ``xyz`` spherical `mesh` to geographic longitude and latitude. :Parameters: **mesh** : :class:`~pyvista.PolyData` The mesh containing the cartesian (x, y, z) points to be converted to longitude and latitude coordinates. **stacked** : :class:`python:bool`, default=True Specify whether the resultant xy0 coordinates have shape (N, 3). Otherwise, they will have shape (3, N). **closed_interval** : :class:`python: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** : :class:`python:float`, optional The relative tolerance for longitudes close to the 'wrap meridian' - see :func:`geovista.common.wrap` for more. **atol** : :class:`python:float`, optional The absolute tolerance for longitudes close to the 'wrap meridian' - see :func:`geovista.common.wrap` for more. :Returns: :class:`~numpy.ndarray` The longitude and latitude coordinates, in degrees. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:function:: 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: **root** : :class:`python:str` The name (dot notation) of the top level package to search under. e.g., ``geovista.examples``. **base** : :class:`python:bool`, optional Flag the top level `root` package, which will then remove the `root` prefix from all packages found and sort them alphabetically. :Returns: :class:`python:list` of :class:`python:str` The sorted list of child module names, relative to the `root`. .. rubric:: Notes .. versionadded:: 0.5.0 .. !! processed by numpydoc !! .. py:function:: 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: **data** : :data:`~numpy.typing.ArrayLike` The masked array to be filled with NaNs. :Returns: :class:`~numpy.ndarray` The `data` with masked values replaced with NaNs. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:function:: point_cloud(mesh) Determine whether the `mesh` is a point-cloud. :Parameters: **mesh** : :class:`~pyvista.PolyData` The mesh to be checked. :Returns: :class:`python:bool` Whether the `mesh` is a point-cloud. .. rubric:: Notes .. versionadded:: 0.2.0 .. !! processed by numpydoc !! .. py:function:: sanitize_data(*meshes) Purge standard VTK helper cell and point data index arrays. :Parameters: **\*meshes** : :term:`python:iterable` of :class:`~pyvista.PolyData` One or more meshes to sanitize. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:function:: set_jupyter_backend(backend = None) Configure the jupyter plotting backend for pyvista. :Parameters: **backend** : :class:`python:str`, optional The pyvista plotting backend. For further details see :func:`pyvista.set_jupyter_backend`. If ``None``, defaults to :data:`JUPYTER_BACKEND`. :Returns: :class:`python:bool` Whether the jupyter backend was successfully configured. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:function:: to_cartesian(lons, lats, radius = None, zlevel = None, zscale = None, stacked = True) Convert geographic longitudes and latitudes to cartesian ``xyz`` points. :Parameters: **lons** : :data:`~numpy.typing.ArrayLike` The longitude values (degrees) to be converted. **lats** : :data:`~numpy.typing.ArrayLike` The latitude values (degrees) to be converted. **radius** : :class:`python:float`, optional The radius of the sphere. Defaults to :data:`RADIUS`. **zlevel** : :class:`python:float` or :data:`~numpy.typing.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`. **zscale** : :class:`python:float`, optional The proportional multiplier for z-axis `zlevel`. Defaults to :data:`ZLEVEL_SCALE`. **stacked** : :class:`python:bool`, default=True Specify whether the resultant xyz points have shape (N, 3). Otherwise, they will have shape (3, N). :Returns: :class:`~numpy.ndarray` The ``xyz`` spherical cartesian points. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:function:: to_lonlat(xyz, radians = False, radius = None, rtol = None, atol = None) Convert cartesian `xyz` point on sphere to geographic longitude and latitude. :Parameters: **xyz** : :data:`~numpy.typing.ArrayLike` The cartesian (x, y, z) point to be converted. **radians** : :class:`python:bool`, default=False Convert resultant longitude and latitude values to radians. Default units are degrees. **radius** : :class:`python:float`, optional The `radius` of the sphere. Defaults to :data:`RADIUS`. **rtol** : :class:`python:float`, optional The relative tolerance for longitudes close to the 'wrap meridian' - see :func:`geovista.common.wrap` for more. **atol** : :class:`python:float`, optional The absolute tolerance for longitudes close to the 'wrap meridian' - see :func:`geovista.common.wrap` for more. :Returns: :class:`~numpy.ndarray` The longitude and latitude values. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:function:: 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: **xyz** : :data:`~numpy.typing.ArrayLike` The cartesian (x, y, z) points to be converted. **radians** : :class:`python:bool`, default=False Convert resultant longitude and latitude values to radians. Default units are degrees. **radius** : :class:`python:float` or :obj:`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 :data:`RADIUS`. **stacked** : :class:`python:bool`, default=True Default the resultant shape to be ``(N, 2)``, otherwise ``(2, N)``. **rtol** : :class:`python:float`, optional The relative tolerance for longitudes close to the 'wrap meridian' - see :func:`geovista.common.wrap` for more. **atol** : :class:`python:float`, optional The absolute tolerance for longitudes close to the 'wrap meridian' - see :func:`geovista.common.wrap` for more. :Returns: :class:`~numpy.ndarray` The longitude and latitude values. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:function:: triangulated(surface) Determine whether the provided mesh is triangulated. :Parameters: **surface** : :class:`~pyvista.PolyData` The surface mesh to check whether the geometry of all its cells are triangles. :Returns: :class:`python:bool` Whether the surface is fully triangulated. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:function:: vtk_warnings_off() Disable :mod:`vtk` warning messages. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:function:: vtk_warnings_on() Enable :mod:`vtk` warning messages. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:function:: 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: **lons** : :data:`~numpy.typing.ArrayLike` One or more longitude values to be wrapped in the interval. **base** : :class:`python:float`, optional The start limit of the half-open interval. Defaults to :data:`BASE`. **period** : :class:`python:float`, optional The end limit of the half-open interval expressed as a length from the `base`, in the same units. Defaults to :data:`PERIOD`. **rtol** : :class:`python: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` in :func:`numpy.isclose`. Defaults to :data:`WRAP_RTOL`. **atol** : :class:`python: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` in :func:`numpy.isclose`. Defaults to :data:`WRAP_ATOL`. **dtype** : data-type, default=float64 The resultant longitude `dtype`. :Returns: :class:`~numpy.ndarray` The transformed longitude values. .. rubric:: Notes .. versionadded:: 0.1.0 .. rubric:: Examples .. pyvista-plot:: >>> 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.]) .. !! processed by numpydoc !! .. py:data:: BASE :type: float Default base for wrapped longitude half-open interval, in degrees. .. !! processed by numpydoc !! .. py:data:: CENTRAL_MERIDIAN :type: float :value: 0.0 Default central meridian. .. !! processed by numpydoc !! .. py:data:: COASTLINES_RESOLUTION :type: str :value: '10m' Default Natural Earth coastline resolution. .. !! processed by numpydoc !! .. py:data:: GV_CELL_IDS :type: str :value: 'gvOriginalCellIds' Name of the geovista cell indices array. .. !! processed by numpydoc !! .. py:data:: GV_FIELD_CRS :type: str :value: 'gvCRS' The field array name of the CF serialized pyproj CRS. .. !! processed by numpydoc !! .. py:data:: GV_FIELD_NAME :type: str :value: 'gvName' The field array name of the mesh containing field, point and/or cell data. .. !! processed by numpydoc !! .. py:data:: GV_FIELD_RADIUS :type: str :value: 'gvRadius' The field array name of the mesh radius. .. !! processed by numpydoc !! .. py:data:: GV_FIELD_RESOLUTION :type: str :value: 'gvResolution' The field array name of the mesh resolution e.g., coastlines. .. !! processed by numpydoc !! .. py:data:: GV_FIELD_ZSCALE :type: str :value: 'gvZScale' The field array name of the mesh proportional multiplier for z-axis levels. .. !! processed by numpydoc !! .. py:data:: GV_POINT_IDS :type: str :value: 'gvOriginalPointIds' Name of the geovista point indices array. .. !! processed by numpydoc !! .. py:data:: GV_REMESH_POINT_IDS :type: str :value: 'gvRemeshPointIds' Name of the geovista remesh point indices/marker array. .. !! processed by numpydoc !! .. py:data:: JUPYTER_BACKEND :type: str :value: 'trame' Default jupyter plotting backend for pyvista. .. !! processed by numpydoc !! .. py:data:: LRU_CACHE_SIZE :type: int LRU cache size, which is auto-disabled for testing. .. !! processed by numpydoc !! .. py:data:: PERIOD :type: float :value: 360.0 Default period for wrapped longitude half-open interval, in degrees. .. !! processed by numpydoc !! .. py:data:: RADIUS :type: float :value: 1.0 Default radius of a spherical mesh. .. !! processed by numpydoc !! .. py:data:: REMESH_JOIN :type: int Marker for remesh filter cell join point. .. !! processed by numpydoc !! .. py:data:: REMESH_SEAM :type: int Marker for remesh filter western cell boundary point. .. !! processed by numpydoc !! .. py:data:: VTK_CELL_IDS :type: str :value: 'vtkOriginalCellIds' Name of the VTK cell indices array. .. !! processed by numpydoc !! .. py:data:: VTK_POINT_IDS :type: str :value: 'vtkOriginalPointIds' Name of the VTK point indices array. .. !! processed by numpydoc !! .. py:data:: WRAP_ATOL :type: float :value: 1e-08 Absolute tolerance for longitudes close to 'wrap meridian'. .. !! processed by numpydoc !! .. py:data:: WRAP_RTOL :type: float :value: 1e-05 Relative tolerance for longitudes close to 'wrap meridian'. .. !! processed by numpydoc !! .. py:data:: ZLEVEL_SCALE :type: float :value: 0.0001 Proportional multiplier for z-axis levels/offsets. .. !! processed by numpydoc !! .. py:data:: ZTRANSFORM_FACTOR :type: int :value: 3 The zlevel scaling to be applied when transforming to a projection. .. !! processed by numpydoc !!