imodfile

Decode, encode, and inspect IMOD model files — from Rust and Python. Read and write .mod files used by the IMOD electron microscopy toolkit, in both binary and ASCII formats.

Install

Rust crate

cargo add imodfile

Python package

pip install git+https://github.com/elemeng/imodfile.git

# Or build from source:
pip install maturin
maturin build --features python
pip install target/wheels/imodfile-*.whl

CLI tool

cargo install imodfile

Quick start (Rust)

use imodfile::Imod;

let model = Imod::load("cells.mod").unwrap();
println!("{} objects, {} views", model.obj.len(), model.view.len());

// Iterate over every point with indices
for (oi, ci, pi, pt) in model.points() {
    println!("[obj {oi}][cont {ci}][pt {pi}]  {} {} {}", pt.x, pt.y, pt.z);
}

// Dump all points as text
model.save_points("points.txt").unwrap();

// Save back as binary or ASCII (chosen by extension)
model.save("output.mod").unwrap();
model.save("output.txt").unwrap();

Quick start (Python)

import imodfile
import numpy as np

model = imodfile.load("cells.mod")
print(model.name, model.image_size)

for obj in model.objects:
    for cont in obj.contours:
        pts = cont.points                 # (N, 3) float32 array
        xs, ys, zs = pts[:, 0], pts[:, 1], pts[:, 2]

# Create new objects and contours
obj = model.add_object()
obj.name = "mitochondria"
obj.color = (1.0, 0.0, 0.0)

cont = obj.add_contour()
cont.points = np.array([[0,0,0],[1,0,0],[0,1,0]], dtype=np.float32)

model.save("output.mod")
model.save("output.txt")          # ASCII format
model.save_points("points.txt")   # point dump

Testing

# Full test suite (Rust + Python)
bash tests/test.sh

# Rust tests only
cargo test

# Python tests only (requires built wheel)
python -m pytest tests/test_python.py -v

The test suite covers:

Suite	Tests
Rust unit/integration	7 tests — binary/ASCII round-trip, labels, point sizes, clip planes, edge cases
Raw byte verification	Binary writer magic, tags, field layout, IEOF marker
Real file round-trip	Read `test_001.mod` → write → re-read → struct comparison (7 contours, 14 points)
Python bindings	15 tests — load, read, create, modify, save, error handling, round-trip

Key types

Type	Description
[`Imod`] / `Model`	Top-level model — image dimensions, transforms, views, objects
[`Iobj`] / `Object`	A named object with colour, material, contours, and meshes
[`Icont`] / `Contour`	A contour — open or closed series of [`Ipoint`]s
[`Imesh`] / `Mesh`	Triangle/quad mesh with vertex and index lists
[`Ipoint`]	Single 3-D coordinate `{ x, y, z }`

Rust API

Use case	API
Load a file	`Imod::load(path)` — auto-detects binary vs ASCII
Save a file	`model.save(path)` — binary, or ASCII if path ends with `.txt`
Iterate points	`model.points()` → `(obj, cont, pt, &Ipoint)`
Format as text	`model.to_points()` → `String`
Write to writer	`model.write_points(&mut writer)`
Low-level read	`read_binary(&mut reader)` / `read_ascii(&mut reader)`
Low-level write	`write_binary(&mut writer, &model)` / `write_ascii(...)`

Python API

Python	What it does
`imodfile.load(path)` → `Model`	Load a file (auto-detect format)
`model.save(path)`	Save (binary, or ASCII if `.txt`)
`model.objects` → `list[Object]`	All objects
`obj.contours` → `list[Contour]`	All contours in an object
`cont.points` → `ndarray(N, 3)`	Point coordinates (read/write)
`cont.surface`, `cont.time`, `cont.flags`	Contour metadata (read/write)
`obj.add_contour()` → `Contour`	Create a new contour
`model.add_object()` → `Object`	Create a new object

The .pyi stub is bundled in the wheel for IDE autocomplete.

CLI

imodfile <input.mod>                     # dump model info
imodfile <input.mod> <output.mod>        # copy / convert
imodfile <input.mod> output.txt          # convert to ASCII
imodfile <input.mod> output.txt --points # extract point coordinates
imodfile <input.mod> --points            # print points to stdout

Format support

Format	Read	Write
Binary (big-endian)	✓	✓
ASCII text	✓	✓
Legacy V0.1	✓	—

All chunk types are supported: objects, contours, meshes, materials, clip planes, labels, point sizes, views, slicer angles, reference transforms, meshing parameters, and general-purpose storage.

Modules

Crate module	Contents
[`model`]	Data types — `Imod`, `Iobj`, `Icont`, `Imesh`, `Ipoint`, ...
[`binary`]	Binary format reader and writer
[`ascii`]	ASCII format reader and writer
[`chunk_ids`]	4-byte magic constants
[`error`]	`ImodError` / `ImodResult`
[`store`]	General-purpose storage helpers

License

MIT

imodfile 0.2.0