@babelfhir-ts/dicomweb

DICOMweb client for SMART-authenticated imaging — URL builders (WADO-RS / QIDO-RS), FHIR ImagingStudy mapping, and Cornerstone3D helpers. Zero runtime dependencies, FHIR-version agnostic.

Installation

npm install @babelfhir-ts/dicomweb

No runtime dependencies. Works with FHIR R4, R4B, and R5 ImagingStudy resources via structural typing.

Usage

DICOMweb Client

import { createDicomwebClient } from '@babelfhir-ts/dicomweb';

const dw = createDicomwebClient({
  baseUrl: 'https://pacs.example.com/dicomweb',
  getAccessToken: () => smartAuth.getToken()?.access_token ?? null,
});

// WADO-RS URLs
const thumb = dw.studyThumbnailUrl('1.2.840.113619.2.55.3...');
const meta  = dw.studyMetadataUrl('1.2.840.113619.2.55.3...');
const rendered = dw.instanceRenderedUrl(studyUID, seriesUID, sopUID);

// QIDO-RS URLs
const seriesUrl    = dw.seriesSearchUrl(studyUID);
const instancesUrl = dw.instancesSearchUrl(studyUID, seriesUID);

// Authenticated headers for fetch
const response = await fetch(meta, { headers: dw.authHeaders() });

FHIR ImagingStudy Mapping

import { getStudyInstanceUID, getPrimaryModality, getStudyTitle, getModalityInfo } from '@babelfhir-ts/dicomweb';

// Extract DICOM Study Instance UID from any FHIR ImagingStudy
const uid = getStudyInstanceUID(imagingStudy); // "1.2.840.113619..."

// Get primary modality code
const modality = getPrimaryModality(imagingStudy); // "CT"

// Human-readable study title (procedureCode → description → fallback)
const title = getStudyTitle(imagingStudy); // "Chest CT with Contrast"

// Modality display info
const info = getModalityInfo('CT'); // { label: "CT Scan", emoji: "🔬" }

Cornerstone3D Helpers

Separate entrypoint for tree-shaking — only imported if you use Cornerstone3D:

import { buildImageId, fetchSeriesImageIds } from '@babelfhir-ts/dicomweb/cornerstone';

// Build a wadors: image ID for Cornerstone3D
const imageId = buildImageId(wadoRsRoot, studyUID, seriesUID, sopUID);
// "wadors:https://pacs.example.com/dicomweb/studies/.../instances/..."

// Fetch all image IDs for a series via QIDO-RS
const imageIds = await fetchSeriesImageIds(wadoRsRoot, studyUID, seriesUID, headers);

With BabelFHIR-TS Generated Code

When you generate an IG with --dicomweb, the generated output includes a dicomweb/ directory with typed wrappers narrowed to the IG's ImagingStudy profiles:

// Generated code narrows ImagingStudyLike → your IG's actual profiles
import { getStudyInstanceUID, createDicomwebClient } from './dicomweb';
import type { ImagingStudyProfile } from './dicomweb';

// Type-safe — only accepts ImagingStudy profiles from your IG
const uid = getStudyInstanceUID(myProfiledImagingStudy);

API

Main Entrypoint (@babelfhir-ts/dicomweb)

| Export | Description | |---|---| | createDicomwebClient(config) | Factory returning a DicomwebClient with bound URL builders and auth | | getStudyInstanceUID(study) | Extract DICOM Study Instance UID from urn:dicom:uid or urn:oid: identifiers | | getPrimaryModality(study) | Get primary modality code (study-level, falls back to first series) | | getStudyTitle(study) | Human-readable title from procedureCode, description, or fallback | | getModalityInfo(code) | Map DICOM modality code to { label, emoji } (15 modalities) | | ImagingStudyLike | Structural interface accepting R4/R4B/R5 ImagingStudy resources | | DicomwebClient | Client interface with URL builders and authHeaders() | | DicomwebClientConfig | Configuration: baseUrl + optional getAccessToken callback | | ModalityInfo | { label: string; emoji: string } |

Cornerstone Entrypoint (@babelfhir-ts/dicomweb/cornerstone)

| Export | Description | |---|---| | buildImageId(wadoRsRoot, studyUID, seriesUID, sopUID, frame?) | Build wadors: URI for Cornerstone3D | | fetchSeriesImageIds(wadoRsRoot, studyUID, seriesUID, headers?) | QIDO-RS query returning an array of Cornerstone3D image IDs |

Part of BabelFHIR-TS

This package provides DICOMweb helpers for BabelFHIR-TS-generated code. Use the --dicomweb CLI flag to generate typed wrappers narrowed to your IG's ImagingStudy profiles. Can also be used standalone for any FHIR + DICOMweb integration.

License

MIT