# ISCE2 SBAS Product Specification

Updated: 2026-04-06

## 1. Goal

Define the stable product contract for the current phase-1 SBAS route:

- `ISCE2 stripmapStack -> MintPy SBAS -> geocode/export -> psinsar publish bundle`

This document answers three practical questions:

- what the final SBAS deliverables are
- which files are runtime-only vs publish-grade
- which file the future system should treat as the publish entrypoint

## 2. Product Layers

The current experiment has three artifact layers.

### 2.1 Processing-layer runtime artifacts

Generated under a MintPy work directory such as:

- `stack_work/mintpy_sbas_v5/`

These are processing outputs, not yet the final publish contract.

Key files:

- `timeseries.h5`
  - radar-coordinate time-series cube
  - core scientific output
- `velocity.h5`
  - radar-coordinate velocity solution
  - useful for quick inspection and later geocode
- `temporalCoherence.h5`
  - quality indicator after inversion
- `maskTempCoh.h5`
  - thresholded reliability mask
- `maskAllValid.h5`
  - strict runtime mask used before inversion
- `numTriNonzeroIntAmbiguity.h5`
  - unwrap/network diagnostic
- `numTriNonzeroIntAmbiguity.png`
  - browseable diagnostic preview

Current runtime boundary:

- the minimum validated SBAS runtime boundary is `timeseries.h5` plus `velocity.h5`

### 2.2 Publish-layer standardized artifacts

Generated under a publish directory such as:

- `publish/mintpy_sbas_v5/`

This is the current publish-grade boundary for system embedding.

Directory contract:

- `manifest.json`
- `assets/`
- `preview/`
- `metadata/`

### 2.3 Catalog-layer registration artifacts

The future backend should publish the standardized bundle into the `psinsar` catalog.

Current rule:

- the backend should not register raw MintPy runtime paths directly
- the backend should register the publish bundle rooted by `manifest.json`
- the backend should populate `manifest.json.group_key` from task/run metadata during publish registration

## 3. Canonical Publish Bundle

### 3.1 Entrypoint

The publish entrypoint is:

- `manifest.json`

Reason:

- it binds product identity, stack dates, reference info, artifact paths, and quality summary in one place
- it allows the backend to register one bundle without hard-coding per-file conventions
- it decouples future UI/backend integration from the temporary MintPy work directory layout

### 3.2 Primary data products

#### `assets/geo_timeseries.h5`

Role:

- primary time-series product

Why it matters:

- this is the file that proves the system has true time-series capability
- every valid pixel contains multi-date displacement values rather than one summary statistic

Recommended system use:

- archive as the canonical analysis cube
- expose as the main download for advanced analysis
- use as the source for future point-query / profile / date-slice APIs

#### `assets/geo_velocity.h5`

Role:

- geocoded structured velocity product

Recommended system use:

- archive together with the time-series cube
- keep for programmatic reading when HDF5-native access is preferred

#### `assets/velocity.tif`

Role:

- publish-grade browse/export raster

Why it matters:

- easiest file for GIS browsing, thumbnail generation, map services, and first-screen display

Recommended system use:

- default map layer for result browsing
- not the only final product
- should be treated as a summary view derived from the time-series solution

### 3.3 Quality products

#### `assets/geo_temporalCoherence.h5`

Role:

- structured quality field

#### `assets/temporalCoherence.tif`

Role:

- GIS-friendly quality raster

Recommended use:

- review where the inversion is reliable

#### `assets/geo_maskTempCoh.h5`

Role:

- structured reliable-pixel mask

#### `assets/maskTempCoh.tif`

Role:

- GIS-friendly publish mask

Recommended use:

- mask browsing products
- support frontend display filtering

### 3.4 Preview and diagnostics

#### `preview/velocity_preview.png`

Role:

- lightweight preview image for cards, list pages, or quick QA

#### `preview/numTriNonzeroIntAmbiguity.png`

Role:

- diagnostic browse image

#### `metadata/source_quality_summary.json`

Role:

- compact machine-readable quality summary

#### `metadata/smallbaselineApp.cfg`

Role:

- reproducibility record of the MintPy configuration

## 4. File Priorities By Use Case

If the goal is system publish or catalog registration:

- focus on `manifest.json`

If the goal is proving time-series capability:

- focus on `assets/geo_timeseries.h5`

If the goal is first-screen map display:

- focus on `assets/velocity.tif`

If the goal is quality control:

- focus on `assets/temporalCoherence.tif`
- focus on `assets/maskTempCoh.tif`

If the goal is full reproducibility:

- keep `manifest.json`
- keep `metadata/smallbaselineApp.cfg`
- keep runtime `maskAllValid.h5` as a workflow artifact even if it is not published as a primary product

## 5. Current Product Typing

Current artifact typing implemented by the experiment bundle builder:

- `timeseries_cube`
  - `assets/geo_timeseries.h5`
- `velocity_map`
  - `assets/geo_velocity.h5`
- `velocity_geotiff`
  - `assets/velocity.tif`
- `temporal_coherence`
  - `assets/geo_temporalCoherence.h5`
- `temporal_coherence_geotiff`
  - `assets/temporalCoherence.tif`
- `quality_mask`
  - `assets/geo_maskTempCoh.h5`
- `quality_mask_geotiff`
  - `assets/maskTempCoh.tif`
- `preview_png`
  - `preview/velocity_preview.png`
- `diagnostic_png`
  - `preview/numTriNonzeroIntAmbiguity.png`

## 6. Publish Rules

Current recommended rules:

- publish the geocoded bundle, not the radar-coordinate MintPy runtime directory
- treat `manifest.json` as the registration root
- treat `geo_timeseries.h5` as the canonical time-series data product
- treat `velocity.tif` as the default visualization product
- always publish at least one quality layer beside the velocity layer
- keep diagnostics and config snapshots for reproducibility even if the frontend does not display all of them

## 7. Current Open Items

Still to be formalized before production:

- final CRS contract beyond the current `EPSG:4326` experiment assumption
- whether the backend stores one product record per artifact or one bundle-root record plus child artifacts
- how the frontend will query time-series pixels from `geo_timeseries.h5`
- whether extra export formats such as COG, CSV point extraction, or JSON summaries should be added

## 8. Current Judgment

For the current phase-1 SBAS route, the final deliverable should be understood as:

- one manifest-driven publish bundle
- centered on `assets/geo_timeseries.h5`
- summarized by `assets/velocity.tif`
- constrained by `assets/temporalCoherence.tif` and `assets/maskTempCoh.tif`

That is the product contract the future system should embed first.