Registry / web-framework / dicomweb-client

dicomweb-client

JSON →
library0.61.0jsnpmunverified

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.

npm install dicomweb-client
INSTALL
IMPORT
SIG · DICOMWEB-CLIENT
D
dicomweb-client
web-frameworkjavascriptv0.61.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

DICOMwebClient
import { DICOMwebClient } from 'dicomweb-client';
const DICOMwebClient = require('dicomweb-client');
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');`.
DICOMwebClient (UMD global)
<script src="https://unpkg.com/dicomweb-client"></script> // Then access via window.DICOMwebClient.api.DICOMwebClient
import { DICOMwebClient } from 'dicomweb-client';
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.
DICOMwebClientOptions (Type)
import type { DICOMwebClientOptions } from 'dicomweb-client';
For TypeScript users, import the `DICOMwebClientOptions` type to define configuration objects for the client, ensuring type safety for client initialization parameters.

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.

import { DICOMwebClient } from 'dicomweb-client'; const dicomwebUrl = process.env.DICOMWEB_URL ?? 'http://localhost:8080/dicomweb'; // Initialize the client with basic configuration const client = new DICOMwebClient({ url: dicomwebUrl }); async function runExample() { try { // 1. Search for studies (QIDO-RS) console.log(`Searching for studies at ${dicomwebUrl}...`); const studies = await client.searchForStudies(); console.log('Found studies (Study Instance UIDs):', studies.map(s => s['0020000D']?.Value[0] || 'N/A')); // 2. Example of storing an instance with progress tracking (STOW-RS) // In a real application, 'dataSet' would be an ArrayBuffer of a valid DICOM object. // For demonstration, we use a dummy ArrayBuffer. const dummyDicomDataSet = new ArrayBuffer(1024); // Represents a single DICOM file as ArrayBuffer // Create a custom XMLHttpRequest to track upload progress const request = new XMLHttpRequest(); request.upload.addEventListener('progress', evt => { if (evt.lengthComputable) { const percentComplete = Math.round((100 * evt.loaded) / evt.total); console.log(`STOW-RS upload progress: ${percentComplete}%`); } }); const storeInstancesOptions = { dataSets: [dummyDicomDataSet], // Pass an array of DICOM data sets request, // Attach the custom XMLHttpRequest for progress }; console.log('Attempting to store a dummy instance...'); await client.storeInstances(storeInstancesOptions); console.log('Dummy instance stored successfully.'); } catch (error) { console.error('An error occurred during DICOMweb operations:', error); // Common errors include CORS issues, network failures, or server-side DICOM validation problems. } } runExample();
Debug
Known issues
gotchaThe 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.
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.
affects: >=0.1.0
gotchaPrior 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.
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.
affects: <0.11.2
gotchaTo 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.
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.
affects: >=0.8.2
Errors
Common errors & fixes
Failed to fetch
Generic network error, often due to the DICOMweb server being unreachable, an invalid URL, or fundamental network configuration issues.
fix
Verify the `dicomwebUrl` is correct and the server is running and accessible from your client's network. Check firewall rules and network connectivity.
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.
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.
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).
TypeError: client.searchForStudies is not a function
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.
fix
Ensure you correctly instantiate the client using `const client = new DICOMwebClient({ url: '...' });`. Double-check your import statement: `import { DICOMwebClient } from 'dicomweb-client';`.
ReferenceError: DICOMwebClient is not defined
The `DICOMwebClient` global or imported module was not successfully loaded or made available in the current JavaScript scope.
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`.
Upgrade
Version history
0.61.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
14 hits · last 30 days
node
12
OpenAI (training)
1
Resources
dicomweb-client — npm install dicomweb-client · libregistry