Dcmjs-imaging NPM

dcmjs-imaging

DICOM image and overlay rendering pipeline for Node.js and browser using Steve Pieper's dcmjs library. This library was inspired by the rendering pipelines of fo-dicom and mdcm.

Note

This effort is a work-in-progress and should not be used for production or clinical purposes.

Install

Node.js

npm install dcmjs-imaging

Browser

<script type="text/javascript" src="https://unpkg.com/dcmjs"></script>
<script type="text/javascript" src="https://unpkg.com/dcmjs-imaging"></script>

Build

npm install
npm run build

Build native decoders WebAssembly

cd wasm
./build.sh

Emscripten SDK (emsdk) is required.

Features

Renders single and multi-frame datasets with optional adjustment of window/level and color palette.
Decodes all major transfer syntaxes using a native WebAssembly module.
Handles color and grayscale datasets, from 1 to 32 bits allocated, with signed, unsigned and float pixel values.
Outputs RGBA pixel arrays, suitable for use with HTML5 Canvas and WebGL, or other imaging libraries.
Provides a common bundle for both Node.js and browser.

Supported Transfer Syntaxes

Implicit VR Little Endian (1.2.840.10008.1.2)
Explicit VR Little Endian (1.2.840.10008.1.2.1)
Deflated Explicit VR Little Endian (1.2.840.10008.1.2.1.99)
Explicit VR Big Endian (1.2.840.10008.1.2.2)
RLE Lossless (1.2.840.10008.1.2.5)*
JPEG Baseline - Process 1 (1.2.840.10008.1.2.4.50)*
JPEG Baseline - Processes 2 & 4 (1.2.840.10008.1.2.4.51)*
JPEG Lossless, Nonhierarchical - Processes 14 (1.2.840.10008.1.2.4.57)*
JPEG Lossless, Nonhierarchical, First-Order Prediction - Processes 14 Selection Value 1*
JPEG-LS Lossless Image Compression (1.2.840.10008.1.2.4.80)*
JPEG-LS Lossy Image Compression - Near-Lossless (1.2.840.10008.1.2.4.81)*
JPEG 2000 Image Compression - Lossless Only (1.2.840.10008.1.2.4.90)*
JPEG 2000 Image Compression (1.2.840.10008.1.2.4.91)*
High Throughput JPEG 2000 Image Compression - Lossless Only (1.2.840.10008.1.2.4.201)*
High Throughput JPEG 2000 with RPCL Options Image Compression - Lossless Only (1.2.840.10008.1.2.4.202)*
High Throughput JPEG 2000 Image Compression (1.2.840.10008.1.2.4.203)*

*: Syntax is decoded using the native decoders WebAssembly.

Usage

Basic image rendering

// Import objects in Node.js
const dcmjsImaging = require('dcmjs-imaging');
const { DicomImage, NativePixelDecoder } = dcmjsImaging;

// Import objects in Browser
const { DicomImage, NativePixelDecoder } = window.dcmjsImaging;

// Optionally register native decoders WebAssembly.
// If native decoders are not registered, only 
// uncompressed syntaxes would be able to be rendered.
await NativePixelDecoder.initializeAsync();

// Create an ArrayBuffer with the contents of the DICOM P10 byte stream.
const image = new DicomImage(arrayBuffer);

// Render image.
const renderingResult = image.render();

// Rendered pixels in an RGBA ArrayBuffer.
const renderedPixels = renderingResult.pixels;
// Rendered width.
const width = renderingResult.width;
// Rendered height.
const height = renderingResult.height;

Advanced image rendering

// Import objects in Node.js
const dcmjsImaging = require('dcmjs-imaging');
const { DicomImage, WindowLevel, NativePixelDecoder } = dcmjsImaging;
const { StandardColorPalette } = dcmjsImaging.constants;

// Import objects in Browser
const { DicomImage, WindowLevel, NativePixelDecoder } = window.dcmjsImaging;
const { StandardColorPalette } = window.dcmjsImaging.constants;

// Create native decoders WebAssembly initialization options.
const initOpts = {
  // Optionally, provide the path or URL to WebAssembly module.
  // If empty or undefined, the module is trying to be resolved 
  // within the same directory.
  webAssemblyModulePathOrUrl: undefined,
  // Optional flag to enable native decoder message logging.
  // If not provided, the native decoder message logging is disabled.
  logNativeDecodersMessages: false
};
// Optionally register native decoders WebAssembly.
// If native decoders are not registered, only 
// uncompressed syntaxes would be able to be rendered.
await NativePixelDecoder.initializeAsync(initOpts);

// Create an ArrayBuffer with the contents of the DICOM P10 byte stream.
const image = new DicomImage(arrayBuffer);

// Create image rendering options.
const renderingOpts = {
  // Optional frame index, in case of multiframe datasets.
  // If not provided, the first frame is rendered.
  frame: 0,
  // Optional user-provided window/level.
  // If not provided, the rendering pipeline calculates it 
  // from DICOM tag information or pixel values.
  windowLevel: new WindowLevel(windowWidth, windowLevel),
  // Optional flag to indicate whether overlays should be rendered.
  // If not provided, the overlays are rendered.
  renderOverlays: true,
  // Optional flag to indicate whether histograms should be calculated.
  // If not provided, the histograms are not calculated.
  calculateHistograms: false,
  // Optional standard color palette.
  // If not provided, the grayscale palette is used.
  colorPalette: StandardColorPalette.Grayscale
};

// Render image.
const renderingResult = image.render(renderingOpts);

// Rendered pixels in an RGBA ArrayBuffer.
const renderedPixels = renderingResult.pixels;
// Rendered frame index.
const frame = renderingResult.frame;
// Rendered width.
const width = renderingResult.width;
// Rendered height.
const height = renderingResult.height;
// Window/level used to render the pixels.
// In case of color images, windowLevel should not be present.
const windowLevel = renderingResult.windowLevel;
// Array of calculated per-channel histograms.
// In case calculateHistograms rendering option is false
// histograms should not be present.
const histograms = renderingResult.histograms;
// Color palette used to render the pixels.
// In case of color images, colorPalette should not be present.
const colorPalette = renderingResult.colorPalette;

Please check a live example here.

Related libraries

dcmjs-dimse - DICOM DIMSE implementation for Node.js using dcmjs.
dcmjs-ecg - DICOM electrocardiography (ECG) rendering for Node.js and browser using dcmjs.