{"id":15592,"library":"dicomweb-client","title":"DICOMweb Client","description":"The `dicomweb-client` library provides a JavaScript implementation of the DICOMweb standard (PS3.18), enabling web applications to interact with DICOM image archives. It supports key RESTful services including STOW-RS (Store), QIDO-RS (Query), and WADO-RS (Retrieve) for DICOM objects. The current stable version is 0.11.2, with releases occurring regularly to address bugs and introduce features, as indicated by its recent update history (e.g., multiple updates in 2025). This library is designed to be lightweight, facilitating straightforward integration into web-based environments for handling medical imaging data. It ships with full TypeScript type definitions, enhancing developer experience in type-safe projects. A key differentiator is its focus on direct DICOMweb protocol implementation for both browser and Node.js environments, providing a foundational layer for building medical image viewers and processing tools without requiring extensive frameworks.","status":"active","version":"0.11.2","language":"javascript","source_language":"en","source_url":"https://github.com/dcmjs-org/dicomweb-client","tags":["javascript","dicom","dcmjs","dicomweb","wado-rs","qido-rs","stow-rs","typescript"],"install":[{"cmd":"npm install dicomweb-client","lang":"bash","label":"npm"},{"cmd":"yarn add dicomweb-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add dicomweb-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the primary class for interacting with DICOMweb services using ES Modules. For CommonJS environments, the correct usage is `const { DICOMwebClient } = require('dicomweb-client');`.","wrong":"const DICOMwebClient = require('dicomweb-client');","symbol":"DICOMwebClient","correct":"import { DICOMwebClient } from 'dicomweb-client';"},{"note":"When using the UMD build (e.g., via a script tag directly in HTML), the main class is exposed globally under `window.DICOMwebClient.api.DICOMwebClient`. Direct ES module imports will not work in this context.","wrong":"import { DICOMwebClient } from 'dicomweb-client';","symbol":"DICOMwebClient (UMD global)","correct":"<script src=\"https://unpkg.com/dicomweb-client\"></script>\n// Then access via window.DICOMwebClient.api.DICOMwebClient"},{"note":"For TypeScript users, import the `DICOMwebClientOptions` type to define configuration objects for the client, ensuring type safety for client initialization parameters.","symbol":"DICOMwebClientOptions (Type)","correct":"import type { DICOMwebClientOptions } from 'dicomweb-client';"}],"quickstart":{"code":"import { DICOMwebClient } from 'dicomweb-client';\n\nconst dicomwebUrl = process.env.DICOMWEB_URL ?? 'http://localhost:8080/dicomweb';\n\n// Initialize the client with basic configuration\nconst client = new DICOMwebClient({ url: dicomwebUrl });\n\nasync function runExample() {\n  try {\n    // 1. Search for studies (QIDO-RS)\n    console.log(`Searching for studies at ${dicomwebUrl}...`);\n    const studies = await client.searchForStudies();\n    console.log('Found studies (Study Instance UIDs):', studies.map(s => s['0020000D']?.Value[0] || 'N/A'));\n\n    // 2. Example of storing an instance with progress tracking (STOW-RS)\n    // In a real application, 'dataSet' would be an ArrayBuffer of a valid DICOM object.\n    // For demonstration, we use a dummy ArrayBuffer.\n    const dummyDicomDataSet = new ArrayBuffer(1024); // Represents a single DICOM file as ArrayBuffer\n\n    // Create a custom XMLHttpRequest to track upload progress\n    const request = new XMLHttpRequest();\n    request.upload.addEventListener('progress', evt => {\n      if (evt.lengthComputable) {\n        const percentComplete = Math.round((100 * evt.loaded) / evt.total);\n        console.log(`STOW-RS upload progress: ${percentComplete}%`);\n      }\n    });\n\n    const storeInstancesOptions = {\n      dataSets: [dummyDicomDataSet], // Pass an array of DICOM data sets\n      request, // Attach the custom XMLHttpRequest for progress\n    };\n\n    console.log('Attempting to store a dummy instance...');\n    await client.storeInstances(storeInstancesOptions);\n    console.log('Dummy instance stored successfully.');\n\n  } catch (error) {\n    console.error('An error occurred during DICOMweb operations:', error);\n    // Common errors include CORS issues, network failures, or server-side DICOM validation problems.\n  }\n}\n\nrunExample();\n","lang":"typescript","description":"Demonstrates initializing the DICOMweb client, performing a QIDO-RS search for studies, and executing a STOW-RS operation to store a dummy DICOM instance, including progress tracking via XMLHttpRequest."},"warnings":[{"fix":"Limit usage to development, research, or non-clinical applications. Always implement independent validation of results and do not deploy in environments where patient safety or diagnostic accuracy depends on the library's correctness.","message":"The library's README explicitly states it is 'work-in-progress and should not be used in clinical practice.' Users must be aware of its experimental nature and potential for unreliability in production medical systems where accuracy and validation are critical.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade to version 0.11.2 or later to benefit from the fix related to transfer syntax UID handling during image decoding. Ensure your DICOMweb server consistently provides the instance transfer syntax UID with image data.","message":"Prior to version 0.11.2, a bug in the library could lead to image decoding failures if the instance transfer syntax UID was not consistently provided by the DICOMweb server or was improperly handled by the client. This could result in images not being decodable.","severity":"gotcha","affected_versions":"<0.11.2"},{"fix":"When calling `client.storeInstances(options)`, populate the `options` object with a `request` property that points to a pre-configured `XMLHttpRequest` object. Attach event listeners (e.g., `progress`) to `request.upload` for tracking.","message":"To enable granular progress tracking or the cancellation of `storeInstances` (STOW-RS) operations, an existing `XMLHttpRequest` instance must be explicitly passed within the `options` parameter. The library's default `storeInstances` call does not expose these functionalities directly.","severity":"gotcha","affected_versions":">=0.8.2"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify the `dicomwebUrl` is correct and the server is running and accessible from your client's network. Check firewall rules and network connectivity.","cause":"Generic network error, often due to the DICOMweb server being unreachable, an invalid URL, or fundamental network configuration issues.","error":"Failed to fetch"},{"fix":"Configure your DICOMweb server to include appropriate CORS headers, allowing requests from your client's origin (e.g., `Access-Control-Allow-Origin: http://localhost:3000` or `*` for development).","cause":"The browser's Same-Origin Policy is preventing a cross-origin request because the DICOMweb server does not send the required `Access-Control-Allow-Origin` HTTP header.","error":"Access to fetch at 'http://localhost:8080/dicomweb/studies' from origin 'http://localhost:3000' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource."},{"fix":"Ensure you correctly instantiate the client using `const client = new DICOMwebClient({ url: '...' });`. Double-check your import statement: `import { DICOMwebClient } from 'dicomweb-client';`.","cause":"This error typically occurs when attempting to invoke methods on the `DICOMwebClient` class itself rather than on an instantiated object, or if the `client` variable is undefined due to an incorrect import or loading issue.","error":"TypeError: client.searchForStudies is not a function"},{"fix":"If using npm/bundlers, verify `npm install dicomweb-client` and `import { DICOMwebClient } from 'dicomweb-client';`. If using a UMD script tag, ensure the script is loaded before use and access it via `window.DICOMwebClient.api.DICOMwebClient`.","cause":"The `DICOMwebClient` global or imported module was not successfully loaded or made available in the current JavaScript scope.","error":"ReferenceError: DICOMwebClient is not defined"}],"ecosystem":"npm"}