🧬 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. Designed for scientific computing with safety and performance as top priorities.

✨ Why mrc?

• 🚀 Iterator-centric: Stream slices, slabs, or tiles on demand
• ⚡ SIMD-accelerated: AVX2/NEON for the common i16→f32 path
• 🔒 Type-safe I/O: Compile-time mode matching prevents silent data corruption
• 🗺️ Memory-mapped I/O: MmapReader / MmapWriter for files larger than RAM
• 📦 Compression: Auto-detect and read gzip / bzip2 MRC files

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

📦 Installation

[dependencies]
mrc = "0.2"

# For all features (defaults are usually sufficient)
mrc = { version = "0.2", features = ["mmap", "f16", "simd", "parallel", "gzip"] }

🚀 Quick Start

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌────────────────┐
│   File System   │────▶│  Header Parsing  │────▶│  Iterator API  │
│ (.mrc/.mrc.gz)  │     │   (1024 bytes)   │     │  (Zero-copy)   │
└─────────────────┘     └──────────────────┘     └────────────────┘
         │                       │                       │
   ┌─────────────┐          ┌────────┐              ┌─────────┐
   │ MrcReader   │          │ Header │              │ VoxelBlock
   │ Reader      │          │        │              │         │
   │ MmapReader  │          └────────┘              └─────────┘
   │ Writer      │
   │ MmapWriter  │
   └─────────────┘

MRC File Structure

| 1024 bytes | NSYMBT bytes | data_size bytes |
|  header    | ext header   | voxel data      |

📖 Reading MRC Files

use mrc::{open, ReaderExt};

fn main() -> Result<(), mrc::Error> {
    // Open an MRC file - auto-detects plain, gzip, or bzip2
    let reader = open("protein.mrc")?;

    // Get volume dimensions
    let shape = reader.shape();
    println!("Volume: {}×{}×{} voxels", shape.nx, shape.ny, shape.nz);

    // Iterate over slices - zero-copy when file type matches
    for slice in reader.slices::<f32>() {
        let block = slice?;  // VoxelBlock<f32>
        println!("Slice {}: {} voxels", block.offset[2], block.len());
    }

    // Or read with automatic conversion to f32 (common cryo-EM workflow)
    for slice in reader.slices_f32()? {
        let block = slice?;
        let sum: f32 = block.data.iter().sum();
        println!("Slice sum: {}", sum);
    }

    Ok(())
}

✏️ Creating New Files

use mrc::{create, VoxelBlock};

fn main() -> Result<(), mrc::Error> {
    // Create a new file with the builder pattern
    let mut writer = create("output.mrc")
        .shape([512, 512, 256])
        .mode::<f32>()
        .finish()?;

    // Write voxel data slice by slice
    for z in 0..256 {
        let block = VoxelBlock::new(
            [0, 0, z],
            [512, 512, 1],
            vec![0.0f32; 512 * 512],
        );
        writer.write_block(&block)?;
    }

    // Finalize rewrites the header to disk.
    // Note: dmin/dmax/dmean/rms are NOT updated automatically.
    writer.finalize()?;
    Ok(())
}

⚠️ Migrating from v0.1

v0.2 is a complete architectural redesign. Key API changes:

v0.1	v0.2
MrcView::new(data)	Reader::open(path) / open(path)
MrcFile::create(path, header)	create(path).shape(dims).mode::<T>().finish()
MrcView::view::<f32>()	reader.slices::<f32>()
MrcViewMut	Writer + VoxelBlock<T>
MrcMmap	MmapReader / MmapWriter

Migration example:

// v0.1: Load entire file into memory
let data = std::fs::read("file.mrc")?;
let view = MrcView::new(data)?;
let floats = view.view::<f32>()?;

// v0.2: Stream with iterators
let reader = open("file.mrc")?;
for slice in reader.slices::<f32>() {
    let block = slice?;
    // process block.data
}

New in v0.2: SIMD acceleration, parallel encoding, type conversion iterators, MmapReader, compression support, unified ReaderExt trait.

🗺️ API Overview

Core Types

