Overview

bioio-conversion

Build Status Documentation PyPI version License Python 3.11–3.13

A BioIO conversion tool for going between image formats.

Documentation

See the full documentation on our GitHub Pages site:

https://bioio-devs.github.io/bioio-conversion

Installation

Install from PyPI along with core BioIO and plugins:

pip install bioio-conversion

Python Package Usage

Available Converters

  • OmeZarrConverter

    • Purpose: Convert any BioImage-supported input (TIFF, CZI, ND2, etc.) into an OME-Zarr store.

    • Features:

      • Multi-scene export (scenes=0, list, or None = all)

      • Flexible multiscale pyramid options (level_shapes, num_levels, downsample_z)

      • Chunk-size tuning (chunk_shape, memory_target, shard_shape)

      • Metadata options (channels, axes_names, axes_units, physical_pixel_size)

      • Output format (zarr_format = 2 or 3)

      • Optional auto Dask cluster

    • Import path:

      from bioio_conversion.converters import OmeZarrConverter

  • BatchConverter

    • Purpose: Orchestrate batch conversions of many files (CSV, directory crawl, or explicit list).

    • Features:

      • Factory methods: from_csv(), from_directory(), from_list()

      • Shared default_opts for per-job overrides

      • Dispatch jobs via .run_jobs()

    • Import path:

      from bioio_conversion.converters import BatchConverter

Example: OmeZarrConverter

Minimal usage
from bioio_conversion.converters import OmeZarrConverter

conv = OmeZarrConverter(
    source='image.tiff',
    destination='out_dir'
)
conv.convert()
Advanced usage: full control
from bioio_conversion.converters import OmeZarrConverter
from zarr.codecs import BloscCodec

conv = OmeZarrConverter(
    source='multi_scene.czi',
    destination='zarr_output',
    scenes=None,
    name='experiment1',
    tbatch=2,
    num_levels=3,
    downsample_z=True,
    chunk_shape=(1,1,16,256,256),
    shard_shape=(1,1,128,1024,1024),
    memory_target=32*1024*1024,
    dtype='uint16',
    compressor=BloscCodec(),
    zarr_format=3,
)
conv.convert()
Explicit level_shapes
conv = OmeZarrConverter(
    source="image_tczyx.tif",
    destination="out_tczyx",
    level_shapes=[
        (1, 3, 5, 325, 475),
        (1, 3, 2, 162, 238),
        (1, 3, 1, 81, 119),
    ],
)
conv.convert()
Channel metadata
from bioio_ome_zarr.writers import Channel

channels = [
    Channel(label="DAPI", color="#0000FF", active=True,
            window={"min":100, "max":2000, "start":200, "end":1200}),
    Channel(label="GFP", color="#00FF00", active=True),
    Channel(label="TRITC", color="#FF0000", active=False),
]

conv = OmeZarrConverter(
    source="multi_channel.czi",
    destination="out_channels",
    channels=channels,
)
conv.convert()
Axes & physical pixel sizes
conv = OmeZarrConverter(
    source="custom_axes.tif",
    destination="out_axes",
    axes_names=["t","c","z","y","x"],
    axes_types=["time","channel","space","space","space"],
    axes_units=[None, None, "micrometer","micrometer","micrometer"],
    physical_pixel_size=[1.0, 1.0, 0.4, 0.108, 0.108],
)
conv.convert()
Example with fewer dimensions (3D ZYX)
conv = OmeZarrConverter(
    source="volume_zyx.tif",
    destination="out_zyx",
    num_levels=2,
    downsample_z=True,
)
conv.convert()

CSV-driven batch conversion

The CSV file should have a header row that names the job parameters. At minimum, include a source column (path to each input image). You may also include per-job overrides for any converter option (e.g. destination, scenes, tbatch, num_levels, downsample_z, level_shapes, memory_target, dtype, channel_names, etc.). Values in each row will be merged with the default_opts you passed to BatchConverter.

from bioio_conversion import BatchConverter

bc = BatchConverter(
    converter_key='ome-zarr',
    default_opts={
        'destination': 'batch_out',
        'tbatch': 4,
    }
)
jobs = bc.from_csv('jobs.csv')  # parse CSV into job dicts
bc.run_jobs(jobs)

Directory-driven batch conversion

from bioio_conversion import BatchConverter

bc = BatchConverter(default_opts={
    'destination': 'dir_out',
})
jobs = bc.from_directory(
    '/data/images',
    max_depth=2,
    pattern='*.tif'
)
bc.run_jobs(jobs)

