Cornerstone WADO Image Loader

To load images using the WADO Image Loader, you must use the wadouri: prefix in your image IDs. While the dicomweb prefix is currently supported, it is deprecated and will be removed in future versions.

Supported formats include:

• Absolute URLs: Full web addresses starting with http:// or https://.
• Relative URLs: Paths relative to the current origin.
• WADO-URI URLs: Specific WADO-URI request strings containing parameters like studyUID, seriesUID, and transferSyntax.
• File Endpoints: Direct links to DICOM files (e.g., from an Orthanc instance).

Important: The web server hosting the DICOM files must support Cross-Origin Resource Sharing (CORS). If CORS is not enabled on the source server, image loading will fail. You can resolve this by enabling CORS on the server or using a reverse proxy to inject the necessary CORS headers.

// Absolute URL
wadouri:http://cornerstonetech.org/images/ClearCanvas/USEcho/IM00001

// Relative URL
wadouri:/images/ClearCanvas/USEcho/IM00001

// WADO-URI URL
wadouri:http://localhost:3333/wado?requestType=WADO&studyUID=1.3.6.1.4.1.25403.166563008443.5076.20120418075541.5076.20120418075541.2&objectUID=1.3.6.1.4.1.25403.166563008443.5076.20120418075557.1&contentType=application%2Fdicom&transferSyntax=1.2.840.10008.1.2.1

// Orthanc file endpoint
wadouri:http://localhost:8042/instances/8cce70aa-576ad738-b76cb63f-caedb3c7-2b213aae/file

You can extend the framework to run CPU-intensive custom logic in the background. Follow these steps:

1. Create the Worker File

Create a new JavaScript file (e.g., myTask.js). Inside this file, register your task using self.registerTaskHandler():

self.registerTaskHandler({
  taskType: 'myCustomTask', // Unique string to identify the task
  initialize: (config) => {
    // Called when worker is first initialized
    // 'config' is the taskConfiguration object from initialize()
  },
  handler: (data, callback) => {
    // 'data' is the object passed from the UI thread
    // 'callback' is used to return the result
    
    const result = { processed: true };
    const transferList = []; // Optional: array of objects to transfer via postMessage
    
    callback(result, transferList);
  }
});

2. Register the Task Path

In your main application thread, add the path to your new file in the webWorkerTaskPaths array during initialization:

cornerstoneWADOImageLoader.webWorkerManager.initialize({
  webWorkerTaskPaths: ['path/to/myTask.js']
});

3. Queue the Task from the UI Thread

Use cornerstoneWADOImageLoader.webWorkerManager.addTask() to execute the task. This returns a promise that resolves with the result returned by the worker's callback.

const task = cornerstoneWADOImageLoader.webWorkerManager.addTask(
  'myCustomTask', // Must match taskType
  { inputData: 123 }, // The 'data' object
  1 // Optional priority (lower numbers = higher priority; default is 0)
);

task.then((result) => {
  console.log('Task completed:', result);
});

cornerstoneWADOImageLoader.webWorkerManager.addTask(
  'myCustomTask',
  { inputData: 123 },
  1
).then((result) => {
  console.log('Task completed:', result);
});

Version 4.x introduces WebAssembly (WASM) support for codecs, which improves performance and reduces bundle size by loading codecs dynamically at runtime.

1. Update Imports

Instead of a standard import, use the dynamic-import path to enable dynamic codec loading:

import cornerstoneWADOImageLoader from 'cornerstone-wado-image-loader/dist/dynamic-import/cornerstoneWADOImageLoader.min.js';

Alternatively, you can configure a Webpack alias:

resolve: {
  alias: {
    'cornerstone-wado-image-loader': 'cornerstone-wado-image-loader/dist/dynamic-import/cornerstoneWADOImageLoader.min.js',
  },
}

2. Copy WASM files to build directory

You must ensure the WASM codec files are available in your build folder. If using CopyWebpackPlugin, add a rule to copy the files from node_modules:

plugins: [
  new CopyWebpackPlugin([
    {
      from: '../../../node_modules/cornerstone-wado-image-loader/dist/dynamic-import',
      to: DIST_DIR,
    },
  ]),
]

Note: The from path is relative to your project's node_modules folder.

3. Server Configuration

If hosting on a server like IIS, ensure it is configured to serve .wasm files with the correct MIME type.

The cornerstoneWADOImageLoader.webWorkerManager.initialize(config) function accepts a configuration object to fine-tune worker behavior and task settings.

Configuration Options

taskConfiguration Details

• decodeTask.initializeCodecsOnStartup: (Boolean) By default, JPEG2000 and JPEG-LS decoders are NOT initialized on startup to save CPU/time. Set to true if you frequently display these image types and want to reduce latency during the first decode.
• Custom Task Config: You can pass arbitrary configuration objects to your custom tasks using keys that match your taskType. For example, taskConfiguration.sleepTask.sleepTime will be passed to a task registered as sleepTask.

var config = {
  maxWebWorkers: navigator.hardwareConcurrency || 1,
  startWebWorkersOnDemand: true,
  webWorkerTaskPaths: [
    '../examples/customWebWorkerTask/sleepTask.js',
    '../examples/customWebWorkerTask/sharpenTask.js',
  ],
  taskConfiguration: {
    decodeTask: {
      initializeCodecsOnStartup: false,
    },
    sleepTask: {
      sleepTime: 3000,
    },
  },
};
cornerstoneWADOImageLoader.webWorkerManager.initialize(config);