pygndc 1.0.0__tar.gz

pygndc-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jianboqi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pygndc-1.0.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: pygndc
+Version: 1.0.0
+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: torch>=2.0.0
+Requires-Dist: rasterio>=1.3.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tqdm>=4.65.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: zstandard>=0.21.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: pillow>=9.0.0
+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://github.com/user-attachments/assets/6c526878-93bc-4b70-bc99-cbb99193931a" />
+
+## What is GeoNDC?
+
+GeoNDC is a neural network-based compression format for multi-dimensional geospatial raster data. A single `.gndc` file stores 4D spatiotemporal data (Time x Height x Width x Bands) with up to **300:1 compression ratios**.
+
+Key capabilities:
+
+- **Arbitrary time reconstruction** - reconstruct data at any time point, not just original observation times
+- **Fast random access** - query any pixel at any timestamp instantly
+- **Analytic gradients** - compute spatial/temporal derivatives directly from the neural network
+- **Multi-sensor support** - Sentinel-2, Landsat, MODIS, HiGLASS, and more
+
+## Online Viewer & 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).
+
+## Installation
+
+```bash
+pip install pygndc
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/jianboqi/pygndc.git
+cd pygndc
+pip install .
+```
+
+### GPU support (recommended)
+
+`pip install pygndc` installs CPU-only PyTorch by default. For GPU acceleration, install CUDA-enabled PyTorch **first**:
+
+```bash
+# Example for CUDA 12.1 (check https://pytorch.org for your CUDA version)
+pip install torch --index-url https://download.pytorch.org/whl/cu121
+
+# Then install pygndc
+pip install pygndc
+```
+
+### tiny-cuda-nn (fastest)
+
+For best performance, install [tiny-cuda-nn](https://github.com/NVlabs/tiny-cuda-nn). This provides the optimized TCNN backend with significantly faster inference and lower memory usage.
+
+```bash
+pip install git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch
+```
+
+> **Note**: tiny-cuda-nn requires an NVIDIA GPU with CUDA support and a C++ compiler. If you cannot install it, pygndc will automatically fall back to pure PyTorch (`torch_gpu` or `torch_cpu`).
+
+### Optional dependencies
+
+```bash
+pip install pygndc[all]       # xarray + geopandas + scipy
+pip install pygndc[xarray]    # xarray support
+pip install pygndc[geo]       # geopandas + shapely
+```
+
+### Inference modes
+
+pygndc uses a single `mode` parameter to control both the backend and device:
+
+| Mode | Backend | Device | Description |
+|------|---------|--------|-------------|
+| `auto` | auto-detect | auto-detect | **Default.** Best available mode |
+| `tcnn_cuda` | tiny-cuda-nn | GPU | Fastest. Requires tinycudann + CUDA |
+| `torch_gpu` | PyTorch | GPU | No extra dependencies, requires CUDA |
+| `torch_cpu` | PyTorch | CPU | Works everywhere, slowest |
+
+## Quick Start
+
+```python
+import pygndc
+
+# Open a .gndc file (auto-detects best mode)
+with pygndc.open("samples/S2_sample_2022_to_2025.gndc") as ds:
+    print(ds)                                          # Shows mode, shape, CRS, etc.
+
+    # Read a frame
+    frame = ds.read(t=0)                               # (H, W, C) by index
+    frame = ds.read(t="2024-06-15")                    # by date string
+    frame = ds.read_at_time("2024-06-15 12:00:00")     # continuous interpolation
+
+    # Point query (coordinates within the sample's bounds)
+    series = ds.sample(lon=116.825, lat=40.486)        # (T, C) full time series
+    values = ds.sample(lon=116.825, lat=40.486, t=0)   # (C,) single time
+
+    # Pixel time series
+    series = ds.pixel_series(row=140, col=140)         # (T, C)
+
+    # Analysis
+    ndvi = ds.ndvi(t=0, red_band=2, nir_band=3)       # (H, W)
+    dx, dy = ds.gradient(t=0, mode="spatial")          # analytic gradients
+
+    # Export
+    arr = ds.to_numpy(t=0)                             # (H, W, C) numpy array
+    ds.to_tif("frame_0.tif", t=0)                     # single frame to GeoTIFF
+    ds.to_tifs("output_dir/")                          # all frames
+    xds = ds.to_xarray()                               # xarray Dataset
+
+# Specify mode explicitly
+with pygndc.open("samples/S2_sample_2022_to_2025.gndc", mode="torch_cpu") as ds:
+    frame = ds.read(t=0)
+```
+
+## CLI Commands
+
+```bash
+# Show model info
+pygndc info model.gndc
+pygndc info model.gndc --json
+
+# Decompress to GeoTIFF files
+pygndc decompress -i model.gndc -o ./output
+pygndc decompress -i model.gndc -o ./output --timestamp 2024-06-15
+pygndc decompress -i model.gndc -o ./output --start 2024-01-01 --end 2024-12-31 --interval 5
+
+# Compute NDVI
+pygndc ndvi -i model.gndc -o ndvi.tif --red-band 0 --nir-band 1
+
+# Compute spatial gradient
+pygndc derivative -i model.gndc -o gradient.tif --grad-mode mag
+
+# Point query
+pygndc sample -i model.gndc --lon 116.5 --lat 39.9
+
+# Export pixel time series to CSV
+pygndc timeseries -i model.gndc --row 100 --col 200 -o series.csv
+
+# Launch interactive viewer
+pygndc viewer -i model.gndc
+
+# All commands support --mode (auto, tcnn_cuda, torch_gpu, torch_cpu)
+pygndc decompress -i model.gndc -o ./output --mode torch_cpu
+```
+
+## Interactive Viewer
+
+A GUI tool for visualizing `.gndc` files with multiple display modes, time navigation, and pixel inspection.
+
+```python
+from pygndc import start_viewer
+start_viewer()
+```
+
+Features:
+- RGB, NDVI, temporal gradient, and spatial gradient display modes
+- Time slider with date navigation
+- Click-to-inspect pixel time series
+- Region selection and zoom
+- Export current frame or entire time series
+
+## File Format
+
+A `.gndc` file is a zstandard-compressed archive containing:
+
+| Component | Description |
+|-----------|-------------|
+| Header | JSON metadata (dimensions, timestamps, CRS, band info) |
+| Model Weights | Compressed neural network parameters |
+| Mask Data | Optional validity mask (static or dynamic) |
+| Residuals | Optional correction data for higher accuracy |
+
+## API Reference
+
+See [API_Reference.md](API_Reference.md) for the full API documentation.
+
+## License
+
+MIT License
+
+## Citation
+
+```bibtex
+@software{pygndc,
+  author = {Jianbo Qi},
+  title = {pygndc: Geographic Neural Data Cube},
+  year = {2024},
+  url = {https://github.com/jianboqi/pygndc},
+  license = {MIT}
+}
+```
+
+## Contact
+
+- Author: Jianbo Qi
+- Email: jianboqi@126.com
+- Issues: [GitHub Issues](https://github.com/jianboqi/pygndc/issues)

pygndc-1.0.0/README.md

@@ -0,0 +1,197 @@
+
+# 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://github.com/user-attachments/assets/6c526878-93bc-4b70-bc99-cbb99193931a" />
+
+## What is GeoNDC?
+
+GeoNDC is a neural network-based compression format for multi-dimensional geospatial raster data. A single `.gndc` file stores 4D spatiotemporal data (Time x Height x Width x Bands) with up to **300:1 compression ratios**.
+
+Key capabilities:
+
+- **Arbitrary time reconstruction** - reconstruct data at any time point, not just original observation times
+- **Fast random access** - query any pixel at any timestamp instantly
+- **Analytic gradients** - compute spatial/temporal derivatives directly from the neural network
+- **Multi-sensor support** - Sentinel-2, Landsat, MODIS, HiGLASS, and more
+
+## Online Viewer & 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).
+
+## Installation
+
+```bash
+pip install pygndc
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/jianboqi/pygndc.git
+cd pygndc
+pip install .
+```
+
+### GPU support (recommended)
+
+`pip install pygndc` installs CPU-only PyTorch by default. For GPU acceleration, install CUDA-enabled PyTorch **first**:
+
+```bash
+# Example for CUDA 12.1 (check https://pytorch.org for your CUDA version)
+pip install torch --index-url https://download.pytorch.org/whl/cu121
+
+# Then install pygndc
+pip install pygndc
+```
+
+### tiny-cuda-nn (fastest)
+
+For best performance, install [tiny-cuda-nn](https://github.com/NVlabs/tiny-cuda-nn). This provides the optimized TCNN backend with significantly faster inference and lower memory usage.
+
+```bash
+pip install git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch
+```
+
+> **Note**: tiny-cuda-nn requires an NVIDIA GPU with CUDA support and a C++ compiler. If you cannot install it, pygndc will automatically fall back to pure PyTorch (`torch_gpu` or `torch_cpu`).
+
+### Optional dependencies
+
+```bash
+pip install pygndc[all]       # xarray + geopandas + scipy
+pip install pygndc[xarray]    # xarray support
+pip install pygndc[geo]       # geopandas + shapely
+```
+
+### Inference modes
+
+pygndc uses a single `mode` parameter to control both the backend and device:
+
+| Mode | Backend | Device | Description |
+|------|---------|--------|-------------|
+| `auto` | auto-detect | auto-detect | **Default.** Best available mode |
+| `tcnn_cuda` | tiny-cuda-nn | GPU | Fastest. Requires tinycudann + CUDA |
+| `torch_gpu` | PyTorch | GPU | No extra dependencies, requires CUDA |
+| `torch_cpu` | PyTorch | CPU | Works everywhere, slowest |
+
+## Quick Start
+
+```python
+import pygndc
+
+# Open a .gndc file (auto-detects best mode)
+with pygndc.open("samples/S2_sample_2022_to_2025.gndc") as ds:
+    print(ds)                                          # Shows mode, shape, CRS, etc.
+
+    # Read a frame
+    frame = ds.read(t=0)                               # (H, W, C) by index
+    frame = ds.read(t="2024-06-15")                    # by date string
+    frame = ds.read_at_time("2024-06-15 12:00:00")     # continuous interpolation
+
+    # Point query (coordinates within the sample's bounds)
+    series = ds.sample(lon=116.825, lat=40.486)        # (T, C) full time series
+    values = ds.sample(lon=116.825, lat=40.486, t=0)   # (C,) single time
+
+    # Pixel time series
+    series = ds.pixel_series(row=140, col=140)         # (T, C)
+
+    # Analysis
+    ndvi = ds.ndvi(t=0, red_band=2, nir_band=3)       # (H, W)
+    dx, dy = ds.gradient(t=0, mode="spatial")          # analytic gradients
+
+    # Export
+    arr = ds.to_numpy(t=0)                             # (H, W, C) numpy array
+    ds.to_tif("frame_0.tif", t=0)                     # single frame to GeoTIFF
+    ds.to_tifs("output_dir/")                          # all frames
+    xds = ds.to_xarray()                               # xarray Dataset
+
+# Specify mode explicitly
+with pygndc.open("samples/S2_sample_2022_to_2025.gndc", mode="torch_cpu") as ds:
+    frame = ds.read(t=0)
+```
+
+## CLI Commands
+
+```bash
+# Show model info
+pygndc info model.gndc
+pygndc info model.gndc --json
+
+# Decompress to GeoTIFF files
+pygndc decompress -i model.gndc -o ./output
+pygndc decompress -i model.gndc -o ./output --timestamp 2024-06-15
+pygndc decompress -i model.gndc -o ./output --start 2024-01-01 --end 2024-12-31 --interval 5
+
+# Compute NDVI
+pygndc ndvi -i model.gndc -o ndvi.tif --red-band 0 --nir-band 1
+
+# Compute spatial gradient
+pygndc derivative -i model.gndc -o gradient.tif --grad-mode mag
+
+# Point query
+pygndc sample -i model.gndc --lon 116.5 --lat 39.9
+
+# Export pixel time series to CSV
+pygndc timeseries -i model.gndc --row 100 --col 200 -o series.csv
+
+# Launch interactive viewer
+pygndc viewer -i model.gndc
+
+# All commands support --mode (auto, tcnn_cuda, torch_gpu, torch_cpu)
+pygndc decompress -i model.gndc -o ./output --mode torch_cpu
+```
+
+## Interactive Viewer
+
+A GUI tool for visualizing `.gndc` files with multiple display modes, time navigation, and pixel inspection.
+
+```python
+from pygndc import start_viewer
+start_viewer()
+```
+
+Features:
+- RGB, NDVI, temporal gradient, and spatial gradient display modes
+- Time slider with date navigation
+- Click-to-inspect pixel time series
+- Region selection and zoom
+- Export current frame or entire time series
+
+## File Format
+
+A `.gndc` file is a zstandard-compressed archive containing:
+
+| Component | Description |
+|-----------|-------------|
+| Header | JSON metadata (dimensions, timestamps, CRS, band info) |
+| Model Weights | Compressed neural network parameters |
+| Mask Data | Optional validity mask (static or dynamic) |
+| Residuals | Optional correction data for higher accuracy |
+
+## API Reference
+
+See [API_Reference.md](API_Reference.md) for the full API documentation.
+
+## License
+
+MIT License
+
+## Citation
+
+```bibtex
+@software{pygndc,
+  author = {Jianbo Qi},
+  title = {pygndc: Geographic Neural Data Cube},
+  year = {2024},
+  url = {https://github.com/jianboqi/pygndc},
+  license = {MIT}
+}
+```
+
+## Contact
+
+- Author: Jianbo Qi
+- Email: jianboqi@126.com
+- Issues: [GitHub Issues](https://github.com/jianboqi/pygndc/issues)

pygndc-1.0.0/pygndc/__init__.py

@@ -0,0 +1,92 @@
+"""
+pygndc - Geographic Neural Data Cube
+
+A Python library for compressing geospatial time-series data using neural networks
+
+Quick Start:
+    import pygndc
+
+    # High-level API (recommended)
+    with pygndc.open("satellite.gndc") as ds:
+        print(ds.crs, ds.bounds, ds.shape)
+        frame = ds.read(t=0)                       # (H, W, C)
+        frame = ds.read_at_time("2024-06-15")      # continuous interpolation
+        ts = ds.sample(lon=116.5, lat=39.9)        # (T, C) point query
+
+    # Low-level API (backward compatible)
+    reader = pygndc.GNDCReader()
+    reader.load("model.gndc")
+    frame = reader.reconstruct_single_frame(0)
+"""
+
+# Fix Intel OpenMP conflict
+import os
+os.environ["KMP_DUPLICATE_LIB_OK"] = "TRUE"
+
+from pygndc._version import __version__, __author__, __license__
+
+# Public API - Reader
+from pygndc.reader import GNDCReader
+
+# Public API - Dataset (high-level)
+from pygndc.dataset import GNDCDataset
+
+# Public API - Analysis
+from pygndc.analysis import (
+    compute_ndvi,
+    compute_evi,
+    compute_ndwi,
+    compute_ndmi,
+    compute_temporal_gradient,
+    compute_spatial_gradient
+)
+
+# Public API - Viewer
+from pygndc.viewer import GNDCInteractiveViewer, start_viewer
+
+def open(path: str, mode: str = "auto") -> GNDCDataset:
+    """
+    Open a .gndc file and return a GNDCDataset.
+
+    This is the recommended entry point for working with .gndc files.
+
+    Args:
+        path: Path to the .gndc file.
+        mode: Inference mode.
+            - 'auto': auto-detect best available (default)
+            - 'tcnn_cuda': tinycudann on GPU (fastest)
+            - 'torch_gpu': pure PyTorch on GPU
+            - 'torch_cpu': pure PyTorch on CPU
+
+    Returns:
+        GNDCDataset instance.
+
+    Examples:
+        >>> ds = pygndc.open("data.gndc")
+        >>> with pygndc.open("data.gndc", mode="torch_cpu") as ds:
+        ...     frame = ds.read(t=0)
+    """
+    return GNDCDataset(path, mode=mode)
+
+
+__all__ = [
+    # Version info
+    "__version__",
+    "__author__",
+    "__license__",
+    # High-level API
+    "open",
+    "GNDCDataset",
+    # Reader
+    "GNDCReader",
+    # Analysis
+    "compute_ndvi",
+    "compute_evi",
+    "compute_ndwi",
+    "compute_ndmi",
+    "compute_temporal_gradient",
+    "compute_spatial_gradient",
+    # Viewer
+    "GNDCInteractiveViewer",
+    "start_viewer",
+]