Metadata-Version: 2.4
Name: pygeospace
Version: 0.6.5
Summary: Powerful, honest, open-source geospatial visualization with true 3D.
Author: PyGeoSpace contributors
License: MIT
Project-URL: Homepage, https://github.com/pygeospace/pygeospace
Project-URL: Documentation, https://github.com/pygeospace/pygeospace#readme
Project-URL: Roadmap, https://github.com/pygeospace/pygeospace/blob/main/ROADMAP.md
Keywords: gis,geospatial,visualization,deck.gl,mapping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: geopandas>=1.0
Requires-Dist: shapely>=2.0
Requires-Dist: pyproj>=3.5
Requires-Dist: pydeck>=0.9
Requires-Dist: matplotlib>=3.7
Requires-Dist: pillow>=10.0
Requires-Dist: scikit-learn>=1.3
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.27
Requires-Dist: click>=8.1
Requires-Dist: pydantic>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Provides-Extra: raster
Requires-Dist: rasterio>=1.3; extra == "raster"
Provides-Extra: 3d
Requires-Dist: pyvista>=0.45; extra == "3d"
Requires-Dist: meshio>=5.3; extra == "3d"
Requires-Dist: trame>=3.0; extra == "3d"
Requires-Dist: trame-vtk>=2.8; extra == "3d"
Requires-Dist: trame-vuetify>=2.7; extra == "3d"
Provides-Extra: pointcloud
Requires-Dist: laspy[lazrs]>=2.5; extra == "pointcloud"
Provides-Extra: streaming
Requires-Dist: websockets>=12.0; extra == "streaming"
Requires-Dist: paho-mqtt>=2.0; extra == "streaming"
Provides-Extra: clustering-h3
Requires-Dist: h3>=4.0; extra == "clustering-h3"
Provides-Extra: network
Requires-Dist: osmnx>=2.0; extra == "network"
Provides-Extra: threed
Requires-Dist: pyvista>=0.45; extra == "threed"
Requires-Dist: meshio>=5.3; extra == "threed"
Requires-Dist: trame>=3.0; extra == "threed"
Requires-Dist: trame-vtk>=2.8; extra == "threed"
Requires-Dist: trame-vuetify>=2.7; extra == "threed"
Provides-Extra: distributed
Requires-Dist: dask[complete]>=2024.1; extra == "distributed"
Provides-Extra: all
Requires-Dist: rasterio>=1.3; extra == "all"
Requires-Dist: laspy[lazrs]>=2.5; extra == "all"
Requires-Dist: websockets>=12.0; extra == "all"
Requires-Dist: paho-mqtt>=2.0; extra == "all"
Requires-Dist: h3>=4.0; extra == "all"
Requires-Dist: pyvista>=0.45; extra == "all"
Requires-Dist: meshio>=5.3; extra == "all"
Requires-Dist: trame>=3.0; extra == "all"
Requires-Dist: trame-vtk>=2.8; extra == "all"
Requires-Dist: trame-vuetify>=2.7; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# PyGeoSpace

**Powerful, honest, open-source geospatial visualization for Python.**

PyGeoSpace is a 2D / true-3D mapping library built on a real geospatial stack
(GeoPandas, Shapely, pyproj, deck.gl, PyVista). It reads the common vector and
raster formats, renders interactive 2D maps and **true 3D terrain, point clouds,
and extruded geometry**, runs spatial + spectral analytics, and exports
interactive HTML, static images, or 3D model files (glTF/STL/PLY/OBJ).

This is the **0.6.0 (Beta)** release — "Advanced Visualization & True 3D". It is
deliberately honest about its boundaries: every capability under "What works
today" is implemented and covered by **81 passing tests**. Capabilities under
"Roadmap" are **not silently stubbed** — calling them raises a clear error that
names exactly what to install or that the feature is planned.

---

## Install

```bash
pip install pygeospace            # core: vector IO, analytics, deck.gl, web, CLI
pip install "pygeospace[raster]"  # + GeoTIFF/COG/JPEG2000 reading (rasterio)
pip install "pygeospace[3d]"      # + true 3D (PyVista, trame, meshio)
pip install "pygeospace[streaming]"  # + WebSocket & MQTT clients
pip install "pygeospace[all]"     # everything optional
```

Python 3.10+.

## True 3D quickstart (0.6.0)

```python
import pygeospace as pgs

# Terrain straight from an elevation GeoTIFF — interactive in the browser.
m = pgs.Map(mode="3d")
m.add_terrain("srtm_everest.tif", exaggeration=2.0, cmap="gist_earth")
m.export_3d("terrain.html")     # interactive vtk.js page
m.render_3d("terrain.png")      # static render
m.export_3d("terrain.gltf")     # 3D model for Blender/Unity/printing

# Classified LIDAR point cloud in 3D.
pgs.Map(mode="3d").add_pointcloud_3d("forest.las").render_3d("canopy.png")

# Extrude building footprints by a height attribute.
pgs.Map(mode="3d").add_extruded("buildings.shp", "height", factor=1.0).export_3d("city.gltf")

# Scripted camera flythrough.
cam = pgs.Camera3D(position=(0, 0, 5000), focal_point=(0, 0, 0))
cam.fly_to(4000, 4000, 2000, duration=3.0).orbit(45).tilt(20)
m.render_3d("flyover.png", camera=cam)
```

```bash
pygeospace 3d terrain elevation.tif --exaggeration 2.0 -o terrain.html
pygeospace 3d pointcloud data.las --classify -o cloud.html
pygeospace spectral sentinel.tif --indices ndvi,ndwi -o indices/
pygeospace flow od_data.csv -o flow.html
pygeospace export-gltf elevation.tif -o scene.gltf
```

## Quickstart (under 5 minutes)

