BioFormats

Bio-Formats wrapper utilities.

io.BioFormats.bfopen3(r, seriesNumber, sliceNo, options)

BFOPEN3 - Open microscopy images in MATLAB using Bio-Formats.

Syntax:
result = io.BioFormats.bfopen3(r, seriesNumber)
result = io.BioFormats.bfopen3(r, seriesNumber, sliceNo, options)

Modified from the original bfopen.m by Ilya Belevich. Returns the selected dataset from a Bio-Formats reader.

Input Arguments:

  • r - handle to a dataset opened with:

    r = loci.formats.ChannelFiller();
r = loci.formats.ChannelSeparator(r);
r = loci.formats.gui.BufferedImageReader(r);
r.setId(handles.filename);

  • seriesNumber - series number to load, starting from 1

  • sliceNo - (optional) desired slice number from the series

  • options - (optional) struct with fields (not yet fully tested):

    • .x1 - starting x position

    • .y1 - starting y position

    • .dx - width

    • .dy - height

Output Arguments:

  • result - struct with the selected series:

    • .img - image array [height, width, color, depth]

    • .ColorType - 'grayscale', 'truecolor', or 'indexed'

    • .ColorMap - colormap for indexed images

Note

This method is ~1.5×-2.5× slower than Bio-Formats’s command line showinf tool, due to overhead from copying arrays.

Internet Explorer sometimes erroneously renames the Bio-Formats library to loci_tools.zip - if this happens, rename it back to loci_tools.jar.

Thanks to all who offered suggestions and improvements:

  • Ville Rantanen

  • Brett Shoelson

  • Martin Offterdinger

  • Tony Collins

  • Cris Luengo

  • Arnon Lieber

  • Jimmy Fong

NB: Internet Explorer sometimes erroneously renames the Bio-Formats library

to loci_tools.zip. If this happens, rename it back to loci_tools.jar.

Updates:

  • 05.09.2013 Ilya Belevich, added sliceNo to load only a single slice

io.BioFormats.bfopen5(r, seriesNumber, sliceNo, options)

BFOPEN5 - Open microscopy images in MATLAB using Bio-Formats with Memoizer support.

Syntax:
result = io.BioFormats.bfopen5(r, seriesNumber)
result = io.BioFormats.bfopen5(r, seriesNumber, sliceNo, options)

Modified from the original bfopen.m by Ilya Belevich. Returns the selected dataset from a Bio-Formats Memoizer reader.

Input Arguments:

  • r - handle to a Memoizer opened as:

    r = loci.formats.Memoizer(bfGetReader(), 0);
r.setId(filename);
r.close();   % optionally

    When the Memoizer class is used, r won’t be closed at the end of the function. Alternatively, pass a filename string to use with setId.

  • seriesNumber - series number to load, starting from 1

  • sliceNo - (optional) desired slice number from the series

  • options - (optional) struct with fields:

    • .bioFormatsMemoizerMemoDir - directory to store Memoizer memo files

    • .dimensionOrder - (char) output order of dimensions:

      • 'XYZCT' - default

      • 'XYCZT'

      • 'XYTZC'

      • 'XYZTC'

    • .x1 - starting x position

    • .y1 - starting y position

    • .z1 - starting z position

    • .dx - width

    • .dy - height

    • .dz - depth

    • .waitbarHandle - (optional) handle to an existing waitbar; [] if none

    • .waitbarUpdateFrequency - (optional) frequency to update the waitbar

Output Arguments:

  • result - struct with the selected series:

    • .img - image array [height, width, depth, color, time]; dims re-projected per options.dimensionOrder

    • .ColorType - 'grayscale', 'multichannel', or 'indexed'

    • .ColorMap - colormap for indexed images

Note

Portions of this code were adapted from: http://www.mathworks.com/support/solutions/en/data/1-2WPAYR/

This method is ~1.5×-2.5× slower than Bio-Formats’s command line showinf tool, due to overhead from copying arrays.

Internet Explorer sometimes erroneously renames the Bio-Formats library to loci_tools.zip - if this happens, rename it back to loci_tools.jar.

Thanks to all who offered suggestions and improvements:

  • Ville Rantanen

  • Brett Shoelson

  • Martin Offterdinger

  • Tony Collins

  • Cris Luengo

  • Arnon Lieber

  • Jimmy Fong

NB: Internet Explorer sometimes erroneously renames the Bio-Formats library

to loci_tools.zip. If this happens, rename it back to loci_tools.jar.

Updates:

  • 30.01.2019 Ilya Belevich, adaptation for use with Memoizer

  • 13.12.2023 Ilya Belevich, added cancel upon waitbar cancel click

  • 07.01.2026 Ilya Belevich, switched to [Y X Z C T] outputs, renamed .ColorType truecolor->multichannel

class io.BioFormats.Config

Bases: handle

CONFIG - process-wide selection of the active BioFormats / WSI reader backend.

