gri-plot 0.2.3

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 implicit surfaces (TDOA hyperboloids, FDOA iso-Doppler surfaces, AOA cones, range spheres, terrain) and geometric shapes (ellipsoids, spheres, cones, cylinders) 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
. .init_venv.sh

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
• add_intersection(): Highlight where multiple surfaces intersect
• 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
from gri_plot.observables import TdoaSurface
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 (for intersection calculations).

• 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 for visualizing measurement iso-surfaces. Some inherit from shapes (reusing parametric rendering), others use marching cubes for mesh extraction.

• TdoaSurface: TDOA hyperboloid where range_1 - range_2 = c x tdoa, from two collector positions + time difference
• FdoaSurface: FDOA iso-Doppler surface from two collector positions/velocities + carrier frequency + frequency difference
• 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
• TerrainSurface: Terrain from XYZ vertex grid with interpolated residual evaluation; factory methods from_xyz_grids() and from_elevation_grid()

Surfaces

Low-level infrastructure for implicit surface 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: field_to_mesh() (marching cubes with Newton-Raphson surface projection and adaptive refinement), grid_to_mesh() (parametric grid triangulation), vertices_to_mesh3d() (vertices/faces to Plotly Mesh3d trace)
• IntersectionField: Euclidean distance in residual space for highlighting multi-surface intersections; distinguishes volumes (interior contribution) from surfaces (boundary contribution)
• Gradient functions: Intensity calculators for mesh coloring -- distance_from_point, distance_from_line, distance_from_line_segment, distance_from_plane, distance_from_axis, axis_value

Dependencies

• plotly: Interactive 2D and 3D visualization
• matplotlib: Static plot support
• numpy: Array operations
• scipy: Marching cubes mesh extraction
• scikit-image: Additional mesh processing
• 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.