codecs#

OpenCV video defaults — the single source of truth for fourcc and the platform-dependent capture backend / pixel format.

Kept deliberately free of heavyweight imports (no pymmcore_plus, cv2 only imported lazily inside functions) so that both the acquisition writer (mesofield.data.writer) / camera (mesofield.devices.cameras) and the config wizard (mesofield.gui.config_builder) can import it without dragging in the acquisition stack. Change a default here and every surface follows.

OpenCV’s FFMPEG VideoWriter needs a fourcc code. The portable choice — the only codec bundled in every opencv-python wheel on Windows, Linux, and macOS with no external library — is MPEG-4 (mp4v in .mp4, MJPG in .avi). H.264 compresses better but needs extra pieces a plain pip install lacks (the Cisco OpenH264 DLL on Windows, libx264 on Linux), so it is opt-in and falls back to the portable codec at runtime.

Selection precedence (see default_fourcc()): explicit caller/config value -> MESOFIELD_FOURCC env var -> portable default for the container.

mesofield.data.codecs.default_cv_backend()[source]#

Platform default capture backend.

Windows uses DSHOW: it’s the most reliable for USB webcams. MSMF (the other Windows option) frequently opens a camera that then delivers no frames.

Return type:: str

mesofield.data.codecs.default_cap_fourcc()[source]#

Platform default capture pixel format — unset (camera default).

Leaving CAP_PROP_FOURCC alone is the safe default: it lets each camera deliver its native format. Forcing a format is opt-in via the per-camera cap_fourcc config key.

History: this briefly defaulted to MJPG on Windows because some USB webcams deliver no frames in their default mode until MJPG is forced. But forcing MJPG on multiple identical cameras makes the DSHOW/MSMF backends bleed their streams together (torn/composite frames under DSHOW, swapped frames under MSMF). So MJPG is now opt-in: set cap_fourcc: MJPG on the specific camera that needs it, rather than imposing it on every capture.

Return type:: str

mesofield.data.codecs.openh264_dll_path()[source]#

Locate an OpenH264 DLL, or None if no usable copy is found.

Return type:: Path | None

mesofield.data.codecs.default_fourcc(filename)[source]#

Codec to use when a caller doesn’t specify one.

Honours MESOFIELD_FOURCC (a global override), else picks the portable codec matching the container extension.

Parameters:: filename (str)
Return type:: str

mesofield.data.codecs.open_video_writer(filename, fourcc, fps, size, is_color)[source]#

Open a cv2.VideoWriter, falling back to a portable codec.

Returns (writer, fourcc_used). If the requested fourcc can’t be opened (e.g. H.264 on a box without the codec), retries once with the portable codec for the container and logs a warning naming the swap. Raises RuntimeError only if even the fallback fails to open.

Parameters:

filename (str)
fourcc (str)
fps (float)
size (tuple[int, int])
is_color (bool)

mesofield.data.codecs.configure_opencv_codec()[source]#

Quiet OpenCV/FFMPEG logging and wire up the OpenH264 DLL if available.

Safe to call repeatedly. Always silences OpenCV/FFMPEG logging. Only touches PATH / OPENH264_LIBRARY / the DLL search path when a usable OpenH264 DLL is actually found (via MESOFIELD_OPENH264_LIBRARY or a dev checkout); otherwise it leaves OpenCV’s own codec resolution untouched.

Return type:: None