ImarisConverter

ImarisConverter is a Python command-line tool for converting an image stack (e.g., TIFF slices) into the Imaris .ims format using PyImarisWriter.

It is designed for large 3D microscopy datasets and supports multi-threaded reading and writing, automatic memory-aware block processing, and logging.

Currently the tool supports single-channel, single-timepoint 3D grayscale image stacks.

---

Features

• Convert image stacks (*.tif, *.tiff, or other formats supported by imageio)

• Output Imaris .ims files compatible with Imaris

• Multi-threaded image reading and writing

• Automatic memory detection to choose between:

  • full in-memory processing
  • block-based streaming processing

• Automatic block size calculation for large datasets

• Logging of conversion progress

• Automatic output filename generation

---

Requirements

• Python ≥ 3.8
• PyImarisWriter
• numpy
• imageio
• tifffile
• psutil
• tqdm

Example installation:

pip install numpy imageio tifffile psutil tqdm

Install PyImarisWriter following its official instructions.

---

Installation

Clone the repository:

git clone https://github.com/bitstorming/ImarisConverter.git
cd ImarisConverter

Test and run the script directly:

python ImarisConverter.py -h

---

Usage

Basic usage:

python ImarisConverter.py "path/to/images/*.tif"

Example:

python ImarisConverter.py "data/mouse01/*.tif"

If no output filename is provided, the program automatically uses the input folder name:

mouse01.ims

---

Command Line Arguments

usage: ImarisConverter.py file_pattern [options]

Required

Argument	Description
file_pattern	File pattern matching the input image stack (e.g. "images/*.tif")

Optional

Argument	Default	Description
-o, --output_filename	FolderName.ims	Output IMS filename
-px, --pixel_size_x	1.0	Pixel size in X (µm)
-py, --pixel_size_y	1.0	Pixel size in Y (µm)
-pz, --pixel_size_z	1.0	Pixel size in Z (µm)
--reading_thread_count	8	Number of threads used to read images
--writing_thread_count	36	Number of threads used to write IMS blocks
--need_log_progress	False	Enable writing progress logging

Example with full options:

python ImarisConverter.py "images/*.tif" \
-o sample.ims \
-px 0.5 -py 0.5 -pz 1.0 \
--reading_thread_count 16 \
--writing_thread_count 32

---

How It Works

1. Input Detection

The program:

1. Collects all files matching the input pattern

2. Determines the image format (tifffile or imageio)

3. Reads the first image to detect:

   • image size
   • data type
   • total dataset size

---

2. Memory Analysis

The system memory is checked using psutil.

If the dataset size is smaller than 60% of available memory, the entire stack is loaded into memory.

Otherwise the program switches to block-based processing.

---

3. Block-based Conversion

Large datasets are processed in blocks along the Z dimension.

This allows conversion of very large datasets that do not fit into memory.

Block size is automatically estimated based on available RAM.

---

4. Parallel Processing

Two types of parallelism are used:

• Reading threads
• Writing threads

Reading uses a thread pool to load images faster, while writing uses PyImarisWriter's internal multithreading.

---

5. Writing the IMS File

The program uses PyImarisWriter's ImageConverter API to:

1. Copy voxel blocks
2. Set image metadata
3. Configure spatial extents
4. Write the final .ims dataset

---

Logging

A log file is automatically created:

output_filename.ims.log

The log records:

• dataset size
• memory usage
• block configuration
• processing progress

---

Example Output

2026-04-04 19:28:23,447 [INFO] Found 752 files
2026-04-04 19:28:23,462 [INFO] Image size:752 x 1756 x 1755, Data type: uint16
2026-04-04 19:28:23,462 [INFO] Total image size: 4.32 GB
2026-04-04 19:28:23,463 [INFO] Total System Memory: 15.86 GB
2026-04-04 19:28:23,463 [INFO] Available System Memory: 8.62 GB
2026-04-04 19:28:23,463 [INFO] Reading whole image stack into memory...
2026-04-04 19:28:23,463 [INFO] Block size: 752 slices per block
2026-04-04 19:28:23,524 [INFO] Settings:
2026-04-04 19:28:23,524 [INFO] Input file pattern: test_image\z*.tif
2026-04-04 19:28:23,524 [INFO] Output filename: test_image.ims
2026-04-04 19:28:23,524 [INFO] Pixel size: 1.0 x 1.0 x 1.0 micrometers
2026-04-04 19:28:23,524 [INFO] Image size: 1755 x 1756 x 752, Channels: 1, Time points: 1
2026-04-04 19:28:23,524 [INFO] Threading: Reading threads: 8, Writing threads: 36
2026-04-04 19:28:23,524 [INFO] Application name: ParallelImarisWriter, Application version: 1.0.0

---

Current Limitations

• Only single channel
• Only single timepoint
• Only 2D grayscale images
• Images must all have identical dimensions

---

Related Official Tools

This project is closely related to several existing tools for generating Imaris .ims datasets.

PyImarisWriter

Official Python bindings for the ImarisWriter library.

It provides the low-level API used to write .ims files.

Repository:

https://github.com/imaris/ImarisWriter https://github.com/imaris/ImarisWriterTest

ImarisConvert (Official CLI Tool)

The official ImarisFileConverter tool provided with Imaris software can also convert image formats to .ims.

However:

• it is typically distributed with Imaris installations
• it is not easily customizable
• integration into custom Python pipelines can be difficult

ImarisConverter provides a lightweight Python alternative for automated workflows.

---

Future Improvements

Potential extensions include:

• multi-channel image stacks
• multi-timepoint datasets
• additional image formats
• GPU-accelerated preprocessing
• direct OME-TIFF support

Acknowledgements

This project is built on top of PyImarisWriter, the official Python interface for writing Imaris .ims files.