{"id":13069,"library":"dicom-parser","title":"DICOM Parser","description":"dicom-parser is a JavaScript library designed for parsing DICOM Part 10 byte streams, as well as raw (non-Part 10) DICOM data. It is compatible with modern web browsers (IE10+), Node.js environments, and Meteor applications. The current stable version is 1.8.21, with releases primarily focusing on bug fixes and minor improvements, maintaining an active development cadence. A key differentiator is its lightweight nature and minimal external dependencies, making it efficient for integration into various projects. While it generally has no required external dependencies, users needing to support the Deflated Explicit VR Little Endian transfer syntax must explicitly install `pako`. It forms a foundational component within the wider CornerstoneJS ecosystem, often used by libraries like `cornerstoneWADOImageLoader` for extracting pixel data.","status":"active","version":"1.8.21","language":"javascript","source_language":"en","source_url":"https://github.com/cornerstonejs/dicomParser","tags":["javascript","DICOM","medical","imaging"],"install":[{"cmd":"npm install dicom-parser","lang":"bash","label":"npm"},{"cmd":"yarn add dicom-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add dicom-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for supporting the Deflated Explicit VR Little Endian transfer syntax for DICOM compression.","package":"pako","optional":true}],"imports":[{"note":"The library primarily exports a default object containing all parsing functionalities, including `parseDicom`.","wrong":"import { parseDicom } from 'dicom-parser'","symbol":"dicomParser","correct":"import dicomParser from 'dicom-parser'"},{"note":"Standard CommonJS import for Node.js environments. The `parseDicom` function is a method of the `dicomParser` object.","wrong":"const { parseDicom } = require('dicom-parser')","symbol":"dicomParser (CommonJS)","correct":"const dicomParser = require('dicom-parser')"},{"note":"Used for type-checking when working with TypeScript. The `DataSet` type represents the object returned by `parseDicom`.","symbol":"DataSet (Type)","correct":"import type { DataSet } from 'dicom-parser'"}],"quickstart":{"code":"// In a real application, `byteArray` would come from a DICOM P10 byte stream\n// (e.g., XMLHttpRequest, file read, or network stream).\n// This is a minimal example to demonstrate parsing structure.\nconst bufferSize = 256; // Dummy size for example\nconst arrayBuffer = new ArrayBuffer(bufferSize);\nconst byteArray = new Uint8Array(arrayBuffer);\n\n// For a valid DICOM file, you'd populate byteArray with the actual data.\n// For demonstration, let's pretend it has some minimal structure.\n// NOTE: This dummy byteArray will likely *not* produce a valid DICOM dataset.\n// It serves to show the API usage.\n\ntry {\n    // Allows parsing raw DICOM (not Part 10 encapsulated) by specifying TransferSyntaxUID.\n    // For disk files, '1.2.840.10008.1.2' (Little Endian Implicit) is a common default.\n    const options = { TransferSyntaxUID: '1.2.840.10008.1.2' };\n    \n    // Parse the byte array to get a DataSet object containing the parsed contents.\n    const dataSet = dicomParser.parseDicom(byteArray, options);\n\n    // Access a string element (e.g., Study Instance UID)\n    // In a real DICOM, 'x0020000d' would be the tag for StudyInstanceUID.\n    // This will likely be undefined in our dummy example.\n    const studyInstanceUid = dataSet.string('x0020000d');\n    console.log('Study Instance UID:', studyInstanceUid);\n\n    // Get the pixel data element (contains the offset and length of the data).\n    // Tag 'x7fe00010' is typically for Pixel Data.\n    const pixelDataElement = dataSet.elements.x7fe00010;\n    console.log('Pixel Data Element:', pixelDataElement);\n\n    // If pixelDataElement exists and has data, create a typed array.\n    // This example assumes 16-bit unsigned data, but actual type varies by DICOM.\n    if (pixelDataElement && pixelDataElement.length > 0) {\n        const pixelData = new Uint16Array(\n            dataSet.byteArray.buffer,\n            pixelDataElement.dataOffset,\n            pixelDataElement.length / 2\n        );\n        console.log('First few pixel data values:', pixelData.slice(0, 10));\n    } else {\n        console.log('No pixel data element found or it is empty.');\n    }\n\n} catch (ex) {\n   console.error('Error parsing byte stream:', ex.message);\n}","lang":"javascript","description":"Demonstrates how to initialize a byte array (mocking DICOM data) and use `dicomParser.parseDicom` to extract elements like Study Instance UID and Pixel Data, including options for raw DICOM parsing."},"warnings":[{"fix":"Install pako: `npm install pako` or `yarn add pako`.","message":"To parse DICOM files compressed with the Deflated Explicit VR Little Endian transfer syntax, the 'pako' library must be manually installed as a separate dependency. It is not bundled or automatically installed by dicom-parser.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Pass an options object to dicomParser.parseDicom with the appropriate TransferSyntaxUID, e.g., `{ TransferSyntaxUID: '1.2.840.10008.1.2' }` for Little Endian Implicit.","message":"When parsing raw DICOM byte streams (i.e., not DICOM Part 10 encapsulated files), you must provide the 'TransferSyntaxUID' option to 'parseDicom'. Failure to do so may result in incorrect parsing or errors.","severity":"gotcha","affected_versions":">=1.8.12"},{"fix":"Refer to the DICOM standard or a data dictionary to find the correct hexadecimal tag for the desired element. Always use the 'x' prefix, e.g., `dataSet.string('x0020000d')`.","message":"DICOM elements are accessed using their hexadecimal tag representations (e.g., 'x0020000d' for Study Instance UID) as strings, not their friendly names. Ensure correct hexadecimal formatting, prefixed with 'x'.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the input `byteArray` contains a complete and valid DICOM Part 10 file or raw DICOM data. Verify the integrity of the byte stream from its source.","cause":"Attempting to parse an incomplete or malformed DICOM byte stream.","error":"Error parsing byte stream: Buffer too small to parse element tag"},{"fix":"Before accessing, check if the DICOM tag exists in `dataSet.elements` or if `dataSet.string()` or `dataSet.uint16()` (etc.) returns a defined value. Ensure the DICOM file contains the expected element.","cause":"Attempting to access a DICOM element (e.g., `dataSet.string('x0020000d')`) that does not exist or was not successfully parsed in the `DataSet` object.","error":"Cannot read properties of undefined (reading 'string')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}