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 (optional)

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] (1.2.840.10008.1.2.4.70)*
• 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. Please check the respecting Wiki section for more examples.

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.

License

dcmjs-imaging is released under the MIT License.