cmapfile 2026.7.25

Quickstart

Install the cmapfile package and all dependencies from the Python Package Index:

python -m pip install -U cmapfile[all]

Print the command line usage:

python -m cmapfile --help

See Examples for usage cases.

Source code and support are available on GitHub.

Requirements

This revision was tested with the following requirements and dependencies (other versions may work):

• CPython 3.12.10, 3.13.14, 3.14.6, 3.15.0b4 64-bit

• Numpy 2.5.1

• Scipy 1.18.0

• H5py 3.16.0

• Tifffile 2026.7.14

• Oiffile 2026.2.8

Revisions

2026.7.25

• Require tifffile >= 2026.5.2.

• Drop support for Python 3.11 and numpy 2.0 (SPEC0).

• Support Python 3.15.

2026.1.8

• Improve code quality.

2025.12.18

• Improve code quality.

• Drop support for Python 3.10, support Python 3.14.

2025.1.1

• Improve type hints.

• Support Python 3.13.

2024.8.28

• …

Refer to the CHANGES file for older revisions.

Notes

The CMAP file format according to [1]:

Example of HDF format written by Chimera (Chimera map format) follows.
The Chimera map file reader will allow all fields to be missing (except
the 3D data).

/image (group, any name allowed)
 name "centriole" (attribute)
 step (1.2, 1.2, 1.2) (attribute)
 origin (-123.4, -522, 34.5) (attribute)
 cell_angles (90.0, 90.0, 90.0) (attribute)
 rotation_axis (0.0, 0.0, 1.0) (attribute)
 rotation_angle 45.0 (attribute, degrees)
 color (1.0, 1.0, 0, 1.0) (attribute, rgba 0-1 float)
 time 5 (attribute, time series frame number)
 channel 0 (attribute, integer for multichannel data)
 /data (3d array of uint8 (123,542,82)) (dataset, any name allowed)
 /data_x (3d array of uint8 (123,542,82), alternate chunk shape) (dataset)
 /data_2 (3d array of uint8 (61,271,41)) (dataset, any name allowed)
    subsample_spacing (2, 2, 2) (attribute)
 (more subsampled or alternate chunkshape versions of same data)

References

1. Thomas Goddard. [Chimera-users] reading in hdf5 files in chimera. https://www.cgl.ucsf.edu/pipermail/chimera-users/2008-September/003052.html

2. UCSF Chimera, an extensible molecular modeling system. https://www.cgl.ucsf.edu/chimera/

3. Globals for Images - SimFCS. https://www.lfd.uci.edu/globals/

Examples

Convert a 5D LSM file to CMAP file:

$ python -m cmapfile "/my data directory/large.lsm"

Convert all BIN files in the current directory to test.cmap. The BIN files are known to contain 128x128x64 samples of 16-bit integers. The CMAP file will store float32 maps using subsampling up to 16:

$ python -m cmapfile --shape 128,128,64 --step 1,1,2 --dtype i2 \
                     --cmap test.cmap --subsample 16 --astype float32 *.bin

Change the step size in the CMAP file:

$ python -m cmapfile --step 1,1,1.5 test.cmap

Print the cmapfile script usage:

$ python -m cmapfile --help

Usage: cmapfile [options] files

Convert volume data files to Chimera MAP files.

Options:
--version             show program's version number and exit
-h, --help            show this help message and exit
-q, --quiet
--filetype=FILETYPE   type of input file(s).
                      For example, BIN, LSM, OIF, TIF
--dtype=DTYPE         type of data in BIN files. For example, uint16
--shape=SHAPE         shape of data in BIN files in F order.
                      For example, 256,256,32
--offset=OFFSET       number of bytes to skip at beginning of BIN files
--step=STEP           stepsize of data in files in F order.
                      For example, 1.0,1.0,8.0
--cmap=CMAP           name of output CMAP file
--astype=ASTYPE       type of data in CMAP file. For example, float32
--subsample=SUBSAMPLE
                      write subsampled datasets to CMAP file