🧬 mrc

Zero-copy, zero-allocation, no_std-friendly 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?

• 🚀 Zero-copy: Direct memory mapping with no intermediate buffers
• 🦀 no_std: Works in embedded environments and WebAssembly
• ⚡ SIMD-accelerated: AVX2/NEON accelerated type conversions
• 🔄 Type conversion: Automatic conversion between voxel types
• 🔒 100% safe: No unsafe blocks in public API

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
mrc = { version = "0.2", features = ["std", "mmap", "f16", "simd", "parallel"] }

🚀 Quick Start

Architecture

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

MRC File Structure

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

📖 Reading MRC Files

use mrc::Reader;

fn main() -> Result<(), mrc::Error> {
    // Open an MRC file - header is parsed automatically
    let reader = 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 type conversion
    // Read Int16 file as Float32 (uses SIMD when available)
    for slice in reader.slices_converted::<i16, 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 writes the header with correct statistics
    writer.finalize()?;
    Ok(())
}

⚠️ Migrating from v0.1

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

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

🗺️ API Overview

Core Types

Iterator API

The library provides an iterator-centric API for efficient processing:

// 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 chunks
for chunk in reader.blocks::<f32>([64, 64, 64]) {
    let block = chunk?;
    // Process 64³ chunk
}

Type Conversion

Automatic type conversion is supported via the Convert trait:

// Read file as one type, convert to another
for slice in reader.slices_converted::<i16, f32>() {
    let block = slice?;
    // i16 data automatically converted to f32
}

// Write with type conversion
let mut writer = create("output.mrc")
    .shape([256, 256, 128])
    .mode::<i16>()  // File stores i16
    .finish()?;

let f32_data: VoxelBlock<f32> = ...;
writer.write_converted::<f32, i16>(&f32_data)?;  // Converts f32 -> i16

Memory-Mapped I/O

For large files (>1GB), 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 for zero-copy scenarios
if reader.can_zero_copy::<f32>() {
    let bytes = reader.data_bytes();  // &[u8] backed by mmap
}

📊 Data Type Support

[^1]: Requires f16 feature and nightly Rust compiler.

⚡ Performance Features

SIMD Acceleration

The library automatically uses SIMD instructions (AVX2 on x86_64, NEON on AArch64) for type conversions:

// These conversions use SIMD when available:
// i8 → f32, i16 → f32, u16 → f32, u8 → f32

// Access SIMD functions directly
#[cfg(feature = "simd")]
{
    let f32_data = mrc::convert_i16_slice_to_f32(&i16_data);
}

Zero-Copy Reading

When the file's native type matches your target type and endianness:

let reader = Reader::open("data.mrc")?;

// Check if zero-copy is possible
if reader.can_zero_copy::<f32>() {
    println!("Using zero-copy fast path!");
}

// The iterator will use zero-copy automatically when possible
for slice in reader.slices::<f32>() {
    // No allocation or conversion happening here
}

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

no_std Usage

For embedded systems, WebAssembly, and other constrained environments:

[dependencies]
mrc = { version = "0.2", default-features = false }

#![no_std]
use mrc::{Header, Mode};

// Create a header (works in no_std)
let mut header = Header::new();
header.nx = 256;
header.ny = 256;
header.nz = 100;
header.mode = Mode::Float32 as i32;

no_std Compatible APIs

🔧 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_str("FEI1")?;

Key Header Fields

🛣️ Development Roadmap

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

• Complete MRC-2014 format support
• Iterator-centric API (slices, slabs, blocks)
• Type conversion pipeline
• 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)
• no_std support

🚧 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
• Compression support (gzip, zstd)
• Cloud storage integration

🧪 Testing

# Run all tests
cargo test --all-features

# Run benchmarks
cargo bench --all-features

# Check no_std build
cargo check --no-default-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

📄 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