Init

Author: dtegunov

.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm test

.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          registry-url: https://registry.npmjs.org
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

README.md

@@ -0,0 +1,102 @@
+# @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
+
+```bash
+npm install @warpem/mrc-parser
+```
+
+## Usage
+
+### Parse an entire MRC file
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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)
+
+```ts
+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