Struct Writer 

pub struct Writer { /* private fields */ }

MRC file writer and its builder. MRC file writer using standard file I/O.

For most use cases, prefer creating via WriterBuilder or the create convenience function.

The writer maintains an open file handle and writes data blocks directly to disk. Call finalize when done to ensure the header is correctly rewritten.

To write to an in-memory buffer instead of a file, use from_writer with a std::io::Cursor:

use mrc::{Header, Writer};
use std::io::Cursor;

let buffer: Vec<u8> = Vec::new();
let header = Header::new();
let mut writer = Writer::from_writer(Cursor::new(buffer), header, &[])?;
// ... write blocks, then finalize
writer.finalize()?;

Implementations

impl Writer

pub fn from_writer<W: Read + Write + Seek + 'static>( writer: W, header: Header, ext_header: &[u8], ) -> Result<Self, Error>

Create a writer that writes to an arbitrary std::io::Read + std::io::Write + std::io::Seek target.

This enables writing directly to in-memory buffers:

use mrc::{Header, Writer};
use std::io::Cursor;

let header = Header::new();
let mut writer = Writer::from_writer(Cursor::new(Vec::new()), header, &[])?;
// ... write blocks, then finalize
writer.finalize()?;

pub fn from_writer_mmap<P: AsRef<Path>>( path: P, header: Header, ext_header: &[u8], ) -> Result<Self, Error>

Create a memory-mapped writer from a Header directly.

Like from_writer but uses a memory-mapped file instead of a file handle. Requires the mmap feature.

The file is truncated to the exact size needed for the header, extended header, and voxel data.

Examples

use mrc::{Header, Writer};
let header = Header::new();
let mut writer = Writer::from_writer_mmap("output.mrc", header, &[])?;

pub fn from_writer_gzip<P: AsRef<Path>>( path: P, header: Header, ext_header: &[u8], compression: Compression, ) -> Result<Self, Error>

Create a gzip-compressed writer from a Header directly.

Like from_writer but buffers the entire file in memory and gzip-compresses it on finalize. Requires the gzip feature.

Examples

use mrc::{Header, Writer, Compression};
let header = Header::new();
let mut writer = Writer::from_writer_gzip("output.mrc.gz", header, &[], Compression::Balanced)?;

pub fn shape(&self) -> VolumeShape

Volume dimensions for this writer.

Examples

use mrc::create;
let mut writer = create("output.mrc")
    .shape([64, 64, 64])
    .mode::<f32>()
    .finish()?;
assert_eq!(writer.shape().nx, 64);

pub fn mode(&self) -> Mode

Voxel data mode for this writer.

Examples

use mrc::create;
let mut writer = create("output.mrc")
    .shape([64, 64, 64])
    .mode::<f32>()
    .finish()?;
assert_eq!(writer.mode(), mrc::Mode::Float32);

pub fn header(&self) -> &Header

Read-only reference to the current header.

For mutable access, use header_mut. Modify header fields before calling finalize to change what gets written to disk.

Examples

use mrc::create;
let mut writer = create("output.mrc")
    .shape([64, 64, 64])
    .mode::<f32>()
    .finish()?;
let h = writer.header();
assert_eq!(h.nx, 64);

pub fn header_mut(&mut self) -> &mut Header

Mutable reference to the current header.

Allows modifying header fields (e.g. labels, density statistics) between writing blocks and calling finalize.

Examples

use mrc::create;
let mut writer = create("output.mrc")
    .shape([64, 64, 64])
    .mode::<f32>()
    .finish()?;
writer.header_mut().ispg = 1;

pub fn write_block<T: Voxel>( &mut self, block: &VoxelBlock<T>, ) -> Result<(), Error>

Write a block of voxels to the file.

The type T must match the file’s voxel mode exactly. Supports arbitrary sub-blocks by scattering row-by-row when necessary.

Examples

use mrc::{create, VoxelBlock};
let mut writer = create("output.mrc")
    .shape([64, 64, 1])
    .mode::<f32>()
    .finish()?;
let block = VoxelBlock::new([0, 0, 0], [64, 64, 1], vec![0.0f32; 64 * 64])?;
writer.write_block(&block)?;

