:py:mod:`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 !! Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: geovista.bridge.Transform Attributes ~~~~~~~~~~ .. autoapisummary:: geovista.bridge.BRIDGE_CLEAN geovista.bridge.NAME_CELLS geovista.bridge.NAME_POINTS geovista.bridge.PathLike geovista.bridge.RIO_SIEVE_SIZE geovista.bridge.Shape .. 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 1-D array of x-values, in canonical `crs` units, defining the vertices of each face in the mesh. **ys** : :obj:`ArrayLike ` A 1-D 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 2-D ``(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 2-D, 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:: 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 1-D 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 1-D 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 1-D 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 2-D 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 2-D 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 2-D 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) :classmethod: Build a point-cloud mesh from x-values, y-values and z-levels. Note that, any optional mesh `data` provided must be in the same order as the spatial points. :Parameters: **xs** : :obj:`ArrayLike ` A 1-D, 2-D or 3-D array of point-cloud x-values, in canonical `crs` units. Must have the same shape as the `ys`. **ys** : :obj:`ArrayLike ` A 1-D, 2-D or 3-D 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`. :Returns: :obj:`PolyData ` The point-cloud spherical mesh. .. 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`, optional The band index to read from the GeoTIFF. Note that, the `band` index is one-based. Defaults to the first band i.e., ``band=1``. **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: >>> plotter = GeoPlotter() >>> _ = plotter.add_mesh(mesh, rgb=True) >>> plotter.view_poi() >>> _ = plotter.add_base_layer(texture=natural_earth_1(), zlevel=0) >>> _ = plotter.add_coastlines(color="white") >>> plotter.show() .. !! processed by numpydoc !! .. py:method:: from_unstructured(xs, ys, connectivity = None, data = None, start_index = None, name = None, crs = None, rgb = None, radius = None, zlevel = None, zscale = None, clean = None) :classmethod: Build a mesh from unstructured 1-D 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` & `ys` (data can be on points or on cells). :Parameters: **xs** : :obj:`ArrayLike ` A 1-D array of x-values, in canonical `crs` units, defining the vertices of each face in the mesh. **ys** : :obj:`ArrayLike ` A 1-D 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 2-D ``(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 2-D, 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: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:: PathLike :type: TypeAlias :value: str | PurePath 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:data:: Shape :type: TypeAlias :value: tuple[int] Type alias for a tuple of integers. .. !! processed by numpydoc !!