Bioimage IO Loader

Overview

Detect file formats automatically, inspect axes and metadata, and load microscopy images into a predictable Python representation that works well with napari-centered workflows.

Default stack

Prefer this baseline unless the user specifies otherwise:

• numpy
• scipy
• scikit-image
• tifffile
• pandas
• matplotlib
• napari

Add readers only when needed:

• aicsimageio for broad microscopy format support and metadata-heavy workflows
• nd2 or nd2reader for ND2 if simpler readers are sufficient
• czifile or aicsimageio for CZI
• readlif or aicsimageio for LIF
• imageio.v3 or skimage.io for PNG/JPEG fallback

Workflow

1. Inspect before loading fully

Start with a lightweight inspection step.

• Identify whether the input is a file, folder, or glob pattern.
• Infer likely format from extension, but verify with an actual reader when possible.
• Report which reader was chosen and why.
• Inspect shape, dtype, channel count, z/t presence, and available metadata before performing downstream analysis.

Preferred extension mapping:

• .tif, .tiff, .ome.tif, .ome.tiff -> try tifffile first
• .png, .jpg, .jpeg -> imageio.v3 or skimage.io
• .czi, .nd2, .lif -> aicsimageio first when available

2. Normalize the in-memory representation

After loading, always make the representation explicit.

• State the array shape and dtype.
• State the inferred axis order.
• If axes are ambiguous, say so and avoid silently reordering.
• Prefer naming conventions such as YX, ZYX, CYX, CZYX, TYX, TCZYX.
• Keep the original data unchanged; create a normalized view or copy for analysis.

3. Prepare napari-friendly outputs

When napari is available:

• Add image data as a napari image layer with an informative layer name.
• Preserve scale information if metadata provides pixel spacing.
• For multichannel data, expose a clear channel mapping.
• For labels or masks loaded from disk, use napari labels layers.

4. Produce a concise loading report

Unless the user asks for raw code only, include a short report with:

• chosen reader
• detected format
• path(s) loaded
• shape, dtype, inferred axes
• metadata fields that matter for analysis
• caveats such as unknown channel semantics or missing physical pixel size

Default code behavior

Generate code that:

1. Imports only the packages actually needed.
2. Tries the simplest suitable reader first.
3. Falls back gracefully for unsupported formats.
4. Prints a compact summary of loaded data.
5. Returns reusable objects for later steps.

Prefer helper functions like:

load_bioimage(path) -> dict

with keys such as:

• data
• axes
• shape
• dtype
• reader
• metadata
• channel_names
• scale

Format-specific guidance

TIFF / OME-TIFF

Use tifffile first. Check:

• OME metadata availability
• series count
• pyramids / multiscale data
• channel and z/t axes
• physical pixel sizes

PNG / JPEG

Treat as simple 2D or RGB images unless metadata proves otherwise. Note that microscopy-relevant metadata is usually limited.

CZI / ND2 / LIF

Prefer aicsimageio when installed because it often simplifies metadata handling and axis normalization. If it is unavailable, choose a narrower reader and explicitly mention reduced metadata coverage.

Safety and analysis rules

• Never guess biological meaning from channels without saying it is an assumption.
• Never collapse dimensions silently.
• Never overwrite source files.
• When the format cannot be read reliably, stop and explain which dependency is missing.
• When a folder contains mixed formats, summarize what was recognized and process each group separately.

Outputs to prepare for downstream skills

When the user asks for a full analysis setup, prepare these default artifacts unless they opt out:

• a runnable Python script that loads the data
• a notebook starter with inspection cells
• napari-ready layer creation code
• a concise metadata summary

Resources

• references/reader-selection.md: reader decision rules and fallback logic
• references/notebook-template.md: reusable notebook structure for inspection and loading
• scripts/load_bioimage.py: reusable loader helper