TIFFTrim

A command-line tool and Python module to trim 3D TIFF stacks (shape [frames, y, x]) while preserving TIFF tags/metadata per page. This tool is mostly meant for 2P photon calcium imaging data, where for certain processing pipelines it is sometimes necessary to split a file into smaller chunks. Metadata handling currently supports files generated by ScanImage.

Features

• Trim a frame range from a multi-page (3D) TIFF stack
• Split a stack into consecutive fixed-size chunks
• Apply a numeric offset from the software tag to pixel values (this is sometimes necessary when concatenating multiple recordings that had different PMT offsets)
• Preserves per-page metadata: TIFF tags (extratags), description, datetime, resolution, compression, photometric, planarconfig, software

Installation

uv sync

Or, to install into an existing environment:

uv pip install -e .

Both install a console script named tifftrim.

CLI usage

Trim a frame range

Keep frames 0–999 (end is exclusive):

tifftrim -i input.tif -o output.tif -r 0:1000

Keep frames 500 to the end:

tifftrim -i input.tif -o output.tif -r 500:

Split into chunks

Split into chunks of 300 frames each, writing multiple TIFFs into out_dir/:

tifftrim -i input.tif -o out_dir/ --chunk-size 300

Output files are named <stem>_frames_<start>_<end>.tif and are lexicographically sorted.

By default each output chunk's frame count is rounded down to a multiple of 3 (--block-size). Override with:

tifftrim -i input.tif -o out_dir/ --chunk-size 300 --block-size 1

Apply pixel offset from software tag

Reads a numeric offset from the SI.hChannels.channelOffset field in the software tag and adds it to every pixel:

tifftrim -i input.tif -o output.tif -r 0:1000 --add-offset

Works with both trim and split modes.

Show tifffile warnings

Warnings from tifffile are suppressed by default. To show them:

tifftrim -i input.tif -o output.tif -r 0:100 --no-quiet

Range format

--range uses Python slice semantics:

Argument	Meaning
0:100	frames 0–99 (100 frames)
10:200	frames 10–199
500:	frame 500 to the last frame

Options reference

Option	Description
-i, --input	Input TIFF path
-o, --output	Output TIFF path (trim) or directory (split)
-r, --range	Frame range start:end (mutually exclusive with --chunk-size)
--chunk-size N	Split into chunks of N frames (mutually exclusive with --range)
--block-size N	Round each chunk's frame count down to a multiple of N (default: 3)
--add-offset	Add numeric offset from software tag to pixel values
--no-quiet	Show tifffile warnings on stderr

Python API

from tifftrim import trim_3d_tiff
from tifftrim.trim import split_3d_tiff_into_chunks

# Trim frames 0–999
trim_3d_tiff("input.tif", "output.tif", start=0, end=1000)

# Trim with offset applied
trim_3d_tiff("input.tif", "output.tif", start=0, end=1000, add_offset=True)

# Split into 300-frame chunks
split_3d_tiff_into_chunks("input.tif", "out_dir/", chunk_size=300, block_size=3)

Notes

• The tool expects the TIFF to load as a 3D array [frames, y, x]. Files with extra dimensions (e.g. channels) may need adapting.
• Some tags may be skipped if they cannot be serialized via extratags.

Development

File	Role
tifftrim/trim.py	Core trimming and splitting logic
tifftrim/cli.py	Argument parsing and entry point
pyproject.toml	Package configuration