abstract
- Python-bioformats is a Python wrapper for Bio-Formats, a standalone Java library for reading and writing life sciences image file formats.
- Because Bio-Formats is a Java library, python-bioformats uses python-javabridge to start and interact with a Java virtual machine.
- Bio-Formats is capable of parsing both pixels and metadata for a large number of formats, as well as writing to several formats.
- Python-bioformats was developed for and is used by the cell image analysis software CellProfiler (cellprofiler.org)
install
# install using pip
pip install python-bioformats
# test
nosetests
# or run by
python nosetests.py
start JVM
# When starting the Java virtual machine with python-javabridge’s javabridge.start_vm(), you must add the contents of bioformats.JARS to the class path.
import javabridge
import bioformats
javabridge.start_vm(class_path=bioformats.JARS)
Initialization and termination
import javabridge
import bioformats
javabridge.start_vm(class_path=bioformats.JARS)
# your program goes here
javabridge.kill_vm()
class bioformats.ImageReader(path=None, url=None, perform_init=True) # Find the appropriate reader for a file
# This class is meant to be harnessed to a scope like this:
with GetImageReader(path) as reader:
....
# It uses __enter__ and __exit__ to manage the random access stream that can be used to cache the file contents in memory.
read(c=None, z=0, t=0, series=None, index=None, rescale=True, wants_max_intensity=False, channel_names=None, XYWH=None) # Read a single plane from the image reader file
# c: read from this channel. None = read color image if multichannel or interleaved RGB.
# z – z-stack index
# t – time index
# series – series for .flex and similar multi-stack formats
# index – if None, fall back to zct, otherwise load the indexed frame
# rescale – True to rescale the intensity scale to 0 and 1; False to return the raw values native to the file.
# wants_max_intensity – if False, only return the image; if True, return a tuple of image and max intensity
# channel_names – provide the channel names for the OME metadata
# XYWH – a (x, y, w, h) tuple
close()
# Convenience functions that create an image reader for a file path or URL and use it to read an image
bioformats.load_image(path, c=None, z=0, t=0, series=None, index=None, rescale=True, wants_max_intensity=False, channel_names=None)
# path – path to the file
# z – the frame index in the z (depth) dimension.
# t – the frame index in the time dimension.
# channel_names – None if you don’t want them, a list which will be filled if you do
# Returns : either a 2-d (grayscale) or 3-d (2-d + 3 RGB planes) image.
bioformats.load_image_url(url, c=None, z=0, t=0, series=None, index=None, rescale=True, wants_max_intensity=False, channel_names=None)
# Cached image readers
bioformats.get_image_reader(key, path=None, url=None) # Make or find an image reader appropriate for the given path
# path - pathname to the reader on disk
# key - use this key to keep only a single cache member associated with that key open at a time
bioformats.release_image_reader(key) # Tell the cache that it should flush the reference for the given key
bioformats.clear_image_reader_cache() # Get rid of any open image readers
# Metadata
bioformats.get_omexml_metadata(path=None, url=None) # Read the OME metadata from a file using Bio-formats
# path – path to the file
# groupfiles – utilize the groupfiles option to take the directory structure into account
# Returns : the metdata as XML.
# The OMEXML class has four main purposes: to parse OME-XML, to output OME-XML,
# to provide a structured mechanism for inspecting OME-XML and to let the caller create and modify OME-XML
class bioformats.OMEXML(xml=None) # Reads and writes OME-XML with methods to get and set it
# There are two ways to invoke the constructor.If you supply XML as a string or unicode string, the constructor will parse it
# and will use it as the base for any inspection and modification. If you don’t supply XML, you’ll get a bland OME-XML object
# which has a one-channel image. You can modify it programatically and get the modified OME-XML back out by calling to_xml.
o = OMEXML()
print o.image().AcquisitionDate # will get you the date that image # 0 was acquired
o.image().Name = "MyImage" # will set the image name to “MyImage”
o.image().Pixels.channel_count = 3
o.image().Pixels.Channel(0).Name = "Red"
o.image().Pixels.Channel(1).Name = "Green"
o.image().Pixels.Channel(2).Name = "Blue"
# Writing images
bioformats.write_image(pathname, pixels, pixel_type, c=0, z=0, t=0, size_c=1, size_z=1, size_t=1, channel_names=None)
# filename – save to this filename
# pixels – the image to save
# pixel_type – save using this pixel type
# c – the image’s channel index
# z – the image’s z index
# t – the image’s t index
# size_c – # of channels in the stack
# size_z – # of z stacks
# size_t – # of timepoints in the stack
# channel_names – names of the channels (make up names if not present).
helpful URL
PyPI record: https://pypi.python.org/pypi/python-bioformats
Documentation: http://pythonhosted.org/python-bioformats/
GitHub repository: https://github.com/CellProfiler/python-bioformats
Report bugs here: https://github.com/CellProfiler/python-bioformats/issues