geovista.bridge =============== .. py:module:: geovista.bridge .. autoapi-nested-parse:: Transform structured grids and unstructured meshes to PyVista format. This module provides the :class:`~geovista.bridge.Transform` factory class for transforming rectilinear, curvilinear, and unstructured geospatial data into geolocated :doc:`PyVista ` mesh instances. Notes ----- .. versionadded:: 0.1.0 - :doc:`pyvista:user-guide/what-is-a-mesh` .. !! processed by numpydoc !! Attributes ---------- .. autoapisummary:: geovista.bridge.BRIDGE_CLEAN geovista.bridge.NAME_CELLS geovista.bridge.NAME_POINTS geovista.bridge.NAME_VECTORS geovista.bridge.PathLike geovista.bridge.RIO_SIEVE_SIZE geovista.bridge.Shape Classes ------- .. autoapisummary:: geovista.bridge.Transform Module Contents --------------- .. py:class:: Transform(xs, ys, /, *, connectivity = None, start_index = None, crs = None, radius = None, zlevel = None, zscale = None, clean = None) Build a mesh from spatial points, connectivity, data and CRS metadata. Notes ----- .. versionadded:: 0.1.0 Build a mesh from spatial points, connectivity, data and CRS metadata. Convenience factory to build multiple identical meshes but with different face or node data. :Parameters: **xs** : :obj:`ArrayLike ` A 1D array of x-values, in canonical `crs` units, defining the vertices of each face in the mesh. **ys** : :obj:`ArrayLike ` A 1D array of y-values, in canonical `crs` units, defining the vertices of each face in the mesh. **connectivity** : :obj:`ArrayLike ` or :obj:`Shape`, optional Defines the topology of each face in the unstructured mesh in terms of indices into the provided `xs` and `ys` mesh geometry arrays. The `connectivity` is a 2D ``(M, N)`` array, where ``M`` is the number of mesh faces, and ``N`` is the number of nodes per face. Alternatively, an ``(M, N)`` tuple defining the connectivity shape may be provided instead, given that the `xs` and `ys` define ``M*N`` points (at most) in the mesh geometry. If no connectivity is provided, and the `xs` and `ys` are 2D, then their shape is used to determine the connectivity. Also, note that masked connectivity may be used to define a mesh consisting of different shaped faces. **start_index** : :class:`python:int`, default=0 Specify the base index of the provided `connectivity` in the closed interval [0, 1]. For example, if `start_index=1`, then the `start_index` will be subtracted from the `connectivity` to result in 0-based indices into the provided mesh geometry. If no `start_index` is provided, then it will be determined from the `connectivity`. **crs** : :obj:`CRSLike `, optional The Coordinate Reference System of the provided `xs` and `ys`. May be anything accepted by :meth:`pyproj.crs.CRS.from_user_input`. Defaults to ``EPSG:4326`` i.e., ``WGS 84``. **radius** : :class:`python:float`, optional The radius of the mesh sphere. Defaults to :data:`~geovista.common.RADIUS`. **zlevel** : :class:`python:int`, default=0 The z-axis level. Used in combination with the `zscale` to offset the `radius` by a proportional amount i.e., ``radius * zlevel * zscale``. **zscale** : :class:`python:float`, optional The proportional multiplier for z-axis `zlevel`. Defaults to :data:`~geovista.common.ZLEVEL_SCALE`. **clean** : :class:`python:bool`, optional Specify whether to merge duplicate points, remove unused points, and/or remove degenerate cells in the resultant mesh. See :meth:`pyvista.PolyDataFilters.clean`. Defaults to :data:`BRIDGE_CLEAN`. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:method:: __call__(*, data = None, name = None) Build the mesh and attach the provided `data` to faces or nodes. :Parameters: **data** : :obj:`ArrayLike `, optional Data to be optionally attached to the mesh face or nodes. **name** : :class:`python:str`, optional The name of the optional data array to be attached to the mesh. If `data` is provided but with no `name`, defaults to either :data:`NAME_POINTS` or :data:`NAME_CELLS`. :Returns: :obj:`PolyData ` The spherical mesh. .. rubric:: Notes ..versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:method:: from_1d(xs, ys, /, *, data = None, name = None, crs = None, rgb = False, radius = None, zlevel = None, zscale = None, clean = None) :classmethod: Build a quad-faced mesh from contiguous 1D x-values and y-values. This allows the construction of a uniform or rectilinear quad-faced ``(M, N)`` mesh grid, where the mesh has ``M``-faces in the y-axis, and ``N``-faces in the x-axis, resulting in a mesh consisting of ``M*N`` faces. The provided `xs` and `ys` will be projected from their `crs` to geographic longitude and latitude values. :Parameters: **xs** : :obj:`ArrayLike ` A 1D array of x-values, in canonical `crs` units, defining the contiguous face x-value boundaries of the mesh. Creating a mesh with ``N``-faces in the `crs` x-axis requires a ``(N+1,)`` array. Alternatively, a ``(N, 2)`` contiguous bounds array may be provided. **ys** : :obj:`ArrayLike ` A 1D array of y-values, in canonical `crs` units, defining the contiguous face y-value boundaries of the mesh. Creating a mesh with ``M``-faces in the `crs` y-axis requires a ``(M+1,)`` array. Alternatively, a ``(M, 2)`` contiguous bounds array may be provided. **data** : :obj:`ArrayLike `, optional Data to be optionally attached to the mesh. The size of the data must match either the shape of the fully formed mesh points ``(M+1)*(N+1)``, or the number of mesh faces, ``M*N`` (but see the `rgb` parameter). **name** : :class:`python:str`, optional The name of the optional data array to be attached to the mesh. If `data` is provided but with no `name`, defaults to either :data:`NAME_POINTS` or :data:`NAME_CELLS`. **crs** : :obj:`CRSLike `, optional The Coordinate Reference System of the provided `xs` and `ys`. May be anything accepted by :meth:`pyproj.crs.CRS.from_user_input`. Defaults to ``EPSG:4326`` i.e., ``WGS 84``. **rgb** : :class:`python:bool`, default=False Whether `data` is an ``RGB`` or ``RGBA`` image. When ``rgb=True``, `data` is expected to have an extra dimension for the colour channels (length ``3`` or ``4``). **radius** : :class:`python:float`, optional The radius of the sphere. Defaults to :data:`~geovista.common.RADIUS`. **zlevel** : :class:`python:int`, default=0 The z-axis level. Used in combination with the `zscale` to offset the `radius` by a proportional amount i.e., ``radius * zlevel * zscale``. **zscale** : :class:`python:float`, optional The proportional multiplier for z-axis `zlevel`. Defaults to :data:`~geovista.common.ZLEVEL_SCALE`. **clean** : :class:`python:bool`, optional Specify whether to merge duplicate points, remove unused points, and/or remove degenerate cells in the resultant mesh. See :meth:`pyvista.PolyDataFilters.clean`. Defaults to :data:`BRIDGE_CLEAN`. :Returns: :obj:`PolyData ` The quad-faced spherical mesh. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:method:: from_2d(xs, ys, /, *, data = None, name = None, crs = None, rgb = False, radius = None, zlevel = None, zscale = None, clean = None) :classmethod: Build a quad-faced mesh from 2D x-values and y-values. This allows the construction of a uniform, rectilinear or curvilinear quad-faced ``(M, N)`` mesh grid, where the mesh has ``M``-faces in the y-axis, and ``N``-faces in the x-axis, resulting in a mesh consisting of ``M*N`` faces. The provided `xs` and `ys` define the four vertices of each quad-face in the mesh for the native `crs`, which will then be projected to geographic longitude and latitude values. :Parameters: **xs** : :obj:`ArrayLike ` A 2D array of x-values, in canonical `crs` units, defining the face x-value boundaries of the mesh. Creating a ``(M, N)`` mesh requires a ``(M+1, N+1)`` x-axis array. Alternatively, a ``(M, N, 4)`` array may be provided. **ys** : :obj:`ArrayLike ` A 2D array of y-values, in canonical `crs` units, defining the face y-value boundaries of the mesh. Creating a ``(M, N)`` mesh requires a ``(M+1, N+1)`` y-axis array. Alternatively, a ``(M, N, 4)`` array may be provided. **data** : :obj:`ArrayLike `, optional Data to be optionally attached to the mesh. The size of the data must match either the shape of the fully formed mesh points ``(M+1)*(N+1)``, or the number of mesh faces, ``M*N`` (but see the `rgb` parameter). **name** : :class:`python:str`, optional The name of the optional data array to be attached to the mesh. If `data` is provided but with no `name`, defaults to either :data:`NAME_POINTS` or :data:`NAME_CELLS`. **crs** : :obj:`CRSLike `, optional The Coordinate Reference System of the provided `xs` and `ys`. May be anything accepted by :meth:`pyproj.crs.CRS.from_user_input`. Defaults to ``EPSG:4326`` i.e., ``WGS 84``. **rgb** : :class:`python:bool`, default=False Whether `data` is an ``RGB`` or ``RGBA`` image. When ``rgb=True``, `data` is expected to have an extra dimension for the colour channels (length ``3`` or ``4``). **radius** : :class:`python:float`, optional The radius of the sphere. Defaults to :data:`~geovista.common.RADIUS`. **zlevel** : :class:`python:int`, default=0 The z-axis level. Used in combination with the `zscale` to offset the `radius` by a proportional amount i.e., ``radius * zlevel * zscale``. **zscale** : :class:`python:float`, optional The proportional multiplier for z-axis `zlevel`. Defaults to :data:`~geovista.common.ZLEVEL_SCALE`. **clean** : :class:`python:bool`, optional Specify whether to merge duplicate points, remove unused points, and/or remove degenerate cells in the resultant mesh. See :meth:`pyvista.PolyDataFilters.clean`. Defaults to :data:`BRIDGE_CLEAN`. :Returns: :obj:`PolyData ` The quad-faced spherical mesh. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:method:: from_points(xs, ys, /, *, data = None, name = None, crs = None, radius = None, zlevel = None, zscale = None, clean = None, vectors = None, vectors_crs = None, vectors_name = None) :classmethod: Build a point-cloud mesh from x-values, y-values and z-levels. Note that optional mesh `data` or `vectors` must be in the same order as the spatial points. :Parameters: **xs** : :obj:`ArrayLike ` A 1D, 2D or 3D array of point-cloud x-values, in canonical `crs` units. Must have the same shape as the `ys`. **ys** : :obj:`ArrayLike ` A 1D, 2D or 3D array of point-cloud y-values, in canonical `crs` units. Must have the same shape as the `xs`. **data** : :obj:`ArrayLike `, optional Data to be optionally attached to the mesh points defined by `xs` and `ys`. **name** : :class:`python:str`, optional The name of the optional data array to be attached to the mesh. If `data` is provided but with no `name`, defaults to :data:`NAME_POINTS`. **crs** : :obj:`CRSLike `, optional The Coordinate Reference System of the provided `xs` and `ys`. May be anything accepted by :meth:`pyproj.crs.CRS.from_user_input`. Defaults to ``EPSG:4326`` i.e., ``WGS 84``. **radius** : :class:`python:float`, optional The radius of the mesh point-cloud. Defaults to :data:`~geovista.common.RADIUS`. **zlevel** : :class:`python:int` or :obj:`ArrayLike `, default=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 the `xs` and `ys`. **zscale** : :class:`python:float`, optional The proportional multiplier for z-axis `zlevel`. Defaults to :data:`~geovista.common.ZLEVEL_SCALE`. **clean** : :class:`python:bool`, optional Specify whether to merge duplicate points. See :meth:`pyvista.PolyDataFilters.clean`. Defaults to :data:`BRIDGE_CLEAN`. **vectors** : :obj:`VectorLike `, optional A tuple of 2 or 3 arrays of the same shape as `xs` and `ys`. These give eastward (``U``), northward (``V``) and optionally upward (``W``) vector components, which are converted to an ``[N, 3]`` array of 3D vectors and attached to the resultant mesh, see `vectors_name`. This can be used to generate glyphs (such as arrows) and streamlines. **vectors_crs** : :obj:`CRSLike `, optional The Coordinate Reference System of the provided `vectors`. May be anything accepted by :meth:`pyproj.crs.CRS.from_user_input`. Defaults to the same as `crs`. Note that `vectors_crs` only specifies horizontal orientation of the vectors. Their magnitudes are always spatial distance, and the vertical component is always radial (i.e., "upwards"). **vectors_name** : :class:`python:str`, optional The name of the vectors array to be attached to the mesh. If `vectors` is provided but with no `vectors_name`, defaults to :data:`NAME_VECTORS`. :Returns: :obj:`PolyData ` The point-cloud mesh with optional vectors attached. .. rubric:: Notes .. versionadded:: 0.2.0 .. !! processed by numpydoc !! .. py:method:: from_tiff(fname, /, *, name = None, band = 1, rgb = False, sieve = False, size = None, extract = False, radius = None, zlevel = None, zscale = None, clean = None) :classmethod: Build a quad-faced mesh from the GeoTIFF. Note that the GeoTIFF data will be located on the ``points`` of the resultant mesh. :Parameters: **fname** : :obj:`PathLike` The file path to the GeoTIFF. **name** : :class:`python:str`, optional The name of the GeoTIFF data array to be attached to the mesh. Defaults to :data:`NAME_POINTS`. Note that ``{units}`` may be used as a placeholder for the units of the data array e.g., ``"Elevation / {units}"``. **band** : :class:`python:int`, default=1 The band index to read from the GeoTIFF. Note that the `band` index is one-based. **rgb** : :class:`python:bool`, default=False Specify whether to read the GeoTIFF as an ``RGB`` or ``RGBA`` image. When ``rgb=True``, the `band` index is ignored. **sieve** : :class:`python:bool`, default=False Specify whether to sieve the GeoTIFF mask to remove small connected regions. See :func:`rasterio.features.sieve` for more information. **size** : :class:`python:int`, optional The size of the `sieve` filter. Defaults to :data:`RIO_SIEVE_SIZE`. **extract** : :class:`python:bool`, default=False Specify whether to extract cells from the mesh with no masked points. **radius** : :class:`python:float`, optional The radius of the mesh sphere. Defaults to :data:`~geovista.common.RADIUS`. **zlevel** : :class:`python:int`, default=0 The z-axis level. Used in combination with the `zscale` to offset the `radius` by a proportional amount i.e., ``radius * zlevel * zscale``. **zscale** : :class:`python:float`, optional The proportional multiplier for z-axis `zlevel`. Defaults to :data:`~geovista.common.ZLEVEL_SCALE`. **clean** : :class:`python:bool`, optional Specify whether to merge duplicate points, remove unused points, and/or remove degenerate cells in the resultant mesh. See :meth:`pyvista.PolyDataFilters.clean`. Defaults to :data:`BRIDGE_CLEAN`. :Returns: :obj:`PolyData ` The GeoTIFF spherical mesh. .. rubric:: Notes .. versionadded:: 0.5.0 .. attention:: Optional package dependency :mod:`rasterio` is required. .. rubric:: Examples .. pyvista-plot:: >>> from geovista import GeoPlotter, Transform >>> from geovista.pantry import fetch_raster >>> from geovista.pantry.textures import natural_earth_1 Render the GeoTIFF ``RGB`` image as a geolocated mesh. First, :func:`rasterio.features.sieve` the GeoTIFF image to remove several unwanted masked regions within the interior of the image, due to a lack of dynamic range in the ``uint8`` image data. Then, extract the mesh to remove cells with no masked points. >>> fname = fetch_raster("bahamas_rgb.tif") >>> mesh = Transform.from_tiff(fname, rgb=True, sieve=True, extract=True) Now render the result: >>> p = GeoPlotter() >>> _ = p.add_mesh(mesh, rgb=True) >>> p.view_poi() >>> _ = p.add_base_layer(texture=natural_earth_1(), zlevel=0) >>> _ = p.add_coastlines(color="white") >>> p.show() .. !! processed by numpydoc !! .. py:method:: from_unstructured(xs, ys, /, *, connectivity = None, data = None, start_index = None, name = None, crs = None, rgb = False, radius = None, zlevel = None, zscale = None, clean = None) :classmethod: Build a mesh from unstructured 1D x-values and y-values. The `connectivity` defines the topology of faces within the unstructured mesh. This is represented in terms of indices into the provided `xs` and `ys` mesh geometry. Note that any optional mesh `data` provided must be in the same order as the mesh face `connectivity`, or in the same order as the points described by `xs` and `ys` (data can only be attached to points or cells). :Parameters: **xs** : :obj:`ArrayLike ` A 1D array of x-values, in canonical `crs` units, defining the vertices of each face in the mesh. **ys** : :obj:`ArrayLike ` A 1D array of y-values, in canonical `crs` units, defining the vertices of each face in the mesh. **connectivity** : :obj:`ArrayLike ` or :obj:`Shape`, optional Defines the topology of each face in the unstructured mesh in terms of indices into the provided `xs` and `ys` mesh geometry arrays. The `connectivity` is a 2D ``(M, N)`` array, where ``M`` is the number of mesh faces, and ``N`` is the number of nodes per face. Alternatively, an ``(M, N)`` tuple defining the connectivity shape may be provided instead, given that the `xs` and `ys` define ``M*N`` points (at most) in the mesh geometry. If no connectivity is provided, and the `xs` and `ys` are 2D, then their shape is used to determine the connectivity. Also, note that masked connectivity may be used to define a mesh consisting of different shaped faces. **data** : :obj:`ArrayLike `, optional Data to be optionally attached to the mesh face or nodes. **start_index** : :class:`python:int`, default=0 Specify the base index of the provided `connectivity` in the closed interval [0, 1]. For example, if `start_index=1`, then the `start_index` will be subtracted from the `connectivity` to result in 0-based indices into the provided mesh geometry. If no `start_index` is provided, then it will be determined from the `connectivity`. **name** : :class:`python:str`, optional The name of the optional data array to be attached to the mesh. If `data` is provided but with no `name`, defaults to either :data:`NAME_POINTS` or :data:`NAME_CELLS`. **crs** : :obj:`CRSLike `, optional The Coordinate Reference System of the provided `xs` and `ys`. May be anything accepted by :meth:`pyproj.crs.CRS.from_user_input`. Defaults to ``EPSG:4326`` i.e., ``WGS 84``. **rgb** : :class:`python:bool`, default=False Whether `data` is an ``RGB`` or ``RGBA`` image. When ``rgb=True``, `data` is expected to have an extra dimension for the colour channels (length ``3`` or ``4``). **radius** : :class:`python:float`, optional The radius of the mesh sphere. Defaults to :data:`~geovista.common.RADIUS`. **zlevel** : :class:`python:int`, default=0 The z-axis level. Used in combination with the `zscale` to offset the `radius` by a proportional amount i.e., ``radius * zlevel * zscale``. **zscale** : :class:`python:float`, optional The proportional multiplier for z-axis `zlevel`. Defaults to :data:`~geovista.common.ZLEVEL_SCALE`. **clean** : :class:`python:bool`, optional Specify whether to merge duplicate points, remove unused points, and/or remove degenerate cells in the resultant mesh. See :meth:`pyvista.PolyDataFilters.clean`. Defaults to :data:`BRIDGE_CLEAN`. :Returns: :obj:`PolyData ` The ``(M*N)``-faced spherical mesh. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:method:: to_structured_grid(xs, ys, zs, /, *, data = None, name = None, crs = None, radius = None, zlevel = None, zscale = None) :classmethod: Build a structured grid from contiguous 1D spatial coordinates. The 3D structured grid consists of cubic voxel cells which are constructed from the 1D spatial coordinates defining the bounds of the cells in each dimension. :Parameters: **xs** : :obj:`ArrayLike ` The 1D array of x-values, in canonical `crs` units, defining the x-axis cell bounds of the grid. **ys** : :obj:`ArrayLike ` The 1D array of y-values, in canonical `crs` units, defining the y-axis cell bounds of the grid. **zs** : :obj:`ArrayLike ` The 1D array of z-values, in canonical `crs` units, defining the z-axis cell bounds of the grid. **data** : :obj:`ArrayLike ` | :data:`python:None`, optional Data to be optionally attached to the structured grid cells or points. Note that the expected data dimensionality is ``(Z, Y, X)`` order. **name** : :class:`python:str` | :data:`python:None`, optional The name of the optional data array to be attached to the grid. If `data` is provided but with no `name`, defaults to either :data:`NAME_POINTS` or :data:`NAME_CELLS`. **crs** : :obj:`CRSLike `, optional The Coordinate Reference System of the provided spatial coordinates. May be anything accepted by :meth:`pyproj.crs.CRS.from_user_input`. Defaults to ``EPSG:4326`` i.e., ``WGS 84``. **radius** : :class:`python:float` | :data:`python:None`, optional The radius of the grid sphere. Defaults to :data:`~geovista.common.RADIUS`. **zlevel** : :class:`python:int`, default=0 The z-axis level. Used in combination with the `zscale` to offset the `radius` by a proportional amount i.e., ``radius * zlevel * zscale``. **zscale** : :class:`python:float`, optional The proportional multiplier for z-axis `zlevel`. Defaults to :data:`~geovista.common.ZLEVEL_SCALE`. :Returns: :obj:`StructuredGrid ` The spherical structured grid. .. rubric:: Notes .. versionadded:: 0.6.0 .. !! processed by numpydoc !! .. py:data:: BRIDGE_CLEAN :type: bool :value: False Whether mesh cleaning performed by the bridge. .. !! processed by numpydoc !! .. py:data:: NAME_CELLS :type: str :value: 'cell_data' Default array name for data on the mesh cells. .. !! processed by numpydoc !! .. py:data:: NAME_POINTS :type: str :value: 'point_data' Default array name for data on the mesh points. .. !! processed by numpydoc !! .. py:data:: NAME_VECTORS :type: str :value: 'vector_data' Default array name for mesh vectors. .. !! processed by numpydoc !! .. py:type:: PathLike :canonical: str | pathlib.Path Type alias for an asset file path. .. !! processed by numpydoc !! .. py:data:: RIO_SIEVE_SIZE :type: int :value: 800 The default size of the :func:`rasterio.features.sieve` filter. .. !! processed by numpydoc !! .. py:type:: Shape :canonical: tuple[int, ...] Type alias for a tuple of integers. .. !! processed by numpydoc !!