DICOMweb Client

Common errors

• Failed to fetch

  cause 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.

  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.
  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

  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.
  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

  cause 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`.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install dicomweb-client npm
• yarn add dicomweb-client yarn
• pnpm add dicomweb-client pnpm

Imports

• DICOMwebClient
  wrong:

  const DICOMwebClient = require('dicomweb-client');

  correct:

  import { DICOMwebClient } from '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)
  wrong:

  import { DICOMwebClient } from 'dicomweb-client';

  correct:

  <script src="https://unpkg.com/dicomweb-client"></script>
  // Then access via window.DICOMwebClient.api.DICOMwebClient

  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.

Quickstart

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();