mrc

Type-safe MRC-2014 file format reader/writer for Rust

A high-performance, memory-efficient library for reading and writing MRC (Medical Research Council) format files used in cryo-electron microscopy and structural biology.

Installation

[dependencies]
mrc = "0.2"

Quick Start

use mrc::{open, create, VoxelBlock};

// Read (auto-detects compression; handles common microscope quirks
// like NVERSION=0 and "MAP\0" automatically)
let reader = open("protein.mrc")?;
for slice in reader.convert::<f32>().slices() {
    let block = slice?;  // Vec<f32>
}

// Write — **always call .finalize()** or the header will be stale
// (density statistics wrong, tools display garbage contrast)
let mut writer = create("output.mrc")
    .shape([512, 512, 256])
    .mode::<f32>()
    .finish()?;
writer.write_block(&VoxelBlock::new(
    [0, 0, 0], [512, 512, 1], vec![0.0f32; 512 * 512],
)?)?;
writer.finalize()?;

Full Documentation

See docs.rs/mrc for the complete API reference, or APIs.md in this repository for a local API surface overview.

• Reading files — Reader, MmapReader, compressed I/O, permissive mode, decompression bomb protection (256 GiB limit, configurable)
• Writing files — Writer, MmapWriter, GzipWriter, Bzip2Writer
• Iterators — slices, slabs, tiles, volumes
• Auto-conversion — reader.convert::<T>().slices() etc.
• Full-volume reads — read_volume::<T>(), read_volume_u8(), auto-conversion via reader.convert::<T>().read_volume()
• Data modes — Mode enum and compile-time Voxel trait, including Packed4Bit read/write via slices_u8 / write_u4_block
• Headers — Header, HeaderBuilder, validation, endianness
• Extended header parsers — FEI1/FEI2 metadata, CCP4 symmetry records, MRCO legacy records, SerialEM records, Agard records
• Error handling — Error and HeaderValidationError
• Validation — validate_full / validate_reader / ValidationReport
• Real-world workflows — tilt series, FEI metadata, volume stacks
• Troubleshooting — common errors and how to fix them

CLI Tools

cargo build --release --bin mrc-validate
./mrc-validate protein.mrc

Migrating from v0.1

v0.2 adds SIMD acceleration, parallel encoding, type conversion iterators, compression support, unified reader API, and FEI extended header parsing.

Roadmap

v0.3.x — Stabilization & Quality (current)

• Complete MRC-2014 format support
• Iterator-centric API (slices, slabs, tiles)
• Type-safe I/O with compile-time mode checking
• SIMD acceleration (AVX2, NEON) — i8→f32, i16→f32, u16→f32, f16↔f32, byte-swap, stats
• Memory-mapped I/O and parallel encoding
• All data types (modes 0–4, 6, 12, 101)
• Compression support (gzip, bzip2)
• All extended header parsers (FEI1/2, CCP4, MRCO, SERI, AGAR)
• Header statistics computation and validation
• Permissive mode and volume stack support
• Decompression bomb protection (configurable 256 GiB limit)
• Criterion benchmark suite + integration tests
• Unified ConvertReader API with inherent forwarding
• ndarray feature for numpy-like volume access
• SIMD f32→i16/i8 clamping in write-hot paths
• Richer error context (offset, mode in BoundsError / ModeMismatch)

v0.4.x — Header & Extended Header API

• Auto-dispatch extended header parsing — reader.parse_extended_header() checks exttyp and routes to the correct parser automatically
• Reader convenience methods — reader.fei1_metadata(), reader.ccp4_records(), etc. (read + parse in one call)
• Expand IMOD metadata with more fields from extra bytes
• Richer Header convenience API — cell volume, better label helpers, more validation utilities
• exttyp-based dispatch enum for generic code over all extended header formats

v0.5.x — Python bindings via PyO3 / maturin (evaluate)

Note: This crate is under active development. While most features are functional, occasional API changes are possible. Contributions welcome — please report issues and share your ideas!

License

MIT — see LICENSE.

Acknowledgments

• CCP-EM for the MRC-2014 specification
• EMDB for providing real-world test data
• Cryo-EM community for invaluable feedback