Mirrors io.zarr.Config for the image-reading side. Holds one module-level setting shared by the io.BioFormats facade (io.BioFormats.Reader):

  • library - which engine reads microscopy / whole-slide image files:

    • 'mib' (default) - MIB’s bundled OME Bio-Formats Java reader (bfGetReader / bfGetPlane / loci.formats.Memoizer). Broadest coverage validated inside MIB; the historical path.

    • 'matlab' - MATLAB’s built-in WSI file readers (bioformatsinfo / bioformatsread and, for classic WSI formats, openslideinfo / openslideread), which return lazy, tiled, pyramid-aware blockedImage objects. No Java dependency.

Benchmark (2026-06-17, 50-series CZI): the two engines are a tie for a full read (~2.5 s, pixel-identical), so the choice is about coverage / robustness / dependencies, not speed.

models.MibModel.initializePreferences pushes this from preferences.IO.BioFormats.Library at start-up; the Preferences dialog calls setLibrary again whenever the user changes it (takes effect immediately).

Examples

io.BioFormats.Config.setLibrary('matlab');   % use bioformatsread/openslideread
tf  = io.BioFormats.Config.isMatlab();        % true
lib = io.BioFormats.Config.library();         % 'matlab'
io.BioFormats.Config.setLibrary('mib');       % back to the Java reader

See also: io.zarr.Config, io.BioFormats.Reader

Method Summary
static isMatlab()

ISMATLAB - true when the MATLAB built-in WSI backend is active.

static library(name)

LIBRARY - get (no args) or set (with a name) the active backend. Returns the canonical name 'mib' or 'matlab'.

static memoDir(dirPath)

MEMODIR - get (no args) or set (with a path) the Bio-Formats Memoizer directory used by the 'mib' backend (where .bfmemo reader caches are written). Default fullfile(tempdir, 'mibVirtual'); models.MibModel.initializePreferences overrides it from preferences.ExternalDirs.BioFormatsMemoizerMemoDir at start-up.

static normalizeName(name)

NORMALIZENAME - map a string to a canonical backend name WITHOUT changing the process-wide setting (unlike library(name)).

static setLibrary(name)

SETLIBRARY - set the active backend (‘mib’|’matlab’, aliases accepted).

static setMemoDir(dirPath)

SETMEMODIR - set the Bio-Formats Memoizer directory (mib backend).

io.BioFormats.mibImage2ometiff(filename, imageS, options)

MIBIMAGE2OMETIFF - Save image in OME.TIF format - either as a single 5D file or a 2D sequence.

Syntax:
[result, options] = io.BioFormats.mibImage2ometiff(filename, imageS)
[result, options] = io.BioFormats.mibImage2ometiff(filename, imageS, options)
Input Arguments:

  • filename - full path for the output file (extension forced to .ome.tiff)

  • imageS - dataset [height, width, color_channels, z_slices, time]

  • options - (optional) struct with fields:

    • .pixSize - MIB pixel-size struct with fields .x, .y, .z, .t, .units, .tunits; default: all 1, units 'um', tunits 's'

    • .lutColors - [C×3] LUT colour matrix (unused in 2D imwrite path)

    • .ImageDescription - (char or cell-string) description embedded in the file (default: '')

    • .DatasetType - 'image' (default) or 'model'

    • .Saving3d - '5D' (default): write all slices into one OME-TIFF via bfsave; '2D': write each z-slice as a separate .tif file

    • .overwrite - 1 = skip the “file exists” prompt (default: 0)

    • .Compression - 'none' (default), 'lzw', or 'packbits' (2D path only)

    • .showWaitbar - 1 = show progress bar (default); 0 = suppress

    • .ParentFigure - handle to the MIB UIFigure; when provided the progress bar is shown as a uiprogressdlg attached to that window; when absent the legacy waitbar is used

    • .silent - [logical] (default: false); when true all interactive dialogs are suppressed

    • .sequentialFn - controls 2D output naming:

      • true (default when NaN) - sequential names, e.g. image_01.ome.tiff

      • false - use original per-slice names from .SliceName; falls back to sequential when .SliceName is absent or empty

      • NaN - decide at runtime (currently defaults to true); normally set by the calling saver (OmeTiffSaver) based on the user’s dialog choice

    • .SliceName - cell array of per-slice source filenames (without path); used by the false branch of .sequentialFn

    • .cmap - colormap matrix for indexed images; NaN (default) means grayscale/RGB

    • .Resolution - [xDPI yDPI] written into 2D .tif files; derived automatically from pixSize when absent

    • .DimensionOrder - dimension order string passed to bfsave / createMinimalOMEXMLMetadata; default: 'XYZCT'

Output Arguments:

  • result - 1 = success, 0 = failure

  • options - the options struct as used (with all defaults filled in)

class io.BioFormats.Reader

Bases: handle

READER - backend-agnostic, on-demand region reader for microscopy / WSI files.

