Python API¶

Everything the command line does can be called from Python. Path arguments accept strings or pathlib.Path.

from mcd_stitcher import mcd_inspect, mcd_process

info = mcd_inspect("slide.mcd")
print(len(info["regions"]), "regions:", ", ".join(info["channels"]))

mcd_process("slide.mcd", convert=True, stitch=True, pyramid=True)

mcd_process is the one-call pipeline behind the command of the same name, and mcd_inspect reads a file's contents without writing anything. mcd_convert, mcd_stitch and tiff_subset run one step each.

Following progress¶

Pass a progress callback to receive an event per region converted or stitched, and per file post-processed:

def progress(event):
    print(f"{event['stage']}: {event['done']} of {event['total']}  {event['name']}")

mcd_process("slide.mcd", stitch=True, progress=progress)

Raising from the callback stops the run at that point without leaving a half-written file. Raise a BaseException subclass to end the whole call: an ordinary Exception is recorded as that file failing, and the next file is processed.

Reference¶

mcd_process ¶

mcd_process(
    input_path: PathLike,
    output_path: Optional[PathLike] = None,
    convert: bool = False,
    stitch: bool = False,
    panorama: Optional[str] = None,
    metadata: bool = False,
    roi_map: Optional[str] = None,
    filter: Optional[str] = None,
    pyramid: bool = False,
    roi: Optional[str] = None,
    output_type: str = "uint16",
    compression: str = "zstd",
    progress: Optional[Callable[[dict], None]] = None,
) -> int

Unified MCD processing pipeline.

Parameters:

Name	Type	Description	Default
`input_path`	`PathLike`	Path to .mcd file or directory of .mcd files.	required
`output_path`	`Optional[PathLike]`	Optional base output directory.	`None`
`convert`	`bool`	Per-ROI conversion to .ome.tiff.	`False`
`stitch`	`bool`	Stitch selected ROIs into one canvas.	`False`
`panorama`	`Optional[str]`	Export panorama(s). "all" or "1,3-5" index string.	`None`
`metadata`	`bool`	Print metadata summary to stdout.	`False`
`roi_map`	`Optional[str]`	Generate ROI overlay + mapping. "0" or "1,3-5".	`None`
`filter`	`Optional[str]`	Post-process channel subset, e.g. "0-5,7" (requires convert/stitch).	`None`
`pyramid`	`bool`	Post-process to a pyramidal OME-TIFF (requires convert/stitch).	`False`
`roi`	`Optional[str]`	ROI filter. None \| "0,2,5" \| "3,5-6,2".	`None`
`output_type`	`str`	"uint16" or "float32".	`'uint16'`
`compression`	`str`	"zstd" \| "LZW" \| "None".	`'zstd'`
`progress`	`Optional[Callable[[dict], None]]`	Optional callback, called with a dict of `stage`, `done`, `total` and `name` per region converted or stitched and per file post-processed. Raising from it abandons the current file; raise a BaseException subclass to end the whole call.	`None`

Returns:

Type	Description
`int`	Number of .mcd files that failed. Failures are reported and skipped so a
`int`	batch run completes; the CLI exits non-zero when this is greater than 0.

mcd_inspect ¶

mcd_inspect(input_path: PathLike) -> dict

Read one .mcd file's regions, channels and panoramas as plain data. Writes nothing.

Parameters:

Name	Type	Description	Default
`input_path`	`PathLike`	Path to a single .mcd file.	required

Returns:

Type	Description
`dict`	A dict with `path`, `stem`, `channels` (the channel names), `panoramas` (each with
`dict`	`index`, `slide_index`, `panorama_index` and `description`) and `regions`, in the order
`dict`	`-r` indexes them (each with `index`, `description`, `timestamp`, `width`, `height`,
`dict`	`pixel_size`, `num_channels` and `file_stem`, the name its converted OME-TIFF gets).

mcd_convert ¶

mcd_convert(
    input_path: PathLike,
    output_path: Optional[PathLike] = None,
    dtype: str = "uint16",
    compression: str = "zstd",
    out_dir: Optional[PathLike] = None,
    silent: bool = False,
    mcd: Optional[MCDFile] = None,
    rois: Optional[List[dict]] = None,
    workers: Optional[int] = None,
    progress: Optional[Callable[[dict], None]] = None,
) -> int

Per-ROI conversion from MCD to OME-TIFF.

Parameters:

