geovista.geoplotter#

Provide specialisation to support a geospatial aware plotter.

See pyvista.Plotter.

Notes#

Added in version 0.1.0.

Module Contents#

Classes#

GeoPlotter

A geospatial aware plotter.

GeoPlotterBase

Base class with common behaviour for a geospatial aware plotter.

Attributes#

ADD_POINTS_STYLE

The valid 'style' options for adding points.

BASE_ZLEVEL_SCALE

Proportional multiplier for z-axis levels/offsets of base-layer mesh.

COASTLINES_RTOL

Coastlines relative tolerance for longitudes close to 'wrap meridian'.

GRATICULE_LABEL_FONT_SIZE

The default font size for graticule labels.

GRATICULE_SHOW_LABELS

Whether to render graticule labels by default.

OPACITY_BLACKLIST

Known GPU renderer and version combinations that don't support opacity.

class geovista.geoplotter.GeoPlotter(*args, crs=None, **kwargs)[source]#

Bases: GeoPlotterBase, pv

A geospatial aware plotter.

See geovista.geoplotter.GeoPlotterBase and pyvista.Plotter.

Notes#

Added in version 0.1.0.

Create geospatial aware plotter.

Parameters:
*argstuple, optional

See pyvista.Plotter for further details.

crsCRSLike, optional

The target CRS to render geolocated meshes added to the plotter. May be anything accepted by pyproj.crs.CRS.from_user_input(). Defaults to EPSG:4326 i.e., WGS 84.

**kwargsdict, optional

See pyvista.Plotter for further details.

Notes

Added in version 0.1.0.

class geovista.geoplotter.GeoPlotterBase(*args, crs=None, **kwargs)[source]#

Base class with common behaviour for a geospatial aware plotter.

See pyvista.Plotter.

Notes#

Added in version 0.1.0.

Create geospatial aware plotter.

Parameters:
*argstuple, optional

See pyvista.Plotter for further details.

crsCRSLike, optional

The target CRS to render geolocated meshes added to the plotter. May be anything accepted by pyproj.crs.CRS.from_user_input(). Defaults to EPSG:4326 i.e., WGS 84.

**kwargsdict, optional

See pyvista.Plotter for further details.

Notes

Added in version 0.1.0.

add_base_layer(mesh=None, resolution=None, radius=None, zlevel=None, zscale=None, rtol=None, atol=None, **kwargs)[source]#

Generate a cubed-sphere base layer mesh and add to the plotter scene.

Optionally, a mesh may be provided (e.g. if one is available that better fits the geometry of the surface mesh).

Parameters:
meshPolyData, optional

Use the provided mesh as the base layer.

resolutionstr, optional

The resolution of the cubed-sphere to generate as the base layer, which may be either c48, c96 or c192. Defaults to geovista.pantry.meshes.LFRIC_RESOLUTION. Alternatively, generate a regular grid using a format of rN, where N is the number of cells in latitude, and N * 1.5 cells in longitude. When adding a base layer to a projection, the default is to use a regular grid with resolution geovista.pantry.meshes.REGULAR_RESOLUTION.

radiusfloat, optional

The radius of the spherical mesh to generate as the base layer. Defaults to geovista.common.RADIUS.

zlevelint, optional

The z-axis level. Used in combination with the zscale to offset the radius by a proportional amount i.e., radius * zlevel * zscale. Defaults to -1.

zscalefloat, optional

The proportional multiplier for z-axis zlevel. Defaults to BASE_ZLEVEL_SCALE.

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.

**kwargsdict, optional

See pyvista.Plotter.add_mesh().

Returns:
Actor

The rendered actor added to the plotter scene.

Notes

Added in version 0.1.0.

add_coastlines(resolution=None, radius=None, zlevel=None, zscale=None, rtol=None, atol=None, **kwargs)[source]#

Generate coastlines and add to the plotter scene.

Parameters:
resolutionstr, optional

The resolution of the Natural Earth coastlines, which may be either 110m, 50m, or 10m. Defaults to geovista.common.COASTLINES_RESOLUTION.

