mesofield 0.3.2b0__py3-none-any.whl

mesofield/data/manager.py

@@ -0,0 +1,388 @@
+from __future__ import annotations
+"""
+DataManager & DataSaver Workflow Overview
+1. Initialization
+    ├─ dm = DataManager()
+    └─ dm.setup(config, path, devices)
+2. Saving experiment outputs via DataSaver
+    ├─ dm.saver.configuration()       # writes experiment config to disk
+    ├─ dm.saver.all_hardware()        # writes hardware outputs
+    ├─ dm.saver.all_notes()           # writes notes.txt if any
+    └─ dm.saver.writer_for(camera)    # returns writer & updates camera output paths
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, List, Any, Dict, Iterable
+from logging import Logger
+
+import os
+import queue
+import csv
+import threading
+import time
+from datetime import datetime
+
+import pandas as pd
+
+from mesofield.config import ExperimentConfig
+from mesofield.data.writer import CustomWriter, CV2Writer
+from mesofield.utils._logger import get_logger, log_this_fr, hyperlink
+
+
+@dataclass
+class DataPacket:
+    """Entry in :class:`DataQueue`."""
+
+    device_id: str
+    timestamp: datetime
+    payload: Any
+    device_ts: float | None = None
+    meta: Dict[str, Any] = field(default_factory=dict)
+
+
+class DataQueue:
+    """Thread-safe queue for data streaming between devices and consumers.
+    
+    Registered DataProducer (the :class:`DataManager`) devices can push data packets to this queue,
+    which can then be consumed by other parts of the system.
+    """
+
+    def __init__(self, maxsize: int = 0) -> None:
+        self._queue: queue.Queue[DataPacket] = queue.Queue(maxsize)
+
+    def push(
+        self,
+        device_id: str,
+        payload: Any,
+        *,
+        timestamp: datetime | None = None,
+        device_ts: float | None = None,
+        **meta: Any,
+    ) -> None:
+        """Add a new data packet to the queue."""
+        if timestamp is None:
+            timestamp = datetime.now()
+        self._queue.put(DataPacket(device_id, timestamp, payload, device_ts, meta))
+
+    def pop(self, block: bool = True, timeout: float | None = None) -> DataPacket:
+        """Return the next :class:`DataPacket` from the queue."""
+        return self._queue.get(block=block, timeout=timeout)
+
+    def empty(self) -> bool:
+        return self._queue.empty()
+
+
+@dataclass
+class DataPaths:
+    """Structured storage for all output paths used by the :class:`DataSaver`.
+    
+    Relies on the :class:`ExperimentConfig` to generate paths based on the
+    experiment's BIDS directory using the `make_path` method, which relies
+    on HardwareDevices implementing a file_type, bids_type.
+    
+    These paths can then be passed to HardwareDevice.save_data(path)  
+    """
+    configuration: str
+    notes: str
+    timestamps: str
+    hardware: Dict[str, str] = field(default_factory=dict)
+    writers: Dict[str, str] = field(default_factory=dict)
+    queue: str = ""
+
+    @classmethod
+    def build(cls, cfg: ExperimentConfig) -> DataPaths:
+        cfg_paths = {
+            "configuration": cfg.make_path("configuration", "csv"),
+            "notes": cfg.make_path("notes", "txt"),
+            "timestamps": cfg.make_path("timestamps", "csv"),
+        }
+        hw_paths: Dict[str, str] = {}
+        for dev_id, device in cfg.hardware.devices.items():
+            args = getattr(device, "path_args", {})
+            suffix = args.get("suffix", dev_id)
+            ext = args.get("extension", getattr(device, "file_type", "dat"))
+            bids_type = args.get("bids_type", getattr(device, "bids_type"))
+            hw_paths[dev_id] = cfg.make_path(suffix, ext, bids_type)
+        return cls(
+            configuration=cfg_paths["configuration"],
+            notes=cfg_paths["notes"],
+            timestamps=cfg_paths["timestamps"],
+            hardware=hw_paths,
+            writers={},
+            queue=cfg.make_path("dataqueue", "csv", "beh"),
+        )
+
+@dataclass
+class DataSaver:
+    """Helper class for saving experiment data to disk.
+    
+    This class handles saving configuration, hardware data, notes, timestamps,
+    and camera data to disk.
+    
+    Takes paths generated from :class:`DataPaths` instance and calls `Device.save_data(path)`
+    on all hardware devices that implement this method.
+    
+    (NOTE: If a device does not implement `save_data`, it will be skipped.)
+    
+    Takes an :class:`ExperimentConfig` to save configuration.
+    """
+    
+    cfg: ExperimentConfig
+    paths: DataPaths = field(init=False)
+    logger: Logger = field(default_factory=lambda: get_logger("DataSaver"))
+
+    def __post_init__(self) -> None:
+        self.paths = DataPaths.build(self.cfg)
+        self.logger.debug(f"Prepared output paths: {self.paths}")
+
+    def configuration(self) -> None:
+        path = self.paths.configuration
+        try:
+            params = self.cfg.items()
+            df = pd.DataFrame(params.items(), columns=["Parameter", "Value"])
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            df.to_csv(path, index=False)
+            self.logger.info(
+                f"Configuration {hyperlink(path, os.path.basename(path))} [saved]"
+            )
+        except Exception as e:
+            self.logger.error(f"Error saving configuration: {e}")
+
+    def all_hardware(self) -> None:
+        for dev_id, path in self.paths.hardware.items():
+            device = self.cfg.hardware.devices.get(dev_id)
+            if not device:
+                continue
+            try:
+                os.makedirs(os.path.dirname(path), exist_ok=True)
+                device.output_path = path
+                if hasattr(device, "save_data"):
+                    device.save_data(path)
+                self.logger.info(
+                    f"Device {dev_id} data {hyperlink(path, os.path.basename(path))} [saved]"
+                )
+            except Exception as e:
+                self.logger.error(f"Error saving device {dev_id}: {e}")
+
+    def all_notes(self) -> None:
+        if not self.cfg.notes:
+            return
+        path = self.paths.notes
+        try:
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with open(path, "w") as f:
+                f.write("\n".join(self.cfg.notes))
+            self.logger.info(f"Notes {hyperlink(path, os.path.basename(path))} [saved]")
+        except Exception as e:
+            self.logger.error(f"Error saving notes: {e}")
+
+    def save_timestamps(self, id, start_time, stop_time) -> None:
+        path = self.paths.timestamps
+        try:
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with open(path, "w", newline="") as csvfile:
+                writer = csv.writer(csvfile)
+                writer.writerow(["device_id", "started", "stopped"])
+                writer.writerow([id, start_time, stop_time])
+                for dev_id, device in self.cfg.hardware.devices.items():
+                    started = getattr(device, "_started", "")
+                    stopped = getattr(device, "_stopped", "")
+                    writer.writerow([dev_id, started, stopped])
+            self.logger.info(
+                f"Timestamps {hyperlink(path, os.path.basename(path))} [saved]"
+            )
+        except Exception as e:
+            self.logger.error(f"Error saving timestamps: {e}")
+
+    def save_queue(self, rows: list[list[Any]], path: str | None = None) -> None:
+        """Save queued data rows to CSV file specified in DataPaths or override path.
+
+        Rows are produced by ``DataManager._queue_writer_loop`` as
+        ``[queue_elapsed, packet_ts, device_ts, device_id, payload]``.
+        If any payload is a ``dict``, its keys are fanned out into
+        dedicated columns; the ``payload`` column then holds the
+        non-dict payloads only (blank when a row has dict columns).
+        """
+        if path is None:
+            path = self.paths.queue
+        try:
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+
+            keys: list[str] = []
+            seen: set[str] = set()
+            for row in rows:
+                payload = row[4] if len(row) > 4 else None
+                if isinstance(payload, dict):
+                    for k in payload:
+                        if k not in seen:
+                            seen.add(k)
+                            keys.append(k)
+
+            base_cols = ["queue_elapsed", "packet_ts", "device_ts", "device_id"]
+            with open(path, "w", newline="") as csvfile:
+                writer = csv.writer(csvfile)
+                if keys:
+                    writer.writerow([*base_cols, "payload", *keys])
+                    for row in rows:
+                        elapsed, ts, dts, dev_id, payload = row[:5]
+                        if isinstance(payload, dict):
+                            writer.writerow(
+                                [elapsed, ts, dts, dev_id, "",
+                                 *(payload.get(k, "") for k in keys)]
+                            )
+                        else:
+                            writer.writerow(
+                                [elapsed, ts, dts, dev_id, payload,
+                                 *("" for _ in keys)]
+                            )
+                else:
+                    writer.writerow([*base_cols, "payload"])
+                    writer.writerows(rows)
+            self.logger.info(
+                f"Queue log {hyperlink(path, os.path.basename(path))} [saved]"
+            )
+        except Exception as e:
+            self.logger.error(f"Error saving queue log: {e}")
+
+
+class DataManager:
+    """Wrapper providing :class:`DataSaver` and :class:`DataQueue`."""
+
+    def __init__(self) -> None:
+        self.save: DataSaver
+        self.queue = DataQueue()
+
+        self.devices: List[Any] = []
+        self._registered_ids: set[str] = set()
+        
+        self.queue_log_path: Optional[str] = None
+        self.queue_packets: list[list[Any]] = []
+        
+        self._queue_thread: Optional[threading.Thread] = None
+        self._stop_queue: bool = False
+
+    def setup(
+        self, config: ExperimentConfig, devices: Iterable[Any] | None = None
+    ) -> None:
+        """Attach configuration and optionally register devices."""
+        self.save = DataSaver(config)
+        if devices is not None:
+            self.register_devices(devices)
+
+    #@log_this_fr
+    def register_devices(self, devices: Iterable[Any]) -> None:
+        """Register a list of hardware devices with the manager.
+
+        Any device exposing a :class:`mesofield.signals.DeviceSignals`
+        bundle on ``device.signals`` is registered.  Devices that do not
+        emit on ``signals.data`` (e.g. stimulus devices) are still tracked
+        but contribute nothing to the queue.
+        """
+        for dev in devices:
+            if hasattr(dev, "signals"):
+                self.register_hardware_device(dev)
+
+    # ------------------------------------------------------------------
+    def start_queue_logger(self, path: str | None = None) -> None:
+        """Begin capturing :class:`DataQueue` contents."""
+        # determine log path, default to DataPaths.queue
+        if path is None and getattr(self, "save", None):
+            path = self.save.paths.queue
+        if path is None:
+            return
+
+        self.queue_log_path = path
+        # in-memory storage for log rows
+        self.queue_packets = []
+        self._stop_queue = False
+
+        # start background thread to record queue packets
+        self._queue_thread = threading.Thread(
+            target=self._queue_writer_loop,
+            daemon=True,
+        )
+        self._queue_thread.start()
+
+    def stop_queue_logger(self) -> None:
+        """Stop the queue logging thread and flush data to disk."""
+        self._stop_queue = True
+        if self._queue_thread:
+            self._queue_thread.join(timeout=1)
+
+        # save recorded packets via DataSaver
+        if self.save and self.queue_log_path:
+            # use the configured log path for writing
+            self.save.save_queue(self.queue_packets, self.queue_log_path)
+
+    def _queue_writer_loop(self) -> None:
+
+        while not self._stop_queue or not self.queue.empty():
+            try:
+                pkt = self.queue.pop(timeout=0.1)
+            except queue.Empty:
+                continue
+
+            now = time.perf_counter()  # Use monotonic time for consistency
+            row = [now, pkt.timestamp, pkt.device_ts, pkt.device_id, pkt.payload]
+            self.queue_packets.append(row)
+
+            # if self._stream and self._writer:
+            #     self._writer.writerow(row)
+            #     assert self._file is not None
+            #     self._file.flush()
+
+    def register_hardware_device(self, device: Any) -> None:
+        """Track a hardware device and connect its data stream to the queue.
+
+        Devices expose a uniform :class:`mesofield.signals.DeviceSignals`
+        bundle on ``device.signals``.  We simply connect ``signals.data``
+        to push ``(payload, device_ts)`` packets onto the queue.  Devices
+        that never emit on ``signals.data`` (e.g. ``StimulusDevice``) are
+        registered but never produce queue entries.
+        """
+        dev_id = getattr(device, "device_id", getattr(device, "id", "unknown"))
+        if device in self.devices or dev_id in self._registered_ids:
+            return
+
+        self.devices.append(device)
+        self._registered_ids.add(dev_id)
+
+        signals = getattr(device, "signals", None)
+        data_sig = getattr(signals, "data", None) if signals is not None else None
+        if data_sig is None or not hasattr(data_sig, "connect"):
+            return
+
+        def _push(payload: Any, device_ts: Any = None, *, _id=dev_id) -> None:
+            self.queue.push(_id, payload, device_ts=device_ts)
+
+        try:
+            data_sig.connect(_push)
+        except Exception:
+            pass
+
+    #TODO: move this logic to DataSaver
+    def get_device_outputs(self, subject: str, session: str) -> pd.DataFrame:
+        """Return a DataFrame of output file paths for registered devices."""
+        records = {}
+        for dev in self.devices:
+            dev_id = getattr(dev, "device_id", getattr(dev, "id", "unknown"))
+            out = getattr(dev, "output_path", None)
+            if out:
+                key = (dev.device_type, dev_id, "file")
+                records[key] = out
+
+                # derive metadata path if attribute not set
+                meta = getattr(dev, "metadata_path", None)
+                if not meta:
+                    if out.endswith("ome.tiff"):
+                        meta = out.replace("ome.tiff", "ome.tiff_frame_metadata.json")
+                    elif out.endswith("ome.tif"):
+                        meta = out.replace("ome.tif", "ome.tif_frame_metadata.json")
+                if meta and os.path.exists(meta):
+                    key = (dev.device_type, dev_id, "metadata")
+                    records[key] = meta
+        if not records:
+            return pd.DataFrame()
+        idx = pd.MultiIndex.from_arrays([[subject], [session]], names=["Subject", "Session"])
+        return pd.DataFrame(records, index=idx)
+

mesofield/data/writer.py

@@ -0,0 +1,289 @@
+"""Custom OME.TIFF + MP4 writers for MDASequences.
+
+`CustomWriter` extends pymmcore-plus's public :class:`OMETiffWriter` with two
+additions:
+
+1. ``bigtiff=True`` on the underlying tifffile call -- mesoscope acquisitions
+   routinely exceed the classic-TIFF 4 GiB ceiling.
+2. A per-frame ``<filename>_frame_metadata.json`` sidecar emitted from
+   :meth:`finalize_metadata`, containing the same metadata pymmcore-plus
+   accumulates internally. This is the legacy ``mesofield`` contract every
+   downstream parser already reads.
+
+The sidecar JSON is the current source of truth for per-frame metadata. The
+broader goal (tracked separately) is to push the same fields into the OME-XML
+embedded in the TIFF itself so the JSON becomes supplementary and redundant;
+see the TODO in :meth:`OMETiffWriter._sequence_metadata` upstream.
+
+`CV2Writer` subclasses the public :class:`OMETiffWriter` purely to reuse its
+inherited ``frameReady`` plumbing (the machinery that turns MMCamera/MDA signals
+into ``new_array`` / ``write_frame`` / ``store_frame_metadata`` calls and
+accumulates pymmcore-plus metadata). It overrides every TIFF-specific method to
+emit MP4/AVI instead -- there is no public MP4 handler in pymmcore-plus to
+inherit from, and inheriting the public ``OMETiffWriter`` avoids depending on
+pymmcore-plus's private ``_5d_writer_base`` module.
+"""
+
+from datetime import timedelta
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pymmcore_plus.mda.metadata import SummaryMetaV1  # type: ignore
+
+from pymmcore_plus.mda.handlers import OMETiffWriter
+from useq import MDAEvent
+
+import numpy as np
+from pathlib import Path
+import json
+
+FRAME_MD_FILENAME = "_frame_metadata.json"
+
+# ─── H264 Video Codec ─────────────────────────────────────────────────────
+# OpenH264 codec DLL for OpenCV video encoding (Windows only).
+# The DLL lives at <repo-root>/external/video-codecs/.
+_REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+CODEC_DIRECTORY = str(_REPO_ROOT / "external" / "video-codecs")
+OPENH264_DLL_PATH = str(Path(CODEC_DIRECTORY) / "openh264-1.8.0-win64.dll")
+# ─────────────────────────────────────────────────────────────────
+
+class CustomWriter(OMETiffWriter):
+    """OME-TIFF writer extending pymmcore-plus's :class:`OMETiffWriter`.
+
+    Two divergences from the public base:
+
+    - Uses ``bigtiff=True`` so multi-GiB mesoscope acquisitions write cleanly.
+    - Emits the per-frame metadata JSON sidecar mesofield's downstream parsers
+      (and the AcquisitionManifest's ``metadata_path``) depend on.
+
+    Everything else -- filename validation, frame writing, OME-XML sequence
+    metadata, memmap handling -- is inherited from :class:`OMETiffWriter`.
+    """
+
+    def __init__(self, filename: Path | str) -> None:
+        super().__init__(filename)
+        self._frame_metadata_filename = self._filename + FRAME_MD_FILENAME
+
+    def new_array(
+        self, position_key: str, dtype: np.dtype, sizes: dict[str, int]
+    ) -> np.memmap:
+        """Mirror :meth:`OMETiffWriter.new_array` but with ``bigtiff=True``.
+
+        Upstream's implementation hardcodes the ``imwrite`` call; we duplicate
+        it here to flip the ``bigtiff`` flag. Keep the bodies in sync if a
+        pymmcore-plus bump changes the upstream version.
+        """
+        from tifffile import imwrite, memmap
+
+        dims, shape = zip(*sizes.items())
+
+        metadata: dict[str, Any] = self._sequence_metadata()
+        metadata["axes"] = "".join(dims).upper()
+
+        if (seq := self.current_sequence) and seq.sizes.get("p", 1) > 1:
+            ext = ".ome.tif" if self._is_ome else ".tif"
+            fname = self._filename.replace(ext, f"_{position_key}{ext}")
+        else:
+            fname = self._filename
+
+        imwrite(
+            fname,
+            shape=shape,
+            bigtiff=True,
+            dtype=dtype,
+            metadata=metadata,
+            imagej=not self._is_ome,
+            ome=self._is_ome,
+        )
+
+        mmap = memmap(fname, dtype=dtype)
+        mmap.shape = shape
+        return mmap  # type: ignore
+
+    def finalize_metadata(self) -> None:
+        """Write the per-frame metadata sidecar.
+
+        Called by ``OMETiffWriter.sequenceFinished`` after the last frame.
+        Serialises ``self.frame_metadatas`` (the dict pymmcore-plus accumulates
+        for us in ``frameReady``) to JSON at ``<filename>_frame_metadata.json``.
+        """
+        regular_dict = dict(self.frame_metadatas)
+        json_str = json.dumps(regular_dict, indent=4, cls=CustomJSONEncoder)
+        with open(self._frame_metadata_filename, "w") as fh:
+            fh.write(json_str)
+
+
+class CustomJSONEncoder(json.JSONEncoder):
+    def default(self, object: Any) -> Any:
+        if isinstance(object, MDAEvent):
+            return None #ignore the MDAEvents for now
+        return super().default(object)
+
+
+def configure_opencv_codec() -> None:
+    """Configure environment so OpenCV can locate the bundled OpenH264 DLL.
+
+    Safe to call repeatedly. Silences OpenCV/FFMPEG logging and prepends the
+    project's ``external/video-codecs`` directory to PATH / DLL search.
+    """
+    import os
+
+    # Set environment variables to suppress OpenCV/FFMPEG output BEFORE importing cv2
+    os.environ.setdefault('OPENCV_LOG_LEVEL', 'SILENT')
+    os.environ.setdefault('OPENCV_FFMPEG_CAPTURE_OPTIONS', 'loglevel;quiet')
+    os.environ.setdefault('OPENCV_VIDEOIO_DEBUG', '0')
+
+    try:
+        import cv2  # noqa: F401
+    except ImportError as e:  # pragma: no cover - optional dependency
+        raise ImportError(
+            "opencv-python is required. Please `pip install opencv-python`."
+        ) from e
+
+    # OpenCV log silencing is version-dependent.
+    try:
+        if hasattr(cv2, 'setLogLevel'):
+            cv2.setLogLevel(0)  # 0 = Silent
+        elif (
+            hasattr(cv2, 'utils')
+            and hasattr(cv2.utils, 'logging')
+            and hasattr(cv2.utils.logging, 'setLogLevel')
+        ):
+            cv2.utils.logging.setLogLevel(0)
+    except Exception:
+        pass
+
+    os.environ['OPENH264_LIBRARY'] = OPENH264_DLL_PATH
+    if CODEC_DIRECTORY not in os.environ.get('PATH', ''):
+        os.environ['PATH'] = CODEC_DIRECTORY + os.pathsep + os.environ.get('PATH', '')
+    if hasattr(os, 'add_dll_directory'):
+        try:
+            os.add_dll_directory(CODEC_DIRECTORY)
+        except (OSError, FileNotFoundError):
+            pass
+
+
+class CV2Writer(OMETiffWriter):
+    """Write frames to an mp4/avi video using OpenCV.
+
+    Subclasses the public :class:`OMETiffWriter` only to reuse its inherited
+    MDA-signal handling (``frameReady`` / ``sequenceStarted`` /
+    ``sequenceFinished`` / ``store_frame_metadata`` and the
+    ``frame_metadatas`` accumulation). Every TIFF-specific method
+    (``__init__`` / ``new_array`` / ``write_frame`` / ``finalize_metadata``) is
+    overridden below to emit video instead, so none of ``OMETiffWriter``'s
+    tifffile machinery is ever reached.
+
+    Two usage modes share the same codec/fourcc/metadata logic:
+
+    - **MDA-driven** (``new_array`` / ``write_frame`` / ``finalize_metadata``)
+      when handed to ``CMMCorePlus.run_mda`` as an output handler.
+    - **Direct** (``begin`` / ``add_frame`` / ``finish``) for cameras that run
+      their own capture loop (e.g. :class:`OpenCVCamera`).
+    """
+
+    def __init__(self, filename: Path | str, fps: int = 30, fourcc: str = "H264") -> None:
+        configure_opencv_codec()
+
+        self._filename = str(filename)
+        if not self._filename.endswith((".mp4", ".avi")):
+            raise ValueError("filename must end with '.mp4' or '.avi'")
+        self._fps = fps
+        self._fourcc = fourcc
+        # FFmpeg expects H.264-in-MP4 with the 'avc1' tag; OpenCV often gets
+        # 'H264' from callers, which triggers a noisy fallback warning.
+        if self._filename.endswith(".mp4") and self._fourcc.upper() == "H264":
+            self._fourcc = "avc1"
+        self._frame_metadata_filename = self._filename + FRAME_MD_FILENAME
+        # Direct-use (non-MDA) capture-loop writer; opened by `begin`.
+        self._direct_writer: Any = None
+
+        # `OMETiffWriter.sequenceStarted` only reorders position_sizes into
+        # ImageJ axis order when `not self._is_ome`; setting it True makes that
+        # override a pass-through to the base `sequenceStarted` (axis order is
+        # irrelevant to video) and avoids an AttributeError.
+        self._is_ome = True
+
+        # Skip `OMETiffWriter.__init__` (it validates a .tif/.tiff filename and
+        # imports tifffile); go straight to the base initializer to set up the
+        # frameReady plumbing state (position_arrays, frame_metadatas, etc.).
+        super(OMETiffWriter, self).__init__()
+
+    def new_array(self, position_key: str, dtype: np.dtype, sizes: dict[str, int]):
+        import cv2
+
+        width = sizes["x"]
+        height = sizes["y"]
+        is_color = sizes.get("c", 1) > 1
+
+        if (seq := self.current_sequence) and seq.sizes.get("p", 1) > 1:
+            fname = self._filename.replace(".mp4", f"_{position_key}.mp4")
+            fname = fname.replace(".avi", f"_{position_key}.avi")
+        else:
+            fname = self._filename
+
+        fourcc = cv2.VideoWriter.fourcc(*self._fourcc)
+        writer = cv2.VideoWriter(fname, fourcc, self._fps, (width, height), isColor=is_color)
+        return writer
+
+    def write_frame(self, ary: Any, index: tuple[int, ...], frame: np.ndarray) -> None:
+        import cv2
+
+        frame_8u = cv2.normalize(frame, None, 0, 255, cv2.NORM_MINMAX).astype(np.uint8)
+        ary.write(frame_8u)
+
+    def finalize_metadata(self) -> None:
+        for writer in self.position_arrays.values():
+            try:
+                writer.release()
+            except Exception:
+                pass
+
+        regular_dict = dict(self.frame_metadatas)
+        json_str = json.dumps(regular_dict, indent=4, cls=CustomJSONEncoder)
+        with open(self._frame_metadata_filename, "w") as file:
+            file.write(json_str)
+
+    # ----- direct (non-MDA) capture-loop interface ----------------------
+    def begin(self, width: int, height: int, is_color: bool = True) -> None:
+        """Open the underlying ``cv2.VideoWriter`` for a self-driven loop."""
+        import cv2
+
+        Path(self._filename).parent.mkdir(parents=True, exist_ok=True)
+        fourcc = cv2.VideoWriter.fourcc(*self._fourcc)
+        writer = cv2.VideoWriter(
+            self._filename, fourcc, float(self._fps), (width, height), isColor=is_color
+        )
+        if not writer.isOpened():
+            raise RuntimeError(
+                f"cv2.VideoWriter failed to open '{self._filename}' "
+                f"(fourcc={self._fourcc}, fps={self._fps})"
+            )
+        self._direct_writer = writer
+
+    def add_frame(self, frame: np.ndarray) -> None:
+        """Write one frame to the direct-mode video (uint8 frames pass through)."""
+        if self._direct_writer is None:
+            raise RuntimeError("CV2Writer.add_frame called before begin()")
+        if frame.dtype != np.uint8:
+            import cv2
+
+            frame = cv2.normalize(frame, None, 0, 255, cv2.NORM_MINMAX).astype(np.uint8)
+        self._direct_writer.write(frame)
+
+    def finish(self, extra_metadata: dict | None = None) -> None:
+        """Release the direct-mode writer and write the metadata sidecar."""
+        if self._direct_writer is not None:
+            try:
+                self._direct_writer.release()
+            except Exception:
+                pass
+            self._direct_writer = None
+
+        payload: dict[str, Any] = {"frame_metadatas": dict(self.frame_metadatas)}
+        if extra_metadata:
+            payload.update(extra_metadata)
+        json_str = json.dumps(payload, indent=4, cls=CustomJSONEncoder)
+        with open(self._frame_metadata_filename, "w") as file:
+            file.write(json_str)
+