Name	Type	Description	Default
`input_path`	`PathLike`	Path to a single .mcd file.	required
`output_path`	`Optional[PathLike]`	Optional base output directory (used for standalone CLI).	`None`
`dtype`	`str`	"uint16" or "float32".	`'uint16'`
`compression`	`str`	"zstd" \| "LZW" \| "None".	`'zstd'`
`out_dir`	`Optional[PathLike]`	Explicit output directory (used when called from mcd_process).	`None`
`silent`	`bool`	Suppress status prints (used when called from mcd_process).	`False`
`mcd`	`Optional[MCDFile]`	Pre-opened MCDFile (used when called from mcd_process).	`None`
`rois`	`Optional[List[dict]]`	Pre-loaded ROI list (used when called from mcd_process).	`None`
`workers`	`Optional[int]`	Override the automatic ROI concurrency.	`None`
`progress`	`Optional[Callable[[dict], None]]`	Optional callback, called with a dict of `stage`, `done`, `total` and `name` per converted ROI.	`None`

Returns:

Type	Description
`int`	Number of ROIs converted (0 if the MCD has no ROIs).

mcd_stitch ¶

mcd_stitch(
    input_path: PathLike,
    output_path: Optional[PathLike] = None,
    dtype: str = "uint16",
    compression: str = "zstd",
    roi_arg: Optional[str] = None,
    out_dir: Optional[PathLike] = None,
    silent: bool = False,
    mcd: Optional[MCDFile] = None,
    all_rois: Optional[List[dict]] = None,
    selected_rois: Optional[List[dict]] = None,
    convert_out_dir: Optional[PathLike] = None,
    progress: Optional[Callable[[dict], None]] = None,
) -> int

Stitch selected ROIs from MCD into a single stitched canvas OME-TIFF.

Parameters:

Name	Type	Description	Default
`input_path`	`PathLike`	Path to .mcd file.	required
`output_path`	`Optional[PathLike]`	Optional base output path (used for standalone CLI).	`None`
`dtype`	`str`	"uint16" or "float32".	`'uint16'`
`compression`	`str`	"zstd" \| "LZW" \| "None".	`'zstd'`
`roi_arg`	`Optional[str]`	ROI filter. None \| "0,2,5" \| "3,5-6,2".	`None`
`out_dir`	`Optional[PathLike]`	Explicit output directory (used when called from mcd_process).	`None`
`silent`	`bool`	Suppress status prints (used when called from mcd_process).	`False`
`mcd`	`Optional[MCDFile]`	Pre-opened MCDFile (used when called from mcd_process).	`None`
`all_rois`	`Optional[List[dict]]`	Pre-loaded ROI list (used when called from mcd_process). Ascending by acquisition time, as load_rois returns it.	`None`
`selected_rois`	`Optional[List[dict]]`	Pre-filtered ROI list (used when called from mcd_process). A SELECTION only -- its order is ignored, since compositing order is re-derived from acquisition time.	`None`
`convert_out_dir`	`Optional[PathLike]`	If set, also write each ROI's own OME-TIFF here from the SAME read that feeds the canvas. `mcd_process --convert --stitch` used to read every acquisition twice; with this it reads once.	`None`
`progress`	`Optional[Callable[[dict], None]]`	Optional callback, called with a dict of `stage`, `done`, `total` and `name` per ROI placed, on the calling thread. A stitch is otherwise silent for minutes under silent=True, so this is the only way to drive a determinate progress bar.	`None`

Returns:

Type	Description
`int`	Number of ROIs stitched (0 if no ROIs are found or selected).

tiff_subset ¶

tiff_subset(
    input_path: Optional[PathLike] = None,
    output_path: Optional[PathLike] = None,
    output_type: str = "uint16",
    compression: str = "zstd",
    filter: Optional[str] = None,
    pyramid: bool = False,
    list_channels: bool = False,
    out_dir: Optional[PathLike] = None,
    silent: bool = False,
    tiff_files: Optional[List[PathLike]] = None,
    progress: Optional[Callable[[dict], None]] = None,
) -> int

Channel-subset / pyramid generation for OME-TIFFs (dual-mode).

Parameters:

Name	Type	Description	Default
`input_path`	`Optional[PathLike]`	.tiff file or directory of .tiff files (standalone mode).	`None`
`output_path`	`Optional[PathLike]`	Optional base output directory (standalone mode).	`None`
`output_type`	`str`	"uint16" or "float32".	`'uint16'`
`compression`	`str`	"zstd" \| "LZW" \| "None".	`'zstd'`
`filter`	`Optional[str]`	Channel subset string, e.g. "0-5,7" (None keeps all channels).	`None`
`pyramid`	`bool`	Write a pyramidal (tiled) OME-TIFF.	`False`
`list_channels`	`bool`	List channels of a single TIFF, then return (standalone).	`False`
`out_dir`	`Optional[PathLike]`	Explicit output directory (delegated mode).	`None`
`silent`	`bool`	Suppress status prints.	`False`
`tiff_files`	`Optional[List[PathLike]]`	Pre-resolved list of .tiff paths (delegated mode).	`None`
`progress`	`Optional[Callable[[dict], None]]`	Optional callback, called with a dict of `stage`, `done`, `total` and `name` per file in delegated mode.	`None`

Returns:

Type	Description
`int`	Number of files processed.