Type	Purpose	Example
[MrcReader]	Auto-detect compression	open("file.mrc")?
[Reader]	Read plain MRC files	Reader::open("file.mrc")?
[MmapReader]	Memory-mapped reading	MmapReader::open("large.mrc")?
[Writer]	Write MRC files	create("out.mrc").shape([64,64,64]).mode::<f32>().finish()?
[MmapWriter]	Memory-mapped writing	MmapWriter::create("out.mrc", header)?
[WriterBuilder]	Configure new files	create(path).shape(dims).mode::<T>()
[Header]	1024-byte MRC header	Header::new()
[Mode]	Data type enumeration	Mode::Float32
[VoxelBlock<T>]	Chunk of voxel data	VoxelBlock::new(offset, shape, data)
[VolumeShape]	Volume dimensions	VolumeShape::new(nx, ny, nz)

Iterator API

All reader types implement [ReaderExt], providing a unified iterator API:

use mrc::ReaderExt;

// Iterate over individual slices (Z axis)
for slice in reader.slices::<f32>() {
    let block = slice?;
    // Process slice
}

// Iterate over slabs (multiple slices at once)
for slab in reader.slabs::<f32>(10) {  // 10 slices per slab
    let block = slab?;
    // Process slab
}

// Iterate over arbitrary 3D tiles
for tile in reader.tiles::<f32>([64, 64, 64]) {
    let block = tile?;
    // Process 64³ tile
}

// Semantic aliases
for image in reader.images::<f32>() { /* same as slices() */ }
for plane in reader.planes::<f32>() { /* same as slices() */ }
for vol in reader.volumes::<f32>()? { /* full volumes from a stack */ }

Type Conversion

The crate intentionally does not provide generic type conversion — that is the caller's responsibility. Only two overwhelmingly common cryo-EM workflows are supported as conveniences:

use mrc::ReaderExt;

// Read an Int16/Uint16/Int8/Float32 file as f32
for slice in reader.slices_f32()? {
    let block = slice?;
    // block.data is Vec<f32>
}

// Write f32 data to a Float16 file
let mut writer = create("output.mrc")
    .shape([256, 256, 128])
    .mode::<f16>()
    .finish()?;

let f32_data: VoxelBlock<f32> = /* ... */;
writer.write_f16_from_f32(&f32_data)?;

Safety note: reader.slices::<f32>() on an Int16 file returns Error::ModeMismatch instead of silently decoding 2-byte voxels as 4-byte floats. Use slices_f32() for automatic conversion.

Compression

MrcReader (and the convenience open()) automatically detects gzip and bzip2 compression from the file magic bytes:

use mrc::open;

// Works for plain .mrc, .mrc.gz, and .mrc.bz2
let reader = open("protein.mrc")?;
println!("Compression: {:?}", reader.compression_type());

You can also open compressed files directly:

use mrc::GzipReader;

let reader = GzipReader::open("protein.mrc.gz")?;

Memory-Mapped I/O

For large files that don't fit in RAM, memory-mapped I/O lets the OS handle paging:

use mrc::MmapReader;

let reader = MmapReader::open("large_volume.mrc")?;

// Same iterator API as Reader
for slice in reader.slices::<f32>() {
    let block = slice?;
    // OS automatically pages data in/out
}

// Direct byte access (zero-copy)
let bytes = reader.data_bytes();  // &[u8] backed by mmap

Use	When
Reader / MrcReader	Small files, simple sequential access
MmapReader	Large files, memory-constrained environments, random access

📊 Data Type Support

[Mode]	Value	Rust Type	Bytes	Description	Use Case
Int8	0	i8	1	Signed 8-bit integer	Binary masks
Int16	1	i16	2	Signed 16-bit integer	Cryo-EM density
Float32	2	f32	4	32-bit float	Standard density
Int16Complex	3	[Int16Complex]	4	Complex 16-bit	Phase data
Float32Complex	4	[Float32Complex]	8	Complex 32-bit	Fourier transforms
Uint16	6	u16	2	Unsigned 16-bit	Segmentation
Float16	12	f161	2	16-bit float	Memory efficiency
Packed4Bit	101	[Packed4Bit]	0.5	Packed 4-bit	Compression

⚡ Performance Features

SIMD Acceleration

