DICOMweb Integration

BabelFHIR-TS can generate typed DICOMweb helpers that bridge FHIR ImagingStudy profiles with DICOMweb APIs and Cornerstone3D rendering.

Enabling DICOMweb

Pass the --dicomweb flag during generation:

babelfhir-ts install hl7.fhir.us.core@8.0.0 --dicomweb

This generates a dicomweb/ directory in the output with helpers typed to your IG's ImagingStudy profiles.

What Gets Generated

File	Description
dicomweb/index.ts	Re-exports from @babelfhir-ts/dicomweb with typed overloads for IG-specific ImagingStudy profiles
dicomweb/cornerstone.ts	Re-exports Cornerstone3D integration helpers

If your IG contains ImagingStudy profiles, a union type ImagingStudyProfile is generated that narrows all helpers to your specific profiles. If no ImagingStudy profiles are found, generic helpers are re-exported.

Base Package

The runtime helpers come from @babelfhir-ts/dicomweb, which is automatically added as a dependency of the generated package.

DICOMweb Client

Create a client for building DICOMweb URLs:

import { createDicomwebClient } from "my-ig-generated/dicomweb";

const dw = createDicomwebClient({
  baseUrl: "https://pacs.example.com/dicomweb",
  getAccessToken: () => myToken,
});

// Build URLs for thumbnails, metadata, and search
const thumbUrl = dw.studyThumbnailUrl(studyUID);
const metaUrl = dw.studyMetadataUrl(studyUID);
const seriesUrl = dw.seriesSearchUrl(studyUID);

// Auth headers for direct fetch
const headers = dw.authHeaders();

FHIR-to-DICOM Mapping

Extract DICOM identifiers and metadata from FHIR ImagingStudy resources:

import {
  getStudyInstanceUID,
  getPrimaryModality,
  getStudyTitle,
  getModalityInfo,
} from "my-ig-generated/dicomweb";

const uid = getStudyInstanceUID(imagingStudy);  // DICOM Study Instance UID
const modality = getPrimaryModality(imagingStudy);  // e.g., "CT"
const title = getStudyTitle(imagingStudy);  // Human-readable title

if (modality) {
  const info = getModalityInfo(modality);
  console.log(`${info.emoji} ${info.label}`);  // e.g., "🫁 Computed Tomography"
}

Cornerstone3D Integration

For medical image rendering with Cornerstone3D, use the Cornerstone submodule:

import { buildImageId, fetchSeriesImageIds } from "my-ig-generated/dicomweb/cornerstone";

// Build a single wadors: imageId
const imageId = buildImageId(wadoRsRoot, studyUID, seriesUID, sopUID);

// Fetch all imageIds for a series (ready for viewport.setStack())
const imageIds = await fetchSeriesImageIds(wadoRsRoot, studyUID, seriesUID, authHeaders);

Full Cornerstone Client

For a higher-level API that handles metadata caching and Cornerstone registration:

import { createCornerstoneDicomweb } from "@babelfhir-ts/dicomweb/cornerstone";
import * as dicomImageLoader from "@cornerstonejs/dicom-image-loader";

const dw = createCornerstoneDicomweb({
  baseUrl: "https://pacs.example.com/dicomweb",
  getAccessToken: () => token,
  cornerstone: { dicomImageLoader },
});

// Loads metadata, registers with Cornerstone, returns renderable imageIds
const { imageIds, fromCache } = await dw.loadSeries(studyUID, seriesUID);
viewport.setStack(imageIds);

// Load all series in a study in parallel
const result = await dw.loadStudy(studyUID, /* concurrency */ 4);

// Cache management
dw.evictStudy(studyUID);
console.log(dw.cacheStats()); // { studies, series, instances }

Package Exports

When --dicomweb is used, the generated package exposes these subpath exports:

{
  "./dicomweb": "./dicomweb/index.js",
  "./dicomweb/cornerstone": "./dicomweb/cornerstone.js"
}

Additional Utilities

The @babelfhir-ts/dicomweb package also exports lower-level DICOM JSON helpers:

import { Tag, getValue, getNumberValue, getStringValue } from "@babelfhir-ts/dicomweb";
import { getFrameCount, isMultiframe } from "@babelfhir-ts/dicomweb";
import { MetadataCache } from "@babelfhir-ts/dicomweb";