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:

Imports only the packages actually needed.
Tries the simplest suitable reader first.
Falls back gracefully for unsupported formats.
Prints a compact summary of loaded data.
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