Metadata-Version: 2.4
Name: pygndc
Version: 1.0.5
Summary: Geographic Neural Data Cube - Read and analyze .gndc compressed geospatial time-series data
Author-email: Jianbo Qi <jianboqi@126.com>
License: MIT
Project-URL: Homepage, https://geondc.org
Project-URL: Repository, https://github.com/jianboqi/pygndc
Project-URL: Issues, https://github.com/jianboqi/pygndc/issues
Keywords: geospatial,satellite,remote-sensing,neural-networks,compression
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Artificial Intelligence
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: numba>=0.58
Requires-Dist: zstandard>=0.21.0
Requires-Dist: rasterio>=1.3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: pillow>=9.0.0
Provides-Extra: gpu
Requires-Dist: numba-cuda>=0.2; extra == "gpu"
Requires-Dist: cuda-bindings; extra == "gpu"
Provides-Extra: torch
Requires-Dist: torch>=2.0.0; extra == "torch"
Provides-Extra: tcnn
Requires-Dist: torch>=2.0.0; extra == "tcnn"
Provides-Extra: xarray
Requires-Dist: xarray>=2022.0; extra == "xarray"
Provides-Extra: geo
Requires-Dist: geopandas>=0.12.0; extra == "geo"
Requires-Dist: shapely>=2.0.0; extra == "geo"
Provides-Extra: all
Requires-Dist: xarray>=2022.0; extra == "all"
Requires-Dist: geopandas>=0.12.0; extra == "all"
Requires-Dist: shapely>=2.0.0; extra == "all"
Requires-Dist: scipy>=1.9.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# pygndc

**Geographic Neural Data Cube** — a Python SDK for reading and analyzing `.gndc` compressed geospatial time-series data.

<img width="286" height="320" alt="GeoNDC" src="https://raw.githubusercontent.com/jianboqi/pygndc/main/assets/logo.png" />

## What is GeoNDC?

GeoNDC is a **continuous-time, AI-ready representation** of Earth observation archives. Unlike traditional Analysis-Ready Data (cloud-corrected raster files) or geospatial foundation model embeddings (abstract feature vectors), GeoNDC preserves the original physical observables — surface reflectance, vegetation indices, biophysical variables — while enabling millisecond-level random-access queries at any *(x, y, t)* coordinate.

Each archive (MODIS, Sentinel-2, Landsat, HiGLASS, …) is encoded into a single self-contained `.gndc` file (typically 0.5–2 GB) that runs on a laptop, a server, or directly in a browser via WebGPU. Data providers train the model once and publish the file; users download it and run inference locally — the compressed form *is* the analysis-ready form. No hosted runtime, no API quota, no vendor lock-in.

## Key Capabilities

- **Continuous-time reconstruction** — query data at any moment, not just original observation times
- **Millisecond random access** — point time series in ~7 ms, full-frame reconstruction in ~2 s on a consumer GPU
- **Analytic gradients** — compute spatial/temporal derivatives directly from the neural network
- **Compact storage** — typically ~100:1 versus Int16 raster baselines, up to ~400:1 versus raw float archives
- **Lightweight, torch-free decoder** — `pip install pygndc` reads `.gndc` with only numpy + numba (no PyTorch, no CUDA toolkit); the default CPU path is faster than PyTorch-CPU, with optional NVIDIA GPU decoding that still needs no PyTorch or tiny-cuda-nn
- **Implicit gap-filling** — cloud-occluded surfaces are reconstructed from the learned spatiotemporal field
- **Multi-sensor support** — Sentinel-2, Landsat, MODIS, HiGLASS, and more

## Online Viewer & Sample Data

- **Web Viewer**: Browse `.gndc` files directly in the browser via WebGPU at [geondc.org/viewer](https://www.geondc.org/viewer/) — no installation required, GPU-accelerated, runs entirely client-side.
- **Sample Data**: Download `.gndc` datasets from [Hugging Face](https://huggingface.co/datasets/geondc/geondc-data).

## Documentation

- **[TUTORIAL.md](TUTORIAL.md)** — Installation, quick-start, CLI commands, end-to-end usage examples.
- **[API_Reference.md](API_Reference.md)** — Full Python API for `pygndc.open()`, `GNDCDataset`, `GNDCReader`, analysis functions.

## License

MIT License

## Citation

```bibtex
@misc{qi2026geondcqueryableneuraldata,
  title={GeoNDC: A Queryable Neural Data Cube for Planetary-Scale Earth Observation},
  author={Jianbo Qi and Mengyao Li and Baogui Jiang and Yidan Chen and Qiao Wang},
  year={2026},
  eprint={2603.25037},
  archivePrefix={arXiv},
  primaryClass={cs.CV},
  url={https://arxiv.org/abs/2603.25037},
}
```

## Contact

- Author: Jianbo Qi
- Email: jianboqi@126.com
- Issues: [GitHub Issues](https://github.com/jianboqi/pygndc/issues)
