writer#

OME-TIFF + MP4 writers for MDASequences.

Two MDA output handlers, both plain classes exposing the sequenceStarted / frameReady / sequenceFinished methods CMMCorePlus.run_mda connects by name, and both emitting the <filename>_frame_metadata.json sidecar every downstream mesofield parser (and the AcquisitionManifest metadata_path) reads:

  • OMEWriter – OME-TIFF, backed by the maintained ome-writers library (incremental, flushed, no giant memmap pre-allocation). This replaced a memmap-based writer that accumulated ~9 GB of dirty pages in a 400 s dual-camera run and overflowed MMCore’s circular buffer.

  • CV2Writer – MP4/AVI via cv2.VideoWriter.

Neither depends on pymmcore_plus.mda.handlers (deprecated upstream in favour of ome-writers). NullWriter is a disk-free OMEWriter subclass used only for benchmarking.

class mesofield.data.writer.CustomJSONEncoder[source]#

Bases: JSONEncoder

default(object)[source]#

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)
Parameters:

object (Any)

Return type:

Any

class mesofield.data.writer.OMEWriter[source]#

Bases: object

OME-TIFF writer backed by the maintained ome-writers library.

Drop-in replacement for CustomWriter as an MDA output handler (run_mda(output=...)): it exposes the three signal handlers the runner connects by name (sequenceStarted / frameReady / sequenceFinished) and drives an ome_writers.OMEStream.

Why this exists (measured, not assumed): the memmap-based CustomWriter pre-allocates the full multi-GB OME-TIFF and writes into it via numpy.memmap with no flush, so dirty pages accumulate in RAM (≈9 GB in a 400 s dual-camera run) until flush stalls back up MMCore’s circular buffer and it overflows. ome-writers writes incrementally with real flushing and no giant up-front allocation, and is the path pymmcore-plus is migrating to (pymmcore_plus.mda.handlers is deprecated).

The mesofield contract is preserved: the <filename>_frame_metadata.json sidecar every downstream parser (and the AcquisitionManifest metadata_path) reads is still emitted from finalize_metadata(), built from the same per-frame pymmcore-plus metadata, accumulated here exactly as the deprecated _5DWriterBase did.

__init__(filename)[source]#
Parameters:

filename (Path | str)

Return type:

None

finalize_metadata()[source]#

Write the per-frame metadata sidecar (mesofield’s legacy contract).

Return type:

None

class mesofield.data.writer.NullWriter[source]#

Bases: OMEWriter

Disk-free OMEWriter used only for benchmarking.

Runs the identical MDA drain path (frameReady is still called per frame and metadata still accumulates) but never opens an ome-writers stream and never writes the sidecar, so no bytes hit disk and no dirty pages build up. Comparing a null-writer run against a real run isolates how much backlog/RAM the write path itself contributes.

Enabled via MESOFIELD_NULL_WRITER=1 (see BaseCamera._make_writer); never selected in normal operation.

class mesofield.data.writer.CV2Writer[source]#

Bases: object

Write frames to an mp4/avi video using OpenCV.

Standalone MDA output handler – it exposes the three signal methods the runner connects by name (sequenceStarted / frameReady / sequenceFinished, mirroring OMEWriter) and drives cv2.VideoWriter directly, so it no longer depends on the deprecated pymmcore_plus.mda.handlers.OMETiffWriter.

Two usage modes share the same codec/fourcc/metadata logic:

  • MDA-driven (sequenceStarted / frameReady / sequenceFinished) 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. OpenCVCamera).

Both modes emit the same <filename>_frame_metadata.json sidecar.

__init__(filename, fps=30, fourcc=None)[source]#
Parameters:
Return type:

None

begin(width, height, is_color=True)[source]#

Open the underlying cv2.VideoWriter for a self-driven loop.

Parameters:
Return type:

None

add_frame(frame)[source]#

Write one frame to the direct-mode video (uint8 frames pass through).

Parameters:

frame (ndarray)

Return type:

None

finish(extra_metadata=None)[source]#

Release the direct-mode writer and write the metadata sidecar.

Parameters:

extra_metadata (dict | None)

Return type:

None