oiffile¶

Read Olympus image files (OIF and OIB).

Oiffile is a Python library to read image and metadata from Olympus Image Format files. OIF is the native file format of the Olympus FluoView(tm) software for confocal microscopy.

There are two variants of the format:

OIF (Olympus Image File) is a multi-file format that includes a main setting file (.oif) and an associated directory with data and setting files (.tif, .bmp, .txt, .pty, .roi, and .lut).
OIB (Olympus Image Binary) is a compound document file, storing OIF and associated files within a single file.

Author:: Christoph Gohlke
License:: BSD-3-Clause
Version:: 2026.2.8
DOI:: 10.5281/zenodo.17905223

Quickstart¶

Install the oiffile package and all dependencies from the Python Package Index:

python -m pip install -U "oiffile[all]"

View image and metadata stored in an OIF or OIB file:

python -m oiffile file.oif

See Examples for using the programming interface.

Source code and support are available on GitHub.

Requirements¶

This revision was tested with the following requirements and dependencies (other versions may work):

CPython 3.11.9, 3.12.10, 3.13.12, 3.14.3 64-bit
NumPy 2.4.2
Tifffile 2026.1.28

Revisions¶

2026.2.8

Fix code review issues.

2026.1.8

Improve code quality.

2025.12.12

Derive OifFileError from ValueError.
Drop support for Python 3.10.

2025.5.10

Remove doctest command line option.
Support Python 3.14.

2025.1.1

Improve type hints.
Drop support for Python 3.9, support Python 3.13.

2024.5.24

…

Refer to the CHANGES file for older revisions.

Notes¶

No specification document is available.

Tested only with files produced on Olympus FV1000 hardware.

Examples¶

Read the image from an OIB file as numpy array:

>>> image = imread('test.oib')
>>> image.shape
(3, 256, 256)
>>> image[:, 95, 216]
array([820,  50, 436], dtype=uint16)

Read the image from a single TIFF file in an OIB file:

>>> from tifffile import natural_sorted
>>> with OifFile('test.oib') as oib:
...     filename = natural_sorted(oib.glob('*.tif'))[0]
...     image = oib.asarray(filename)
...
>>> filename
'Storage00001/s_C001.tif'
>>> print(image[95, 216])
820

Access metadata and the OIB main file:

>>> with OifFile('test.oib') as oib:
...     oib.axes
...     oib.shape
...     oib.dtype
...     dataname = oib.mainfile['File Info']['DataName']
...
'CYX'
(3, 256, 256)
dtype('uint16')
>>> dataname
'Cell 1 mitoEGFP.oib'

Extract the OIB file content to an OIF file and associated data directory:

>>> import tempfile
>>> tempdir = tempfile.mkdtemp()
>>> oib2oif('test.oib', location=tempdir)
Saving ... done.

Read the image from the extracted OIF file:

>>> image = imread(f'{tempdir}/{dataname[:-4]}.oif')
>>> image[:, 95, 216]
array([820,  50, 436], dtype=uint16)

Read OLE compound file and access the ‘OibInfo.txt’ settings file:

>>> with CompoundFile('test.oib') as com:
...     info = com.open_file('OibInfo.txt')
...     len(com.files())
...
14
>>> info = SettingsFile(info, 'OibInfo.txt')
>>> info['OibSaveInfo']['Version']
'2.0.0.0'

License¶

Copyright (c) 2012-2026, Christoph Gohlke
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

oiffile module¶

oiffile.__version__ = '2026.2.8'¶: Oiffile version string.

class oiffile.CompoundFile(filename, /)¶

Bases: object

Compound Document File.

A partial implementation of the “[MS-CFB] - v20120705, Compound File Binary File Format” specification by Microsoft Corporation.

This should be able to read Olympus OIB and Zeiss ZVI files.

Parameters:: filename (str | os.PathLike[Any]) – Path to compound document file.

__init__(filename, /)¶

Parameters:: filename (str | os.PathLike[Any])
Return type:: None

files()¶

Return sequence of file names.

Return type:: Iterable[str]

direntry(filename, /)¶

Return DirectoryEntry of filename.

Parameters:: filename (str) – Name of file.
Return type:: DirectoryEntry

open_file(filename, /)¶

Return stream as file like object.

Parameters:: filename (str) – Name of file to open.
Return type:: BytesIO

format_tree()¶

Return formatted string with list of all files.

Return type:: str

close()¶

Close file handle.

Return type:: None

__repr__()¶

Return repr(self).

Return type:: str

__str__()¶

Return str(self).

Return type:: str

__weakref__¶: list of weak references to the object

class oiffile.FileSystemAbc¶

Bases: object

Abstract base class for OIF and OIB file systems.

filename: str¶: Name of OIB or OIF file.

name: str¶: Name from settings file.

version: str¶: Version from settings file.

mainfile: str¶: Name of main settings file.

settings: SettingsFile¶: Main settings.

abstractmethod open_file(filename, /)¶

Return file object from path name.

Parameters:: filename (str) – Name of file to open.
Return type:: BinaryIO

abstractmethod files()¶

Return iterator over unsorted files in FileSystem.

Return type:: Iterator[str]

abstractmethod close()¶

Close file handle.

Return type:: None

__repr__()¶

Return repr(self).

Return type:: str

__weakref__¶: list of weak references to the object

class oiffile.OibFileSystem(filename, /)¶

Bases: FileSystemAbc

Olympus Image Binary file system.

Parameters:: filename (str) – Name of OIB file.

filename: str¶: Name of OIB or OIF file.

__init__(filename, /)¶

