bffile
Modern Bio-Formats wrapper for python
Documentation 📖
https://imaging-formats.github.io/bffile/
Installation
pip install bffile
Usage
Quick Start
from bffile import BioFile
import numpy as np
with BioFile("tests/data/ND2_dims_p4z5t3c2y32x32.nd2") as bf:
# Access OME metadata
print(bf.ome_metadata) # ome_types.OME object
# Get lazy array for series 0 (no data loaded yet)
arr = bf.as_array(series=0)
print(arr.shape, arr.dtype) # (T, C, Z, Y, X) shape
# Index specific planes on-demand
plane = arr[0, 0, 2] # Only reads this plane
roi = arr[:, :, :, 100:200, 50:150] # Sub-regions
# Materialize all data when needed
full_data = np.array(arr)
# Or use dask for lazy computation
darr = bf.to_dask(series=0, chunks="auto")
result = darr.mean(axis=2).compute()
For simple cases, use imread() to load a single series/resolution into memory:
from bffile import imread
# Read series0/resolution0 into numpy array
# series and resolution parameters are optional and default to 0
data = imread("image.nd2", series=0, resolution=0)
print(data.shape, data.dtype) # (T, C, Z, Y, X) array
Selecting Bio-Formats Version
Bio-Formats is downloaded at runtime (via jgo).
By default, it will download the latest ome:formats-gpl:RELEASE maven artifact.
You can specify a different version by setting the BIOFORMATS_VERSION environment variable:
This variable accepts either a simple version string (e.g. 6.0.1) or a full maven coordinate
(e.g. ome:formats-gpl:6.0.1 or ome:formats-bsd:7.3.1):
# Use Bio-Formats 6.0.1 (GPL-licensed)
export BIOFORMATS_VERSION="6.0.1"
# Use BSD-licensed Bio-Formats 7.3.1
export BIOFORMATS_VERSION="ome:formats-bsd:7.3.1"
To see the currently installed version of Bio-Formats, you can check the
BioFile.bioformats_version static method:
from bffile import BioFile
print(BioFile.bioformats_version()) # e.g. "8.1.1"
and to see the full maven coordinate that was used:
from bffile import BioFile
print(BioFile.bioformats_maven_coordinate()) # e.g. "ome:formats-gpl:8.1.1"
[!NOTE]
We test back to version 6.0.1, but older versions may also work. If you specifically need
this code to work with an older version of bioformats, please open an issue.
Java Runtime
[!TIP]
No manual Java installation required!
This package automatically downloads and manages the Java runtime using
cjdk (via scyjava).
By default, scyjava uses Zulu JRE 11 (defined
here).
You can configure the Java version and/or vendor using environment variables:
# Use Adoptium JDK 17
export BFF_JAVA_VERSION=17
export BFF_JAVA_VENDOR=adoptium
# Use Temurin JDK 21
export BFF_JAVA_VERSION=21
export BFF_JAVA_VENDOR=temurin
Available vendors: zulu-jre, zulu, adoptium, temurin, and
other vendors listed in cjdk
Java 8 Support
Bffile is not currently expected to work with Java 8, as jpype has
deprecated support for Java 8 as of jpype version 1.6. If you do want to try
with Java 8, you will minimally need to explicitly pin jpype<1.6. If this is
an important use case for you, please open an issue to discuss Java 8 support.
License
Licensing is a bit complicated for this project, so please read carefully.
- All code in this
bffile repository is licensed under the BSD-3-Clause
License. You may use and distribute this code under the
terms of the BSD-3-Clause License.
- However, a user who installs
bffile from PyPI will, by default, end up with
Java jars that are licensed under the GPL-2.0 License (read below). As such,
this package is listed on PyPI as GPL-2.0-or-later.
When you run bffile for the first time, it will automatically download a number
of Java jars (via jgo), each of which has its
own license. By default, bffile downloads the
ome:formats-gpl:RELEASE
maven artifact.
If you would like to use bffile without any GPL-licensed jars, you can instead
opt into using
ome:formats-bsd by
setting the BIOFORMATS_VERSION environment variable:
BIOFORMATS_VERSION="ome:formats-bsd"
If you need a package that defaults to BSD-licensed jars (and ships as
BSD-3 on PyPI), open an issue to discuss a bffile-bsd variant.
