DOCSEARCHbyAlgolia
Submit Docs

dicom-parser

repository·master·Indexed 20 days ago

https://github.com/cornerstonejs/dicomparser

A lightweight, high-performance JavaScript library for parsing DICOM Part 10 and raw byte streams in web browsers, Node.js, and Meteor. It provides access to DICOM elements and pixel data without requiring a full data dictionary, supporting both Explicit and Implicit VR, as well as Deflated Explicit VR Little Endian transfer syntaxes. Key features include on-demand decoding, partial reading via untilTag, and utility functions for parsing specific VRs like Person Name (PN), Time (TM), and Date (DA).

Tokens
2.5K
Snippets
7
Records
12
Agent score
73%

What's inside dicom-parser

  1. Key features of dicomParser

    master

    Parsing Capabilities

    • DICOM Part 10 Support: Parses all known valid DICOM Part 10 byte arrays (Explicit/Implicit, Little/Big Endian).
    • Deflated Transfer Syntax: Supports Deflated Explicit VR Little Endian (requires pako in browsers or zlib in Node.js).
    • Complex Structures: Supports all VRs including sequences, elements with undefined length, and sequence items with undefined length.
    • Pixel Data Extraction: Supports extraction of encapsulated pixel data frames, including Basic Offset Table decoding and fragment decoding.

    Developer Experience

    • On-Demand Decoding: Decodes individual elements only when requested, which improves performance and removes the need for a mandatory data dictionary.
    • Low Overhead: No external dependencies; designed for modern browsers (IE10+), Node.js, and Meteor.
    • Memory Efficient: Exposes the offset and length of each element's data within the underlying byte stream, allowing for direct typed array creation (e.g., for pixel data).
    • Partial Reading: Supports reading incomplete byte streams by specifying an untilTag or catching exceptions to retrieve partially parsed elements.

  2. Install dicomParser via npm or Meteor

    master

    You can install dicom-parser using npm for standard Node.js or web projects, or via Atmosphere for Meteor applications.

    Note: If you need to support the Deflated Explicit VR Little Endian transfer syntax in a web browser, you must also install the pako library.

    # Using npm
npm install dicom-parser

# Using Meteor
meteor add chafey:dicom-parser

  3. Run the Meteor test application example

    master

    To run the Meteor test application, which demonstrates how to use dicomParser within a Meteor environment, clone the repository and execute the Meteor command from the example directory.

    # Clone the repository
git clone https://github.com/cornerstonejs/dicomParser.git

# Navigate to the Meteor test app directory
cd examples/meteorTestApp

# Run the application using meteor
meteor

  4. Parse a DICOM byte stream with parseDicom()

    master

    To parse a DICOM P10 or raw byte stream, use dicomParser.parseDicom(). It accepts a Uint8Array or a Node.js Buffer as the first argument and an optional options object as the second.

    Once parsed, you receive a dataSet object. You can access elements using their tag (e.g., as a string like 'x0020000d') and use helper methods like .string() to convert values to native JavaScript types. For pixel data, you can access the element to get the dataOffset and length, then create a typed array (like Uint16Array) directly from the underlying buffer.

    // create a Uint8Array or node.js Buffer with the contents of the DICOM P10 byte stream
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);
}

  5. Configure parseDicom options

    master

    The dicomParser.parseDicom method accepts an optional configuration object with the following properties:

    PropertyTypeDescription
    TransferSyntaxUIDstringThe default transfer syntax UID used for parsing raw DICOM (not encapsulated in Part 10). For raw files, use the LEI UID value.
    untilTagstringA tag in the format xggggeeee (e.g., 'x7fe00010'). Parsing stops after this tag, which is useful for partial reading.
    vrCallbackfunctionA callback that receives a tag and returns its two-character Value Representation (VR). Return undefined if the VR is not provided.
    inflaterfunctionA callback that receives the byteArray and the position of the deflated buffer, returning a byteArray containing the concatenated DICOM P10 header and inflated data set.

  6. Convert DICOM DataSets to JavaScript objects with explicitDataSetToJS()

    master

    If you have a parsed DICOM DataSet and want to convert its contents into a plain JavaScript object, use explicitDataSetToJS(). This is useful for serializing data or working with standard JS object patterns instead of the specialized DataSet class.

    import { explicitDataSetToJS } from 'dicom-parser';

// const jsObject = explicitDataSetToJS(dataSet);

  7. Parse DICOM data with parseDicom()

    master

    The primary way to parse a DICOM file is using the parseDicom function. It supports both Little Endian Implicit (LEI) and Little Endian Explicit (LEE) transfer syntaxes. This function processes the byte stream to produce a DICOM data set.

    Commonly used constants for transfer syntax include:

    • LEI: Little Endian Implicit
    • LEE: Little Endian Explicit
    import dicomParser, { LEI, LEE } from 'dicom-parser';

// Example usage (conceptual):
// const byteArray = ...; 
// const dataSet = dicomParser.parseDicom(byteArray, LEE);

  8. Parse an implicit DICOM data set with parseDicomDataSetImplicit

    master

    Use parseDicomDataSetImplicit to parse a DICOM data set where the Value Representation (VR) is not explicitly stated in the byte stream and must be looked up via a dictionary. This function populates the elements object of the provided dataSet.

    Parameters

    • dataSet: The data set object to be populated. It must have an elements property.
    • byteStream: The byte stream object containing the DICOM data. It must have a position and a byteArray.
    • maxPosition (optional): The maximum position in the byte stream to read up to. If undefined, it defaults to dataSet.byteArray.length.
    • options (optional): An object containing configuration:
      • untilTag: If provided, parsing stops once this specific DICOM tag is encountered.
      • vrCallback: A callback function used during implicit parsing to determine the VR.
    // Example usage (conceptual)
// parseDicomDataSetImplicit(dataSet, byteStream, maxPosition, options)

parseDicomDataSetImplicit(dataSet, byteStream, undefined, { 
  untilTag: 0x00080010, 
  vrCallback: myVrCallback 
});

  9. Use utility functions for DICOM VR parsing

    master

    The library exports several utility functions to parse specific DICOM Value Representations (VRs):

    • parsePN: Parses Person Name (PN).
    • parseTM: Parses Time (TM).
    • parseDA: Parses Date (DA).
    • isStringVr: Checks if a VR is a string-based type.
    • isPrivateTag: Determines if a tag is a private DICOM tag.

  10. Parse an explicit DICOM data set with parseDicomDataSetExplicit

    master

    Use parseDicomDataSetExplicit to parse a DICOM data set where the Value Representation (VR) is explicitly stated in the byte stream. This function populates the elements object of the provided dataSet with parsed DICOM elements.

    Parameters

    • dataSet: The data set object to be populated. It must have an elements property.
    • byteStream: The byte stream object containing the DICOM data. It must have a position and a byteArray.
    • maxPosition (optional): The maximum position in the byte stream to read up to. If undefined, it defaults to the length of byteStream.byteArray.
    • options (optional): An object containing configuration:
      • untilTag: If provided, parsing stops once this specific DICOM tag is encountered.
    // Example usage (conceptual)
// parseDicomDataSetExplicit(dataSet, byteStream, maxPosition, options)

parseDicomDataSetExplicit(dataSet, byteStream, undefined, { untilTag: 0x00080010 });

  11. Parse DICOM DataSets explicitly or implicitly

    master

    The library provides specialized functions for parsing data sets when the transfer syntax is known:

    • parseDicomDataSetExplicit: Parses a DICOM data set using Explicit VR.
    • parseDicomDataSetImplicit: Parses a DICOM data set using Implicit VR.