pub fn write_u8_block(&mut self, block: &VoxelBlock<u8>) -> Result<(), Error>

Write a block of u8 data by automatically widening to u16 (Mode 6).

The file must have been created with Mode::Uint16. Each u8 voxel is widened to u16 before writing, matching Python mrcfile’s auto-conversion behaviour for np.uint8 data.

Errors

Returns Error::ModeMismatch if the file mode is not Uint16.

Examples

use mrc::{create, VoxelBlock};
let mut writer = create("output.mrc")
    .shape([64, 64, 1])
    .mode::<u16>()
    .finish()?;
let block = VoxelBlock::new([0, 0, 0], [64, 64, 1], vec![0u8; 64 * 64])?;
writer.write_u8_block(&block)?;

pub fn write_block_as(&mut self, block: &VoxelBlock<f32>) -> Result<(), Error>

Write a block with automatic type conversion to the file’s mode.

The caller provides data as f32 and it is converted to the file’s on-disk mode. Supported conversions:

File mode	Conversion
Int8	f32 → i8 (clamped, SIMD)
Int16	f32 → i16 (clamped, SIMD)
Uint16	f32 → u16 (clamped, SIMD)
Float32	f32 → f32 (pass-through)
Float16	f32 → f16 (SIMD, requires f16 feature)

Complex modes and Packed4Bit are not convertible from real f32 data. Use write_block with the matching complex type instead.

Examples

use mrc::{create, VoxelBlock};
let mut writer = create("output.mrc")
    .shape([64, 64, 1])
    .mode::<u16>()
    .finish()?;
let block = VoxelBlock::new([0, 0, 0], [64, 64, 1], vec![0.0f32; 64 * 64])?;
writer.write_block_as(&block)?;

pub fn write_block_parallel<T: Voxel>( &mut self, block: &VoxelBlock<T>, ) -> Result<(), Error>

Write a block with parallel encoding and sequential file I/O.

Encoding is performed in parallel using all available cores. File writes are performed sequentially to ensure cross-platform compatibility.

For non-contiguous blocks (sub-XY slabs), this falls back to the serial write_block implementation.

Examples

use mrc::{create, VoxelBlock};
let mut writer = create("output.mrc")
    .shape([64, 64, 1])
    .mode::<f32>()
    .finish()?;
let block = VoxelBlock::new([0, 0, 0], [64, 64, 1], vec![0.0f32; 64 * 64])?;
writer.write_block_parallel(&block)?;

pub fn write_u4_block(&mut self, block: &VoxelBlock<u8>) -> Result<(), Error>

Write a block of u8 data (0–15 per voxel) by packing to 4-bit (Mode 101).

The file must have been created with Mode::Packed4Bit. Each u8 value is checked to be in the range 0–15; values exceeding 15 produce an error.

Examples

use mrc::{create, VoxelBlock};
let mut writer = create("output.mrc")
    .shape([64, 64, 1])
    .mode_raw(101)  // Packed4Bit
    .finish()?;
let data = vec![0u8; 64 * 64];
let block = VoxelBlock::new([0, 0, 0], [64, 64, 1], data)?;
writer.write_u4_block(&block)?;

pub fn finalize(&mut self) -> Result<(), Error>

Finalize the MRC file by rewriting the header.

Examples

use mrc::{create, VoxelBlock};
let mut writer = create("output.mrc")
    .shape([64, 64, 1])
    .mode::<f32>()
    .finish()?;
let block = VoxelBlock::new([0, 0, 0], [64, 64, 1], vec![0.0f32; 64 * 64])?;
writer.write_block(&block)?;
writer.finalize()?;

pub fn update_header_stats(&mut self) -> Result<(), Error>

Scan the written data block and update header statistics.

Examples

use mrc::{create, VoxelBlock};
let mut writer = create("output.mrc")
    .shape([64, 64, 1])
    .mode::<f32>()
    .finish()?;
let block = VoxelBlock::new([0, 0, 0], [64, 64, 1], vec![0.0f32; 64 * 64])?;
writer.write_block(&block)?;
writer.update_header_stats()?;
writer.finalize()?;

Trait Implementations

impl Debug for Writer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.