radiusfloat, optional

The radius of the sphere. Defaults to geovista.common.RADIUS.

zlevelint, optional

The z-axis level. Used in combination with the zscale to offset the radius by a proportional amount i.e., radius * zlevel * zscale. Defaults to geovista.common.ZTRANSFORM_FACTOR.

zscalefloat, optional

The proportional multiplier for z-axis zlevel. Defaults to geovista.common.ZLEVEL_SCALE.

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.

**kwargsdict, optional

See pyvista.Plotter.add_mesh().

Returns:
Actor

The rendered actor added to the plotter scene.

Notes

Added in version 0.1.0.

add_graticule(lon_start=None, lon_stop=None, lon_step=None, lat_start=None, lat_stop=None, lat_step=None, poles_parallel=None, poles_label=None, show_labels=None, radius=None, zlevel=None, zscale=None, mesh_args=None, point_labels_args=None)[source]#

Generate a graticule and add to the plotter scene.

This involves generating lines of constant latitude (parallels) and lines of constant longitude (meridians), which together form the graticule.

Parameters:
lon_startfloat, optional

The first line of longitude (degrees). The graticule will include this meridian. Defaults to geovista.gridlines.LONGITUDE_START.

lon_stopfloat, optional

The last line of longitude (degrees). The graticule will include this meridian when it is a multiple of lon_step. Also see closed_interval in create_meridians(). Defaults to geovista.gridlines.LONGITUDE_STOP.

lon_stepfloat, optional

The delta (degrees) between neighbouring meridians. Defaults to geovista.gridlines.LONGITUDE_STEP.

lat_startfloat, optional

The first line of latitude (degrees). The graticule will include this parallel. Also see poles_parallel. Defaults to geovista.gridlines.LATITUDE_START.

lat_stopfloat, optional

The last line of latitude (degrees). The graticule will include this parallel when it is a multiple of lat_step. Defaults to geovista.gridlines.LATITUDE_STOP.

lat_stepfloat, optional

The delta (degrees) between neighbouring parallels. Defaults to geovista.gridlines.LATITUDE_STEP.

poles_parallelbool, optional

Whether to create a line of latitude at the north/south poles. Defaults to geovista.gridlines.LATITUDE_POLES_PARALLEL.

poles_labelbool, optional

Whether to create a single north/south pole label. Only applies when poles_parallel=False. Defaults to geovista.gridlines.LATITUDE_POLES_LABEL.

show_labelsbool, optional

Whether to render the labels of the parallels and meridians. Defaults to GRATICULE_SHOW_LABELS.

radiusfloat, optional

The radius of the sphere. Defaults to geovista.common.RADIUS.

zlevelint, optional

The z-axis level. Used in combination with the zscale to offset the radius by a proportional amount i.e., radius * zlevel * zscale. Defaults to geovista.gridlines.GRATICULE_ZLEVEL.

zscalefloat, optional

The proportional multiplier for z-axis zlevel. Defaults to geovista.common.ZLEVEL_SCALE.

mesh_argsdict, optional

Arguments to pass through to pyvista.Plotter.add_mesh().

point_labels_argsdict, optional

Arguments to pass through to pyvista.Plotter.add_point_labels().

Notes

Added in version 0.3.0.

add_meridian(lon, lat_step=None, n_samples=None, show_labels=None, radius=None, zlevel=None, zscale=None, mesh_args=None, point_labels_args=None)[source]#

Generate a line of constant longitude and add to the plotter scene.

Parameters:
lonfloat

The constant line of longitude (degrees) to generate.

lat_stepfloat, optional

The delta (degrees) between neighbouring parallels. Sets the frequency of the labels. Defaults to geovista.gridlines.LATITUDE_STEP.

n_samplesint, optional

The number of points in a single line of longitude. Defaults to geovista.gridlines.LONGITUDE_N_SAMPLES.

show_labelsbool, optional

Whether to render the meridian label. Defaults to GRATICULE_SHOW_LABELS.

radiusfloat, optional

The radius of the sphere. Defaults to geovista.common.RADIUS.

