Export Pipeline¶

Source: dev_note/topic_export_pipeline.md

Context¶

The export pipeline handles batch exports for FOVs, ROIs (including map-mode ROIs), and single-cell crops. It also provides a shared scale bar computation utility.

Key Decisions¶

A job runner abstraction structures exports as per-item jobs with result tracking.
Export rendering is independent of UI widget state — channel_settings are read directly from the marker profile.
Overlay snapshots (masks, annotations) and configurable outline thickness are supported.
Scale bar helpers compute a rounded physical length capped to 10% of image width.

Job Runner¶

Each export run produces a list of JobItem objects. The runner processes them sequentially, writing the output file and recording success/failure per item. Results are displayed in the plugin UI.

Rendering Pipeline¶

_build_roi_items()
    ↓
for each item:
    _export_fov_worker()          ← single-FOV exports
    _export_map_roi_worker()      ← map-mode ROI exports
        ↓
        _render_map_region_direct()
            ↓
            VirtualMapLayer._collect_visible_tiles()
            render_fov_to_array(tile, ..., channel_settings)
            _blit_tile()
    ↓
    _finalise_array()
    _write_image()

Scale Bar¶

Computed in ueler/viewer/scale_bar.py: compute_scale_bar_spec() returns a ScaleBarSpec, and add_scale_bar() draws it onto an axes.
Physical length is rounded to a "nice" value from a 1, 2, 5 engineering sequence and capped to max_fraction of the image width (default 0.1, i.e. 10%).
Shared between the live viewer display and all export paths.
effective_pixel_size_nm() folds the downsample factor into the pixel size, so a decimated render measures correctly.
pixel_size_nm for map-mode exports: base_pixel_size_um × 1000 × downsample.

Map-Mode ROI Export¶

Map-mode ROIs (fov="", map_id non-empty) are routed to _export_map_roi_worker():

Retrieve the VirtualMapLayer via _get_map_layer(map_id).
Convert canvas pixels to physical µm using layer.map_bounds() + base_pixel_size_um().
Call _render_map_region_direct() to render without UI dependency.
Pass through _finalise_array() + _write_image().

NaN Sanitization¶

_ensure_dataframe() sanitizes the fov column: empty CSV cells read back as float('nan') by pandas. Without sanitization, NaN is truthy and _build_roi_items() would route map-mode ROIs to the single-FOV path, producing black output with a filename of nan_....

#1
#78