gri-plot 0.2.6

3D geolocation visualization and 2D plotting utilities built on Plotly

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.

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.