Skip to content

Usage

Command-Line Interface

The CLI provides restart-safe entry points for downloading NEON flightlines, running the full pipeline, generating QA outputs, and repairing missing intermediate products.

Legacy CLI aliases still forward to the same implementation, but the primary command names are spectralbridge-*.

Entry points

Available commands

spectralbridge-download

Download NEON HDF5 flightlines into a workspace.

spectralbridge-pipeline

Run the full NEON processing pipeline end to end.

spectralbridge-qa

Re-render QA PNG/JSON outputs for processed flightlines.

spectralbridge-recover-raw

Backfill raw ENVI exports when corrected outputs already exist.

spectralbridge-qa-summary

Build a multi-page PDF summary of recursive drone QA PNG outputs.

spectralbridge-merge-duckdb

Merge per-product parquet outputs into a flightline-level master table.

spectralbridge-download

Downloads NEON HDF5 flightlines into a workspace directory using the package download helpers.

NEON's download endpoint requires an API token. Export NEON_API_TOKEN (or NEON_TOKEN) in the shell before running either the download command or the full pipeline. Keep the token out of notebooks, configuration files, prompts, and version control.

export NEON_API_TOKEN="<your-token>"
spectralbridge-download SOAP \
  --year-month 2021-06 \
  --flight NEON_D17_SOAP_DP1_L057-1_20210615_directional_reflectance \
  --output data
  • Required: positional site, --year-month, and one or more --flight values
  • Optional: --product defaults to DP1.30006.001
  • Optional: --output defaults to data, with downloads written under <output>/<site>/

spectralbridge-pipeline

Runs the main NEON pipeline and writes all canonical outputs for each flightline.

spectralbridge-pipeline \
  --base-folder output_demo \
  --site-code NIWO \
  --year-month 2023-08 \
  --product-code DP1.30006.001 \
  --flight-lines NEON_D13_NIWO_DP1_L020-1_20230815_directional_reflectance \
  --engine thread \
  --max-workers 2

Required options

--base-folder, --site-code, --year-month, --product-code, and --flight-lines.

Parallel defaults

The pipeline defaults to --engine ray and --max-workers 8.

Resampling controls

--resample-method accepts convolution, legacy, or resample.

Merge controls

Use --merge-memory-limit, --merge-threads, --merge-row-group-size, and --merge-temp-directory to tune DuckDB merging.

Outputs include raw ENVI exports when available, corrected ENVI, sensor-resampled products, per-product parquet sidecars, _merged_pixel_extraction.parquet, and QA files. See Outputs & File Structure for the full contract.

spectralbridge-qa

Recomputes QA PNG and JSON outputs for existing flightline folders.

spectralbridge-qa --base-folder output_demo --quick
  • --base-folder is required
  • --quick uses the deterministic 25k-pixel path; --full disables that subsampling shortcut
  • --n-sample defaults to 100000
  • --rgb-bands accepts values such as 660,560,490 or symbolic R,G,B
  • --save-json / --no-save-json controls whether _qa.json is written alongside the PNG
  • --out-dir copies the generated QA files elsewhere after rendering

spectralbridge-recover-raw

Scans a base folder for HDF5 plus corrected ENVI outputs and backfills missing raw ENVI exports so restart-safe downstream stages can continue cleanly.

spectralbridge-recover-raw \
  --base-folder output_demo \
  --brightness-offset 0.0

spectralbridge-qa-summary

Builds a multi-page PDF summary by recursively finding drone QA PNG files.

spectralbridge-qa-summary drone_outputs --output-pdf drone_outputs/qa_summary.pdf
  • Required: positional base_dir
  • Optional: --output-pdf to override the default output path
  • Optional: --pattern defaults to *__qa.png

spectralbridge-merge-duckdb

Merges per-product parquet tables into a master parquet and can optionally render QA alongside the merge output.

spectralbridge-merge-duckdb --help

Use this command when you need direct control over parquet merging outside the main pipeline orchestration.