zlevelint, optional

The z-axis level. Used in combination with the zscale to offset the radius by a proportional amount i.e., radius * zlevel * zscale. Defaults to geovista.gridlines.GRATICULE_ZLEVEL.

zscalefloat, optional

The proportional multiplier for z-axis zlevel. Defaults to geovista.common.ZLEVEL_SCALE.

mesh_argsdict, optional

Arguments to pass through to pyvista.Plotter.add_mesh().

point_labels_argsdict, optional

Arguments to pass through to pyvista.Plotter.add_point_labels().

Notes

Added in version 0.3.0.

add_meridians(start=None, stop=None, step=None, lat_step=None, n_samples=None, show_labels=None, radius=None, zlevel=None, zscale=None, mesh_args=None, point_labels_args=None)[source]#

Generate lines of constant longitude and add to the plotter scene.

Parameters:
startfloat, optional

The first line of longitude (degrees). The graticule will include this meridian. Defaults to geovista.gridlines.LONGITUDE_START.

stopfloat, optional

The last line of longitude (degrees). The graticule will include this meridian when it is a multiple of step. Also see closed_interval in create_meridians(). Defaults to geovista.gridlines.LONGITUDE_STOP.

stepfloat, optional

The delta (degrees) between neighbouring meridians. Defaults to geovista.gridlines.LONGITUDE_STEP.

lat_stepfloat, optional

The delta (degrees) between neighbouring parallels. Sets the frequency of the labels. Defaults to geovista.gridlines.LATITUDE_STEP.

n_samplesint, optional

The number of points in a single line of longitude. Defaults to geovista.gridlines.LONGITUDE_N_SAMPLES.

show_labelsbool, optional

Whether to render the labels of the meridians. Defaults to GRATICULE_SHOW_LABELS.

radiusfloat, optional

The radius of the sphere. Defaults to geovista.common.RADIUS.

zlevelint, optional

The z-axis level. Used in combination with the zscale to offset the radius by a proportional amount i.e., radius * zlevel * zscale. Defaults to geovista.gridlines.GRATICULE_ZLEVEL.

zscalefloat, optional

The proportional multiplier for z-axis zlevel. Defaults to geovista.common.ZLEVEL_SCALE.

mesh_argsdict, optional

Arguments to pass through to pyvista.Plotter.add_mesh().

point_labels_argsdict, optional

Arguments to pass through to pyvista.Plotter.add_point_labels().

Notes

Added in version 0.3.0.

add_mesh(mesh, radius=None, zlevel=None, zscale=None, rtol=None, atol=None, **kwargs)[source]#

Add the mesh to the plotter scene.

See pyvista.Plotter.add_mesh().

Parameters:
meshPolyData

The mesh to add to the plotter.

radiusfloat, optional

The radius of the sphere. Defaults to geovista.common.RADIUS.

zlevelint or ArrayLike, optional

The z-axis level. Used in combination with the zscale to offset the radius/vertical by a proportional amount e.g., radius * zlevel * zscale. If zlevel is not a scalar, then its shape must match or broadcast with the shape of the mesh.points. Defaults to 0.

zscalefloat, optional

The proportional multiplier for z-axis zlevel. Defaults to geovista.common.ZLEVEL_SCALE.

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.

**kwargsdict, optional

See pyvista.Plotter.add_mesh().

Returns:
Actor

The rendered actor added to the plotter scene.

Notes

Added in version 0.1.0.

add_parallel(lat, lon_step=None, n_samples=None, poles_parallel=None, show_labels=None, radius=None, zlevel=None, zscale=None, mesh_args=None, point_labels_args=None)[source]#

Generate a line of constant latitude and add to the plotter scene.

Parameters:
latfloat

The constant line of latitude (degrees) to generate.

lon_stepfloat, optional

The delta (degrees) between neighbouring meridians. Sets the frequency of the labels. Defaults to geovista.gridlines.LONGITUDE_STEP.

n_samplesint, optional

The number of points in a single line of latitude. Defaults to geovista.gridlines.LATITUDE_N_SAMPLES.

