Cloud mask

Cloud confidence with dust restoral, Eqs. 1-12.

DEBRA cloud mask, Eqs. 1-12 (Miller et al. 2017).

Continuous cloud confidence in [0, 1] from IR-only tests, with dust-restoral terms so dust pixels are not masked as cloud. Two deliberate deviations from the printed equations, both following the paper’s own prose (the 2020 erratum does not touch either); see docs/deviations.md:

• Eq. 4 (CM2) is implemented magnitude-reversed, CM2 = 1 - N(BT10.4 - BT6.2; 0, 25) (deep convection -> 1, clear -> 0). As printed, clear sky (split of 25-55 K) would give CM2 ~ 1 and saturate the mask everywhere, degenerating the algorithm; the prose (“in a similar fashion” to the reversed Eq. 1) and Figure 3c confirm the reversed intent.

• Eq. 11 (CM_day) uses CM3, not the misprinted CM4 (the 3.9-um test is night-only): CM_day = (CM1 + CM2 + CM3) * (1 - max(R1, R2_day)).

shachen.cloudmask.cloud_mask(scene: Dataset, skin_temperature: DataArray, constants: CloudMaskConstants = CloudMaskConstants(cm1_cold_offset_k=50.0, cm2=Bounds(min=0.0, max=25.0), cm3=Bounds(min=2.0, max=4.5), cm4=Bounds(min=5.0, max=8.0), r1=Bounds(min=0.0, max=3.5), r2=Bounds(min=-1.0, max=3.0), cm_norm=Bounds(min=0.45, max=0.8))) → Dataset

Cloud-mask components and combined masks on the scene grid.

scene needs bt_swir_39, bt_wv_62, bt_tir_86, bt_tir_104, bt_tir_123 (K); skin_temperature (K) must be on the same grid (ValueError on 2-D shape mismatch). NaN inputs propagate.

Returns a Dataset with cm1..``cm4`` (Eqs. 1, 4-6; CM1 reduces to 1 - N(BT10.4 - T_skin; -offset, 0) since the per-pixel bounds share a constant width), r1, r2_day, r2_ngt (Eqs. 7-9), cm_day, cm_ngt (Eqs. 10-11), and cm_norm_day, cm_norm_ngt (Eq. 12).