The simd feature (enabled by default) uses AVX2 (x86_64) or NEON (AArch64) to accelerate the common i16→f32 and u16→f32 paths inside slices_f32() and slabs_f32(). No explicit SIMD code is required in user code.

Zero-Copy Reading

Reader loads the entire file into memory (as raw bytes) and decodes slices on demand. For true zero-copy access, use MmapReader:

use mrc::MmapReader;

// Memory-mapped reading
let reader = MmapReader::open("data.mrc")?;
for slice in reader.slices::<f32>() {
    // Decodes on demand; raw bytes are backed by the OS page cache
}

Parallel Writing

With the parallel feature, large writes use Rayon for parallel encoding:

let mut writer = create("large.mrc")
    .shape([2048, 2048, 512])
    .mode::<f32>()
    .finish()?;

// This uses parallel encoding internally
writer.write_block_parallel(&large_block)?;
writer.finalize()?;

🎯 Feature Flags

Feature	Description	Default
mmap	Memory-mapped I/O	✅
f16	Half-precision support (via half crate)	✅
simd	SIMD acceleration	✅
parallel	Parallel encoding	✅
gzip	Gzip-compressed MRC files	✅
bzip2	Bzip2-compressed MRC files	❌

🔧 Header Structure

The MRC header contains 56 fields (1024 bytes total):

use mrc::Header;

let mut header = Header::new();

// Basic dimensions
header.nx = 2048;
header.ny = 2048;
header.nz = 512;

// Data type
header.mode = Mode::Float32 as i32;

// Physical dimensions in Ångströms
header.xlen = 204.8;
header.ylen = 204.8;
header.zlen = 102.4;

// Cell angles for crystallography
header.alpha = 90.0;
header.beta = 90.0;
header.gamma = 90.0;

// Extended header type (optional)
header.set_exttyp(*b"FEI1");

Key Header Fields

Field	Type	Description
nx, ny, nz	i32	Image dimensions
mode	i32	Data type (see Mode enum)
xlen, ylen, zlen	f32	Cell dimensions (Å)
alpha, beta, gamma	f32	Cell angles (°)
mapc, mapr, maps	i32	Axis mapping (1,2,3 permutation)
dmin, dmax, dmean	f32	Data statistics
ispg	i32	Space group number
nsymbt	i32	Extended header size
origin	[f32; 3]	Origin coordinates
exttyp	[u8; 4]	Extended header type

🛣️ Development Roadmap

✅ Current Release (v0.2.x): Core + SIMD

• Complete MRC-2014 format support
• Iterator-centric API (slices, slabs, tiles)
• Type-safe I/O with compile-time mode checking
• SIMD acceleration (AVX2, NEON)
• Zero-copy fast paths
• Parallel encoding
• Memory-mapped I/O (MmapReader, MmapWriter)
• All data types (modes 0-4, 6, 12, 101)
• Compression support (gzip, bzip2)
• Unified reader traits (ReaderCore, ReaderExt)

🚧 Next Release (v0.3.x): Extended Features

• Extended header parsing (CCP4, FEI1, FEI2, etc.)
• Statistics functions (histogram, moments)
• Validation utilities
• Streaming API for very large datasets

🚀 Future Releases (v1.x)

• Python bindings via PyO3
• GPU acceleration
• Cloud storage integration

🧪 Testing

# Run all tests
cargo test --all-features

# Run benchmarks
cargo bench --all-features

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Setup

# Clone repository
git clone https://github.com/elemeng/mrc.git
cd mrc

# Build with all features
cargo build --all-features

# Run tests
cargo test --all-features

# Check formatting
cargo fmt --check

# Run clippy
cargo clippy --all-features --all-targets

📄 MIT License

MIT License

Copyright (c) 2024-2025 mrc contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🙏 Acknowledgments

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

📞 Support & Community

• 🐛 Issues: Report bugs
• 📖 Documentation: Full docs
• 🏷️ Releases: Changelog

---

Made with ❤️ by the cryo-EM community for the scientific computing world

[Zero-copy • SIMD-accelerated • 100% safe Rust]

Footnotes

1. Requires f16 feature. Uses the half crate; no nightly Rust required. ↩