poles_parallelbool, optional

Whether to create a line of latitude at the north/south poles. Defaults to geovista.gridlines.LATITUDE_POLES_PARALLEL.

show_labelsbool, optional

Whether to render the parallel label. Defaults to GRATICULE_SHOW_LABELS.

radiusfloat, optional

The radius of the sphere. Defaults to geovista.common.RADIUS.

zlevelint, optional

The z-axis level. Used in combination with the zscale to offset the radius by a proportional amount i.e., radius * zlevel * zscale. Defaults to geovista.gridlines.GRATICULE_ZLEVEL.

zscalefloat, optional

The proportional multiplier for z-axis zlevel. Defaults to geovista.common.ZLEVEL_SCALE.

mesh_argsdict, optional

Arguments to pass through to pyvista.Plotter.add_mesh().

point_labels_argsdict, optional

Arguments to pass through to pyvista.Plotter.add_point_labels().

Notes

Added in version 0.3.0.

add_parallels(start=None, stop=None, step=None, lon_step=None, n_samples=None, poles_parallel=None, poles_label=None, show_labels=None, radius=None, zlevel=None, zscale=None, mesh_args=None, point_labels_args=None)[source]#

Generate lines of constant latitude and add to the plotter scene.

Parameters:
startfloat, optional

The first line of latitude (degrees). The graticule will include this parallel. Also see poles_parallel. Defaults to geovista.gridlines.LATITUDE_START.

stopfloat, optional

The last line of latitude (degrees). The graticule will include this parallel when it is a multiple of step. Also see poles_parallel. Defaults to geovista.gridlines.LATITUDE_STOP.

stepfloat, optional

The delta (degrees) between neighbouring parallels. Defaults to geovista.gridlines.LATITUDE_STEP.

lon_stepfloat, optional

The delta (degrees) between neighbouring meridians. Sets the frequency of the labels. Defaults to geovista.gridlines.LONGITUDE_STEP.

n_samplesint, optional

The number of points in a single line of latitude. Defaults to geovista.gridlines.LATITUDE_N_SAMPLES.

poles_parallelbool, optional

Whether to create a line of latitude at the north/south poles. Defaults to geovista.gridlines.LATITUDE_POLES_PARALLEL.

poles_labelbool, optional

Whether to create a single north/south pole label. Only applies when poles_parallel=False. Defaults to geovista.gridlines.LATITUDE_POLES_LABEL.

show_labelsbool, optional

Whether to render the labels of the parallels. Defaults to GRATICULE_SHOW_LABELS.

radiusfloat, optional

The radius of the sphere. Defaults to geovista.common.RADIUS.

zlevelint, optional

The z-axis level. Used in combination with the zscale to offset the radius by a proportional amount i.e., radius * zlevel * zscale. Defaults to geovista.gridlines.GRATICULE_ZLEVEL.

zscalefloat, optional

The proportional multiplier for z-axis zlevel. Defaults to geovista.common.ZLEVEL_SCALE.

mesh_argsdict, optional

Arguments to pass through to pyvista.Plotter.add_mesh().

point_labels_argsdict, optional

Arguments to pass through to pyvista.Plotter.add_point_labels().

Notes

Added in version 0.3.0.

add_points(points=None, xs=None, ys=None, scalars=None, crs=None, radius=None, style=None, zlevel=None, zscale=None, **kwargs)[source]#

Add points to the plotter scene.

See pyvista.Plotter.add_mesh().

Parameters:
pointsArrayLike or PolyData, optional

Array of xyz points, or the points of the mesh to be rendered. Passed to pyvista.core.utilities.helpers.wrap() without any cartographic transformation, i.e. 0 0 0 is centre of the globe (the plot origin), 0 0 1 is the north pole.

xsArrayLike, optional

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.

ysArrayLike

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.

scalarsstr or ArrayLike, optional

Values used to color the points. Either, the string name of an array that is present on the points mesh or an array equal to the number of points. If both color (see kwargs) and scalars are None, then the active scalars on the points mesh are used.

