@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