List-driven batch conversion

from bioio_conversion import BatchConverter

paths = ['/data/a.czi', '/data/b.czi', '/data/c.zarr']
bc = BatchConverter(default_opts={
    'destination': 'list_out',
    'scenes': 0
})
jobs = bc.from_list(paths)
bc.run_jobs(jobs)

Command-Line Interface: bioio-convert

Single-file converter using the configured backend (default: OME-Zarr).

bioio-convert SOURCE -d DESTINATION [options]

Key options:

  • source (positional): input image path

  • -d, --destination: output directory for .ome.zarr

  • -n, --name: base name (defaults to source stem)

  • -s, --scenes: scene(s) to export (0 by default; comma-separated list; None = all scenes)

  • --tbatch: timepoints per write batch (default: 1)

  • --start-t-src: source T index to begin reading (default: 0)

  • --start-t-dest: destination T index to begin writing (default: 0)

Multiscale:

  • --level-shapes: semicolon-separated absolute shapes (level 0 first)

  • --num-levels: number of pyramid levels (including level 0)

  • --downsample-z: include Z in half-pyramid downsampling

Chunking / shards:

  • --chunk-shape: explicit chunk shape (e.g. 1,1,16,256,256)

  • --chunk-shape-per-level: semicolon-separated chunk shapes per level

  • --memory-target: bytes per chunk (default: 16 MB)

  • --shard-shape: shard shape (Zarr v3 only)

  • --shard-shape-per-level: per-level shard shapes (Zarr v3 only)

Writer / metadata:

  • --dtype: output dtype override (e.g. uint16; default: reader’s dtype)

  • --physical-pixel-sizes: comma-separated floats (per axis, level-0)

  • --zarr-format: 2 (NGFF 0.4) or 3 (NGFF 0.5); default: writer decides

Channels:

  • --channel-labels: comma-separated channel names

  • --channel-colors: comma-separated colors (hex or CSS names)

  • --channel-actives: channel visibility flags (true,false,...)

  • --channel-coefficients: per-channel coefficient floats

  • --channel-families: intensity family names (linear,sRGB,...)

  • --channel-inverted: channel inversion flags

  • --channel-window-min/max/start/end: per-channel windowing values

Examples

Basic usage
bioio-convert image.tif -d out_dir
Custom name
bioio-convert sample.czi -d out_dir -n my_run
Export all scenes
bioio-convert multi_scene.ome.tiff -d zarr_out
Export specific scenes
bioio-convert multi_scene.ome.tiff -d zarr_out -s 0,2
Simple half-pyramid (XY only)
bioio-convert volume.tif -d out_xy --num-levels 3
Simple half-pyramid (XYZ)
bioio-convert volume_tczyx.tif -d out_xyz --num-levels 3 --downsample-z
Explicit level shapes
bioio-convert image.tif -d out_explicit \
  --level-shapes "1,3,5,325,475;1,3,2,162,238;1,3,1,81,119"
Dtype and chunking
bioio-convert image.tif -d out_dir --dtype uint16 --memory-target 33554432
Custom channels
bioio-convert image_with_channels.czi -d out_dir \
  --channel-labels DAPI,GFP,TRITC \
  --channel-colors "#0000FF,#00FF00,#FF0000" \
  --channel-actives true,true,false
Physical pixel sizes
bioio-convert image.tif -d out_dir --physical-pixel-sizes 1.0,1.0,0.4,0.108,0.108

Command-Line Interface: bioio-batch-convert

Batch mode: convert many files via CSV, directory walk, or explicit list.

bioio-batch-convert --mode [csv|dir|list] [options]

Examples

CSV mode
bioio-batch-convert \
  --mode csv \
  --csv-file jobs.csv \
  --destination batch_out \
  --tbatch 4 \
  --dtype uint16 \
  --num-levels 3
Directory mode
bioio-batch-convert \
  --mode dir \
  --directory data/ \
  --depth 2 \
  --pattern '*.czi' \
  --destination output_zarr \
  --level-shapes "1,3,5,325,475;1,3,2,162,238;1,3,1,81,119"
List mode
bioio-batch-convert \
  --mode list \
  --paths a.czi b.czi c.tiff \
  --destination list_out \
  --name batch_run \
  --num-levels 2 --downsample-z

License & Issues

BSD 3-Clause https://bioio-devs.github.io/bioio-conversion/LICENSE

Report bugs at: https://github.com/bioio-devs/bioio-conversion/issues