msi_processor.computing.pansharpen package

Optional pan-sharpening processing unit (C-PU-PAN; DPM-M-PAN).

Terminal, default-off post-L2A derivative (CR-4): fuses the BOA (surface) reflectance stack with the panchromatic band to trade spectral fidelity for spatial sharpness, emitting the DPM-PR-L2A-PAN product. Not science-grade.

Submodules

msi_processor.computing.pansharpen.core module

Pure pan-sharpening core (C-PU-PAN; ALG-PAN-ALIGN/FUSE).

CPM-free, I/O-free functions implementing the optional pan-sharpening algorithms of ATBD <5.9>. Pan-sharpening is a terminal, post-L2A derivative (CR-4): it runs after atmospheric correction, fusing the BOA (surface) reflectance stack with the high-resolution panchromatic (PAN) band to trade spectral/radiometric fidelity for spatial sharpness. It is optional and default-off, and the product it emits (DPM-PR-L2A-PAN) is a visual/derivative product, not a science-grade input to quantitative retrieval (DPM <8.9>).

Algorithm split (operational baseline vs [impl])

• ALG-PAN-ALIGN (MS -> PAN registration). The multispectral bands are resampled onto the PAN grid by reusing the co-registration core (CLAHE -> SIFT -> FLANN -> RANSAC homography -> warpPerspective); see align_ms_to_pan(). No new matching code lives here – alignment is the same heritage estimator the coregister unit uses, with the PAN band as the reference (SDD <5.4.10>).

• ALG-PAN-FUSE (fusion). The simple-mean fusion \(\hat{P}_b = \tfrac{1}{2}(\mathrm{MS}^{\mathrm{reg}}_b + \mathrm{PAN})\) (heritage, ATBD <5.9>) is realised here (fuse(), method="simple_mean") and fully unit-tested. The sharper component-substitution methods (Brovey, Gram-Schmidt, IHS, a-trous wavelet – down-selected per sensor profile in the DPM) are the deferred bodies ([impl]); requesting one raises PansharpenError (ATBD <5.9> open point 6).

Spectral fidelity (REQ-F-PAN-02)

Fusion is lossy by construction. spectral_fidelity() quantifies, per band, how much of the input MS radiometry survives the fusion – the Pearson correlation between the aligned MS band and its fused counterpart. The wrapper reports these scalars as QA metrics and checks them against the per-profile fidelity budget (the budget itself is private; None accepts any value).

PAN-reflectance handling (ATBD <5.9> open point 7, unresolved)

Rigorous atmospheric correction is band-specific, but the broadband PAN response is too wide for a well-defined per-band correction. Whether the PAN passed to fuse() is a synthesised BOA-PAN (approximated from the corrected MS bands) or the raw TOA-PAN (a TOA/BOA domain mismatch) is an open [impl]/profile decision; this core operates on whatever PAN array the wrapper supplies and does not itself resolve that choice. The settled part is only the order (atmospheric correction precedes fusion, ATBD <5.9>).

Trace: REQ-F-PAN-01..02; DPM-M-PAN; ALG-PAN-ALIGN/FUSE; SYS-CAP-04.

msi_processor.computing.pansharpen.core.FusionMethod

Fusion methods recognised by the unit; only OPERATIONAL_METHODS are realised, the rest are [impl] (ATBD <5.9> open point 6).

alias of Literal[‘simple_mean’, ‘brovey’, ‘gs’, ‘ihs’, ‘atrous’]

msi_processor.computing.pansharpen.core.OPERATIONAL_METHODS: tuple[Literal['simple_mean', 'brovey', 'gs', 'ihs', 'atrous'], ...] = ('simple_mean',)

The operational baseline realised in this increment (PDR/CDR target). The component-substitution methods are deferred [impl] bodies.

msi_processor.computing.pansharpen.core.align_ms_to_pan(ms_stack, pan, params)

ALG-PAN-ALIGN – resample each MS band onto the PAN grid.

Reuses the co-registration estimator (estimate_homography() + warp_to_reference() from msi_processor.computing.coregistration.core) with the panchromatic band as the reference: for every MS band a projective homography \(H_b\) (band \(\to\) PAN) is fitted by CLAHE-enhanced SIFT + FLANN + RANSAC, then the original (radiometric) band is warped onto the PAN \((\text{rows}, \text{cols})\) extent. This is the same heritage alignment the coregister unit performs, so no matching logic is re-implemented (SDD <5.4.10>).

Return type:

dict[str, ndarray[tuple[Any, ...], dtype[float32]]]

Parameters:

ms_stack:

Mapping of MS band id to its 2-D BOA-reflectance array (post atmospheric correction). Must be non-empty.

pan:

2-D panchromatic array; its shape defines the output grid.

params:

Co-registration parameters (reference band is ignored here – PAN is the reference; the RANSAC threshold, CLAHE and keypoint gates apply).

Returns:

dict

Mapping of band id to its PAN-grid float32 array, in input order.

Raises:

PansharpenError

If ms_stack is empty, pan is not 2-D, or alignment fails for any band (insufficient keypoints/matches/inliers) – fail-stop (REQ-F-PAN-01).

msi_processor.computing.pansharpen.core.fuse(ms_aligned, pan, method='simple_mean')

ALG-PAN-FUSE – fuse PAN-grid MS bands with the PAN band.

For the operational "simple_mean" method each fused band is the per-pixel average of the aligned MS band and the PAN band, :rtype: dict[str, ndarray[tuple[Any, ...], dtype[float32]]]

\[\hat{P}_b = \tfrac{1}{2}\big(\mathrm{MS}^{\mathrm{reg}}_b + \mathrm{PAN}\big),\]