Facade over the BioFormats / WSI engine selected by io.BioFormats.Config ('mib' = bundled OME Bio-Formats Java reader, 'matlab' = MATLAB built-in bioformatsread / openslideread). It exposes a small, reader-agnostic contract designed to match io.loaders.Zarr3VirtualLoader so that - in a later phase - the BigData image read seam (MibVirtualImage.getDataZarr → loaders{1}.readRegion(...)) can be backed by a WSI file directly, giving the same on-demand, level-aware read experience as a zarr3 dataset.

Contract

  • s = info() - dimensions, class, and resolution-level metadata.

  • block = readRegion(level, Ylim, Xlim, Zlim, Clim, Tlim, dataClass) - read a sub-region at a 1-based resolution level; returns MIB3-order [y, x, z, c, t].

  • close() - release the underlying handle.

Phase A (2026-06-17): only the 'mib' (Java) backend is implemented, and only full resolution (level == 1); nothing in the app calls this class yet (no behaviour change). True pyramid-level reads (setResolution) and the 'matlab' backend land in later phases (see development/bigdata/bigdata_implementation_plan.md).

Examples

r = io.BioFormats.Reader('C:\data\slide.czi', 0);   % series 0
s = r.info();                                        % dims + levels
blk = r.readRegion(1, [1 512], [1 512], [1 1], [1 s.colors], [1 1], s.imgClass);
r.close();

See also: io.BioFormats.Config, io.loaders.Zarr3VirtualLoader, io.loaders.BioFormatsVirtualLoader

Constructor Summary
Reader(filename, seriesIndex, options)

READER - construct an on-demand reader; backend from io.BioFormats.Config.

Input Arguments:

  • filename - [char] full path to the file

  • seriesIndex - (optional) [double] 0-based series index (default 0)

  • options - (optional) struct:

    • .library - [char] override the backend: 'mib' (Java), 'matlab' (bioformatsread), or 'openslide' (openslideread). When omitted, the BioFormats engine comes from io.BioFormats.Config ('mib'``|’matlab’); ``'openslide' must be requested explicitly.

    • .memoDir - [char] Bio-Formats Memoizer directory (mib backend)

Property Summary
filename
library

[double] 0-based series index.

memoDir

[char] resolved backend (‘mib’ | ‘matlab’) at construction.

seriesIndex

[char] full path to the microscopy / WSI file.

Method Summary
close()

CLOSE - release the underlying handle. Safe to call repeatedly.

delete()

DELETE - destructor; closes the reader.

info()

INFO - return dimensions + resolution-level metadata.

Output Arguments:

  • s - struct with fields:

    • .height .width .depth .colors .time

    • .imgClass - [char] e.g. 'uint8' / 'uint16'

    • .numLevels - number of resolution (pyramid) levels

    • .levelSizes - [numLevels x 2] per-level [height width]

pyramidStruct(voxelSize)

PYRAMIDSTRUCT - build the MIB pyramid metadata struct for this image.

Returns the fields core.MibVirtualImage / MibBigDataImage need so the existing pyramidal read path (getDataZarr / future getDataPyramid) can drive this WSI reader exactly like a zarr3 dataset (level selection by magnification + level-local region reads).

Input Arguments:

  • voxelSize - (optional) [1x3] full-resolution [y x z] voxel size (µm); default [1 1 1].

Output Arguments:

  • pyramid - struct with fields:

    • .sourceType - 'bioformats' (used by the read dispatch)

    • .levelNames - {1 x nLevels} '0'..'N-1' (resolution keys)

    • .levelImageSizes - [nLevels x 3] per-level [Y X Z]

    • .levelScaleFactors - [nLevels x 3] level0 ./ levelN [y x z]

    • .levelVoxelSizes - [1 x 3] full-resolution [y x z] voxel size

    • .axisOrder - '' (the reader returns native MIB3 [y x z c t])

    • .chunkSizes / .shardSizes - []

readRegion(level, Ylim, Xlim, Zlim, Clim, Tlim, dataClass)

READREGION - read a sub-region; returns MIB3-order [y, x, z, c, t].

Input Arguments:

  • level - [double] 1-based resolution level (1 = full resolution)

  • Ylim, Xlim, Zlim - [1x2] inclusive 1-based LEVEL-LOCAL ranges

  • Clim - [1x2] inclusive 1-based colour-channel range

  • Tlim - [1x2] inclusive 1-based time range

  • dataClass - [char] output class

io.BioFormats.wavelength2rgb(wavelength)

WAVELENGTH2RGB - Convert wavelength into RGB value (0-255).

Syntax:
rgb = io.BioFormats.wavelength2rgb(wavelength)

The code is adapted from http://www.efg2.com/Lab/ScienceAndEngineering/Spectra.htm

Input Arguments:

  • wavelength - a number containing wavelength

Output Arguments:

  • rgb - an array containing, (red, green, blue) components of the color, range 0-255