@warpem/mrc-parser

Parser for MRC (Medical Research Council) format files, commonly used in cryo-EM (cryogenic electron microscopy) for storing 2D images, 3D volumes, and image stacks.

Install

npm install @warpem/mrc-parser

Usage

Parse an entire MRC file

import { parseMRC } from "@warpem/mrc-parser";

const buffer = await fs.readFile("map.mrc");
const { header, data } = parseMRC(buffer.buffer);

console.log(header.dimensions); // { x: 256, y: 256, z: 256 }
console.log(data.length);       // 16777216

Parse header only, then read individual slices

import { parseHeader, readSlice } from "@warpem/mrc-parser";

const buffer = await fs.readFile("stack.mrc");
const header = parseHeader(buffer.buffer);

console.log(`${header.dimensions.z} slices, ${header.dimensions.x}x${header.dimensions.y} each`);

const slice0 = readSlice(buffer.buffer, header, 0);

Fetch from a URL with progress

import { fetchMRC } from "@warpem/mrc-parser";

const { header, data } = await fetchMRC("/api/file/abc123", {
  onProgress: (received, total) => {
    console.log(`${((received / total) * 100).toFixed(0)}%`);
  },
});

Fetch only the header (Range request)

import { fetchMRCHeader, fetchSlice } from "@warpem/mrc-parser";

const header = await fetchMRCHeader("/api/file/abc123");
const middleSlice = await fetchSlice("/api/file/abc123", header, Math.floor(header.dimensions.z / 2));

API

Types

Type	Description
Int3	{ x: number; y: number; z: number } — integer triplet
Float3	{ x: number; y: number; z: number } — float triplet
MRCDataType	Data mode enum: Byte, Short, Float, Half, UnsignedShort, ShortComplex, FloatComplex, RGB
MRCHeader	Parsed header with dimensions, pixel size, statistics, labels, and IMOD metadata
ReadOptions	{ sliceStart?: number; sliceEnd?: number }
FetchOptions	{ signal?: AbortSignal; onProgress?: (received, total) => void }

Functions

Function	Description
parseHeader(buffer)	Parse an MRC header from an ArrayBuffer
readData(buffer, header, options?)	Read voxel data (all or a slice range) as Float32Array
readSlice(buffer, header, sliceIndex)	Read a single slice as Float32Array
parseMRC(buffer)	Parse header + all data in one call
fetchMRC(url, options?)	Fetch and parse a complete MRC file
fetchMRCHeader(url, options?)	Fetch only the header via Range request
fetchSlice(url, header, sliceIndex, options?)	Fetch a single slice via Range request
fetchSlices(url, header, sliceStart, sliceEnd, options?)	Fetch a range of slices via Range request

All data is decoded into Float32Array regardless of the source data type (Byte, Short, Half, etc.).

Supported MRC modes

Mode	Description	Bytes/element
0	Unsigned 8-bit integer	1
1	Signed 16-bit integer	2
2	32-bit float	4
3	Complex (2 × int16)	4
4	Complex (2 × float32)	8
6	Unsigned 16-bit integer	2
12	16-bit float (half)	2
16	RGB (3 × uint8)	3

License

BSD-3-Clause