Parameters:: filename (str | os.PathLike[Any])
Return type:: None

name: str¶: Name from settings file.

version: str¶: Version from settings file.

mainfile: str¶: Name of main settings file.

settings: SettingsFile¶: Main settings.

open_file(filename, /)¶

Return file object from case sensitive path name.

Parameters:: filename (str) – Name of file to open.
Return type:: BinaryIO

files()¶

Return iterator over unsorted files in OIB.

Return type:: Iterator[str]

saveas_oif(location='', *, verbose=0)¶

Save all streams in OIB file as separate files.

Raise FileExistsError if target files or directories already exist.

The main .oif file name and storage names are determined from the OibInfo.txt settings.

Parameters:

location (str) – Directory, where files are written.
verbose (int) – Level of printed status messages (0: none, 1: dots, >1: paths).

Return type:

None

close()¶

Close file handle.

Return type:: None

__str__()¶

Return str(self).

Return type:: str

class oiffile.OifFile(filename, /)¶

Bases: object

Olympus Image File.

Parameters:: filename (str) – Path to OIB or OIF file.

filename: str¶: Name of OIB or OIF file.

__init__(filename, /)¶

Parameters:: filename (str | os.PathLike[Any])
Return type:: None

filesystem: FileSystemAbc¶: Underlying file system instance.

mainfile: SettingsFile¶: Main settings.

open_file(filename, /)¶

Return open file object from path name.

Parameters:: filename (str) – Name of file to open.
Return type:: BinaryIO

glob(pattern='*', /)¶

Return iterator over unsorted file names matching pattern.

Parameters:: pattern (str) – File glob pattern.
Return type:: Iterator[str]

property is_oib: bool¶: File has OIB format.

property axes: str¶

Character codes for dimensions in image array according to mainfile.

This might differ from the axes order of series.

property shape: tuple[int, ...]¶

Shape of image data according to mainfile.

This might differ from the shape of series.

property dtype: numpy.dtype[Any]¶

Type of image data according to mainfile.

This might differ from the dtype of series.

property series: tuple[TiffSequence, ...]¶: Sequence of series of TIFF files with matching names.

asarray(series=0, **kwargs)¶

Return image data from TIFF file(s) as numpy array.

Parameters:

series (int | str) – Specifies which series to return as array.
kwargs (Any) – Additional parameters passed to TiffFile.asarray() or TiffSequence.asarray().

Return type:

NDArray[Any]

close()¶

Close file handle.

Return type:: None

__repr__()¶

Return repr(self).

Return type:: str

__str__()¶

Return str(self).

Return type:: str

__weakref__¶: list of weak references to the object

class oiffile.OifFileError¶

Bases: ValueError

Exception to raise issues with OIF or OIB structure.

__weakref__¶: list of weak references to the object

class oiffile.OifFileSystem(filename, /, storage_ext='.files')¶

Bases: FileSystemAbc

Olympus Image File file system.

Parameters:

filename (str) – Name of OIF file.
storage_ext (str) – Name extension of storage directory.

filename: str¶: Name of OIB or OIF file.

name: str¶: Name from settings file.

version: str¶: Version from settings file.

mainfile: str¶: Name of main settings file.

settings: SettingsFile¶: Main settings.

__init__(filename, /, storage_ext='.files')¶

Parameters:

filename (str | os.PathLike[Any])
storage_ext (str)

Return type:

None

open_file(filename, /)¶

Return file object from path name.

The returned file object must be closed by the user.

Parameters:: filename (str) – Name of file to open.
Return type:: BinaryIO

files()¶

Return iterator over unsorted files in OIF.

Return type:: Iterator[str]

close()¶

Close file handle.

Return type:: None

__str__()¶

Return str(self).

Return type:: str

class oiffile.SettingsFile(file, /, name=None)¶

Bases: dict

Olympus settings file (oif, txt, pty, roi, lut).

Settings files contain little endian UTF-16 or UTF-8 encoded strings, except for [ColorLUTData] sections, which contain uint8 binary arrays.

Settings can be accessed as a nested dictionary {section: {key: value}}, except for {‘ColorLUTData’: numpy array}.

Parameters:

file (str | os.PathLike[Any] | IO[bytes]) – Name of file or open file containing UTF-16 or UTF-8 string. File objects are closed.
name (str) – Human readable label of stream.

name: str¶: Name of settings.

__init__(file, /, name=None)¶

Parameters:

file (str | os.PathLike[Any] | IO[bytes])
name (str | None)

Return type:

None

__repr__()¶

Return repr(self).

Return type:: str

__str__()¶

Return str(self).

Return type:: str

__weakref__¶: list of weak references to the object

oiffile.filetime(ft, /)¶

Return Python datetime from Microsoft FILETIME number.

Return None if ft is 0 or cannot be converted.

Parameters:: ft (int) – Microsoft FILETIME number.
Return type:: datetime | None

oiffile.imread(filename, /, **kwargs)¶

Return image data from OIF or OIB file.

Parameters:

filename (str | os.PathLike[Any]) – Path to OIB or OIF file.
**kwargs (Any) – Additional arguments passed to OifFile.asarray().

Return type:

NDArray[Any]

oiffile.oib2oif(filename, /, location='', *, verbose=1)¶

Convert OIB file to OIF.

Parameters:

filename (str | os.PathLike[Any]) – Name of OIB file to convert.
location (str) – Directory, where files are written.
verbose (int) – Level of printed status messages.

Return type:

None

oiffile¶

Quickstart¶

Requirements¶

Revisions¶

Notes¶

Examples¶

License¶

oiffile module¶

Documentation

Table of Contents

Related Topics