pygndc 1.0.0__py3-none-any.whl

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",
+]

pygndc/__main__.py

@@ -0,0 +1,202 @@
+"""
+CLI entry point for pygndc.
+"""
+
+import argparse
+import sys
+import os
+
+from pygndc import __version__
+from pygndc.reader import GNDCReader
+
+MODE_CHOICES = ["auto", "tcnn_cuda", "torch_gpu", "torch_cpu"]
+
+
+def _add_mode_arg(parser):
+    """Add --mode argument to a subparser."""
+    parser.add_argument(
+        "--mode", choices=MODE_CHOICES, default="auto",
+        help="Inference mode (default: auto)"
+    )
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="pygndc - Geographic Neural Data Compression",
+        prog="pygndc"
+    )
+    parser.add_argument("--version", action="version", version=f"pygndc {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Decompress command
+    decompress_parser = subparsers.add_parser("decompress", help="Decompress/reconstruct data")
+    decompress_parser.add_argument("-i", "--input", required=True, help="Input .gndc model file")
+    decompress_parser.add_argument("-o", "--output", required=True, help="Output path (file or directory)")
+    decompress_parser.add_argument("--timestamp", help="Specific timestamp (YYYY-MM-DD)")
+    decompress_parser.add_argument("--start", dest="start_date", help="Start date (YYYY-MM-DD)")
+    decompress_parser.add_argument("--end", dest="end_date", help="End date (YYYY-MM-DD)")
+    decompress_parser.add_argument("--interval", type=int, default=5, help="Interval in days")
+    decompress_parser.add_argument("--format", choices=["tif", "npy"], default="tif", help="Output format")
+    _add_mode_arg(decompress_parser)
+
+    # Info command
+    info_parser = subparsers.add_parser("info", help="Show model information")
+    info_parser.add_argument("model", help="Path to .gndc model file")
+    info_parser.add_argument("--json", action="store_true", help="Output as JSON")
+
+    # Viewer command
+    viewer_parser = subparsers.add_parser("viewer", help="Launch interactive viewer")
+    viewer_parser.add_argument("-i", "--input", required=True, help="Input .gndc model file")
+    _add_mode_arg(viewer_parser)
+
+    # NDVI command
+    ndvi_parser = subparsers.add_parser("ndvi", help="Compute NDVI and export as TIF")
+    ndvi_parser.add_argument("-i", "--input", required=True, help="Input .gndc model file")
+    ndvi_parser.add_argument("-o", "--output", required=True, help="Output NDVI TIF file")
+    ndvi_parser.add_argument("--timestamp", type=int, default=0, help="Time index (default: 0)")
+    ndvi_parser.add_argument("--red-band", type=int, default=0, help="0-based red band index")
+    ndvi_parser.add_argument("--nir-band", type=int, default=1, help="0-based NIR band index")
+    _add_mode_arg(ndvi_parser)
+
+    # Derivative command
+    deriv_parser = subparsers.add_parser("derivative", help="Compute spatial gradients")
+    deriv_parser.add_argument("-i", "--input", required=True, help="Input .gndc model file")
+    deriv_parser.add_argument("-o", "--output", required=True, help="Output gradient TIF file")
+    deriv_parser.add_argument("--grad-mode", choices=["dx", "dy", "mag", "dir"], default="mag",
+                              help="Derivative mode (default: mag)")
+    deriv_parser.add_argument("--timestamp", type=int, default=0, help="Time index (default: 0)")
+    _add_mode_arg(deriv_parser)
+
+    # Sample command
+    sample_parser = subparsers.add_parser("sample", help="Point query by coordinates")
+    sample_parser.add_argument("-i", "--input", required=True, help="Input .gndc model file")
+    sample_parser.add_argument("--lon", type=float, required=True, help="Longitude")
+    sample_parser.add_argument("--lat", type=float, required=True, help="Latitude")
+    sample_parser.add_argument("--timestamp", type=int, default=None,
+                               help="Time index (omit for full series)")
+    _add_mode_arg(sample_parser)
+
+    # Timeseries command
+    ts_parser = subparsers.add_parser("timeseries", help="Export pixel time series to CSV")
+    ts_parser.add_argument("-i", "--input", required=True, help="Input .gndc model file")
+    ts_parser.add_argument("--row", type=int, required=True, help="Pixel row")
+    ts_parser.add_argument("--col", type=int, required=True, help="Pixel column")
+    ts_parser.add_argument("-o", "--output", required=True, help="Output CSV file")
+    _add_mode_arg(ts_parser)
+
+    args = parser.parse_args()
+
+    if args.command == "decompress":
+        reader = GNDCReader(mode=args.mode)
+        reader.load(args.input)
+
+        if args.timestamp:
+            from datetime import datetime
+            from pygndc.utils.date_utils import normalize_time
+            import numpy as np
+            meta = reader.dataset_meta
+            g_start = datetime.strptime(str(meta['global_start_date']), "%Y-%m-%d %H:%M:%S")
+            g_end = datetime.strptime(str(meta['global_end_date']), "%Y-%m-%d %H:%M:%S")
+            t_norms = meta.get('t_norms', [])
+            target_dt = datetime.strptime(args.timestamp, "%Y-%m-%d")
+            target_tnorm = normalize_time(target_dt, g_start, g_end)
+            t_idx = min(range(len(t_norms)), key=lambda i: abs(t_norms[i] - target_tnorm))
+            frame = reader.reconstruct_single_frame(t_idx)
+            np.save(args.output, frame)
+            print(f"Saved frame {t_idx} ({args.timestamp}) to {args.output}")
+        else:
+            recons_dates = None
+            if args.start_date and args.end_date:
+                recons_dates = (args.start_date, args.end_date, args.interval)
+            reader.reconstruct_and_save_all(args.output, recons_dates=recons_dates)
+
+    elif args.command == "info":
+        import json
+        import pygndc
+        ds = pygndc.open(args.model)
+
+        if args.json:
+            print(json.dumps(ds.meta, indent=2, default=str))
+        else:
+            print(ds.info())
+        ds.close()
+
+    elif args.command == "viewer":
+        from pygndc.viewer.interactive import GNDCInteractiveViewer
+        app = GNDCInteractiveViewer()
+        app.root.mainloop()
+
+    elif args.command == "ndvi":
+        import pygndc
+        import numpy as np
+        ds = pygndc.open(args.input, mode=args.mode)
+        ndvi = ds.ndvi(t=args.timestamp, red_band=args.red_band, nir_band=args.nir_band)
+
+        from pygndc.interop.interop import save_frame_as_tif
+        save_frame_as_tif(
+            ndvi[:, :, np.newaxis], args.output, ds.crs, ds.transform, "float32"
+        )
+        print(f"NDVI saved to {args.output}")
+        ds.close()
+
+    elif args.command == "derivative":
+        import pygndc
+        ds = pygndc.open(args.input, mode=args.mode)
+        result = ds.gradient(t=args.timestamp, mode=args.grad_mode)
+        if isinstance(result, tuple):
+            import numpy as np
+            result = np.sqrt(result[0] ** 2 + result[1] ** 2)
+
+        from pygndc.interop.interop import save_frame_as_tif
+        if result.ndim == 2:
+            import numpy as np
+            result = result[:, :, np.newaxis]
+        save_frame_as_tif(result, args.output, ds.crs, ds.transform, "float32")
+        print(f"Gradient ({args.grad_mode}) saved to {args.output}")
+        ds.close()
+
+    elif args.command == "sample":
+        import pygndc
+        import numpy as np
+        ds = pygndc.open(args.input, mode=args.mode)
+
+        if args.timestamp is not None:
+            vals = ds.sample(lon=args.lon, lat=args.lat, t=args.timestamp)
+            print(f"Values at ({args.lon}, {args.lat}), t={args.timestamp}: {vals}")
+        else:
+            series = ds.sample(lon=args.lon, lat=args.lat)
+            print(f"Time series at ({args.lon}, {args.lat}): shape={series.shape}")
+            for t_idx in range(series.shape[0]):
+                ts_str = ds.timestamps[t_idx] if t_idx < len(ds.timestamps) else str(t_idx)
+                vals_str = ", ".join(f"{v:.4f}" for v in series[t_idx])
+                print(f"  [{t_idx}] {ts_str}: {vals_str}")
+        ds.close()
+
+    elif args.command == "timeseries":
+        import pygndc
+        import numpy as np
+        ds = pygndc.open(args.input, mode=args.mode)
+        series = ds.pixel_series(row=args.row, col=args.col)
+
+        # Write CSV
+        os.makedirs(os.path.dirname(os.path.abspath(args.output)), exist_ok=True)
+        n_bands = series.shape[1]
+        band_headers = [f"band_{i}" for i in range(n_bands)]
+
+        with open(args.output, "w") as f:
+            f.write("t_idx,timestamp," + ",".join(band_headers) + "\n")
+            for t_idx in range(series.shape[0]):
+                ts_str = str(ds.timestamps[t_idx]) if t_idx < len(ds.timestamps) else str(t_idx)
+                vals_str = ",".join(f"{v:.6f}" for v in series[t_idx])
+                f.write(f"{t_idx},{ts_str},{vals_str}\n")
+
+        print(f"Time series ({args.row}, {args.col}) saved to {args.output}")
+        ds.close()
+
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

pygndc/_version.py

@@ -0,0 +1,11 @@
+"""
+pygndc version information.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Jianbo Qi"
+__email__ = "jianboqi@126.com"
+__license__ = "MIT"
+__url__ = "https://github.com/jianboqi/pygndc"
+
+VERSION = __version__

pygndc/analysis/__init__.py

@@ -0,0 +1,24 @@
+"""
+Analysis module for GNDC.
+
+This module provides functions for analyzing compressed geospatial data,
+including vegetation indices and derivatives.
+"""
+
+from pygndc.analysis.vegetation import (
+    compute_ndvi,
+    compute_evi,
+    compute_ndwi,
+    compute_ndmi,
+    compute_temporal_gradient,
+    compute_spatial_gradient
+)
+
+__all__ = [
+    'compute_ndvi',
+    'compute_evi',
+    'compute_ndwi',
+    'compute_ndmi',
+    'compute_temporal_gradient',
+    'compute_spatial_gradient'
+]

pygndc/analysis/vegetation.py

@@ -0,0 +1,160 @@
+"""
+Analysis module for GNDC.
+
+This module provides functions for analyzing compressed data,
+including derivatives and vegetation indices.
+"""
+
+import numpy as np
+
+
+def compute_ndvi(red, nir):
+    """
+    Compute Normalized Difference Vegetation Index.
+    
+    Args:
+        red: Red band data
+        nir: Near-infrared band data
+    
+    Returns:
+        NDVI values in range [-1, 1]
+    """
+    with np.errstate(divide='ignore', invalid='ignore'):
+        ndvi = (nir - red) / (nir + red + 1e-8)
+        ndvi = np.where(np.isfinite(ndvi), ndvi, np.nan)
+    return ndvi
+
+
+def compute_evi(blue, green, nir, g=2.5, c1=6, c2=7.5, l=1):
+    """
+    Compute Enhanced Vegetation Index.
+    
+    Args:
+        blue: Blue band data
+        green: Green band data  
+        nir: Near-infrared band data
+        g: Gain factor
+        c1, c2: Coefficient parameters
+        l: Canopy background adjustment
+    
+    Returns:
+        EVI values
+    """
+    with np.errstate(divide='ignore', invalid='ignore'):
+        evi = g * (nir - red) / (nir + c1 * red - c2 * blue + l + 1e-8)
+        evi = np.where(np.isfinite(evi), evi, np.nan)
+    return evi
+
+
+def compute_ndwi(green, nir):
+    """
+    Compute Normalized Difference Water Index.
+    
+    Args:
+        green: Green band data
+        nir: Near-infrared band data
+    
+    Returns:
+        NDWI values in range [-1, 1]
+    """
+    with np.errstate(divide='ignore', invalid='ignore'):
+        ndwi = (green - nir) / (green + nir + 1e-8)
+        ndwi = np.where(np.isfinite(ndwi), ndwi, np.nan)
+    return ndwi
+
+
+def compute_ndmi(nir, swir):
+    """
+    Compute Normalized Difference Moisture Index.
+    
+    Args:
+        nir: Near-infrared band data
+        swir: Short-wave infrared band data
+    
+    Returns:
+        NDMI values in range [-1, 1]
+    """
+    with np.errstate(divide='ignore', invalid='ignore'):
+        ndmi = (nir - swir) / (nir + swir + 1e-8)
+        ndmi = np.where(np.isfinite(ndmi), ndmi, np.nan)
+    return ndmi
+
+
+def compute_temporal_gradient(time_series_data):
+    """
+    Compute temporal gradient (first derivative) of time series.
+    
+    Args:
+        time_series_data: 3D array [T, H, W] or 2D array [T, pixels]
+    
+    Returns:
+        Temporal gradient array of same shape
+    """
+    if time_series_data.ndim == 3:
+        T, H, W = time_series_data.shape
+        gradient = np.zeros_like(time_series_data)
+        gradient[1:-1] = (time_series_data[2:] - time_series_data[:-2]) / 2
+        gradient[0] = time_series_data[1] - time_series_data[0]
+        gradient[-1] = time_series_data[-1] - time_series_data[-2]
+    else:
+        T = time_series_data.shape[0]
+        gradient = np.zeros_like(time_series_data)
+        gradient[1:-1] = (time_series_data[2:] - time_series_data[:-2]) / 2
+        gradient[0] = time_series_data[1] - time_series_data[0]
+        gradient[-1] = time_series_data[-1] - time_series_data[-2]
+    
+    return gradient
+
+
+def compute_spatial_gradient(image_data):
+    """
+    Compute spatial gradient using Sobel operator.
+    
+    Args:
+        image_data: 2D array [H, W] or 3D array [H, W, C]
+    
+    Returns:
+        Tuple of (grad_x, grad_y) gradient arrays
+    """
+    if image_data.ndim == 3:
+        grad_x = np.zeros_like(image_data)
+        grad_y = np.zeros_like(image_data)
+        for c in range(image_data.shape[2]):
+            gx, gy = _sobel_2d(image_data[:, :, c])
+            grad_x[:, :, c] = gx
+            grad_y[:, :, c] = gy
+    else:
+        grad_x, grad_y = _sobel_2d(image_data)
+    
+    return grad_x, grad_y
+
+
+def _sobel_2d(img):
+    """
+    Apply Sobel operator to 2D image.
+    """
+    sx = np.array([[-1, 0, 1], [-2, 0, 2], [-1, 0, 1]])
+    sy = sx.T
+    
+    pad_img = np.pad(img, 1, mode='edge')
+    
+    gx = np.zeros_like(img)
+    gy = np.zeros_like(img)
+    
+    for i in range(img.shape[0]):
+        for j in range(img.shape[1]):
+            window = pad_img[i:i+3, j:j+3]
+            gx[i, j] = np.sum(window * sx)
+            gy[i, j] = np.sum(window * sy)
+    
+    return gx, gy
+
+
+__all__ = [
+    'compute_ndvi',
+    'compute_evi', 
+    'compute_ndwi',
+    'compute_ndmi',
+    'compute_temporal_gradient',
+    'compute_spatial_gradient'
+]

pygndc/dataset/__init__.py

@@ -0,0 +1,9 @@
+"""
+Dataset module for pygndc.
+
+Provides the high-level GNDCDataset API for GDAL/rasterio-style access.
+"""
+
+from pygndc.dataset.dataset import GNDCDataset
+
+__all__ = ["GNDCDataset"]