Metadata-Version: 2.4
Name: pygndc
Version: 1.0.12
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: numpy>=1.21.0
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: cryptography>=41.0.0
Requires-Dist: matplotlib>=3.5.0 ; extra == 'all'
Requires-Dist: pillow>=9.0.0 ; 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'
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'
Requires-Dist: geopandas>=0.12.0 ; extra == 'geo'
Requires-Dist: shapely>=2.0.0 ; extra == 'geo'
Requires-Dist: matplotlib>=3.5.0 ; extra == 'viewer'
Requires-Dist: pillow>=9.0.0 ; extra == 'viewer'
Requires-Dist: xarray>=2022.0 ; extra == 'xarray'
Provides-Extra: all
Provides-Extra: dev
Provides-Extra: geo
Provides-Extra: viewer
Provides-Extra: xarray
License-File: LICENSE
Summary: Geographic Neural Data Cube - Read and analyze .gndc compressed geospatial time-series data
Keywords: geospatial,satellite,remote-sensing,neural-networks,compression
Author-email: Jianbo Qi <jianboqi@126.com>
Requires-Python: >=3.10, <3.14
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://geondc.org
Project-URL: Issues, https://github.com/jianboqi/pygndc/issues
Project-URL: Repository, https://github.com/jianboqi/pygndc

# 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
- **Portable Native encoder and decoder** — the default CPU/WGPU path needs no PyTorch, Numba, CUDA toolkit, or runtime JIT; WGPU targets Vulkan, DX12, and Metal, while Torch and tiny-cuda-nn remain optional compatibility extras
- **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.

## Installation Extras

The default wheel includes the native CPU/WGPU runtime, encoder, GeoTIFF I/O,
and core Python API. The desktop viewer is optional:

```bash
pip install pygndc[viewer]
```

## License

GeoNDC is proprietary binary software. Decoder operations may be used without
an encoder license; creating or exporting `.gndc` data requires a valid encoder
license. See [LICENSE](LICENSE) for the complete terms.

The GeoNDC file-format specification is published separately to support
interoperability. Previously released copies remain governed by the license
that accompanied those copies.

## 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)

