# CelerisLab/body/preprocess/flag_overlay.py
"""
Flag overlay: merge per-object flag masks onto a clean domain base.
"""

from __future__ import annotations

from typing import List

import numpy as np


def merge_flag_masks(
    base: np.ndarray,
    masks: List[np.ndarray],
) -> np.ndarray:
    """Merge object flag masks onto a clean domain base.

    For each mask in *masks*, non-zero entries overwrite the corresponding
    positions in *base*.  Callers should pass a fresh channel-layout flag
    array to prevent stale obstacle bits from surviving after geometry edits.

    Args:
        base: uint16 domain flag array (e.g. from build_channel_flags()).
        masks: List of uint16 mask arrays from each object's get_flag_mask().

    Returns:
        New uint16 array with object overlays applied.
    """
    merged = np.array(base, copy=True)
    for mask in masks:
        nonzero = mask != 0
        merged[nonzero] = mask[nonzero]
    return merged
