An efficient TIFF/Zarr reader/writer for ImageJ/Fiji that can utilize all the cores of your CPU!
The heavy lifting is done by the native cpp-tiff and cpp-zarr libraries, which are bundled inside the plugin jar and loaded automatically.
- RGB images are saved with ImageJ's own tiff writer rather than the parallel one, and cannot be saved as zarr
- Complex-valued zarr arrays cannot be opened. Data types ImageJ lacks are converted: float16, bfloat16, 32- and 64-bit integers and doubles open as 32-bit float images, and bool arrays as images of 0 and 1
- On Windows, file and folder names with characters outside the system's code page (Chinese or Japanese on a Western Windows, for example, or emoji) work only for files and folders that exist on drives keeping short 8.3 names, as most system drives do, and a file being saved needs a name in the code page. The plugin says when a path cannot be used. Names in the code page, such as é or µ, work everywhere, and on Linux and macOS any name works
- An up-to-date installation of Fiji which can be downloaded from here: https://imagej.net/software/fiji/downloads
- OS versions supported: Windows 10 or later, Ubuntu 22.04 (Most modern Linux distributions should also work), and macOS 13 or later (Apple Silicon/M-series only. Intel Macs are not supported as of v1.3.0)
- On Macs, use the Apple silicon Fiji download. The classic/"stable" Fiji ships an Intel Java and runs through Rosetta even on M-series Macs, so it cannot load the plugin's ARM natives (the plugin will show an error explaining this)
Install the plugin through Fiji's updater. Fiji then keeps it up to date along with everything else.
- In Fiji, open Help › Update… and click Manage Update Sites.
- Click Add Unlisted Site and fill in the new row:
- Name:
Parallel-Fiji-Visualizer - URL:
https://sites.imagej.net/Parallel-Fiji-Visualizer/
- Name:
- Click Apply and Close, then Apply Changes, and restart Fiji.
The plugin is then in the Plugins menu as Parallel Fiji Visualizer.
Copied the plugin jar into Fiji by hand before? Delete Parallel_Fiji_Visualizer-<version>.jar from Fiji's plugins folder first. Otherwise Fiji may keep your copy and never update it.
No internet on the Fiji machine? Copy Parallel_Fiji_Visualizer-<version>.jar from the latest release into Fiji's plugins folder instead. It will not update itself.
Upgrading from 1.2.x or older? Delete the old
Parallel_Fiji_Visualizer_lib folder from Fiji.app/lib/<os> and the old
Parallel_Fiji_Visualizer_plugin jar from Fiji.app/plugins first; they are
no longer used.
Drag a Zarr folder onto the plugin window. A folder is a Zarr if it holds Zarr
metadata (.zarray, zarr.json or .zgroup). The
plugin opens:
- Zarr v2 and v3 arrays with 2 to 5 axes, as hyperstacks with channel and time sliders
- OME-Zarr images (their full-resolution level, with its pixel size)
- groups that hold a single image
Axis names come from the metadata: Zarr v3 dimension_names, xarray's
_ARRAY_DIMENSIONS, or the OME-Zarr axes. Arrays without names are read as:
- Zarr v2: MATLAB's order (y, x, z, c, t), as PetaKit5D and this plugin write them. Chunks of 1 on the first axes mean NumPy's order (t, c, z, y, x) instead, and so does C storage order for 4D and 5D arrays.
- Zarr v3: (t, z, y, x, c), or (t, c, z, y, x) when the last axis is longer than 8, so arrays with more than 8 channels last need their axis names (or the Zarr axis order below).
Arrays with fewer axes leave out the ones they lack: a 4D Zarr v2 array is (y, x, z, t), and a 3D Zarr v3 volume (z, y, x).
Axes mixed up? Set Zarr axis order at the bottom of the plugin window
to the array's axes in order, using x, y, z, c (channel) and t (time), e.g.
tzyxc, and open it again. An order applies to unnamed arrays with that many
axes, so give one per number of axes, separated by commas: yxz, tzyxc.
Auto goes back to the rules above. Macros can set it with
call("ij.Prefs.set", "pfv.zarrAxisOrder", "tzyxc");.
TIFF and Zarr images that do not fit in Fiji's memory (Edit › Options › Memory & Threads) open as virtual stacks, which read a block of planes at a time as they are shown, and read the next block ahead while you scroll or play them. The plugin counts what an image really needs in Java's memory (large planes can take up to twice their size) beside the images already open, and a line in the Log window says when an image opens as a virtual stack, and why. If memory runs short while an image is being read, it opens as a virtual stack instead of failing. Virtual stacks are ordinary ImageJ images: macros, Duplicate, ImageJ's own Save As and its tools work on them.
8-bit color TIFFs open as RGB images, and 16-bit or float color as one channel per color, as ImageJ shows them.
Save as Tiff and Save as Zarr save in the background, so Fiji stays usable while they run. The image is locked until it has been saved, as ImageJ locks the images its commands are working on: its sliders are greyed out and other commands leave it alone.
Images are saved a run of planes at a time, so a save needs about 1 GB (TIFF) to 5 GB (Zarr) of memory beside Fiji's instead of a second copy of the image, and virtual stacks larger than memory can be saved too: a TIFF bigger than memory can be saved as Zarr, for example. A save is written under a hidden temporary name next to the file you chose and renamed when it is complete, so a save that fails leaves nothing under that name, and a file saved there before stays as it was.
Save as Zarr writes a Zarr v2 array in MATLAB's axis order, as PetaKit5D
does: (y, x, z), or (y, x, z, c, t) for a hyperstack, with the axis names
recorded so the plugin (and xarray) read the hyperstack back as it was. Chunk
files go in nested folders (0/0/0), which writes much faster to network file
systems than one folder of them all.
Requirements:
- JDK 16+ and Maven
- CMake ≥ 3.18 and a C++ toolchain with OpenMP (g++ on Linux/Windows-MinGW, Homebrew gcc on macOS)
- Network access on the first build (the native build downloads pinned releases of cpp-tiff, cpp-zarr and their dependencies)
# Java only (uses natives already staged under target/classes, if any):
mvn clean package
# Java + native libraries for the current platform:
mvn clean package -PnativeThe result is target/Parallel_Fiji_Visualizer-<version>.jar containing the
natives for the platform you built on. Release jars are produced by a Jenkins
pipeline that runs the -Pnative build on Linux, Windows and macOS and merges
the three native sets into one cross-platform jar.
src/test/java holds regression tests for the JNI layer and the Java glue:
native round trips for every data type, end-to-end reads through the plugin's
readers, Zarr v2, v3 and OME-Zarr layouts and their axes, color and ImageJ
TIFFs, saving stacks and hyperstacks as Zarr, folder and hyperstack opening,
the virtual stacks, reads and saves in slabs (each compared plane by plane, or
byte by byte, with a read or save in one piece), images that do not fit in
memory, paths with non-ASCII characters, and checks that the plugin still
loads in a stock Fiji. mvn package -Pnative builds the natives
and runs every test; a test that needs the natives fails if they were built but
cannot be loaded. Without -Pnative those tests are skipped and the Java-only
tests still run.
GitHub Actions runs the same build and tests on Linux x64, Windows x64 and macOS arm64 for every push that changes more than documentation.
Import the repository root via File → Import → Maven → Existing Maven
Projects, then run ParallelFijiVisualizer as a Java Application — its
main() starts ImageJ with the plugin loaded.
Build the natives once with mvn process-classes -Pnative. They are staged
both into target/classes/natives/ (packaged into the jar) and into
target/natives/ — IDE full builds wipe the former, and the plugin
automatically falls back to the latter, so Eclipse cleans don't break native
loading. After mvn clean (which removes both), rerun
mvn process-classes -Pnative. To point at natives somewhere else entirely,
set -Dpfv.natives.dir=/path/to/libs on the run configuration.
pom.xml Maven build; javac -h generates the JNI headers
src/main/java/ the ImageJ plugin (edu.abc.berkeley) + ij.* extensions
src/main/native/ CMake superbuild: fetches pinned cpp-tiff/cpp-zarr
releases and compiles the two JNI libraries
(libParallelReadC, libParallelWriteC)
src/main/resources/ plugins.config (Fiji menu entry)
To bump the native library versions, edit CPP_TIFF_VERSION /
CPP_ZARR_VERSION (and their SHA256 pins) in src/main/native/CMakeLists.txt.
Please cite our software if you find it useful in your work:
Xiongtao Ruan, Matthew Mueller, Gaoxiang Liu, Frederik Görlitz, Tian-Ming Fu, Daniel E. Milkie, Joshua L. Lillvis, Alexander Kuhn, Chu Yi Aaron Herr, Wilmene Hercule, Marc Nienhaus, Alison N. Killilea, Eric Betzig, Srigokul Upadhyayula. Image processing tools for petabyte-scale light sheet microscopy data. Nature Methods (2024). https://doi.org/10.1038/s41592-024-02475-4