libera_utils.l1a.wfov_image_metadata.enhance_wfov_l1a_dataset

libera_utils.l1a.wfov_image_metadata.enhance_wfov_l1a_dataset(packet_ds: Dataset) → Dataset

Stitch complete WFOV images, drop raw packet payloads, and attach CAMERA_TIME metadata.

Raises if no image completes, before dropping anything, so a granule that produces nothing keeps its raw payload for diagnosis instead of being silently emptied.

ICIE__WFOV_DATA is dropped from the returned dataset entirely, for every packet regardless of completeness: content folded into a complete image is already duplicated (compressed) on CAMERA_TIME as WFOV_COMPRESSED_IMAGE, and content that never completed an image (edge truncation or a mid-stream anomaly) cannot be assembled from this granule alone — the raise above guarantees at least one image did complete before any payload is discarded, and PacketCountNotUsedInImages plus PACKET_IMAGE_ID == -1 record what was dropped. PACKET_IMAGE_ID remains the only per-packet trace-back to a stitched image (-1 if none). Dropping the whole variable, rather than zeroing it row by row, avoids a second full-size copy of the ~GB-scale raw array: zeroing in place would corrupt the caller’s dataset, since copy(deep=False) shares the buffer. Note that drop_vars here does not itself free that buffer — parse_packets_to_l1a_dataset still holds the original packet_ds across this call, so the array survives until the caller rebinds on return.

Parameters:

packet_ds (xarray.Dataset) – APID 1040 packet-level L1A dataset containing mem-dump flag/offset/length fields and ICIE__WFOV_DATA.

Returns:

Input dataset merged with CAMERA_TIME metadata, PACKET_IMAGE_ID, and file-level stitch quality attributes; ICIE__WFOV_DATA is absent.

Return type:

xarray.Dataset

Raises:

ValueError – If required WFOV packet variables are missing from packet_ds, or if no complete image could be stitched from the packet stream. In the latter case packet_ds is left untouched, so the caller still holds the raw payloads.