clipped to the reflectance range \([0, 1]\) (the operating domain is BOA reflectance; the heritage DN clip [0, 2^{12}-1] is the same operation in DN units, DPM <8.9>). The component-substitution methods ("brovey", "gs", "ihs", "atrous") are deferred [impl] (ATBD <5.9> open point 6).

Parameters:

ms_aligned:

Mapping of band id to its PAN-grid array (output of align_ms_to_pan()). Must be non-empty.

pan:

2-D panchromatic array; every aligned band must share its shape.

method:

Fusion method; only OPERATIONAL_METHODS are realised.

Returns:

dict

Mapping of band id to its fused float32 array, in input order.

Raises:

PansharpenError

On an unknown method, a deferred [impl] method, an empty stack, or a band whose shape does not match pan.

msi_processor.computing.pansharpen.core.spectral_fidelity(ms_aligned, fused)

Per-band spectral-fidelity metric (REQ-F-PAN-02).

Reports, for each fused band, the Pearson correlation coefficient between the aligned MS band (the spectral reference) and its fused counterpart – a value in \([-1, 1]\) where 1 means the fusion preserved the band’s spatial-spectral structure perfectly. Fusion necessarily lowers it; the wrapper checks the per-band value against the per-profile fidelity budget and records it as QA (the budget is private).

A band whose MS or fused array is constant (zero variance) has an undefined correlation; 0.0 is reported for it (no linear structure to preserve).

Return type:

dict[str, float]

Parameters:

ms_aligned, fused:

Matching mappings of band id to PAN-grid arrays (same keys/shapes).

Returns:

dict

Mapping of band id to its fidelity coefficient, in fused order.

msi_processor.computing.pansharpen.unit module

Thin EOProcessingUnit wrapper for pan-sharpening (C-PU-PAN).

Adapts the pure core to the EOPF CPM runtime following the wrapper template of SDD <5.4.1>/<5.4.10>: read parameters, split the BOA-MS bands from the PAN band, orchestrate the pure-core functions (ALG-PAN-ALIGN -> ALG-PAN-FUSE -> spectral fidelity), and build the optional DPM-PR-L2A-PAN derivative product. No algorithm lives here.

Input convention. The upstream stage is the atmospheric unit; its l2a product carries the BOA (surface) reflectance under measurements/reflectance/<band> (IF-PROD-04). One of those bands is the high-resolution panchromatic band, named by the pan_band parameter; the remaining bands form the MS stack that is sharpened onto the PAN grid. Building a science-grade PAN reflectance (the BOA-PAN vs TOA-PAN choice) is an open [impl]/profile point (ATBD <5.9> open point 7): this wrapper fuses whatever reflectance the pan_band carries.

Optionality (CR-4). Pan-sharpening is a terminal, default-off derivative. The chain runner skips it when optional_stages.pansharpen is false; if the unit is nevertheless invoked with enabled=false it fail-stops rather than silently emitting a product (defensive, REQ-F-PAN-01).

Fail-stop (REQ-F-PAN-01/02). A missing reflectance group, an absent pan_band, fewer than one MS band, an alignment failure, or a deferred [impl] fusion method raise PansharpenError (or InputValidationError for malformed inputs); it propagates to the chain runner so no derivative is emitted from incomplete inputs. Per-band spectral fidelity is reported as QA and, when a profile fidelity budget is supplied, checked against it (REQ-F-PAN-02).

Mandatory inputs are declared by the CPM computing-model JSON (models/msi_pansharpen_1.0.0.json), not by overriding the list methods.

Trace: REQ-F-PAN-01..02; DPM-M-PAN, DPM-PR-L2A-PAN; ALG-PAN-ALIGN/FUSE; ICD IF-PROD-04; SYS-CAP-04.

class msi_processor.computing.pansharpen.unit.PansharpenUnit(identifier='')

Bases: EOProcessingUnit

Optional pan-sharpening processing unit (C-PU-PAN; SDD <5.4.10>).

Attributes:

identifier

Identifier of the processing step

Methods

run:	Align the BOA-MS bands onto the PAN grid, fuse them with the PAN band and emit the optional DPM-PR-L2A-PAN derivative with per-band spectral-fidelity QA. Only method="simple_mean" is operational; the component-substitution methods are [impl] (ATBD <5.9> open point 6).

PROCESSOR_LEVEL = 'L2A'

PROCESSOR_MODEL = True

PROCESSOR_NAME = 'msi_pansharpen'

PROCESSOR_VERSION = '1.0.0'

run(inputs, adfs=None, mode=None, **kwargs)

Run the pan-sharpening derivative.

Return type:

Mapping[str, Union[EOProduct, EOContainer, DataTree, Iterable[Union[EOProduct, EOContainer, DataTree]]]]

Parameters:

inputs:

{"l2a": EOProduct} with BOA reflectance under measurements/reflectance/<band>, including the panchromatic band.

adfs:

None required (the PAN band is carried by the L2A product).

mode:

"nominal" (the only supported processing mode).

**kwargs:

enabled (bool, default True; False fail-stops), method (fusion method, default "simple_mean"), pan_band (band id of the PAN band; required), fidelity_budget (optional minimum acceptable per-band fidelity), the alignment parameters (ransac_tau, clahe_clip/clahe_grid, match_fraction, min_keypoints/min_keypoints_pan, seed, max_residual), and an optional name for the output product.

Returns:

Mapping[str, DataType]

{"pan": EOProduct} with fused measurements/reflectance/<band> and quality/spectral_fidelity/<band>.

Raises:

PansharpenError

On a missing pan_band, no MS bands, an alignment failure, a deferred [impl] fusion method, or enabled=false – fail-stop (REQ-F-PAN-01).

InputValidationError

On a missing input / reflectance group or an unknown mode/method type.