[![NPM version][npm-version-image]][npm-url] [![NPM downloads][npm-downloads-image]][npm-url] [![MIT License][license-image]][license-url] [![Build Status][travis-image]][travis-url] [![Coverage Status][coverage-image]][coverage-url]

dicomParser

dicomParser is a lightweight library for parsing DICOM P10 byte streams, as well as raw (not encapsulated in part 10) byte streams, in modern HTML5 based web browsers (IE10+), Node.js and Meteor. dicomParser is fast, easy to use and has no required external dependencies.

Live Examples

The best way to see the power of this library is to actually see it in use. A number of live examples are included that are not only useful but also show how to use dicomParser. Click here for a list of all live examples Make sure you try out the DICOM Dump with Data Dictionary which is a very useful tool and excellent example of most features.

Community

Have questions? Try posting on our google groups forum.

Install

Get a packaged source file:

• dicomParser.js
• dicomParser.min.js

Or install via NPM:

npm install dicom-parser

Or install via atmosphere for Meteor applications

meteor add chafey:dicom-parser

• Note - make sure you install pako if you need to support the Deflated Explicit VR Little Endian transfer syntax

Usage

// create a Uint8Array or node.js Buffer with the contents of the DICOM P10 byte stream
// you want to parse (e.g. XMLHttpRequest to a WADO server)
var arrayBuffer = new ArrayBuffer(bufferSize);
var byteArray = new Uint8Array(arrayBuffer);

try
{
    // Allow raw files
    const options = { TransferSyntaxUID: '1.2.840.10008.1.2' };
    // Parse the byte array to get a DataSet object that has the parsed contents
    var dataSet = dicomParser.parseDicom(byteArray, options);

    // access a string element
    var studyInstanceUid = dataSet.string('x0020000d');

    // get the pixel data element (contains the offset and length of the data)
    var pixelDataElement = dataSet.elements.x7fe00010;

    // create a typed array on the pixel data (this example assumes 16 bit unsigned data)
    var pixelData = new Uint16Array(dataSet.byteArray.buffer, pixelDataElement.dataOffset, pixelDataElement.length / 2);
}
catch(ex)
{
   console.log('Error parsing byte stream', ex);
}

See the live examples for more in depth usage of the library

Note that actually displaying DICOM images is quite complex due to the variety of pixel formats and compression algorithms that DICOM supports. If you are interested in displaying images, please take a look at the cornerstone library and the cornerstoneWADOImageLoader which uses this library to extract the pixel data from DICOM files and display the images with cornerstone library. You can find the actual code that extracts pixel data using this library here.

Options

dicomParser.parseDicom accepts an optional second argument that is an options object. The accepted properties are:

TransferSyntaxUID

A string value used as the default transfer syntax uid for parsing raw DICOM (not encapsualted in Part 10). For raw DICOM files, this value should be the LEI UID value.

untilTag

A tag in the form xggggeeee (where gggg is the hexadecimal group number and eeee is the hexadecimal element number, e.g. 'x7fe00010') that specifies the final tag to parse. Any tags occurring after this in the file will be ignored. Useful for partial reading of byte streams.

vrCallback

A callback that, given a tag, will return the two-character Value Representation associated with that tag (see PS 3.5 of the DICOM standard for more information). It may return undefined to indicate that the VR was not provided.

inflater

A callback that given the underlying byteArray and position of the deflated buffer returns a byteArray containing the DICOM P10 header and inflated data set concatenated together.

Key Features

• Parses all known valid DICOM Part 10 byte arrays
  • Explicit and implicit
  • Little endian and big endian
  • Deflated Explicit VR Little Endian transfer syntax
    • Uses zlib when running node.js
    • requires pako in web browsers
    • has callback to support use of other inflate libraries
• Supports all VR's including sequences
• Supports elements with undefined length
• Supports sequence items with undefined length
• Provides functions to convert from all VR types to native Javascript types
• Does not require a data dictionary
• Designed for use in the browser
• Each element exposes the offset and length of its data in the underlying byte stream
• Packaged using the module pattern, as an AMD module and as a CommonJS module for Node.js
• No external dependencies
• Supports extraction of encapsulated pixel data frames
  • Basic Offset Table decoded
  • Fragments decoded
  • Function to extract image frame when basic offset table is present
  • Function to extract image frame from fragments when no basic offset table is present
• Convenient utility functions to parse strings formatted in DA, TM and PN VRs and return JavaScript objects
• Convenient utility function to create a string version of an explicit element
• Convenient utility function to convert a parsed explicit dataSet into a javascript object
• Convenient utility function to generate a basic offset table for JPEG images
• Supports reading incomplete/partial byte streams
  • By specifying a tag to stop reading at (e.g. parseDicom(byteArray, {untilTag: "x7fe00010"}); )
  • By returning the elements parsed so far in the exception thrown during a parse error (the elements parsed will be in the dataSet property of the exception)
• Supports reading from Uint8Arrays and Node.js Buffers

Build System

This project uses Webpack to build the software.

Pre-requisites:

NodeJs - click to visit web site for installation instructions.

Common Tasks

Update dependencies (after each pull):

npm install

Running the build:

npm run build

Automatically running the build and unit tests after each source change:

npm run watch

Publish

This library uses semantic-release to publish packages. The syntax of commits against the master branch determine how the new version calculated.

<table> <tr> <th>Example Commit</th> <th>Release Type</th> </tr> <tr> <td>fix(pencil): stop graphite breaking when too much pressure applied</td> <td>Patch Release</td> </tr> <tr> <td>feat(pencil): add 'graphiteWidth' option</td> <td>Feature Release</td> </tr> <tr> <td> perf(pencil): remove graphiteWidth option<br /> <br /> BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reasons. </td> <td> Major Breaking Release </td> </tr> </table>

Backlog

Future:

• Add unit tests for sequence parsing functionality and encapsulated pixel frames
• Figure out how to automatically generate documentation from the source (jsdoc)
• Optimize findItemDelimitationItemAndSetElementLength() for speed
• Optimize functions in byteArrayParser.js for speed
• Add example that allows you to compare two sop instances against each other
• Figure out how to not have a global dicomParser object when used with an AMD loader
• See what needs to be done to support different character sets (assumes ASCII currently)
• Support for parsing from streams on Node.js and Meteor
• Switch to JavaScript ES6
• Separate the parsing logic from the dataSet creation logic (e.g. parsing generates events which dataSet creation logic creates the dataSet from). Similar concept to SAX parsers.
  • dataSet creation logic could filter out unwanted tags to improve performance of parse
  • dataSet creation logic could defer creation of sequence dataSets to improve performance of parse
• Function to parse non P10 byte streams given the byte stream and the transfer syntax
• Support for encrypted dicom

Contributors

• @neandrake for help with getting Node.js support
• @ggerade for implementing support for floats/doubles with VM > 1
• @yagni for bug fix related to parsing implicit little endian files and big endian support
• @snagytx, @doncharkowsky - for bug fix related to reading encapsulated frames
• @bbunderson, @jpambrun - bug fix for reading encapsulated frames
• @henryqdineen, adil.tiadi@gmail.com - bug report for sequences with undefined lengths and zero items
• @swederik - bug fixes on sequences with undefined lengths and zero items
• @jkrot - performance enhancement in byteArrayParser
• @cancan101 - issue related to multi-frame with multiple fragments and no basic offset table

Why another Javascript DICOM parsing library?

While building the WADO Image Loader for cornerstone, I couldn't find a Javascript DICOM parser that exactly met my needs. DICOM really isn't that hard to parse so I figured I would just make my own. Here are some of the key things that I really wanted out of