feat(image loaders): Allow reusing DICOM image loader code for custom image loaders

[sgielen]

NOTE: This PR is currently set to merge into the beta branch. We may want to await the merge of beta into main first and then merge this PR into main afterwards?

Context

This PR makes it easier to write DICOM-based custom image loaders that work with DICOM files, but do not use WADO-RS or WADO-URI directly. An example is added to show this functionality.

Relevant issues / PRs:

• back and forth on fix: Lockup in request pool when returning non promise result #990, fix(DicomImageLoader): Returns options.loader #1154, fix(wadouri): custom loaders should register their schema, and add new debounce listener to event target #1216
• possibly How to put images into cache that are already loaded #266
• fix: Lockup in request pool when returning non promise result #990 (comment) and the comments after it

See also a partially related documentation PR: #1508

Changes & Results

• The WADOURI metadata provider is now externally exposed. This allows any custom metadata provider based on DICOM files to expose its metadata to Cornerstone without duplicating its code.
  • There is a lot of duplication between the WADOURI and WADO-RS metadata providers - they all pull the same tags towards the same object fields in metadata providers. However, one pulls the tags from dicomParser and the other from a Record<string, any> and in the latter, the individual byte array and element references are not available. This difference makes it nontrivial to generalize well, but I still think there is some value there.
• The WADOURI pixel provider is also externally exposed. This allows any custom image loader based on DICOM files to retrieve pixel data and create Cornerstone image loading objects.
• I've added an example custom image loader that uses both components to load DICOM files as ByteArrays from other sources (e.g. a caching layer, websockets, etc) and displays them as individual stack images, stack volumes or actual volumes.

There are some open points:

• DBT volumes don't display correctly yet.
• Because of [Bug] All individual volume slices must be preloaded to prevent "Cannot destructure property 'pixelRepresentation'" error #889, this example still calls await loadVolume() on all individual slices to ensure that metadata is available.
• I haven't seen decache ever being called yet.

Testing

Run the new example DICOM custom image loader. Drag and drop slices into the image drop area, and click them to display.

Checklist

PR

• My Pull Request title is descriptive, accurate and follows the
  semantic-release format and guidelines.

Code

• My code has been well-documented (function documentation, inline comments,
  etc.)

• [] I have run the yarn build:update-api to update the API documentation, and have
  committed the changes to this PR. (Read more here https://www.cornerstonejs.org/docs/contribute/update-api)

Public Documentation Updates

• The documentation page has been updated as necessary for any public API
  additions or removals.

See #1508

Tested Environment

• OS: macOS 15
• Node version: v22.8
• Browser: Chrome 129, Safari 18

[netlify]

❌ Deploy Preview for cornerstone-3d-docs failed. Why did it fail? →

Name	Link
🔨 Latest commit	b631614
🔍 Latest deploy log	https://app.netlify.com/sites/cornerstone-3d-docs/deploys/6717a960523ef00008d4fa87

[sedghi]

These are all great examples, thanks a lot!