Plot (3D Geolocation Visualization)

3D geolocation visualization and 2D plotting utilities built on Plotly. Requires Python 3.12+.

Overview

This library renders parametric geometric shapes (ellipsoids, spheres, cones, cylinders) and observable surfaces that inherit from them (AOA cones, line-of-sight rays, range spheres) as interactive 3D meshes. It also provides shorthand functions for 2D scatter plots and geographic maps.

Documentation

The wheel ships its documentation inside the package, in gri_plot/docs/, so it is available wherever the package is installed:

• overview.md -- conventions, error ellipses, 3D shapes and measurement surfaces, 3D figures, and maps
• api_summary.md -- every public class and signature (generated)

Print the directory with python -c "import gri_plot, pathlib; print(pathlib.Path(gri_plot.__file__).parent / 'docs')". Every example in those files is run by the test suite.

Installation

pip install gri-plot

For development:

git clone https://gitlab.com/geosol-foss/python/gri-plot.git
cd gri-plot
uv sync

Quick Start

from gri_plot import scatter

# Simple 2D scatter plot -- pass traces as (y,), (x,y), or (x,y,kwargs)
scatter(
    ([1, 2, 3, 4],),                         # y-only trace
    ([0, 1, 2, 3], [1, 4, 2, 5]),            # x,y trace
    ([0, 1, 2, 3], [2, 3, 1, 4], {"name": "Series B"}),
    title="Example Plot",
)

Scatter

Plotly scatter plots with flexible input formats. Accepts variable-length trace info as (y,), (x,y), or (x,y,trace_args). All traces must consistently define or omit x. Uses plotly_dark template by default.

Scatter Map

Geographic scatter maps using Plotly's Scattermapbox. Takes lat/lon sequences, uses ArcGIS World Imagery as the base layer, and auto-centers the map based on data bounds.

from gri_plot import scatter_map

scatter_map(
    lats=[40.0, 40.1, 40.2],
    lons=[-105.0, -104.9, -104.8],
    title="Station Locations",
)

Figure3D

Scene builder for composing 3D visualizations from multiple surfaces and points:

• add_surface(): Add any ImplicitShape (shapes or observables)
• add_points(): Add labeled scatter points
• add_line(): Add line segments connecting points
• plot_surfaces(): Convenience function for quick multi-surface plots
• Method chaining, automatic color cycling from D3 palette, plotly_dark template

from gri_plot import Figure3D
from gri_plot.shapes import Sphere
import numpy as np

fig = Figure3D()
fig.add_surface(Sphere(center=np.array([0, 0, 0]), radius=100))
fig.add_points(np.array([[50, 50, 50]]), labels=["Target"])
fig.show()

Frames

Coordinate frame handling for 3D display:

• Frame enum: XYZ (ECEF), ENU (local tangent plane), LLA (lat/lon/alt)
• FrameTransformer: Converts between XYZ and display frame using gri-utils coordinate conversions
• Bounds: Named tuple for axis-aligned bounding boxes with frame metadata
• All internal computation in XYZ; frame conversion applied only for display

Shapes

Geometric primitives implementing the ImplicitShape ABC. Each supports parametric mesh generation (fast, exact geometry) and implicit residual evaluation.

• Ellipsoid: From center + covariance matrix, or center + semi-axes + rotation matrix
• Sphere: From center + radius
• Cone: From apex + axis direction + half-angle + height
• Cylinder: From center + axis direction + radius + height
• Mesh generators: Standalone functions (sphere_mesh, ellipsoid_mesh, cone_mesh, cylinder_mesh) for direct vertex/face generation

Observables

Geolocation-specific surfaces that inherit from parametric shapes:

• AoaSurface: AOA cone (extends Cone) from collector position + measured direction + angular error
• LosSurface: Line of sight ray (extends Cylinder) from start point + direction + length; also provides to_line_trace() for simple line rendering
• RangeSphere: Range/TOA sphere (extends Sphere) from collector position + range measurement

Surfaces

Low-level infrastructure for shape rendering:

• ImplicitShape ABC: Interface requiring residual_fn(), get_bounds_xyz(), to_mesh(), to_trace(), is_volume, label; also provides contains() for point-in-shape testing
• Mesh utilities: grid_to_mesh() (parametric grid triangulation), vertices_to_mesh3d() (vertices/faces to Plotly Mesh3d trace)

Dependencies

• plotly: Interactive 2D and 3D visualization
• numpy: Array operations
• gri-utils: Coordinate conversions and constants

Other Projects

Current list of other GRI FOSS Projects we are building and maintaining.

License

MIT License. See LICENSE for details.