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
# or add to Cargo.toml: imodfile = "0.1"

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

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

Build

pip install maturin
maturin develop --features python    # develop mode
maturin build --features python      # or build a wheel

The .pyi stub is bundled automatically for IDE autocomplete.

Note: Set PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 if your Python is newer than PyO3's max supported version.

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.1.0