dicom-toolkit

Pure TypeScript DICOM parsing, ingestion, and export toolkit for the browser. All processing runs client-side — no data leaves the user's machine.

Install

bun add dicom-toolkit
# or
npm install dicom-toolkit

Optional peer dependencies (only needed for specific export formats):

# PDF export (waveforms, structured reports)
bun add dcmjs jspdf

# 3D mesh export (STL, OBJ, GLTF)
bun add three

# File download trigger
bun add file-saver

Usage

DICOM Parsing

import { fastParse, buildHierarchy, detectDataType } from "dicom-toolkit/dicom";

// Pass 1: fast parse (reads classification tags only, ~0.1ms/file)
const parsed = fastParse({ fileName: "CT001.dcm", arrayBuffer });

// Build patient/study/series/instance hierarchy
const { patients } = buildHierarchy(parsedFiles);

// Detect data type from SOP Class UID
const dataType = detectDataType(sopClassUID, numberOfFrames);

File Ingestion

import { classifyFile, extractZip, collectFromDragEvent } from "dicom-toolkit/ingestion";

// Classify a file by magic bytes
const fileType = classifyFile(fileName, new Uint8Array(buffer));

// Extract ZIP archives
const entries = extractZip(zipBuffer, "archive.zip");

// Collect files from a drag-drop event (main thread, needs DOM)
const payloads = await collectFromDragEvent(dragEvent);

Export

import {
  exportInstance,
  exportSeries,
  triggerDownload,
  getAvailableFormats,
  ExportFormat,
} from "dicom-toolkit/export";

// Check available formats for a data type
const formats = getAvailableFormats(instance.dataType);

// Export a single instance
const result = await exportInstance(instance, arrayBuffer, {
  format: ExportFormat.PNG,
});
await triggerDownload(result);

// Export a series as NIfTI
const nifti = await exportSeries(series, getArrayBuffer, {
  format: ExportFormat.NIFTI,
});
await triggerDownload(nifti);

Web Workers

Pre-bundled workers for off-main-thread processing:

import { getDicomParserWorkerURL, getIngestionWorkerURL } from "dicom-toolkit/workers";

const worker = new Worker(getDicomParserWorkerURL(), { type: "module" });
worker.postMessage({ type: "parse-files", files: payloads });

Sub-path Exports

| Import path | Contents | |---|---| | dicom-toolkit | Everything re-exported | | dicom-toolkit/dicom | Parsing, types, constants, specialized parsers | | dicom-toolkit/ingestion | File classification, ZIP, DICOMDIR, collection | | dicom-toolkit/export | Multi-format export (PNG, NIfTI, STL, CSV, PDF...) | | dicom-toolkit/workers | Worker URL factories |

Tree-shaking: importing only dicom-toolkit/dicom will not pull in Three.js, jsPDF, or other export-only dependencies.

Key Types

import type {
  DicomPatient,
  DicomStudy,
  DicomSeries,
  DicomInstance,
  DicomDataType,
  ParsedDicomFile,
} from "dicom-toolkit/dicom";

import type {
  RawFile,
  FilePayload,
  IngestionProgress,
} from "dicom-toolkit/ingestion";

import type {
  ExportFormat,
  ExportOptions,
  ExportResult,
} from "dicom-toolkit/export";

Architecture

• Two-pass parsing: Pass 1 reads only classification tags via dicom-parser (~0.1ms/file). Pass 2 uses dcmjs for full parsing, only on demand when a viewer opens.
• Web Workers: All CPU-intensive work (parsing, ingestion, export) runs in workers. Workers are self-contained bundles with zero external dependencies.
• Lazy loading: Export format handlers are dynamically imported — loading the image exporter doesn't pull in Three.js or jsPDF.

License

MIT