Struct MmapReader 

pub struct MmapReader { /* private fields */ }

Memory-mapped MRC reader (requires mmap feature). Memory-mapped MRC file reader.

Maps the file into the process address space rather than loading it into a heap-allocated buffer. The OS pages data in and out on demand, making this ideal for very large files or when only a small subset of slices needs to be accessed.

Zero-copy access

slab_as returns &[T] directly into the memory map with no allocation — this is true zero-copy. It requires the file endianness to match the host and T to match the voxel mode.

data_bytes returns a &[u8] view of the raw voxel data, also zero-copy.

For non-native-endian files or type-mismatched reads, use subregion which always allocates.

Example

use mrc::MmapReader;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let reader = MmapReader::open("large_file.mrc")?;
    println!("Dimensions: {:?}", reader.shape());

    // Zero-copy typed access (native endian, mode-matching type)
    let slice: &[f32] = reader.slab_as::<f32>(0, 1)?;
    println!("First slice has {} voxels", slice.len());

    // Generic typed iteration (always allocates per block)
    for slice in reader.slices::<f32>() {
        let block = slice?;
        // process block.data
    }
    Ok(())
}

Implementations

impl MmapReader

pub fn slices<T: Voxel>(&self) -> RegionIter<'_, T, MmapReader, SliceStepper>

Iterate over Z-slices (1 voxel thick along Z) as VoxelBlocks.

Each item is a contiguous full-XY slab at one Z position. See also slices_f32 for automatic mode conversion.

pub fn slabs<T: Voxel>( &self, k: usize, ) -> RegionIter<'_, T, MmapReader, SlabStepper>

Iterate over Z-slabs of k slices as VoxelBlocks.

Each item is a contiguous full-XY slab of k Z-planes. The final slab may be shorter than k near the end of the volume. See also slabs_f32 for automatic mode conversion.

pub fn tiles<T: Voxel>( &self, tile_shape: [usize; 3], ) -> RegionIter<'_, T, MmapReader, TileStepper>

Iterate over 3D tiles of the given shape as VoxelBlocks.

The volume is partitioned into non-overlapping tiles of size tile_shape. Tiles at the trailing edges may be truncated to fit the volume bounds.

pub fn images<T: Voxel>(&self) -> RegionIter<'_, T, MmapReader, SliceStepper>

Alias for slices.

pub fn image_stack<T: Voxel>( &self, k: usize, ) -> RegionIter<'_, T, MmapReader, SlabStepper>

Alias for slabs.

pub fn planes<T: Voxel>(&self) -> RegionIter<'_, T, MmapReader, SliceStepper>

Alias for slices.

pub fn plane_stack<T: Voxel>( &self, k: usize, ) -> RegionIter<'_, T, MmapReader, SlabStepper>

Alias for slabs.

pub fn volumes<T: Voxel>( &self, ) -> Result<RegionIter<'_, T, MmapReader, SlabStepper>, Error>

Iterate over sub-volumes of a volume-stack file.

Each sub-volume is mz slices thick, where mz is taken from the header’s sampling field.

Errors

Returns Error::NotAVolumeStack if the file is not a volume stack (ispg not in 401–630).

pub fn subregion<T: Voxel>( &self, offset: [usize; 3], shape: [usize; 3], ) -> Result<VoxelBlock<T>, Error>

Read a single arbitrary 3D sub-region as a VoxelBlock.

Unlike the iterators (slices, slabs, tiles), this reads exactly one block at the given offset and shape. Useful for random-access reads of specific regions.

Errors

Returns Error::BoundsError if the region exceeds volume bounds. Returns Error::ModeMismatch if T does not match the file mode.

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

Read the entire volume as a VoxelBlock<T>.

Shorthand for subregion([0, 0, 0], [nx, ny, nz]).

Errors

Returns Error::ModeMismatch if T does not match the file mode.

pub fn read_volume_f32(&self) -> Result<VoxelBlock<f32>, Error>

Read the entire volume as f32, converting from any mode.

Supports all real-valued modes (Int8, Int16, Uint16, Float32, Float16) and converts complex modes via magnitude. Returns the full volume in a single VoxelBlock<f32>.

Errors

Returns Error::UnsupportedMode for Mode 101 (Packed4Bit).

pub fn slices_f32( &self, ) -> Box<dyn Iterator<Item = Result<VoxelBlock<f32>, Error>> + '_>

