nisar-pytools 0.1.0__tar.gz

nisar_pytools-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: conda-incubator/setup-miniconda@v3
+        with:
+          environment-file: environment.yml
+          activate-environment: nisar_pytools
+          miniforge-version: latest
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Run tests
+        run: pytest tests/ -v -m "not integration"
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: twine check dist/*

nisar_pytools-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

nisar_pytools-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Local data
+local/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Environments
+.env
+.venv/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Ruff
+.ruff_cache/

nisar_pytools-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+repos:
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.8.1
+    hooks:
+      - id: nbstripout
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.4
+    hooks:
+      - id: ruff
+        args: [--fix]

nisar_pytools-0.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## v0.1.0
+
+### IO
+- `open_nisar()` — read NISAR HDF5 files into lazy xarray DataTree with CRS
+- `stack_gslcs()` — stack multiple same-track GSLCs into a `(time, y, x)` DataArray
+- `find_nisar()` — search ASF for NISAR product URLs by AOI, dates, track, direction
+- `download_urls()` — parallel download with retry and post-download HDF5 validation
+- `to_zarr()` / `to_netcdf()` / `read_netcdf()` — export and import with complex data support
+- Generic h5py-to-DataTree walker with dask-backed lazy arrays
+- Automatic coordinate assignment and CRS from `projection` dataset
+- HDF5 dimension scale resolution via `DIMENSION_LIST` attributes
+
+### Processing
+- `interferogram()` — complex interferogram with grid matching validation
+- `coherence()` — sliding-window coherence estimation
+- `multilook()` / `multilook_interferogram()` — spatial averaging and downsampling
+- `unwrap()` — phase unwrapping via SNAPHU
+- `calculate_phase()` — extract phase from complex data
+- `phase_link()` — EMI phase linking with SHP selection on SLC stacks
+- `h_a_alpha()` — Cloude-Pottier polarimetric decomposition (entropy, anisotropy, alpha)
+- Individual `entropy()`, `anisotropy()`, `alpha()`, `mean_alpha()` functions
+
+### Utilities
+- `fetch_dem()` — auto-download Copernicus GLO-30 DEM matching a NISAR file's extent
+- `local_incidence_angle()` — compute LIA from LOS vectors and a DEM
+- `get_acquisition_time()`, `get_orbit_info()`, `get_bounding_polygon()` — metadata extraction
+- `apply_mask()` / `get_mask()` — apply NISAR mask datasets
+- `to_db()` / `from_db()` — dB conversion
+- Date, AOI, URL, and path validation utilities
+
+### Visualization
+- `plot_amplitude()`, `plot_phase()`, `plot_interferogram()`, `plot_coherence()`
+
+### Infrastructure
+- PyPI-ready packaging with `pyproject.toml`
+- CI/CD via GitHub Actions (lint, test, build, publish)
+- Pre-commit hooks (nbstripout, ruff)
+- Conda environment file
+- 243 tests with synthetic HDF5 fixtures

nisar_pytools-0.1.0/CLAUDE.md

@@ -0,0 +1,52 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+Python tools for reading NISAR (NASA-ISRO SAR) HDF5 data products into lazy xarray DataTree objects. Currently supports GSLC and GUNW product types.
+
+## Commands
+
+```bash
+# Use the nisar_pytools conda env for all commands
+# Install: mamba env create -f environment.yml
+# Activate or prefix with: /Users/zmhoppinen/miniforge3/envs/nisar_pytools/bin/python
+
+# Run all unit tests
+/Users/zmhoppinen/miniforge3/envs/nisar_pytools/bin/python -m pytest tests/ -v -m "not integration"
+
+# Run a single test file or test
+/Users/zmhoppinen/miniforge3/envs/nisar_pytools/bin/python -m pytest tests/test_reader.py -v
+/Users/zmhoppinen/miniforge3/envs/nisar_pytools/bin/python -m pytest tests/test_reader.py::TestOpenNisar::test_lazy_by_default -v
+
+# Run integration tests (requires real NISAR files in local/)
+NISAR_TEST_GSLC=local/gslcs/<file>.h5 NISAR_TEST_GUNW=local/gunws/<file>.h5 \
+  /Users/zmhoppinen/miniforge3/envs/nisar_pytools/bin/python -m pytest tests/ -v
+
+# Lint
+/Users/zmhoppinen/miniforge3/envs/nisar_pytools/bin/ruff check src/ tests/
+
+# Install dependencies with mamba, not pip or conda
+mamba install -n nisar_pytools -c conda-forge <package>
+```
+
+## Architecture
+
+**Entry point**: `from nisar_pytools import open_nisar` — takes an HDF5 file path, validates it, detects product type, returns `xr.DataTree` with dask-backed lazy arrays.
+
+**Flow**: `open_nisar()` → `validate_nisar_hdf5()` → `detect_product_type()` → `h5_to_datatree()`
+
+**Key design decisions**:
+- Uses custom h5py walker (not `xr.open_datatree` with h5netcdf) because NISAR files have named types at root and 100+ scalar datasets that belong in attrs, not as DataArrays.
+- All 2D+ arrays are dask-backed via `dask.array.from_array()`. Coordinates (1D `xCoordinates`/`yCoordinates`) are loaded eagerly since they're small.
+- Scalar datasets become `Dataset.attrs`. 1D non-coordinate arrays (e.g., `listOfPolarizations`) also go to attrs.
+- Unnamed dimensions are prefixed with the variable name (e.g., `eulerAngles_dim_1`) to avoid conflicts when sibling datasets have different shapes.
+- The `h5py.File` handle is kept alive on `tree.__dict__["_h5file"]` to prevent GC while dask arrays reference it.
+
+**`src/nisar_pytools/` layout**:
+- `io/_reader.py` — `open_nisar()` entry point
+- `io/_h5_to_datatree.py` — generic HDF5 group walker that builds DataTree
+- `utils/_validation.py` — file validation and product type detection
+
+**Tests** use synthetic HDF5 fixtures (tiny 8x10 arrays) defined in `tests/conftest.py`. Integration tests against real files are gated behind `@pytest.mark.integration` and env vars.

nisar_pytools-0.1.0/LICENSE.txt

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Zachary Hoppinen
+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.

nisar_pytools-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE.txt
+include README.md
+include CHANGELOG.md
+recursive-include src/nisar_pytools *.py

nisar_pytools-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: nisar-pytools
+Version: 0.1.0
+Summary: Open source Python tools for working with NISAR datasets
+Author-email: Zachary Hoppinen <zachary.hoppinen@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zmhoppinen/nisar_pytools
+Project-URL: Repository, https://github.com/zmhoppinen/nisar_pytools
+Project-URL: Issues, https://github.com/zmhoppinen/nisar_pytools/issues
+Keywords: nisar,sar,insar,radar,remote-sensing,hdf5,xarray
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+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 :: Image Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: asf_search>=7.0
+Requires-Dist: dask[array]>=2024.0
+Requires-Dist: h5py>=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyproj>=3.4
+Requires-Dist: rasterio>=1.3
+Requires-Dist: requests
+Requires-Dist: rioxarray>=0.15
+Requires-Dist: scipy>=1.10
+Requires-Dist: shapely>=2.0
+Requires-Dist: snaphu>=0.3
+Requires-Dist: xarray>=2024.10
+Provides-Extra: dem
+Requires-Dist: dem_stitcher; extra == "dem"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: nbstripout; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: notebooks
+Requires-Dist: jupyter; extra == "notebooks"
+Requires-Dist: matplotlib; extra == "notebooks"
+Provides-Extra: viz
+Requires-Dist: matplotlib; extra == "viz"
+Provides-Extra: all
+Requires-Dist: nisar-pytools[dem,notebooks,viz]; extra == "all"
+Dynamic: license-file
+
+# nisar_pytools
+
+Open source Python tools for working with NISAR datasets.
+
+## About
+
+`nisar_pytools` provides utilities for searching, downloading, reading, and processing data products from NASA's [NISAR](https://nisar.jpl.nasa.gov/) (NASA-ISRO Synthetic Aperture Radar) mission.
+
+### Supported Products
+
+- **GSLC** - Geocoded Single Look Complex
+- **GUNW** - Geocoded Unwrapped Interferogram
+
+Additional NISAR product types will be added over time.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.10+
+- [Miniforge](https://github.com/conda-forge/miniforge) (recommended)
+- NASA Earthdata login (for downloading from ASF)
+
+### Installation
+
+1. Clone the repository
+   ```sh
+   git clone https://github.com/zmhoppinen/nisar_pytools.git
+   cd nisar_pytools
+   ```
+2. Create the conda environment
+   ```sh
+   mamba env create -f environment.yml
+   conda activate nisar_pytools
+   ```
+
+## Usage
+
+### Search and Download
+
+```python
+from nisar_pytools import find_nisar, download_urls
+
+# Search ASF for GSLC products over an area of interest
+urls = find_nisar(
+    aoi=[-115, 43, -114, 44],
+    start_date="2025-06-01",
+    end_date="2025-12-01",
+    product_type="GSLC",
+    path_number=77,
+    direction="ASCENDING",
+)
+
+# Download in parallel with automatic validation
+fps = download_urls(urls, "local/gslcs/")
+```
+
+### Read a Single File
+
+```python
+from nisar_pytools import open_nisar
+
+dt = open_nisar("NISAR_L2_PR_GSLC_...h5")
+
+# Access a frequency/polarization group
+freq_a = dt["science/LSAR/GSLC/grids/frequencyA"].dataset
+hh = freq_a["HH"]  # lazy dask-backed DataArray with CRS set
+
+# Coordinates and CRS are assigned automatically
+print(hh.rio.crs)  # e.g. EPSG:32611
+```
+
+### Stack GSLCs into a Time Series
+
+```python
+from nisar_pytools import stack_gslcs
+
+# Stack multiple same-track GSLCs into a (time, y, x) DataArray
+stack = stack_gslcs(
+    ["gslc_date1.h5", "gslc_date2.h5", "gslc_date3.h5"],
+    frequency="frequencyA",
+    polarization="HH",
+)
+# Sorted by time, grid-validated, dask-backed, CRS assigned
+```
+
+### SAR Processing
+
+```python
+from nisar_pytools.processing import (
+    interferogram, coherence, multilook, unwrap, calculate_phase
+)
+
+# Interferogram (validates matching grids)
+ifg = interferogram(slc1, slc2)
+
+# Multilooked interferogram
+ml_ifg = multilook(ifg, looks_y=4, looks_x=4)
+
+# Coherence estimation
+coh = coherence(slc1, slc2, window_size=11)
+
+# Phase unwrapping with SNAPHU
+unw, conncomp = unwrap(ifg, coh, nlooks=20.0)
+```
+
+### Phase Linking
+
+```python
+from nisar_pytools.processing import phase_link
+
+# EMI phase linking on a GSLC stack
+linked, temporal_coh = phase_link(stack, window_size=11, confidence=0.95)
+```
+
+### Polarimetric Decomposition
+
+```python
+from nisar_pytools.processing import h_a_alpha
+
+# H-A-alpha decomposition from quad-pol SLC channels
+ds = h_a_alpha(hh, hv, vv)
+# Returns Dataset with: entropy, anisotropy, alpha, mean_alpha
+```
+
+### Local Incidence Angle
+
+```python
+from nisar_pytools.utils.local_incidence_angle import local_incidence_angle
+
+lia = local_incidence_angle(dem, los_x, los_y, los_z, heights, x_rg, y_rg, epsg=32611)
+```
+
+## Roadmap
+
+- [x] Lazy HDF5 reader returning xarray DataTree with CRS
+- [x] GSLC and GUNW support
+- [x] ASF search and parallel download with validation
+- [x] GSLC time-series stacking
+- [x] Interferogram, coherence, multilooking, phase extraction
+- [x] Phase unwrapping (SNAPHU)
+- [x] Phase linking (EMI with SHP selection)
+- [x] Polarimetric decomposition (H-A-alpha)
+- [x] Local incidence angle computation
+- [x] Visualization helpers (amplitude, phase, interferogram, coherence)
+- [ ] Support for additional NISAR product types
+
+## Contributing
+
+Contributions are welcome! Please fork the repo and open a pull request, or open an issue to suggest improvements.
+
+## License
+
+Distributed under the MIT License. See `LICENSE.txt` for more information.

nisar_pytools-0.1.0/README.md

@@ -0,0 +1,154 @@
+# nisar_pytools
+
+Open source Python tools for working with NISAR datasets.
+
+## About
+
+`nisar_pytools` provides utilities for searching, downloading, reading, and processing data products from NASA's [NISAR](https://nisar.jpl.nasa.gov/) (NASA-ISRO Synthetic Aperture Radar) mission.
+
+### Supported Products
+
+- **GSLC** - Geocoded Single Look Complex
+- **GUNW** - Geocoded Unwrapped Interferogram
+
+Additional NISAR product types will be added over time.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.10+
+- [Miniforge](https://github.com/conda-forge/miniforge) (recommended)
+- NASA Earthdata login (for downloading from ASF)
+
+### Installation
+
+1. Clone the repository
+   ```sh
+   git clone https://github.com/zmhoppinen/nisar_pytools.git
+   cd nisar_pytools
+   ```
+2. Create the conda environment
+   ```sh
+   mamba env create -f environment.yml
+   conda activate nisar_pytools
+   ```
+
+## Usage
+
+### Search and Download
+
+```python
+from nisar_pytools import find_nisar, download_urls
+
+# Search ASF for GSLC products over an area of interest
+urls = find_nisar(
+    aoi=[-115, 43, -114, 44],
+    start_date="2025-06-01",
+    end_date="2025-12-01",
+    product_type="GSLC",
+    path_number=77,
+    direction="ASCENDING",
+)
+
+# Download in parallel with automatic validation
+fps = download_urls(urls, "local/gslcs/")
+```
+
+### Read a Single File
+
+```python
+from nisar_pytools import open_nisar
+
+dt = open_nisar("NISAR_L2_PR_GSLC_...h5")
+
+# Access a frequency/polarization group
+freq_a = dt["science/LSAR/GSLC/grids/frequencyA"].dataset
+hh = freq_a["HH"]  # lazy dask-backed DataArray with CRS set
+
+# Coordinates and CRS are assigned automatically
+print(hh.rio.crs)  # e.g. EPSG:32611
+```
+
+### Stack GSLCs into a Time Series
+
+```python
+from nisar_pytools import stack_gslcs
+
+# Stack multiple same-track GSLCs into a (time, y, x) DataArray
+stack = stack_gslcs(
+    ["gslc_date1.h5", "gslc_date2.h5", "gslc_date3.h5"],
+    frequency="frequencyA",
+    polarization="HH",
+)
+# Sorted by time, grid-validated, dask-backed, CRS assigned
+```
+
+### SAR Processing
+
+```python
+from nisar_pytools.processing import (
+    interferogram, coherence, multilook, unwrap, calculate_phase
+)
+
+# Interferogram (validates matching grids)
+ifg = interferogram(slc1, slc2)
+
+# Multilooked interferogram
+ml_ifg = multilook(ifg, looks_y=4, looks_x=4)
+
+# Coherence estimation
+coh = coherence(slc1, slc2, window_size=11)
+
+# Phase unwrapping with SNAPHU
+unw, conncomp = unwrap(ifg, coh, nlooks=20.0)
+```
+
+### Phase Linking
+
+```python
+from nisar_pytools.processing import phase_link
+
+# EMI phase linking on a GSLC stack
+linked, temporal_coh = phase_link(stack, window_size=11, confidence=0.95)
+```
+
+### Polarimetric Decomposition
+
+```python
+from nisar_pytools.processing import h_a_alpha
+
+# H-A-alpha decomposition from quad-pol SLC channels
+ds = h_a_alpha(hh, hv, vv)
+# Returns Dataset with: entropy, anisotropy, alpha, mean_alpha
+```
+
+### Local Incidence Angle
+
+```python
+from nisar_pytools.utils.local_incidence_angle import local_incidence_angle
+
+lia = local_incidence_angle(dem, los_x, los_y, los_z, heights, x_rg, y_rg, epsg=32611)
+```
+
+## Roadmap
+
+- [x] Lazy HDF5 reader returning xarray DataTree with CRS
+- [x] GSLC and GUNW support
+- [x] ASF search and parallel download with validation
+- [x] GSLC time-series stacking
+- [x] Interferogram, coherence, multilooking, phase extraction
+- [x] Phase unwrapping (SNAPHU)
+- [x] Phase linking (EMI with SHP selection)
+- [x] Polarimetric decomposition (H-A-alpha)
+- [x] Local incidence angle computation
+- [x] Visualization helpers (amplitude, phase, interferogram, coherence)
+- [ ] Support for additional NISAR product types
+
+## Contributing
+
+Contributions are welcome! Please fork the repo and open a pull request, or open an issue to suggest improvements.
+
+## License
+
+Distributed under the MIT License. See `LICENSE.txt` for more information.

nisar_pytools-0.1.0/environment.yml

@@ -0,0 +1,31 @@
+name: nisar_pytools
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - python>=3.10
+  - asf_search>=7.0
+  - dask>=2024.0
+  - h5py>=3.10
+  - numpy>=1.24
+  - rasterio>=1.3
+  - pyproj>=3.4
+  - requests
+  - rioxarray>=0.15
+  - shapely>=2.0
+  - scipy>=1.10
+  - snaphu>=0.3
+  - xarray>=2024.10
+  - zarr
+  - h5netcdf
+  - build
+  - nbstripout
+  - pre-commit
+  - pytest
+  - ruff
+  - twine
+  - jupyter
+  - matplotlib
+  - pip
+  - pip:
+      - -e .