Metadata-Version: 2.4
Name: gri-plot
Version: 0.2.5
Summary: 3D geolocation visualization and 2D plotting utilities built on Plotly
Project-URL: Homepage, https://geosolresearch.com
Project-URL: Repository, https://gitlab.com/geosol-foss/python/gri-plot
Project-URL: Issues, https://gitlab.com/geosol-foss/python/gri-plot/-/issues
Project-URL: Changelog, https://gitlab.com/geosol-foss/python/gri-plot/-/releases
Author-email: GeoSol Research Inc <contact@geosolresearch.com>
License-Expression: MIT
License-File: LICENSE
Keywords: 3D,geolocation,matplotlib,plotly,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.12
Requires-Dist: gri-utils>=0.3.3
Requires-Dist: numpy>=2.3.3
Requires-Dist: pillow>=11.0.0
Requires-Dist: plotly>=6.3.0
Description-Content-Type: text/markdown

[![GeoSol Research Logo](https://geosolresearch.com/logos/foss_logo.png "GeoSol Research")](https://geosolresearch.com)

# 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

```bash
pip install gri-plot
```

For development:

```bash
git clone https://gitlab.com/geosol-foss/python/gri-plot.git
cd gri-plot
. .init_venv.sh
```

## Quick Start

```python
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.

```python
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

```python
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](https://gitlab.com/geosol-foss/python/gri-plot/-/blob/main/.docs_other_projects.md) we are building and maintaining.

## License

MIT License. See [LICENSE](https://gitlab.com/geosol-foss/python/gri-plot/-/blob/main/LICENSE) for details.
