geovista.geoplotter

`geovista.geoplotter`#

Provide specialisation to support a geospatial aware plotter.

See pyvista.Plotter.

Notes#

Added in version 0.1.0.

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.

Classes#

`GeoPlotter`	A geospatial aware plotter.
`GeoPlotterBase`	Base class with common behaviour for a geospatial aware plotter.

Module Contents#

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.

>>> p = geovista.GeoPlotter()
>>> _ = p.add_mesh(bahamas, rgb=True)
>>> p.view_poi()
>>> _ = p.add_base_layer(texture=geovista.natural_earth_1())
>>> p.show()

Static Scene

../../../../../_images/index-1_00_002.png

Interactive Scene

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.

>>> p = geovista.GeoPlotter()
>>> _ = p.add_base_layer(texture=geovista.natural_earth_1())
>>> _ = p.add_mesh(bahamas, rgb=True)
>>> p.view_poi()
>>> p.show()

Static Scene

../../../../../_images/index-1_01_00.png

Interactive Scene

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.

geovista.geoplotter

On this page

geovista.geoplotter#

Notes#

Attributes#

Classes#

Module Contents#

Notes#

Notes#

`geovista.geoplotter`#