About

pyometiff is a Python library for reading and writing OME-TIFF files that are compliant with the OME-XML specifications.

pyometiff tries to cover most of the tags in the latest OMEXML format specification, while most of the available Python conversion tools are often missing key tags like PhysicalSizeXUnit which are fundamental in any microscopy environment.

Installation

Run the following to install:

pip install pyometiff

Usage

pyometiff exposes two main classes: OMETIFFReader and OMETIFFWriter which you can use to read and write OME TIFF files.

To open a OME-TIFF image you can create an OMETIFFReaderobject and call its .read() method.

import pathlib
from pyometiff import OMETIFFReader
img_fpath = pathlib.Path("/path/to/img.ome.tiff")

reader = OMETIFFReader(fpath=img_fpath)

img_array, metadata, xml_metadata = reader.read()

similarly, to write an OME-TIFF file, we use the OMETIFFWriter class and its .write() method as in the example.

import pathlib
import numpy as np
from pyometiff import OMETIFFWriter
output_fpath = pathlib.Path.cwd().joinpath("test_out.ome.tiff")

# a template metadata dict is available at OMETIFFReader._get_metadata_template()

metadata_dict = {
    "PhysicalSizeX" : "0.88",
    "PhysicalSizeXUnit" : "µm",
    "PhysicalSizeY" : "0.88",
    "PhysicalSizeYUnit" : "µm",
    "PhysicalSizeZ" : "3.3",
    "PhysicalSizeZUnit" : "µm",
    "Channels" : {
        "405" : {
            "Name" : "405nm",
            "SamplesPerPixel": 1,
            "ExcitationWavelength": 405.,
            "ExcitationWavelengthUnit": "nm"
        },
        "488" : {
            "Name" : "488nm",
            "SamplesPerPixel": 1,
            "ExcitationWavelength": 488.,
            "ExcitationWavelengthUnit": "nm"
        },
        "638" : {
            "Name" : "638nm",
            "SamplesPerPixel": 1,
            "ExcitationWavelength": 638.,
            "ExcitationWavelengthUnit": "nm"
        },
    }
}

# our data in npy format
npy_array_data = np.random.randint(0, 255, (2, 10, 3, 512, 512), dtype=np.uint8)
# a string describing the dimension ordering
dimension_order = "ZTCYX"

writer = OMETIFFWriter(
    fpath=output_fpath,
    dimension_order=dimension_order,
    array=npy_array_data,
    metadata=metadata_dict,
    explicit_tiffdata=False)

writer.write()

Licensing

pyometiff is distributed under the GNU General Public License v3.0 (GNU GPLv3),

see the LICENSE file for more info.

This implementation is partially based on aicsimageio by the Allen Institute for Cell Science and python-bioformats by the Broad Institute, part of the CellProfiler project.

The relative licensing and copyright notices are included in the LICENSE file.

External Resources

Cite

Zenodo DOI: 10.5281/zenodo.7520378

@software{filippo_castelli_2024_10612149,
  author       = {Filippo Castelli and
                  Giacomo Mazzamuto},
  title        = {filippocastelli/pyometiff: 1.0.0},
  month        = feb,
  year         = 2024,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.10612149},
  url          = {https://doi.org/10.5281/zenodo.10612149}
}

Contacts

Author:

Filippo Maria Castelli, PhD

filippocastelli42@gmail.com

[formerly] LENS, European Laboratory for Non-linear Spectroscopy

Pyometiff

Install / Use

README