Struct Reader 

pub struct Reader { /* private fields */ }

Buffered MRC reader with lazy slice/slab iterators. In-memory buffered MRC file reader.

The entire file is read into memory on open, making this suitable for smaller files or when random access to any slice is needed.

For large files that don’t fit in RAM, consider MmapReader (requires the mmap feature).

Example

use mrc::Reader;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let reader = Reader::open("protein.mrc")?;
    for slice in reader.slices::<f32>() {
        let block = slice?;
        // block.data is Vec<f32>
    }
    Ok(())
}

Opening compressed files

Reader::open auto-detects gzip and bzip2 compression from magic bytes. Use open_plain to force plain (uncompressed) reading, open_gzip for gzip-only, or open_bzip2 for bzip2-only.

Implementations

impl Reader

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

Open an MRC file, auto-detecting gzip/bzip2 compression from magic bytes.

For plain files this is equivalent to open_plain. For gzip files it delegates to open_gzip; for bzip2 files to open_bzip2.

Decompression safety: Gzip and bzip2 files are decompressed with a hard cap of DEFAULT_MAX_DECOMPRESSED_BYTES (256 GiB) to prevent decompression bombs. Use open_gzip_with_limit or open_bzip2_with_limit for a custom limit.

Note: gzip and bzip2 support require the gzip and bzip2 feature flags respectively. Both are enabled by default. If a compressed file is opened without the corresponding feature, it will be misinterpreted as plain and fail with InvalidHeader.

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

Open a plain (uncompressed) MRC file.

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

Open in permissive mode, auto-detecting compression.

Non-fatal header issues (unusual MAP field, unexpected nversion, non-standard axis mapping, etc.) are collected as warning strings instead of causing a hard error. Only genuinely unreadable files (negative dimensions, unsupported mode, IO failure) return Err.

pub fn shape(&self) -> VolumeShape

Volume dimensions of the opened file.

pub fn mode(&self) -> Mode

Voxel data mode of the opened file.

pub fn header(&self) -> &Header

A reference to the parsed MRC header.

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

Read a block of raw voxel bytes from the file.

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.

impl Reader

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

Get a reference to the raw data bytes

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

Cross-check header statistics against actual data.

Computes dmin, dmax, dmean and rms from the 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 endian(&self) -> FileEndian

Get the file endianness

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

Get the extended header bytes, if any.

impl Reader

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

See ReaderMethods::slices

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

See ReaderMethods::slabs

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

See ReaderMethods::tiles

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

See ReaderMethods::volumes

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

See ReaderMethods::subregion

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

See ReaderMethods::read_volume

pub fn read_volume_u8(&self) -> Result<VoxelBlock<u8>, Error>

See ReaderMethods::read_volume_u8

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

See ReaderMethods::slices_u8

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

See ReaderMethods::slabs_u8

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

See ReaderMethods::slices_mode0

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

See ReaderMethods::slabs_mode0

pub fn convert<T>(&self) -> ConvertReader<'_, Reader, T>

where T: Voxel + ConvertFrom<f32>,

See ConvertMethods::convert

pub fn parse_extended_header(&self) -> ExtHeaderData

See [ReaderCore::parse_extended_header]

pub fn fei1_metadata(&self) -> Option<Vec<Fei1Metadata>>

See [ReaderCore::fei1_metadata]

pub fn fei2_metadata(&self) -> Option<Vec<Fei2Metadata>>

See [ReaderCore::fei2_metadata]

pub fn ccp4_records(&self) -> Option<Vec<Ccp4Record>>

See [ReaderCore::ccp4_records]

pub fn mrco_records(&self) -> Option<Vec<MrcoRecord>>

See [ReaderCore::mrco_records]

pub fn seri_records(&self) -> Option<Vec<SeriRecord>>

See [ReaderCore::seri_records]

pub fn agar_records(&self) -> Option<Vec<AgarRecord>>

See [ReaderCore::agar_records]

pub fn imod_metadata(&self) -> Option<ImodMetadata>

See [ReaderCore::imod_metadata]

impl Reader

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

Open a gzip-compressed MRC file.

Requires the gzip feature (enabled by default). The file is decompressed into memory with a safety limit of DEFAULT_MAX_DECOMPRESSED_BYTES (256 GiB). To set a custom limit, use open_gzip_with_limit.

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

Open a gzip-compressed MRC file with a custom decompression byte limit.

The decompressed stream is capped at max_bytes before the header is parsed. If the stream exceeds this limit, a decompression-bomb error is returned. Use the default open_gzip for the built-in 256 GiB safety limit.

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

Open a gzip-compressed MRC file in permissive mode.

Trait Implementations

impl Debug for Reader

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

Formats the value using the given formatter.