@ubercode/dcmtk

ALPHA PREVIEW — API may have breaking changes before 1.0. Use in production at your own risk.

Type-safe Node.js bindings for the DCMTK (DICOM Toolkit) command-line utilities. Wraps 51 DCMTK binaries, 6 long-lived server processes, a pooled DicomReceiver with auto-scaling workers, and a high-throughput DicomSender with queuing and backpressure — all with a modern async/await API, branded types, and the Result pattern for safe error handling.

Features

• 51 tool wrappers — async functions for every DCMTK command-line binary with verbosity control and full CLI flag coverage
• Network resilience — all 7 network tools support PDU sizing, ACSE/DIMSE/association timeouts, and hostname lookup control
• 6 server classes + DicomReceiver + DicomSender — long-lived DICOM listeners with typed EventEmitter APIs, a pooled receiver with auto-scaling workers, and a high-throughput sender with queuing, bucketing, and backpressure
• PacsClient — high-level PACS client with Echo, Query, Retrieve, and Store operations
• DICOM data layer — immutable DicomDataset, explicit ChangeSet builder, and DicomInstance unified file I/O
• Result pattern — all fallible operations return Result<T> instead of throwing
• Branded types — DicomTag, AETitle, Port, and more prevent primitive-type mix-ups at compile time
• Full TypeScript — strict mode, dual CJS/ESM build, complete .d.ts declarations
• AbortSignal support — cancel any operation with standard AbortController
• Zero native dependencies — delegates to system-installed DCMTK binaries

Prerequisites

• Node.js >= 20
• DCMTK installed on the system — set the DCMTK_PATH environment variable or install to a standard location (/usr/bin, /usr/local/bin, C:\Program Files\DCMTK). Pre-built Docker images with Node.js + DCMTK are available: michaelleehobbs/nodejs-dcmtk

Installation

npm install @ubercode/dcmtk
# or
pnpm add @ubercode/dcmtk
# or
yarn add @ubercode/dcmtk

Quick Start

Read DICOM metadata

import { dcm2json } from '@ubercode/dcmtk';

const result = await dcm2json('/path/to/image.dcm');

if (result.ok) {
    console.log(result.value.data); // DICOM JSON Model object
} else {
    console.error(result.error);
}

Network C-ECHO

import { echoscu } from '@ubercode/dcmtk';

const result = await echoscu({
    host: '127.0.0.1',
    port: 4242,
    calledAETitle: 'PACS',
    verbosity: 'verbose',
    associationTimeout: 10,
});

if (result.ok) {
    console.log('PACS is reachable');
}

Receive DICOM files

import { Dcmrecv } from '@ubercode/dcmtk';

const result = Dcmrecv.create({ port: 4242, outputDirectory: './incoming' });

if (result.ok) {
    const server = result.value;

    server.onEvent('C_STORE_REQUEST', data => {
        console.log(`Receiving: ${data.sopClassUID}`);
    });

    server.onEvent('STORED_FILE', data => {
        console.log(`Saved: ${data.filename}`);
    });

    await server.start();
}

For production workloads with concurrent connections, use DicomReceiver — a pooled receiver that manages multiple Dcmrecv workers behind a TCP proxy with auto-scaling.

Documentation

Tool Reference

51 async functions wrapping DCMTK command-line binaries, organized by category:

Server Reference

License

MIT - Michael Hobbs