Quickstart¶

Run SpectralBridge end to end from the command line or from Python using the same restart-safe pipeline.

CLI path

Best for laptops, servers, containers, and batch jobs.

spectralbridge-pipeline

Notebook path

Best for exploratory and reproducible Python workflows.

from spectralbridge import go_forth_and_multiply

Install

Install SpectralBridge¶

Install from a cloned source checkout:

pip install -e .

Ray is part of the standard dependency set. The earthlab-spectralbridge[full] extra remains available as a compatibility alias for existing automation and currently resolves to the same dependency set.

Legacy imports and CLI aliases still work, but the Quickstart uses the canonical spectralbridge namespace and spectralbridge-* entry points.

CLI workflow

Run a NEON flight line from the terminal¶

Use the CLI when you want a file-based, restart-safe run that works the same way on your laptop, in a container, or on HPC.

BASE=output_quickstart
mkdir -p "$BASE"

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

What it writes

Per-flightline ENVI exports, corrected ENVI, sensor-resampled products, Parquet sidecars, a merged parquet, and QA outputs.

What happens on rerun

Completed stages are validated and skipped when their outputs are already present and usable.

Why `thread` here

The pipeline defaults to ray, but thread keeps the example deterministic and lightweight for first runs.

Typical first-run stages:

download the NEON HDF5 flightline
export the raw ENVI cube
build correction JSON
apply topographic and BRDF correction
resample into configured target sensors
write Parquet sidecars and the merged parquet
render QA PNG and JSON outputs

To inspect QA outputs after the run, look inside the flightline subdirectory under $BASE for files such as *_qa.png and *_qa.json. PDF output may also be present when enabled during rendering.

Python workflow

Run the same pipeline from Python¶

Use the Python API when you want to stay in a notebook or script while keeping the same on-disk outputs and restart behavior.

from spectralbridge import go_forth_and_multiply

base = "output_quickstart_py"

go_forth_and_multiply(
    base_folder=base,
    site_code="NIWO",
    year_month="2023-08",
    product_code="DP1.30006.001",
    flight_lines=[
        "NEON_D13_NIWO_DP1_L020-1_20230815_directional_reflectance",
    ],
    max_workers=2,
    engine="thread",
)

Preview the merged parquet after the run:

import duckdb
import os

flightline = "NEON_D13_NIWO_DP1_L020-1_20230815_directional_reflectance"
merged = os.path.join(base, flightline, f"{flightline}_merged_pixel_extraction.parquet")

duckdb.query(f"SELECT * FROM '{merged}' LIMIT 5").df()

Where to go next

Next steps¶

Why cross-sensor calibration? Understand the scientific motivation behind the workflow. Tutorials Walk through a fuller NEON processing example. Pipeline stages See what each stage consumes, writes, and validates. Working with Parquet outputs Use the authoritative analysis-ready outputs directly.

The source-install commands assume you have cloned earthlab/spectralbridge and changed into its directory. The distribution name is earthlab-spectralbridge, but no PyPI project was exposed at that name in the 19 October 2026 audit. See the beginner path for setup and a tiny offline example.