crsCRSLike, optional

The Coordinate Reference System of the provided points, or xs and ys. May be anything accepted by pyproj.crs.CRS.from_user_input(). Defaults to EPSG:4326 i.e., WGS 84.

radiusfloat, optional

The radius of the mesh point-cloud. Defaults to geovista.common.RADIUS.

stylestr, optional

Visualization style of the points to be rendered. May be either points or points_gaussian. The points_gaussian option may be controlled with the emissive and render_points_as_spheres options in kwargs.

zlevelint or ArrayLike, optional

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. Defaults to 0.

zscalefloat, optional

The proportional multiplier for z-axis zlevel. Defaults to geovista.common.ZLEVEL_SCALE.

**kwargsdict, optional

See pyvista.Plotter.add_mesh().

Returns:
Actor

The rendered actor added to the plotter scene.

Notes

Added in version 0.4.0.

view_poi(x=None, y=None, crs=None)[source]#

Center the camera at a point-of-interest (POI).

If no POI is provided, then the center of the previous mesh added to the scene is used, if available.

Note that, the camera will be positioned at the POI to view all the actors added to the scene so far; order is important. The point at which view_poi() is called relative to the other actors influences the final rendered scene.

Parameters:
xfloat, optional

The spatial x-value point, in canonical crs units, of the POI. Defaults to 0 if unspecified and y has been provided, otherwise None.

yfloat, optional

The spatial y-value point, in canonical crs units, of the POI. Defaults to 0 if unspecified and x has been provided, otherwise None.

crsCRSLike, optional

The Coordinate Reference System of the POI. May be anything accepted by pyproj.crs.CRS.from_user_input(). Defaults to EPSG:4326 i.e., WGS 84.

Notes

Added in version 0.5.0.

Examples

First, create an RGB mesh of the Bahamas from a GeoTIFF.

>>> import geovista
>>> from geovista.pantry import fetch_raster
>>> fname = fetch_raster("bahamas_rgb.tif")
>>> bahamas = geovista.Transform.from_tiff(
...     fname, rgb=True, sieve=True, extract=True
... )

Now add the bahamas mesh to a plotter before adding a texture mapped base layer. Note that, the camera is centered over the bahamas mesh, which is the primary focus of the scene.

>>> plotter = geovista.GeoPlotter()
>>> _ = plotter.add_mesh(bahamas, rgb=True)
>>> plotter.view_poi()
>>> _ = plotter.add_base_layer(texture=geovista.natural_earth_1())
>>> plotter.show()
../../../../../_images/index-1_00_002.png

In comparison, add a texture mapped base layer to a plotter before the bahamas mesh. The camera is still centered over the bahamas in the rendered scene, however the base layer is now fully visible.

>>> plotter = geovista.GeoPlotter()
>>> _ = plotter.add_base_layer(texture=geovista.natural_earth_1())
>>> _ = plotter.add_mesh(bahamas, rgb=True)
>>> plotter.view_poi()
>>> plotter.show()
../../../../../_images/index-1_01_00.png
crs#
geovista.geoplotter.ADD_POINTS_STYLE: list[str, str] = ['points', 'points_gaussian']#

The valid ā€˜styleā€™ options for adding points.

geovista.geoplotter.BASE_ZLEVEL_SCALE: int = 0.001#

Proportional multiplier for z-axis levels/offsets of base-layer mesh.

geovista.geoplotter.COASTLINES_RTOL: float = 1e-08#

Coastlines relative tolerance for longitudes close to ā€˜wrap meridianā€™.

geovista.geoplotter.GRATICULE_LABEL_FONT_SIZE: int = 9#

The default font size for graticule labels.

geovista.geoplotter.GRATICULE_SHOW_LABELS: bool = True#

Whether to render graticule labels by default.

geovista.geoplotter.OPACITY_BLACKLIST = [('llvmpipe (LLVM 7.0, 256 bits)', '3.3 (Core Profile) Mesa 18.3.4')]#

Known GPU renderer and version combinations that donā€™t support opacity.