"""An optional local preview window.

A source node showing its own frames overlaps with what a viewer node does, and
that is the point: it means checking that a camera works needs this repository
only, not a second node wired into a dataflow. It is off unless asked for, and
never opens under CI.
"""

import cv2
import numpy as np

WINDOW = "dora-webcam"


def show(frame: np.ndarray) -> bool:
    """Display one frame and report whether the viewer asked to quit.

    Parameters
    ----------
    frame : np.ndarray
        The captured BGR frame, before encoding, which is what a person wants
        to look at.

    Returns
    -------
    bool
        True when `q` was pressed, which stops the node.

    """
    cv2.imshow(WINDOW, frame)
    return cv2.waitKey(1) & 0xFF == ord("q")


def close() -> None:
    """Tear the window down, if one was ever opened."""
    cv2.destroyAllWindows()