Iterate over Z-slices, converting each to f32 automatically.

Supports all real-valued MRC modes (Int8, Int16, Uint16, Float32, Float16) and converts complex modes via magnitude. This is the most convenient method for viewing or processing cryo-EM data.

Errors

Returns Error::UnsupportedMode for Mode 101 (Packed4Bit). Returns Error::ModeMismatch if no matching conversion exists.

pub fn slabs_f32( &self, k: usize, ) -> Box<dyn Iterator<Item = Result<VoxelBlock<f32>, Error>> + '_>

Iterate over Z-slabs, converting each to f32 automatically.

See slices_f32 for supported mode conversions.

pub fn slices_u8( &self, ) -> Box<dyn Iterator<Item = Result<VoxelBlock<u8>, Error>> + '_>

Iterate over Z-slices as u8, narrowing from Mode 6 (Uint16).

Only works on files stored as Mode::Uint16. Each 16-bit value is narrowed to 8 bits; values exceeding 255 produce an error.

See also slices_mode0 for Mode 0 (Int8) files.

Errors

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

pub fn slices_mode0( &self, interp: M0Interpretation, ) -> Box<dyn Iterator<Item = Result<VoxelBlock<f32>, Error>> + '_>

Iterate over Z-slices of a Mode 0 file, interpreting as signed or unsigned.

Mode 0 (Int8) is ambiguous — some files store unsigned 8-bit data. Use this method to control interpretation via M0Interpretation.

Errors

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

pub fn slabs_mode0( &self, k: usize, interp: M0Interpretation, ) -> Box<dyn Iterator<Item = Result<VoxelBlock<f32>, Error>> + '_>

Iterate over Z-slabs of a Mode 0 file, interpreting as signed or unsigned.

Like slices_mode0 but reads k slices per iteration for improved throughput.

Errors

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

impl MmapReader

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self, Error>

Open an MRC file via memory mapping.

The file is mapped read-only into the process address space. The OS will page data in/out as needed, making this efficient for large files.

pub fn open_permissive<P: AsRef<Path>>( path: P, ) -> Result<(Self, Vec<String>), Error>

Open an MRC file via memory mapping in permissive mode.

Non-fatal header issues are collected as warning strings instead of causing hard errors.

pub fn shape(&self) -> VolumeShape

Get the volume shape (dimensions).

pub fn mode(&self) -> Mode

Get the voxel mode (data type) of the file.

Falls back to Mode::Float32 if the header mode value is not recognised.

pub fn header(&self) -> &Header

Get a reference to the header.

pub fn endian(&self) -> FileEndian

Get the file endianness.

pub fn ext_header_bytes(&self) -> &[u8]

Get the extended header bytes, if any.

pub fn data_bytes(&self) -> &[u8]

Get the raw data bytes from the memory map.

This returns a slice starting at the beginning of voxel data (after the header and extended header).

pub fn slab_as<T: Voxel>(&self, z: usize, k: usize) -> Result<&[T], Error>

Zero-copy read of a contiguous Z-slab as &[T].

Returns a slice pointing directly into the memory map, avoiding any allocation or copying. This is the most efficient way to access voxel data when the file endianness matches the host.

Requirements

• T::MODE must match the file’s voxel mode
• File endianness must be native (host byte order)
• k > 0 and z + k <= nz

For non-native-endian files or type mismatches, use subregion instead.

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

Cross-check header statistics against actual data.

Computes dmin, dmax, dmean and rms from the memory-mapped data block and compares them with the header values using a 1 % relative tolerance (matching Python mrcfile’s np.isclose(rtol=0.01)).

Errors

Returns Error::StatsMismatch if any statistic deviates by more than 1 %.

pub fn read_block_bytes( &self, offset: [usize; 3], shape: [usize; 3], ) -> Result<Vec<u8>, Error>

Read a block of voxels as raw bytes from the mmap.

Supports arbitrary sub-blocks; non-contiguous regions are gathered into a contiguous buffer automatically.

pub fn read_block<T: Voxel>( &self, offset: [usize; 3], shape: [usize; 3], ) -> Result<VoxelBlock<T>, Error>

👎Deprecated since 0.2.4:

use subregion instead

Read and decode a block of voxels to the specified type.

Returns an error if T does not match the file’s voxel mode.

Use subregion instead — it is available on all reader types and behaves identically.

Trait Implementations

impl Debug for MmapReader

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

Formats the value using the given formatter.