```python
import pygeospace as pgs

m = pgs.Map()

# Read any vector format; style fluently; results chain.
cities = m.add_layer("cities.geojson")
cities.style(get_fill_color=[255, 90, 0, 200], get_radius=3000)

# Classify an attribute into a choropleth (quantiles / equal_interval / jenks).
from pygeospace.analytics import choropleth
districts = m.add_layer("districts.shp")
choropleth(districts, "population", method="jenks", k=5)

# A geometry pipeline, returning new layers at each step.
buffered = m.add_layer("rivers.gpkg").buffer(250)  # 250 m, in true meters

m.fit().save("map.html")     # interactive, offline-capable deck.gl page
m.save("map.png", dpi=300)   # static export
```

Command line:

```bash
pygeospace visualize cities.geojson -o map.html --style choropleth --attribute pop --method jenks
pygeospace export cities.geojson -o map.png --dpi 300
pygeospace serve cities.geojson --port 8000      # live preview in the browser
pygeospace serve --api --port 8000               # REST CRUD API
pygeospace info data.gpkg
```

## What works today (0.5.0)

| Area | Capability | Status |
|------|-----------|--------|
| **IO** | Shapefile, GeoJSON, GeoPackage, KML, GPX, GML (via GeoPandas/OGR) | ✅ |
| | CSV with coordinate columns | ✅ |
| | PostGIS query → layer | ✅ |
| | Format autodetect (extension + magic bytes) | ✅ |
| | GeoTIFF / COG / JPEG2000 read | ✅ with `[raster]` |
| | LAS/LAZ point cloud read | ✅ with `[pointcloud]` |
| **Vector viz** | deck.gl scatter / GeoJSON / heatmap / hexagon-bin | ✅ |
| | Choropleth: quantiles, equal-interval, **Jenks natural breaks** | ✅ |
| | pandas-query attribute filtering (instant, no reload) | ✅ |
| | CRS auto-reprojection to EPSG:4326 | ✅ |
| **Raster** | Multi-band arrays, on-the-fly NDVI, hillshade | ✅ |
| **Analytics** | Buffer (true meters via UTM), intersection, difference, dissolve | ✅ |
| | KMeans / DBSCAN clustering, hex/grid binning (H3 if installed) | ✅ |
| **3D (0.6.0)** | True 3D terrain from rasters (exaggeration, elevation colormap) | ✅ `[3d]` |
| | 3D point clouds with LAS-classification coloring; polygon extrusion; cut planes | ✅ `[3d]` |
| | Render to PNG + interactive HTML; export glTF/GLB/STL/PLY/OBJ/VTK | ✅ `[3d]` |
| | `Camera3D`: fly_to / orbit / tilt / path recording | ✅ `[3d]` |
| | Tilted (pitch/bearing) pseudo-3D deck.gl view | ✅ |
| **Raster (0.6.0)** | Spectral indices NDVI/NDWI/NDBI/SAVI/EVI; band compositing; slope | ✅ |
| | On-the-fly reprojection + multi-raster mosaicing | ✅ `[raster]` |
| **Vector (0.6.0)** | Contour lines from scattered points; O-D flow maps (arcs); H3 hexbins | ✅ |
| **Streaming** | WebSocket & MQTT clients; trail buffer; threshold alerts | ✅ with `[streaming]`¹ |
| **Publishing** | Interactive HTML, static PNG/PDF, Jupyter inline (`_repr_html_`) | ✅ |
| | FastAPI dev server + REST CRUD API | ✅ |
| **Extensibility** | Decorator plugin system (data sources, renderers, tools) | ✅ |

¹ The clients are real and connect to any reachable endpoint. Connecting to a
specific public broker requires network access to that host.

## Roadmap — what is *not* in 0.5.0

These are tracked in [`ROADMAP.md`](ROADMAP.md). Where the public API touches
them, it raises a clear, actionable error rather than pretending.

| Planned for | Feature |
|-------------|---------|
| **0.6.0** | True PyVista 3D globe + terrain extrusion; raster↔vector opacity blending in the static renderer; vector-tile generation |
| **0.7.0** | Getis-Ord Gi\* hotspot maps with significance shading; zonal statistics charts; OSMnx shortest-path routing |
| **1.0.0** | WebGPU renderer for multi-million-point scenes; COG tile server with LRU disk cache; Dask-parallel distributed loading; flow-map & time-slider widgets as first-class UI |

## Design notes

- **Honesty over surface area.** A smaller set of things that genuinely work
  beats a large set that breaks on first use.
- **Real units.** Buffers reproject to the local UTM zone so "250 m" means 250
  meters, not 250 degrees.
- **Lazy optional deps.** Heavy/optional libraries (rasterio, laspy, paho-mqtt,
  h3, pyvista) are imported only when used, with install hints on failure.

## Development

```bash
pip install -e ".[dev]"
pytest            # 43 tests
ruff check .
```

## License

MIT.

## 3D & 2D Gallery

Rendered headlessly by the test/example suite (see `examples/`):

| | |
|---|---|
| ![terrain](docs/gallery/terrain.png) 3D terrain (elevation colormap) | ![mountain](docs/gallery/terrain_mountain.png) Terrain from GeoTIFF |
| ![pointcloud](docs/gallery/pointcloud_classified.png) Classified point cloud | ![ndvi](docs/gallery/ndvi.png) NDVI spectral index |
| ![true_color](docs/imagery/true_color.png) True color satellite imagery | ![false_color_ir](docs/imagery/false_color_ir.png) False color infrared (FCIR) |
| ![agriculture](docs/imagery/agriculture.png) Agriculture/Vegetation analysis | ![nyc_map](docs/imagery/nyc_map.png) 2D NYC interactive map |

