Read MRC and CCP4 cryo-EM volumes in JavaScript

Import

import { openMrc, renderScientificPlane } from 'purejsimage/scientific'

Node.js example

import { FileSource } from 'purejsimage'
import { openMrc, sliceScientificVolume } from 'purejsimage/scientific'

const volume = await openMrc(await FileSource.open('map.mrc'))
const xz = sliceScientificVolume(volume, { axis: 'xz', index: 64 })
for await (const block of xz.readPlane({ z: 0, c: 0, t: 0 })) {
  console.log(block.width, block.height, block.data)
}

Browser example

const file = document.querySelector<HTMLInputElement>('#mrc')?.files?.[0]
if (!file) throw new Error('Choose an MRC file')
const volume = await openMrc(file, { maxInputBytes: file.size })
const display = await renderScientificPlane(volume, {
  plane: { z: 0, c: 0, t: 0 },
  range: { mode: 'percentile', low: 1, high: 99 },
})

Supported MODE values

Header and byte order

openMrc() reads the 1024-byte main header and retains dimensions, starts, unit-cell sampling, cell dimensions and angles, density statistics, space group, extended-header length, origin, version, machine stamp, RMS, and ordered labels. The MAP signature and machine stamp are required. Little-endian stamps 44 44 00 00 and 44 41 00 00, plus big-endian 11 11 00 00, are supported.

Axis mapping

MAPC, MAPR, and MAPS map stored columns, rows, and sections to logical X, Y, and Z. The public dataset dimensions always use logical coordinates. Default 1, 2, 3 layouts read contiguous X ranges. Other permutations remain bounded but may use strided sample reads.

Voxel spacing and origin

Positive cell dimensions divided by positive MX, MY, and MZ sampling counts become physicalSizeX, physicalSizeY, and physicalSizeZ in ångströms. Finite ORIGIN components become originX, originY, and originZ.

Bounded reads

The extended header is skipped by its validated NSYMBT byte count. Its unknown contents are not decoded. A selected logical Z plane and spatial region calculate source offsets directly. The complete volume is not materialized.

Slice and projection

const yz = sliceScientificVolume(volume, { axis: 'yz', index: 120 })
const maximum = projectScientificVolume(volume, { axis: 'z', mode: 'max' })
const mean = projectScientificVolume(volume, { axis: 'z', mode: 'mean' })

Unsupported features

Complex MODE 3 and 4, packed MODE 101, MRC writing, extended-header interpretation, volume-stack splitting, crystallographic symmetry operations, and handedness inference are not implemented. The MRC2014 header does not define data handedness consistently, so the reader does not guess it.

Official specification

CCP-EM MRC2014 format specification · CCP-EM MRC format overview

Scientific Raster Explorer · Volume slicing and projection · CBF guide · API