Installation

Use this page as the authoritative setup path for local development, conda environments with ESA SNAP, and container runs. SNAP-dependent workflows need both the Python package and a working SNAP Graph Processing Tool executable, usually named gpt.

Prerequisites

• Python >=3.11, <4.
• uv (recommended by repository tooling).
• Conda or mamba when using the conda + SNAP engine workflow.
• ESA SNAP + Java when running SNAP-dependent commands such as worldsar and explicit pipeline recipes.
• Docker Engine if using container workflows.

Local Python Setup

Use this path for development, tests, and non-SNAP processing.

# from the repository root
uv venv .venv
source .venv/bin/activate
uv sync
uv run sarpyx --help

Conda + SNAP Engine Setup

Use this path when SNAP processing must run outside Docker. The helper scripts assume the conda environment is active and default SNAP to $CONDA_PREFIX/opt/esa-snap.

conda create -n sarpyx-snap python=3.11 -y
conda activate sarpyx-snap
python -m pip install -e .

# Linux helper install. Set SNAP_HOME first so SNAP lands inside the conda env.
SNAP_HOME="$CONDA_PREFIX/opt/esa-snap" SNAP_SKIP_UPDATES=1 bash support/snap-install.sh

# Export SNAP_HOME, GPT_PATH, gpt_path, SNAP_USERDIR, snap_userdir, and PATH.
source scripts/setvars.sh
"$GPT_PATH" --help

support/snap-install.sh is Linux-oriented. On macOS or Windows, install ESA SNAP manually, then set SNAP_HOME or GPT_PATH before sourcing scripts/setvars.sh.

GPT Path Setting

GPT_PATH must point to the SNAP gpt executable, not another system command named gpt. Prefer an absolute path and keep SNAP_USERDIR writable and isolated per environment or run.

export GPT_PATH="/absolute/path/to/snap/bin/gpt"
export gpt_path="$GPT_PATH"
export SNAP_USERDIR="${SNAP_USERDIR:-$PWD/.snap}"
export snap_userdir="$SNAP_USERDIR"
export PATH="$(dirname "$GPT_PATH"):$PATH"
test -x "$GPT_PATH"

For the WorldSAR CLI, resolution order is: explicit --gpt-path, gpt_path/GPT_PATH, $CONDA_PREFIX/opt/esa-snap/bin/gpt, $SNAP_HOME/bin/gpt, then a SNAP-looking gpt found on PATH. Direct Python use of sarpyx.snapflow.engine.GPT should pass gpt_path=os.environ["GPT_PATH"] or another explicit path.

Helper Scripts

• scripts/setvars.sh is the user-facing helper; it sources the existing scripts/setvar.sh implementation. It requires an active conda environment, sets SNAP_HOME, GPT_PATH, lowercase compatibility variables, SNAP_USERDIR, and prepends SNAP to PATH.
• scripts/worldsar.sh activates CONDA_ENV (default sarpyx-snap), sources the same helper, prints the resolved SNAP GPT path, and runs sarpyx.cli.worldsar.
• support/snap-install.sh installs SNAP 12 or 13 on Linux. It honors SNAP_HOME, SNAP_SKIP_UPDATES, and SNAP_SKIP_SYSTEM_PACKAGES.
• make install-snap is the Makefile wrapper for a Linux SNAP install under ./snap, with default GPT memory set to 8G.

# Run WorldSAR through the conda/SNAP helper.
CONDA_ENV=sarpyx-snap scripts/worldsar.sh /data/product.SAFE outputs/run --grid-path grid/grid_10km.geojson

# Or run the installed CLI with explicit SNAP paths.
sarpyx-worldsar \
  --input /data/product.SAFE \
  --output outputs/run \
  --grid-path grid/grid_10km.geojson \
  --gpt-path "$GPT_PATH" \
  --snap-userdir "$SNAP_USERDIR"

Validation

Run these checks after any SNAP or path change.

conda activate sarpyx-snap
source scripts/setvars.sh
test -x "$GPT_PATH"
"$GPT_PATH" --help
python -c "from sarpyx.snapflow.config import resolve_gpt_path; print(resolve_gpt_path())"
python -c "import sarpyx; print(sarpyx.__version__)"

Docker

Docker builds pin Python, Java, and SNAP in the image. The runtime image sets SNAP_HOME=/workspace/snap13, adds SNAP to PATH, and links gpt into /usr/local/bin.

docker compose version
make check-grid
make recreate

Container startup requires an existing grid: set GRID_PATH to an in-container *.geojson or mount one under /workspace/grid. Startup no longer generates a grid automatically.

Build and Test

uv sync --group dev
uv run pytest -q
uv build
make docker-build

Troubleshooting

• scripts/setvars.sh reports CONDA_PREFIX is not set: run conda activate sarpyx-snap first.
• SNAP GPT not found or not executable: check SNAP_HOME, install SNAP at $CONDA_PREFIX/opt/esa-snap, or export an absolute GPT_PATH.
• WorldSAR finds the wrong gpt: pass --gpt-path "$GPT_PATH". The resolver rejects common non-SNAP paths such as /usr/sbin/gpt.
• SNAP cache or permission errors: set SNAP_USERDIR to a writable run-local directory and pass --snap-userdir "$SNAP_USERDIR".
• Large-product failures: lower --gpt-parallelism, raise --gpt-memory or --gpt-timeout, and keep SNAP_USERDIR on fast local storage.
• Grid errors: set GRID_PATH or provide a mounted *.geojson file under ./grid/ or /workspace/grid.
• Upload auth failures: set HF_TOKEN or run Hugging Face CLI login.

- matplotlib
- seaborn>=0.13.2
- scipy
- python-dateutil>=2.9.0
- six>=1.16.0
- geopandas>=1.1.1
- shapely
- numpy
- openpyxl
- h5py
- numba
- jupyter
- rasterio==1.4.3
- zarr>=3.0.0
- joblib>=1.5.1
- dask>=2025.5.1
- lxml>=5.4.0
- huggingface-hub>=0.34.1
- tifffile>=2025.6.11
- folium>=0.20.0