# OHIF Documentation > OHIF (Open Health Imaging Foundation) Viewer is an open-source, web-based, zero-footprint DICOM viewer platform designed for medical imaging. It provides a highly configurable and extensible framework for building diagnostic quality medical imaging applications. OHIF Viewer supports various imaging formats (primarily DICOM), offers advanced visualization tools, customizable workflows, and integration capabilities with different data sources. This file contains the complete documentation for OHIF Viewer, concatenated for easy reference and searching. Each section is clearly marked with its source URL. # Root Documentation ## Where to next? Source: https://docs.ohif.org/llm/README The [Open Health Imaging Foundation][ohif-org] (OHIF) Viewer is an open source, web-based, medical imaging platform. It aims to provide a core framework for building complex imaging applications. Key features: - Designed to load large radiology studies as quickly as possible. Retrieves metadata ahead of time and streams in imaging pixel data as needed. - Leverages [Cornerstone3D](https://github.com/cornerstonejs/cornerstone3D-beta) for decoding, rendering, and annotating medical images. - Works out-of-the-box with Image Archives that support [DICOMWeb][dicom-web]. Offers a Data Source API for communicating with archives over proprietary API formats. - Provides a plugin framework for creating task-based workflow modes which can reuse core functionality. - Beautiful user interface (UI) designed with extensibility in mind. UI components available in a reusable component library built with React.js and Tailwind CSS

Subscribe to our newsletter Release Notes

| | | | | :-: | :--- | :--- | |

| Measurement Tracking | [Demo](https://viewer.ohif.org/viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095438.5) | |

| Labelmap Segmentations | [Demo](https://viewer.ohif.org/viewer?StudyInstanceUIDs=1.3.12.2.1107.5.2.32.35162.30000015050317233592200000046) | |

| Fusion and Custom Hanging protocols | [Demo](https://viewer.ohif.org/tmtv?StudyInstanceUIDs=1.3.6.1.4.1.14519.5.2.1.7009.2403.334240657131972136850343327463) | |

| Volume Rendering | [Demo](https://viewer.ohif.org/viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095438.5&hangingprotocolId=mprAnd3DVolumeViewport) | | PDF

| PDF | [Demo](https://viewer.ohif.org/viewer?StudyInstanceUIDs=2.25.317377619501274872606137091638706705333) | | RTSTRUCT

| RT STRUCT | [Demo](https://viewer.ohif.org/viewer?StudyInstanceUIDs=1.3.6.1.4.1.5962.99.1.2968617883.1314880426.1493322302363.3.0) | |

| 4D | [Demo](https://viewer.ohif.org/dynamic-volume?StudyInstanceUIDs=2.25.232704420736447710317909004159492840763) | | VIDEO

| Video | [Demo](https://viewer.ohif.org/viewer?StudyInstanceUIDs=2.25.96975534054447904995905761963464388233) | |

| Slide Microscopy | [Demo](https://viewer.ohif.org/microscopy?StudyInstanceUIDs=2.25.141277760791347900862109212450152067508) | #### Where to next? The Open Health Imaging Foundation intends to provide an imaging viewer framework which can be easily extended for specific uses. If you find yourself unable to extend the viewer for your purposes, please reach out via our [GitHub issues][gh-issues]. We are actively seeking feedback on ways to improve our integration and extension points. Check out these helpful links: - Ready to dive into some code? Check out our [Getting Started Guide](./development/getting-started.md). - We're an active, vibrant community. [Learn how you can be more involved.](./development/contributing.md) - Feeling lost? Read our [help page](/help). #### Citing OHIF To cite the OHIF Viewer in an academic publication, please cite > _Open Health Imaging Foundation Viewer: An Extensible Open-Source Framework > for Building Web-Based Imaging Applications to Support Cancer Research_ > > Erik Ziegler, Trinity Urban, Danny Brown, James Petts, Steve D. Pieper, Rob > Lewis, Chris Hafey, and Gordon J. Harris _JCO Clinical Cancer Informatics_, no. 4 (2020), 336-345, DOI: > [10.1200/CCI.19.00131](https://www.doi.org/10.1200/CCI.19.00131) This article is freely available on Pubmed Central: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7259879/ or, for Lesion Tracker of OHIF v1, please cite: > _LesionTracker: Extensible Open-Source Zero-Footprint Web Viewer for Cancer > Imaging Research and Clinical Trials_ > > Trinity Urban, Erik Ziegler, Rob Lewis, Chris Hafey, Cheryl Sadow, Annick D. > Van den Abbeele and Gordon J. Harris _Cancer Research_, November 1 2017 (77) (21) e119-e122 DOI: > [10.1158/0008-5472.CAN-17-0334](https://www.doi.org/10.1158/0008-5472.CAN-17-0334) This article is freely available on Pubmed Central. https://pubmed.ncbi.nlm.nih.gov/29092955/ **Note:** If you use or find this repository helpful, please take the time to star this repository on Github. This is an easy way for us to assess adoption, and it can help us obtain future funding for the project. #### License MIT © [OHIF](https://github.com/OHIF) [ohif-org]: https://www.ohif.org [ohif-demo]: http://viewer.ohif.org/ [dicom-web]: https://en.wikipedia.org/wiki/DICOMweb [gh-issues]: https://github.com/OHIF/Viewers/issues --- ## DICOM Conformance Statement Source: https://docs.ohif.org/llm/conformance You can find a version that has been open sourced by Radical Imaging [in this link](https://docs.google.com/document/d/1hbDlUApX4svX33gAUGxGfD7fXXZNaBsX0hSePbc-hNA/edit?usp=sharing) --- ## OHIF Viewer Release Notes Source: https://docs.ohif.org/llm/release-notes #### Release Notes You can find the detailed release notes on the OHIF website. Please visit [https://ohif.org/release-notes](https://ohif.org/release-notes) --- ## OHIF Viewer Educational Resources Source: https://docs.ohif.org/llm/resources #### Resources Throughout the development of the OHIF Viewer, we have participated in various conferences and "hackathons". In this page, we will provide the presentations and other resources that we have provided to the community in the past: #### 2025 #### Machine Learning in Medical Imaging Consortium (MaLMIC) | January 2025 We presented two talks at the Machine Learning in Medical Imaging Consortium (MaLMIC) 2025 conference. - Advanced Medical Imaging Visualization [Slides](https://docs.google.com/presentation/d/1HZDL-72nNe4BPawDxR3XnSFLB3oLo72RjExc-KHDZfo/edit?usp=sharing) - Introducing Advanced Segmentation Tools in the OHIF Viewer and Cornerstone3D [Slides](https://docs.google.com/presentation/d/146oJ24PPsFZaDPHeFudRF1dmbL42K9yHzQdXXAXdWxk/edit?usp=sharing) #### 2024 #### ITCR Sustainment Session 2024 Dr. Gordon Harris presented at ITCR sustainment session about the future of OHIF. - OHIF Sustainability [Slides](https://docs.google.com/presentation/d/15380mjCzBKBj9PuysCW1Q9ODnyoypJrCDpj3atTtK6I/edit?usp=sharing) #### ITCR Sustainment Panel 2024 - Advanced Medical Imaging Visualization [Slides](https://docs.google.com/presentation/d/1alUp9uJpoJs3aAUE0KqrufGo6e6HHvXYmOAdJp-Rlkc/edit?usp=sharing) #### IMNO 2024 - March 19-20, 2024 We participated in the Imaging Network Ontario (ImNO) 2024 symposium, presenting three posters. One of our presentations received the best talk award during the session. - Advancing Medical Imaging on the Web: Implementation of Hanging Protocols for Automated Image Display Configuration in OHIF V3 [Poster](https://www.dropbox.com/scl/fi/z4h86bmsxi0c62e1n6h9l/P7-9-Alireza-Sedghi-Final.pdf?rlkey=v5pm0p5ygkbq41x9bz3hr5yi8&dl=0) - Advancing Medical Imaging on the Web: Optimizing the Dicomweb Server Architecture with Static Dicomweb [Poster](https://www.dropbox.com/scl/fi/ep0lxjp90kbxhjoffe4kh/P7-10-Bill-Wallace-Final.pdf?rlkey=xl2u6tdnh9j9hgvkajxv3b02o&dl=0) - (**🏆🏆 BEST PRESENTATION AWARD in the Session 7 Pitches: Devices, HW, SW Development 🏆🏆**) Advancing Medical Imaging on the Web: Integrating High Throughput JPEG 2000 (HTJ2K) in Cornerstone3D for Streamlined Progressive Loading and Visualization [Poster](https://www.dropbox.com/scl/fi/srs2rxgtv2r69ver9ub1j/P7-8-Bill-Wallace-Final.pdf?rlkey=k9mmraw76r9q2s3b9w9s0793w&dl=0) #### 2023 #### ITCR 2023 Conference | September 11-13, 2023 Dr. Gordon Harris presented an update on OHIF in [NCI Informatics Technology for Cancer Research Annual Meeting](https://www.itcr2023.org/). You can find the slides and poster here: [[Slides]](https://docs.google.com/presentation/d/1R38s95db_yZj0WoYdlUbaWGZsWVb3H-3u_hXBZXiTaE/edit?usp=sharing)[[Poster]](https://ohif-assets.s3.us-east-2.amazonaws.com/presentations/OHIF-ITCR-2023-FINAL-PRINT.pdf) #### SIIM 2023 Tech Tools Webinar | April 12th, 2023 Free, Open Source Tools for Research: MONAI and OHIF Viewer [[Slides](https://docs.google.com/presentation/d/1afJ5Y9Tzukgn7eAbaO1oiCtN7XvIimFdmZP-HcOUofA/edit?usp=sharing)][[Video](https://www.youtube.com/watch?v=lo8J5w5jUJI)] #### NA-MIC Project Week 38th 2023 - Remote We participated in the 38th Project Week with three projects around OHIF. [[Website](https://projectweek.na-mic.org/PW38_2023_GranCanaria/)] - PolySeg representations for OHIF Viewer ([link](https://projectweek.na-mic.org/PW38_2023_GranCanaria/Projects/OHIF_PolySeg/)) - Cross study synchronizer for OHIF Crosshair ([link](https://projectweek.na-mic.org/PW38_2023_GranCanaria/Projects/OHIF_SyncCrosshair/)) - DATSCAN Viewer implementation in OHIF ([link](https://projectweek.na-mic.org/PW38_2023_GranCanaria/Projects/OHIF_DATSCAN/)) #### 2022 #### OHIF Demo to Interns [[Slides]](https://docs.google.com/presentation/d/1a2PkUnqkVMaXaBsuFn7-PPlBJULU3dBwzI_44gKFeYI/edit?usp=sharing) #### SIIM 2022 - Updates from the Imaging Informatics Community We participated in the SIIM 2022 conference to give update for the imaging informatics community. [[Slides]](https://docs.google.com/presentation/d/1EUGaUzQtGhZbZWpGLe6ONqChpVMw9Qr9l3KHODevMow/edit?usp=sharing) [[Video]](https://vimeo.com/734463662/dbd5a88371) #### The Imaging Network Ontario - Remote The Imaging Network Ontario (ImNO) is an annual symposium that brings together medical imaging researchers and scientists from across Canada to share knowledge, ideas, and experiences. [[Slides]](https://docs.google.com/presentation/d/18XZDon4-Sitc2a70V5sFyhyUVZI_mIgfXHGtdxhZMjE/edit?usp=sharing) [[Video]](https://vimeo.com/843234581/ad7d308a44) #### [NA-MIC Project Week 36th 2022 - Remote](https://github.com/NA-MIC/ProjectWeek/blob/master/PW36_2022_Virtual/README.md) The Project Week is a week-long hackathon of hands-on activity in which medical image computing researchers. OHIF team participated and gave a talk on OHIF and Cornerstone in the 36th Project Week: [[Slides]](https://docs.google.com/presentation/d/1-GtOKmr2cQi-r3OFyseSmgLeurtB3KXUkGMx2pVLh1I/edit?usp=sharing) [[Video]](https://vimeo.com/668339696/63a2c48de8) #### 2021 #### [NA-MIC Project Week 35th 2021 - Remote](https://github.com/NA-MIC/ProjectWeek/tree/master/PW35_2021_Virtual) The Project Week is a week-long hackathon of hands-on activity in which medical image computing researchers. OHIF team participated in the 35th Project Week in 2021. [[Slides]](https://docs.google.com/presentation/d/1KYNjuiI8lT1foQ4P9TGNV0lBhM6H-5KBs0wkYj4JJbk/edit?usp=sharing) #### Chan Zuckerberg Initiative (CZI) Project presentations and demonstrations of Essential Open Source Software for Science (EOSS) grantees [[Slides]](https://docs.google.com/presentation/d/1_CLtG2hsL3ZxOtV2olVnzBOzq-TMLrHLomOy3FiU4NE/edit?usp=sharing) [[Video]](https://youtu.be/0FjKkTJO0Rc?t=3737) #### Google Cloud Tech Healthcare Imaging with Cloud Healthcare API [[Video]](https://www.youtube.com/watch?v=2MiX9ScHFhY) #### 2020 #### OHIF ITCR Pitch OHIF pitch for Informatics Technology for Cancer Research (ITCR) [[Slides]](https://docs.google.com/presentation/d/1MZXnZrVAnjmhVIWqC-aRSvJOoMMRLhLddACdCa1TybM/edit?usp=sharing) [[Video]](https://vimeo.com/843234613/625bdb8793) #### 2019 #### OHIF and VTK.js Training Course OHIF and Kitware collaboration to create a training course for OHIF and VTK.js developers. Funding for this work was provided by Kitware (NIH NINDS R44NS081792, NIH NINDS R42NS086295, NIH NIBIB and NIGMS R01EB021396, NIH NIBIB R01EB014955), Isomics (NIH P41 EB015902), and Massachusetts General Hospital (NIH U24 CA199460). 1. Introduction to VTK.js and OHIF [[Slides]](https://docs.google.com/presentation/d/1NCJxpfx_qUGJI_2DhbECzaOg0k-Z6b65QlUptCofN-A/edit#slide=id.p) [[Video]](https://vimeo.com/375520781) 2. Developing with VTK.js [[Slides]](https://docs.google.com/presentation/d/17TCS6EhFi6SWFIrcAJ-DFdFzFFL-WD9BBTv-owmMdDU/edit#slide=id.p) [[Video]](https://vimeo.com/375521036) 3. VTK.js Architecture and Tooling [[Slides]](https://docs.google.com/presentation/d/1Sr1OGxMSw0oCt46koKQbmwSIE11Kqq8MGtyW3W0ASpk/edit?usp=gmail_thread) [[Video]](https://vimeo.com/375521810) 4. OHIF + VTK.js Integration [[Slides]](https://docs.google.com/presentation/d/1Iwg-u01HGVf1CgC6NbcBD3gm3uHN9WhjU59FSz55TN8/edit?ts=5d9c9ce4#slide=id.g59aa99cda4_0_131) [[Video]](https://vimeo.com/375521206) #### 2017 #### Lesion Tracker LesionTracker: Extensible Open-Source Zero-Footprint Web Viewer for Cancer Imaging Research and Clinical Trials. This project was supported in part by grant U24 CA199460 from the National Cancer Institute (NCI) Informatics Technology for Cancer Research (ITCR) Program. [[Video]](https://www.youtube.com/watch?v=gUIPtoSBL-Q) #### OHIF Community Meeting - June [[Slides]](https://docs.google.com/presentation/d/1K9Y6eP5DYTXoDlfwCZE6GkCUp83AK4_40YQS0dlzVBo/edit?usp=sharing) #### 2016 #### Imaging Community Call Open Source Oncology Web Viewer; Presentation by Gordon J. Harris [[Slides]](https://www.slideshare.net/imgcommcall/lesiontracker) #### OHIF Community Meeting - June [[Slides]](https://docs.google.com/presentation/d/1Ai25mBG0ZWUPhaadp3VnbCVmkYs9K51sQ8osMixrvJ0/edit?usp=sharing) #### OHIF Community Meeting - September [[Slides]](https://docs.google.com/presentation/d/1iYZoU7v7KHSLHiKwH1_9_wweAkG7RGnyxrWeeHva4zQ/edit?usp=sharing) --- ## OHIF Viewer Test Coverage Source: https://docs.ohif.org/llm/test-coverage #### Test Coverage #### Playwright Here's the test coverage report for our Playwright tests. Keep in mind that this doesn't include our Cypress tests, so our actual test coverage is likely higher than what's shown. We're focusing on Playwright for future OHIF testing, and we're really pushing to improve that coverage number. You can view our latest test coverage report here: - [OHIF Playwright Test Coverage Report](https://docs.ohif.org/coverage) --- # Behaviours ## Behaviours Source: https://docs.ohif.org/llm/behaviours/README.md #### Behaviours This section documents **how the system and UI actually behave** — the end-to-end behaviours that emerge from the interaction of services, extensions, the data source, and Cornerstone3D, rather than the API of any single module. It is the place for: - **Observed behaviours** — how a feature works today across the stack (e.g. how a DICOM SEG is fetched, decoded, and rendered; what the viewport does on study change; how measurements round-trip to SR). - **Design proposals** — proposed or in-progress changes to a behaviour, captured before/while they are implemented so the intent and trade-offs are recorded. These are clearly marked as proposals until they land. - **Edge cases and failure modes** — what happens when something is missing, slow, or malformed, and how the system is expected to degrade. The goal is a durable, discoverable record of *behaviour* — the kind of cross-cutting knowledge that is otherwise only in people's heads or scattered across code comments. Prefer linking to the relevant source files (with line references) so each behaviour doc stays anchored to the code it describes. #### Index - [Segmentation: loading a multiframe SEG as a single Part 10 instance](./segmentation-multiframe-part10-prefetch.md) — _implemented, enabled by default_. Prefetch the whole instance in one request and register it into the Cornerstone3D NATURALIZED frame registry so the per-frame load path (WADO-RS and WADO-URI) is served locally, while keeping the standard decode path unchanged. Per-frame loading is the exception — disable via `loadMultiframeAsPart10: false` (data source config or the `cornerstone.segmentation.loadMultiframeAsPart10` customization). #### Writing a new behaviour doc 1. Add a `kebab-case.md` file in this directory. 2. State whether it documents **current behaviour** or is a **proposal**. 3. Link to the code (`path:line`) that implements or will implement it. 4. Add it to the **Index** above. --- ## Full-instance prefetch for segmentation (and multiframe) loading Source: https://docs.ohif.org/llm/behaviours/segmentation-multiframe-part10-prefetch.md #### Full-instance prefetch for segmentation (and multiframe) loading Status: **Implemented — enabled and awaited to completion by default; per-frame loading is the explicit opt-out** The boolean `loadMultiframeAsPart10` resolves, in order: the data source `configuration`, the global customization `cornerstone.segmentation.loadMultiframeAsPart10`, then the built-in default of `true` — i.e. by default the SEG load **waits for the whole-instance fetch+parse to complete or fail** (deliberately no timeout) and serves every frame from the registry. Set `loadMultiframeAsPart10: false` explicitly to force per-frame loading — the exception, for back ends that need to fetch the individual images instead (e.g. servers that cannot serve a whole-instance retrieve, or deployments where holding the full Part 10 object in memory is undesirable). A failed or unsupported instance fetch resolves quickly and falls back to per-frame regardless of the setting, so it never wedges the load. Note the per-frame endpoint itself is not inefficient — each frame request is cheap — but SEG frames are so small and numerous that one bulk Part 10 fetch beats hundreds of tiny requests (see Problem below). This holds even for very large SEG objects (hundreds of MB): any finite race cap would simply expire on those and storm per-frame anyway while abandoning the bulk fetch's benefit, which is why there is no timeout. Implemented across: - `@cornerstonejs/dicom-image-loader` - `imageLoader/prefetchPart10Instance.ts` — registers a Part 10 instance into the frame registry (thin wrapper over `addDicomPart10Instance`). - `imageLoader/wadors/loadImageFromRegistry.ts` + `wadors/loadImage.ts` — WADO-RS loads now consult the registry first. - `@ohif/extension-default` `DicomWebDataSource` — `retrieve.prefetchInstanceFrames`. - `@ohif/extension-cornerstone-dicom-seg` `getSopClassHandlerModule.ts` — call site (resolves the config and awaits the prefetch). Related: `@cornerstonejs/adapters` `labelmapImagesFromBuffer.ts` (`decodeSegPixelDataFromFrameIds`, bounded by `concurrency`, default 16). #### Problem The SEG load path now fetches/decodes frames through the cornerstone image loader, one loadable `imageId` per frame, parallelized up to `N=16` (`concurrency`). For a SEG (or any multiframe instance) with **800+ small frames**, this means 800+ independent HTTP requests, each with its own request/response overhead. Even at 16-wide concurrency the *per-request* latency floor dominates: each frame is < 1 KB of payload but pays a full round trip. Streaming **one large object** (the entire Part 10 / multiframe instance) is far cheaper than streaming hundreds of tiny ones — a single connection, a single set of headers, no per-frame TTFB. The whole instance for an 800-frame binary SEG is typically a few hundred KB to a few MB. #### Goal Add a **generic data-source capability** that, _just before_ the segmentation loader runs, optionally fetches the **entire original instance** in one request and **registers it into the Cornerstone3D frame registry** (the `@cornerstonejs/metadata` NATURALIZED + `COMPRESSED_FRAME_DATA` framework, parsed by the dcmjs async reader) — so the existing per-frame `imageId` fetch path transparently hits local data instead of the network, while the **cornerstone decode path stays byte-for-byte identical** (same decompressor, same workers). Crucially this is **best-effort**: - By default (`loadMultiframeAsPart10` unset → `true`) the load **waits for the full-instance fetch+parse to complete or fail** — no timeout — then every frame is served from the registry. - If `loadMultiframeAsPart10` resolves to `false` (explicitly configured), the capability is **disabled** — no full-instance fetch is attempted. Per-frame loading is the exception, opted into per deployment. - If the full-instance fetch or parse **fails for any reason**, it must **never** fail the segmentation decode. We log and fall back to per-frame fetches. #### Why this is safe / transparent There is **one uniform frame registry: the Cornerstone3D `@cornerstonejs/metadata` NATURALIZED framework**, populated by `addDicomPart10Instance` (which parses the Part 10 with the dcmjs `AsyncDicomReader`) and read per-frame via the `COMPRESSED_FRAME_DATA` typed provider. Frame imageIds are normalized to the base instance by `baseImageIdQueryFilter` (strips `/frames/N`, `?frame=N`, `&frame=N`), so one registration under the instance serves every frame. This is the **same registry the WADO-URI / `dicomweb` loader already uses**: `wadouri/loadImage.ts`'s `loadImageFromNaturalizedMetadata` resolves each frame from `COMPRESSED_FRAME_DATA` and decodes it with `createImage`. The gap was that **WADO-RS** (`wadors/loadImage.ts`) always issued a per-frame `/frames/N` request and never consulted the registry. The adapter closes that gap: - `wadors/loadImageFromRegistry.ts` — `loadImageFromCompressedFrameRegistry(imageId)` looks up `COMPRESSED_FRAME_DATA` for the frame; if present it decodes via the **same `createImage`** path and returns the image; if absent it returns `undefined`. - `wadors/loadImage.ts` calls it first and short-circuits when the registry has the frame, otherwise falls through to the existing network path. So once `prefetchPart10Instance` has registered the instance, **both WADO-URI and WADO-RS** serve every frame from the single registry, with the **same decode pipeline** (`createImage` → worker decoder). From cornerstone's perspective nothing changed except the compressed bytes came from the registry instead of the wire. > Rejected alternatives: (1) a bespoke `Map` registry plus > `getPixelData` shims — duplicates a registry that already exists; (2) seeding > the core image cache (`cache.putImageLoadObject`) per frame — works, but the > per-frame compressed data already lives in the NATURALIZED registry, so basing > the design on that registry (and teaching WADO-RS to read it) keeps a single > source of truth instead of copying frames into a second cache. #### API (as implemented) A generic capability on the data source's `retrieve` namespace (so it works for any multiframe instance, not just SEG, and alternate data sources can override it), plus the SEG handler call site that awaits it. `IWebApiDataSource.create` passes `retrieve` through verbatim, so the capability is added there (no `@ohif/core` change): ```ts // On the data source (DicomWebDataSource): dataSource.retrieve.prefetchInstanceFrames({ instance, // study/series/sop UIDs for retrieveInstance imageId, // SEG instance imageId (frame qualifiers normalized away) }): { done: Promise; // resolves true if fetched+registered, false if skipped/failed cancel: () => void; }; ``` The implementation fetches the instance with `wadoDicomWebClient.retrieveInstance` (which returns the Part 10 as an `ArrayBuffer`, unwrapping `multipart/related` transparently) and passes a **lazy resolver** to `dicomImageLoader.prefetchPart10Instance(imageId, resolver)`. All work is wrapped so any failure resolves `done` to `false` — it never throws into the loader. #### Call site (just before the loader) In `getSopClassHandlerModule.ts`, immediately before `createFromDicomSegImageId(...)` (abridged from the actual code): ```ts const loadMultiframeAsPart10 = (dataSource?.getConfig?.()?.loadMultiframeAsPart10 as boolean | undefined) ?? (customizationService?.getCustomization?.( 'cornerstone.segmentation.loadMultiframeAsPart10' ) as boolean | undefined) ?? true; let prefetch; if (loadMultiframeAsPart10) { prefetch = dataSource.retrieve?.prefetchInstanceFrames?.({ instance, imageId: segImageIdForMetadata, }); if (prefetch?.done) { // Wait for the bulk fetch to complete or fail — no timeout. await prefetch.done; } } try { results = await adaptersSEG.Cornerstone3D.Segmentation.createFromDicomSegImageId( imageIds, segImageIdForMetadata, { metadataProvider: metaData, tolerance, parserType, frameImageIds, concurrency: SEG_FRAME_DECODE_CONCURRENCY } ); } finally { eventTarget.removeEventListener(Enums.Events.SEGMENTATION_LOAD_PROGRESS, onProgress); prefetch?.cancel?.(); } ``` The SEG loader and adapter are **unchanged** — the loader still asks the image loader for each frame. Registered frames resolve from the registry; the rest fetch normally. #### Mechanism (the 4 requested points) #### 1. Async DICOM reader (dcmjs) to parse the instance Parsing is done by `@cornerstonejs/metadata`'s `addDicomPart10Instance`, which uses the dcmjs **`AsyncDicomReader`** (`naturalizePart10Buffer` in `naturalizedHandlers.ts`) and understands encapsulated PixelData fragmentation, so the NATURALIZED instance exposes pixel data as an array of per-frame ArrayBuffer fragments. `COMPRESSED_FRAME_DATA` then slices out the requested frame. We did not re-implement any parsing — the prefetch just feeds the fetched Part 10 buffer to this existing reader. **Implemented as full-buffer v1**: the whole instance is fetched, then parsed. `addDicomPart10Instance` accepts a lazy resolver, so the fetch is what the race waits on. Progressive/streaming registration (registering frames as bytes arrive) is a future optimization — see rollout step 4. #### Response envelope: `multipart/related` vs raw DICOM The full-instance fetch can come back in **two shapes**, and the parser must handle both before any DICOM parsing happens: - **`multipart/related`** — a WADO-RS instance retrieve (`GET …/instances/{sop}` with `Accept: multipart/related; type="application/dicom"`) wraps the Part 10 object(s) in a MIME multipart envelope: leading part headers, a `--boundary` marker, the DICOM bytes, then a terminal `--boundary--`. The inner DICOM byte offsets are **shifted** by the MIME header length, so dcmjs must be fed the *unwrapped* inner part, never the raw response. - **raw DICOM** — WADO-URI, a direct file/object URL, or a `bulkDataURI` that returns a single `application/dicom` body: the response **is** the Part 10 bytes, no envelope. **As implemented**, the full-buffer path delegates this to **`dicomweb-client`'s `retrieveInstance`**, which performs the WADO-RS instance retrieve and returns the Part 10 as an `ArrayBuffer` with the `multipart/related` envelope already unwrapped (and returns the single-part body as-is). `prefetchInstanceFrames` additionally tolerates an `[ArrayBuffer]` or `ArrayBufferView` shape defensively. So the implemented path is: ``` retrieveInstance() → ArrayBuffer (multipart unwrapped by dicomweb-client) → prefetchPart10Instance → addDicomPart10Instance → dcmjs AsyncDicomReader ``` Detection by `Content-Type` and manual unwrapping (the approach `wadors/extractMultipart.ts` uses: `contentType.indexOf('multipart') === -1` → bytes as-is; else strip the boundary/part headers) becomes relevant only for the **future streaming path** (rollout step 4), where these wrinkles must be handled directly: - The multipart preamble/boundary stripped at the **start** of the stream and the terminal boundary detected at the **end**; a boundary token can **straddle chunk boundaries**, so the unwrapper must buffer across chunks (the existing `findIndexOfString` + `tokenIndex` carry-over in `extractMultipart` is built for incremental calls). - `multipart/related` may contain **multiple parts**; a single-instance retrieve yields one — guard for >1. - A truncated/partial body (no terminal boundary yet) must not be mis-parsed. #### 2. Register the compressed data into the frame registry The fetched Part 10 buffer is registered **once per instance** via the `prefetchPart10Instance` adapter (a thin wrapper over `addDicomPart10Instance`): ```ts // @cornerstonejs/dicom-image-loader: imageLoader/prefetchPart10Instance.ts import { utilities } from '@cornerstonejs/metadata'; const { addDicomPart10Instance } = utilities; export function prefetchPart10Instance(baseImageId, part10 /* buffer | resolver */) { return addDicomPart10Instance(baseImageId, part10); } ``` That populates NATURALIZED for the instance; `COMPRESSED_FRAME_DATA` then yields each frame's compressed bytes + transfer syntax on demand. Frame imageIds normalize to the instance key automatically (`baseImageIdQueryFilter`), so there is no per-frame registration loop and no second cache to keep coherent — the registry **is** the existing NATURALIZED framework. The "few new adapters" the task calls for: 1. `prefetchPart10Instance(baseImageId, part10)` — entry point to register a fetched instance into the registry (exported from `@cornerstonejs/dicom-image-loader`). 2. `loadImageFromCompressedFrameRegistry(imageId, options)` in `wadors/loadImageFromRegistry.ts` — teaches the **WADO-RS** loader to read the registry. It looks up `COMPRESSED_FRAME_DATA` for the frame and, if present, decodes via the same `createImage` the network path uses; `wadors/loadImage.ts` calls it first and short-circuits on a hit. (WADO-URI already reads the registry via `loadImageFromNaturalizedMetadata`.) Metadata the decoder needs (`imagePixelModule`, transfer syntax) comes from the same NATURALIZED instance, plus the SEG handler's existing `_ensureSegInstanceMetadataAvailable` per frame imageId. #### 3. Cornerstone uses its existing decompressor — identical downstream Both the WADO-URI path and the new WADO-RS registry path decode via `createImage` (→ the same web-worker decoder used for every network frame), so encapsulated transfer syntaxes are decompressed exactly as if fetched per-frame and native/uncompressed frames pass through unchanged. No new decode path, no codec changes, no divergence in pixel output — the only difference is that the compressed bytes came from the registry instead of the wire. #### 4. Failure is non-fatal — fall back to per-frame fetches `prefetchInstanceFrames` wraps the fetch + parse so that **any** failure (network error, cancel, parse error, unexpected `retrieveInstance` shape) resolves `done` to `false` and logs a warning — it never throws into the SEG load. When the registry has no data for a frame, `loadImageFromCompressedFrameRegistry` returns `undefined` and the WADO-RS loader falls through to its normal `/frames/N` request. So if the prefetch is slow, disabled, or fails, loading is exactly today's per-frame behaviour. Edge cases that degrade gracefully: - `cancel()` (viewport closed / segmentation removed mid-load) → the resolver throws on its cancelled flag; `done` resolves `false`; any already-registered data stays usable. - A misbehaving metadata provider → the registry lookup is wrapped in try/catch and returns `undefined`, so per-frame loading is never broken. #### Semantics (the `loadMultiframeAsPart10` knob) - Unset (default) or `true` → start the full-instance fetch+parse and **await it to completion or failure** (`await prefetch.done`) — deliberately no timeout; every frame is then served from the registry. Fetch failure resolves `done` quickly, so unsupported servers fall straight through to per-frame. - `false` (explicitly configured) → **disabled**; per-frame loading is the exception, opted into per deployment. > `addDicomPart10Instance` registers the instance atomically (one parse), so > registration is all-or-nothing rather than progressive. Progressive > registration (rollout step 4) would let frames be served as they arrive. There is no timeout because a bounded wait loses on exactly the objects where the prefetch matters most: a large SEG (hundreds of MB) cannot finish inside any small cap, so a capped race expires and storms per-frame anyway while abandoning the bulk fetch's benefit. The only failure mode a timeout would bound — a fetch that never settles — is already covered by the browser's network-level failure surfacing through `done`. #### Where the generic capability lives - The **registry is the existing `@cornerstonejs/metadata` NATURALIZED framework** — no new cache. New code in `@cornerstonejs/dicom-image-loader` is the thin adapter `prefetchPart10Instance()` plus the WADO-RS read path (`wadors/loadImageFromRegistry.ts`, wired into `wadors/loadImage.ts`). - The **fetch + register orchestration** lives in the **data source** (`extensions/default/.../DicomWebDataSource` → `retrieve.prefetchInstanceFrames`), because it knows how to retrieve a full instance (auth headers, `wadoRoot`, WADO-RS instance retrieve via `dicomweb-client`, CORS), and so alternate data sources can implement/override it. - The SEG handler only **reads the configuration and awaits the prefetch**. This keeps the layering clean: data source = "how to get bytes", image loader = "how to register/decode bytes", SEG handler = "when to ask". #### Open questions / risks 1. **NATURALIZED registry key alignment.** Both registration (`addDicomPart10Instance`) and the WADO-RS read normalize frame imageIds to the base instance via `baseImageIdQueryFilter`, so they agree. Worth a sanity check per data source that the SEG `imageId` passed to `prefetchInstanceFrames` and the frame imageIds the SEG loader requests share the same instance base. 2. **Memory.** Holding the full instance plus the still-compressed frames in the registry raises memory for that instance until it is evicted. Compressed frames are small and decode is on-demand. Registry/cache eviction lifecycle for prefetched instances should be verified (especially repeated SEG loads). 3. **Streaming availability.** v1 uses a single full-buffer `retrieveInstance`. A future streaming path (step 4) would register frames as bytes arrive. 4. **Auth / headers.** Handled — the resolver sets `wadoDicomWebClient.headers = getAuthorizationHeader()` before retrieve, reusing the data source's existing decoration. 5. **Per-frame overhead.** Every WADO-RS load now does one cheap `COMPRESSED_FRAME_DATA` lookup (a Map get after base normalization) before falling through. Negligible, and only short-circuits when an instance was actually prefetched. #### Incremental rollout 1. ✅ `prefetchPart10Instance` adapter + WADO-RS registry read (`wadors/loadImageFromRegistry.ts`) in dicom-image-loader. No behaviour change until something registers an instance. 2. ✅ `retrieve.prefetchInstanceFrames` in DicomWebDataSource (full-buffer v1 via `retrieveInstance`); whether to call it is the caller's policy. 3. ✅ SEG handler call site. Now **enabled and awaited to completion by default** (no timeout); per-frame loading requires an explicit `loadMultiframeAsPart10: false`. 4. ⏳ Progressive (streaming) parse to register frames as they arrive (handle the `multipart/related` unwrap + boundary-straddle directly). 5. ⏳ Extend to other multiframe loaders (the registry path is generic). --- # Configuration ## Configuration Files Source: https://docs.ohif.org/llm/configuration/configurationFiles.md #### Config files After following the steps outlined in [Getting Started](./../development/getting-started.md), you'll notice that the OHIF Viewer has data for several studies and their images. You didn't add this data, so where is it coming from? By default, the viewer is configured to connect to a Amazon S3 bucket that is hosting a Static WADO server (see [Static WADO DICOMWeb](https://github.com/RadicalImaging/static-dicomweb)). By default we use `default.js` for the configuration file. You can change this by setting the `APP_CONFIG` environment variable and select other options such as `config/local_orthanc.js` or `config/google.js`. #### Configuration Files The configuration for our viewer is in the `platform/app/public/config` directory. Our build process knows which configuration file to use based on the `APP_CONFIG` environment variable. By default, its value is [`config/default.js`][default-config]. The majority of the viewer's features, and registered extension's features, are configured using this file. The simplest way is to update the existing default config: ```js title="platform/app/public/config/default.js" window.config = { routerBasename: null, extensions: [], modes: [], showStudyList: true, dataSources: [ { namespace: '@ohif/extension-default.dataSourcesModule.dicomweb', sourceName: 'dicomweb', configuration: { friendlyName: 'dcmjs DICOMWeb Server', name: 'DCM4CHEE', wadoUriRoot: 'https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/wado', qidoRoot: 'https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/rs', wadoRoot: 'https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/rs', qidoSupportsIncludeField: true, supportsReject: true, imageRendering: 'wadors', thumbnailRendering: 'wadors', enableStudyLazyLoad: true, supportsFuzzyMatching: true, supportsWildcard: true, omitQuotationForMultipartRequest: true, }, }, ], defaultDataSourceName: 'dicomweb', }; ``` > As you can see a new change in `OHIF-v3` is the addition of `dataSources`. You > can build your own datasource and map it to the internal data structure of > OHIF’s > metadata and enjoy using other peoples developed mode on your own > data! > > You can read more about data sources at > [Data Source section in Modes](../platform/modes/index.md) The configuration can also be written as a JS Function in case you need to inject dependencies like external services: ```js window.config = ({ servicesManager } = {}) => { const { UIDialogService } = servicesManager.services; return { cornerstoneExtensionConfig: { tools: { ArrowAnnotate: { configuration: { getTextCallback: (callback, eventDetails) => UIDialogService.create({... } } }, }, routerBasename: null, dataSources: [ { namespace: '@ohif/extension-default.dataSourcesModule.dicomweb', sourceName: 'dicomweb', configuration: { friendlyName: 'dcmjs DICOMWeb Server', name: 'DCM4CHEE', wadoUriRoot: 'https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/wado', qidoRoot: 'https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/rs', wadoRoot: 'https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/rs', qidoSupportsIncludeField: true, supportsReject: true, imageRendering: 'wadors', thumbnailRendering: 'wadors', enableStudyLazyLoad: true, supportsFuzzyMatching: true, supportsWildcard: true, omitQuotationForMultipartRequest: true, }, }, ], defaultDataSourceName: 'dicomweb', }; }; ``` #### Configuration Options Here are a list of some options available: - `customizationService`: An array of customization module references and inline overrides applied at the global scope. This is how deployers enable optional features like the [Appearance & Theming](./ui.md) system and configure UI components without modifying core code. See [Customization Service](../platform/services/customization-service/customizationService.md) for the full syntax reference. - `disableEditing`: If true, it disables editing in OHIF, hiding edit buttons in segmentation panel and locking already stored measurements. - `maxNumberOfWebWorkers`: The maximum number of web workers to use for decoding. Defaults to minimum of `navigator.hardwareConcurrency` and what is specified by `maxNumberOfWebWorkers`. Some windows machines require smaller values. - `acceptHeader` : accept header to request specific dicom transfer syntax ex : [ 'multipart/related; type=image/jls; q=1', 'multipart/related; type=application/octet-stream; q=0.1' ] - `investigationalUseDialog`: This should contain an object with `option` value, it can be either `always` which always shows the dialog once per session, `never` which never shows the dialog, or `configure` which shows the dialog once and won't show it again until a set number of days defined by the user, if it's set to configure, you are required to add an additional property `days` which is the number of days to wait before showing the dialog again. - `groupEnabledModesFirst`: boolean, if set to true, all valid modes for the study get grouped together first, then the rest of the modes. If false, all modes are shown in the order they are defined in the configuration. - `experimentalStudyBrowserSort`: boolean, if set to true, you will get the experimental StudyBrowserSort component in the UI, which displays a list of sort functions that the displaySets can be sorted by, the sort reflects in all part of the app including the thumbnail/study panel. These sort functions are defined in the customizationModule and can be expanded by users. - `disableConfirmationPrompts`: boolean, if set to true, it skips confirmation prompts for segmentation related prompts. - `showPatientInfo`: string, if set to 'visible', the patient info header will be shown and its initial state is expanded. If set to 'visibleCollapsed', the patient info header will be shown but it's initial state is collapsed. If set to 'disabled', the patient info header will never be shown, and if set to 'visibleReadOnly', the patient info header will be shown and always expanded. - `requestTransferSyntaxUID` : Request a specific Transfer syntax from dicom web server ex: 1.2.840.10008.1.2.4.80 (applied only if acceptHeader is not set) - `omitQuotationForMultipartRequest`: Some servers (e.g., .NET) require the `multipart/related` request to be sent without quotation marks. Defaults to `false`. If your server doesn't require this, then setting this flag to `true` might improve performance (by removing the need for preflight requests). Also note that if auth headers are used, a preflight request is required. - `maxNumRequests`: The maximum number of requests to allow in parallel. It is an object with keys of `interaction`, `thumbnail`, and `prefetch`. You can specify a specific number for each type. For `thumbnail`, a small pool (around `5`) is recommended: the study list preview panel fetches a thumbnail per series in parallel, and a larger pool yields little throughput benefit while risking server overload and contention with `interaction`/`prefetch` requests. - `modesConfiguration`: Allows overriding modes configuration. - Example config: ```js modesConfiguration: { '@ohif/mode-longitudinal': { displayName: 'Custom Name', routeName: 'customRouteName', routes: [ { path: 'customPath', layoutTemplate: () => { /** Custom Layout */ return { id: ohif.layout, props: { leftPanels: [tracked.thumbnailList], rightPanels: [dicomSeg.panel, tracked.measurements], rightPanelClosed: true, viewports: [ { namespace: tracked.viewport, displaySetsToDisplay: [ohif.sopClassHandler], }, ], }, }; }, }, ], } }, ``` Note: Although the mode configuration is passed to the mode factory function, it is up to the particular mode itself if its going to use it to allow overwriting its original configuration e.g. ```js function modeFactory({ modeConfiguration }) { return { id, routeName: 'viewer', displayName: 'Basic Viewer', ... onModeEnter: ({ servicesManager, extensionManager, commandsManager }) => { ... }, /** * This mode allows its configuration to be overwritten by * destructuring the modeConfiguration value from the mode fatory function * at the end of the mode configuration definition. */ ...modeConfiguration, }; } ``` - `showLoadingIndicator`: (default to true), if set to false, the loading indicator will not be shown when navigating between studies. - `showStudyList`: (default to false), if set to false, the OHIF search (or work list) page will not be shown nor will there be a back button (chevron) in the viewer to navigate to it - `useNorm16Texture`: (default to false), if set to true, it will use 16 bit data type for the image data wherever possible which has significant impact on reducing the memory usage. However, the 16Bit textures require EXT_texture_norm16 extension in webGL 2.0 (you can check if you have it here https://webglreport.com/?v=2). In addition to the extension, there are reported problems for Intel Macs that might cause the viewer to crash. In summary, it is great a configuration if you have support for it. - `useSharedArrayBuffer` (default to 'TRUE', options: 'AUTO', 'FALSE', 'TRUE', note that these are strings), for volume loading we use sharedArrayBuffer to be able to load the volume progressively as the data arrives (each webworker has the shared buffer and can write to it). However, there might be certain environments that do not support sharedArrayBuffer. In that case, you can set this flag to false and the viewer will use the regular arrayBuffer which might be slower for large volume loading. - `supportsWildcard`: (default to false), if set to true, the datasource will support wildcard matching for patient name and patient id. - `allowMultiSelectExport`: (default to false), if set to true, the user will be able to select the datasource to export the report to. - `activateViewportBeforeInteraction`: (default to true), if set to false, tools can be used directly without the need to click and activate the viewport. - `autoPlayCine`: (default to false), if set to true, data sets with the DICOM frame time tag (i.e. (0018,1063)) will auto play when displayed - `addWindowLevelActionMenu`: (default to true), if set to false, the window level action menu item is NOT added to the viewport action corners - `showErrorDetails`: determines which runtime environments can display exception and error details caught at the `ErrorBoundary`; acceptable values include: `always`, `dev`, and `production` - `dangerouslyUseDynamicConfig`: Dynamic config allows user to pass `configUrl` query string. This allows to load config without recompiling application. If the `configUrl` query string is passed, the worklist and modes will load from the referenced json rather than the default .env config. If there is no `configUrl` path provided, the default behaviour is used and there should not be any deviation from current user experience.
Points to consider while using `dangerouslyUseDynamicConfig`:
- User have to enable this feature by setting `dangerouslyUseDynamicConfig.enabled:true`. By default it is `false`. - Regex helps to avoid easy exploit. Default is `/.*/`. Setup your own regex to choose a specific source of configuration only. - System administrators can return `cross-origin: same-origin` with OHIF files to disallow any loading from other origin. It will block read access to resources loaded from a different origin to avoid potential attack vector. - Example config: ```js dangerouslyUseDynamicConfig: { enabled: false, regex: /.*/ } ``` > Example 1, to allow numbers and letters in an absolute or sub-path only.
`regex: /(0-9A-Za-z.]+)(\/[0-9A-Za-z.]+)*/`
Example 2, to restricts to either hosptial.com or othersite.com.
`regex: /(https:\/\/hospital.com(\/[0-9A-Za-z.]+)*)|(https:\/\/othersite.com(\/[0-9A-Za-z.]+)*)/`
Example usage:
`http://localhost:3000/?configUrl=http://localhost:3000/config/example.json`
- `onConfiguration`: Currently only available for DicomWebDataSource, this option allows the interception of the data source configuration for dynamic values e.g. values coming from url params or query params. Here is an example of building the dicomweb datasource configuration object with values that are based on the route url params: ``` { namespace: '@ohif/extension-default.dataSourcesModule.dicomweb', sourceName: 'gcpdicomweb', configuration: { friendlyName: 'GCP DICOMWeb Server', name: 'gcpdicomweb', qidoSupportsIncludeField: false, imageRendering: 'wadors', thumbnailRendering: 'wadors', enableStudyLazyLoad: true, supportsFuzzyMatching: false, supportsWildcard: false, singlepart: 'bulkdata,video,pdf', onConfiguration: (dicomWebConfig, options) => { const { params } = options; const { project, location, dataset, dicomStore } = params; const pathUrl = `https://healthcare.googleapis.com/v1/projects/${project}/locations/${location}/datasets/${dataset}/dicomStores/${dicomStore}/dicomWeb`; return { ...dicomWebConfig, wadoRoot: pathUrl, qidoRoot: pathUrl, wadoUri: pathUrl, wadoUriRoot: pathUrl, }; }, }, }, ``` This configuration would allow the user to build a dicomweb configuration from a GCP healthcare api path e.g. http://localhost:3000/projects/your-gcp-project/locations/us-central1/datasets/your-dataset/dicomStores/your-dicom-store/study/1.3.6.1.4.1.1234.5.2.1.1234.1234.123123123123123123123123123123 :::note You can stack multiple panel components on top of each other by providing an array of panel components in the `rightPanels` or `leftPanels` properties. For instance we can use ``` rightPanels: [[dicomSeg.panel, tracked.measurements], [dicomSeg.panel, tracked.measurements]] ``` This will result in two panels, one with `dicomSeg.panel` and `tracked.measurements` and the other with `dicomSeg.panel` and `tracked.measurements` stacked on top of each other. ::: #### Study Prefetcher You can enable the study prefetcher so that OHIF loads the next/previous series/display sets based on the proximity to the current series/display set. This can be useful to improve the user experience ```js studyPrefetcher: { /* Enable/disable study prefetching service (default: false) */ enabled: true, /* Number of displaysets to be prefetched (default: 2)*/ displaySetsCount: 2, /** * Max number of concurrent prefetch requests (default: 10) * High numbers may impact on the time to load a new dropped series because * the browser will be busy with all prefetching requests. As soon as the * prefetch requests get fulfilled the new ones from the new dropped series * are sent to the server. * * TODO: abort all prefetch requests when a new series is loaded on a viewport. * (need to add support for `AbortController` on Cornerstone) * */ maxNumPrefetchRequests: 10, /* Display sets loading order (closest (deafult), downward or upward) */ order: 'closest', }, ``` #### More on Accept Header Configuration In the previous section we showed that you can modify the `acceptHeader` configuration to request specific dicom transfer syntax. By default we use `acceptHeader: ['multipart/related; type=application/octet-stream; transfer-syntax=*']` for the following reasons: - **Ensures Optimal Transfer Syntax**: By allowing the server to select the transfer syntax, the client is more likely to receive the image in a syntax that's well-suited for fast transmission and rendering. This might be the original syntax the image was stored in or another syntax that the server deems efficient. - **Avoids Transcoding**: Transcoding (converting from one transfer syntax to another) can be a resource-intensive process. Since the OHIF Viewer supports all transfer syntaxes, it is fine to accept any transfer syntax (transfer-syntax=*). This allows the server to send the images in their stored syntax, avoiding the need for costly on-the-fly conversions. This approach not only saves server resources but also reduces response times by leveraging the viewer's capability to handle various syntaxes directly. - **Faster Data Transfer**: Compressed transfer syntaxes generally result in smaller file sizes compared to uncompressed ones. Smaller files transmit faster over the network, leading to quicker load times for the end-user. By accepting any syntax, the client can take advantage of compression when available. However, if you would like to get compressed data in a specific transfer syntax, you can modify the `acceptHeader` configuration or `requestTransferSyntaxUID` configuration. #### Data Source: stackRetrieveOptions At the data source configuration level, you can set `stackRetrieveOptions` to customize Cornerstone stack image retrieval. Merged with defaults; only specify overrides. For example, set `streaming: false` when the data source returns uncompressed DICOM (e.g. `application/octet-stream` only) to avoid black image on load: ```js configuration: { acceptHeader: ['application/octet-stream'], stackRetrieveOptions: { retrieveOptions: { single: { streaming: false } }, }, } ``` #### Environment Variables We use environment variables at build and dev time to change the Viewer's behavior. We can update the `HTML_TEMPLATE` to easily change which extensions are registered, and specify a different `APP_CONFIG` to connect to an alternative data source (or even specify different default hotkeys). | Environment Variable | Description | Default | | -------------------- | -------------------------------------------------------------------------------------------------- | ------------------- | | `HTML_TEMPLATE` | Which [HTML template][html-templates] to use as our web app's entry point. Specific to PWA builds. | `index.html` | | `PUBLIC_URL` | The route relative to the host that the app will be served from. Specific to PWA builds. | `/` | | `APP_CONFIG` | Which [configuration file][config-file] to copy to output as `app-config.js` | `config/default.js` | | `PROXY_TARGET` | When developing, proxy requests that match this pattern to `PROXY_DOMAIN` | `undefined` | | `PROXY_DOMAIN` | When developing, proxy requests from `PROXY_TARGET` to `PROXY_DOMAIN` | `undefined` | | `OHIF_PORT` | The port to run the webpack server on for PWA builds. | `3000` | You can also create a new config file and specify its path relative to the build output's root by setting the `APP_CONFIG` environment variable. You can set the value of this environment variable a few different ways: - ~[Add a temporary environment variable in your shell](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#adding-temporary-environment-variables-in-your-shell)~ - Previous `react-scripts` functionality that we need to duplicate with `dotenv-webpack` - ~[Add environment specific variables in `.env` file(s)](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#adding-development-environment-variables-in-env)~ - Previous `react-scripts` functionality that we need to duplicate with `dotenv-webpack` - Using the `cross-env` package in a npm script: - `"build": "cross-env APP_CONFIG=config/my-config.js react-scripts build"` After updating the configuration, `yarn run build` to generate updated build output. [dcmjs-org]: https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/wado [dicom-web]: https://en.wikipedia.org/wiki/DICOMweb [storescu]: https://support.dcmtk.org/docs/storescu.html [webpack-proxy]: https://webpack.js.org/configuration/dev-server/#devserverproxy [orthanc-docker-compose]: https://github.com/OHIF/Viewers/tree/master/platform/app/.recipes/Nginx-Orthanc [dcm4chee]: https://github.com/dcm4che/dcm4chee-arc-light [dcm4chee-docker]: https://github.com/dcm4che/dcm4chee-arc-light/wiki/Running-on-Docker [orthanc]: https://www.orthanc-server.com/ [orthanc-docker]: https://book.orthanc-server.com/users/docker.html [dicomcloud]: https://github.com/DICOMcloud/DICOMcloud [dicomcloud-install]: https://github.com/DICOMcloud/DICOMcloud#running-the-code [osirix]: https://www.osirix-viewer.com/ [horos]: https://www.horosproject.org/ [default-config]: https://github.com/OHIF/Viewers/blob/master/platform/app/public/config/default.js [html-templates]: https://github.com/OHIF/Viewers/tree/master/platform/app/public/html-templates [config-files]: https://github.com/OHIF/Viewers/tree/master/platform/app/public/config --- ## Configuring Tours in OHIF Source: https://docs.ohif.org/llm/configuration/tours.md #### Configuring Tours in OHIF with Shepherd.js In OHIF, you can configure guided tours for users by leveraging [Shepherd.js](https://shepherdjs.dev/), a JavaScript library for building feature tours. This page explains how you can define and customize these tours within your app configuration file. #### Overview Tours allow you to provide step-by-step guidance to users, explaining different features of your mode/extension or the viewer. Each tour is associated with a route and consists of several steps, each guiding the user through specific interactions in the viewer. #### Adding a Tour to your Configuration Here's how you can add a tour to your configuration file: ```javascript window.config = { customizationService: { 'ohif.tours': { $set: [ { id: 'basicViewerTour', route: '/viewer', steps: [ { id: 'zoom', title: 'Zooming In and Out', text: 'You can zoom the images using the right click.', attachTo: { element: '.viewport-element', on: 'left', }, advanceOn: { selector: '.cornerstone-viewport-element', event: 'CORNERSTONE_TOOLS_MOUSE_UP', }, }, ], }, ], }, }, }; ``` #### Explanation of Parameters #### `tours` Array Each item in the `tours` array defines a specific tour for a particular route. The object contains the following properties: - **`id`**: A unique identifier for the tour. This helps in tracking whether the tour has been shown. - **`route`**: The route in the application where the tour is applicable. When the user navigates to this route, the tour can automatically trigger if it hasn't been shown before. - **`steps`**: An array of steps that define the individual guide elements in the tour. Each step corresponds to a UI element and guides the user through interactions. - **`tourOptions`**: An object that allows you to configure the overall behavior of the tour, such as using a modal overlay or defining default step options. #### `steps` Array Each step defines a part of the tour. Here's a breakdown of the properties you can define: - **`id`**: A unique identifier for the step within the tour. - **`title`**: The title of the step, which appears at the top of the tooltip for the step. - **`text`**: The content or description of the step, explaining what the user needs to do or understand. - **`attachTo`**: Specifies where the step should be attached in the DOM. It includes: - `element`: A string selector or a DOM element that the step should attach to. - `on`: Specifies the position of the tooltip relative to the element (e.g., 'top', 'left', 'bottom', 'right'). - **`advanceOn`**: Defines an event that will automatically advance the tour to the next step. This is useful for actions like clicking a button or scrolling. - `selector`: The CSS selector for the element that triggers the advance. - `event`: The event name that advances the step, this can be a OHIF service event, or a cornerstone event, or any native JS event (e.g., 'click', 'CORNERSTONE_TOOLS_MOUSE_WHEEL'). - **`beforeShowPromise`**: A function that returns a promise. When the promise resolves, the rest of the show logic for the step will execute. You can use this to ensure that the target element is ready before the step shows. #### `tourOptions` The `tourOptions` object allows you to configure the overall behavior of the tour. Here's a breakdown of the available properties: - **`useModalOverlay`**: A boolean that, if set to `true`, places the tour steps above a darkened modal overlay. The overlay creates an opening around the target element so it can remain interactive. - **`defaultStepOptions`**: Default options that apply to all steps in the tour. You can override these in individual steps. The following are some options available: - `buttons`: An array of button objects that appear in the footer of each step. Each button can trigger actions like advancing the tour or skipping it. For example: - **`text`**: The label text on the button. - **`action`**: A function to execute when the button is clicked. You can advance the tour using `this.next()`, or complete it using `this.complete()`. - **`secondary`**: A boolean that, when set to `true`, styles the button as secondary (often for actions like skipping). #### `floatingUIOptions` You can define positioning options for the steps using **Floating UI** middleware. This helps control how the steps are positioned, especially near the browser edges. For example, you can ensure that the steps maintain a margin of 24px from the viewport edges by configuring `preventOverflow` middleware: ```javascript floatingUIOptions: { middleware: [ preventOverflow({ padding: 24 }), flip(), // Allows the step to flip if it is overflowing ] } ``` #### Shepherd.js Lifecycle Events Each step and tour can have lifecycle events like `show`, `hide`, `complete`, or `cancel`. These events allow you to hook into the tour’s lifecycle to perform actions when certain events are triggered. For example: ```javascript when: { show() { console.log('Step shown!'); }, hide() { console.log('Step hidden.'); } } ``` #### Customizing Your Tour Once you have a basic tour in place, you can extend it with more advanced features like custom scrolling behavior, dynamic elements, and event-based step advancement. For more details, check out the [Shepherd.js documentation](https://shepherdjs.dev/). #### Licensing All versions below 14.0 for Shepherd.JS is under the MIT license, if you wish to use any version above 14.0, you can visit the ShepherdJS website to learn about their pricing and plans [Shepherd.js](https://www.shepherdjs.dev/) [LICENSE](https://github.com/shipshapecode/shepherd?tab=License-1-ov-file#readme) #### Demo ![Tour Demo]() #### Conclusion By leveraging **Shepherd.js**, you can provide users with interactive and informative guided tours of the viewer. This can greatly improve the user experience and help users understand how to use key features. --- ## UI & Appearance Source: https://docs.ohif.org/llm/configuration/ui.md #### UI & Appearance OHIF's user interface is built on **ui-next**, a component library purpose-built for medical imaging workflows. It provides a consistent set of React components, a token-based theming system, a curated icon set, and a collection of UI services that manage runtime behavior like modals, notifications, and viewport layout. This page gives a high-level map of how these pieces fit together and where to find detailed documentation for each. #### Component Library The [component library](/components) is the foundation of every panel, toolbar, dialog, and control in the viewer. Components are organized into three tiers: - **Simple components** — atomic building blocks like Button, Checkbox, Input, Label, Slider, and Switch. These are styled with the design system's tokens and are the smallest interactive units. - **Compound components** — composed from simple components to handle more complex interactions: Select, Dialog, DropdownMenu, Tabs, Table, Popover, Tooltip, Toast, and others. These manage their own state (open/close, selection, focus) via headless patterns. - **OHIF-specific components** — built for medical imaging workflows and not found in general-purpose libraries: AllInOneMenu, CinePlayer, DataRow, DataTable, Numeric, PanelSection, SmartScrollbar, ToolButton, and ToolButtonList. These integrate directly with OHIF's services and extension system. Every component renders live in the interactive [Components](/components) section of this documentation site, where you can see props, variants, and copy usage examples. #### Appearance Dialog The Appearance dialog is an optional UI that lets end users switch presets, apply custom CSS overrides, and share themes via URL. It is not enabled by default, but deployers can [opt in via configuration](../platform/services/customization-service/appearance-theming.md#enabling-the-theme-module). See [Appearance & Theming](../platform/services/customization-service/appearance-theming.md) for the full setup and developer guide. #### Colors & Theming OHIF uses a **token-based color system** built on CSS custom properties with HSL values. The base theme (dark mode) is defined in `:root` via Tailwind CSS, and theme presets override specific tokens by applying a CSS class to `document.body`. The theming system covers: - **[Design tokens](/colors-and-theming#color-tokens-and-roles)** — a set of semantic color variables (`--background`, `--primary`, `--card`, `--border`, etc.) that every component references. Tokens are defined as HSL triplets and consumed via Tailwind's `hsl(var(...))` pattern. - **Theme presets** — six built-in themes (three tonal, three neutral) that shift the entire interface's color palette. Presets are defined as JSON files and applied via CSS classes. Also see: [Creating Themes](/colors-and-theming#creating-themes) and [Adding a Theme Preset](../platform/services/customization-service/appearance-theming.md#adding-a-theme-preset). - **Accessibility** — foreground tokens are paired with every surface token to maintain contrast ratios across themes. When adding custom themes, [test colors to match accessibility standards](/colors-and-theming#accessibility). Explore the live token swatches and theme picker in the interactive [Colors & Theming](/colors-and-theming) page, and see [Appearance & Theming](../platform/services/customization-service/appearance-theming.md) for the full configuration and developer guide. #### Iconography OHIF ships a curated set of icons designed specifically for medical imaging interfaces. Icons are SVG-based, registered via `addIcon()`, and rendered through the `Icons` component. They follow the same token system as the rest of the UI, so icon colors respond to the active theme. Browse the full set with search and click-to-copy in the [Iconography](/components/icons) page. #### White Labeling OHIF supports replacing the header logo with custom branding via the `whiteLabeling` configuration key. This lets you rebrand the viewer without modifying source code. Add a `whiteLabeling` entry to your configuration file with a `createLogoComponentFn` that returns a React element: ```js window.config = { /** .. **/ whiteLabeling: { createLogoComponentFn: function(React) { return React.createElement( 'a', { target: '_self', rel: 'noopener noreferrer', className: 'text-purple-600 line-through', href: '/', }, React.createElement('img', { src: './customLogo.svg', }) ); }, }, /** .. **/ }; ``` ![custom-logo](../assets/img/custom-logo.png) You can use Tailwind CSS utility classes in the `className` property to style your custom logo component. #### UI Services While the component library handles what gets rendered, **UI services** handle the runtime behavior: opening modals, showing notifications, managing viewport layout, and coordinating dialogs. These services use a pub/sub architecture and are accessed through the `servicesManager`: | Service | What it manages | |---------|----------------| | [Modal Service](../platform/services/ui/ui-modal-service.md) | Full-screen and contained modals (including the Appearance dialog) | | [Dialog Service](../platform/services/ui/ui-dialog-service.md) | Lightweight dialogs with form inputs and confirmations | | [Notification Service](../platform/services/ui/ui-notification-service.md) | Toast notifications (success, warning, error, info) | | [Viewport Grid Service](../platform/services/ui/viewport-grid-service.md) | Viewport layout, grid arrangement, and active viewport tracking | | [Viewport Dialog Service](../platform/services/ui/ui-viewport-dialog-service.md) | Dialogs anchored to specific viewports | | [Viewport Action Menu](../platform/services/ui/viewport-action-menu.md) | Context menus and action buttons on viewport corners | | [Cine Service](../platform/services/ui/cine-service.md) | Cine playback controls and frame rate | UI services are documented in the [Services > UI](../platform/services/ui/index.md) section. #### Customization Service The [Customization Service](../platform/services/customization-service/customizationService.md) is the mechanism that ties everything together. It allows deployers and extension authors to override, extend, or replace UI components and behaviors without modifying core code. Customizations can be scoped to a specific mode, set globally via configuration, or provided as defaults by extensions. The Appearance dialog itself is delivered as a customization module. Deployers enable it by adding a single reference to their config's `customizationService` array. This pattern means that any part of the UI that supports customization can be configured the same way. See the full customization guide at [Customization Service](../platform/services/customization-service/customizationService.md), including the syntax reference for `$set`, `$push`, `$merge`, `$filter`, and other operations. --- ## URL Parameters Source: https://docs.ohif.org/llm/configuration/url.md #### URL You can modify the URL at any state of the app to get the desired result. Here are different part of the APP that you can modify: #### WorkList The WorkList can be modified by adding the following query parameters: #### PatientName The patient name can be modified by adding the `PatientName` query parameter. ```js /?patientName=myQuery ``` #### MRN The MRN can be modified by adding the `MRN` query parameter. ```js /?mrn=myQuery ``` #### Description The description can be modified by adding the `Description` query parameter. ```js /?description=myQuery ``` #### Modality The modality can be modified by adding the `modalities` query parameter. ```js /?modalities=MG ``` #### Accession Number The accession number can be modified by adding the `accession` query parameter. ```js /?accession=myQuery ``` #### DataSources If you happen to have multiple data sources configured, you can filter the WorkList by adding the `dataSources` query parameter. ```js /?dataSources=orthanc ``` Note1: You should pass the `sourceName` of the data source in the configuration file (not the friendly name nor the name) Note2: Make sure that the configuration file you are using actually includes that data source. You cannot use a data source from another configuration file. :::tip You can add `sortBy` and `sortDirection` query parameters to sort the WorkList ```js /?patientName=myquery&sortBy=studyDate&sortDirection=ascending ``` ::: #### Viewer The Viewer can be modified by adding the following query parameters: #### Mode As you have seen before, the Viewer can be configured to be in different modes. Each mode registers their `id` in the URL. For instance ```js /viewer?StudyInstanceUIDs=1.3.6.1.4.1.14519.5.2.1.7009.2403.871108593056125491804754960339 ``` will open the viewer in the basic (longitudinal) mode with the StudyInstanceUID 1.3.6.1.4.1.14519.5.2.1.7009.2403.871108593056125491804754960339. And if configured, the same study can be opened in the `tmtv` mode ```js /tmtv?StudyInstanceUIDs=1.3.6.1.4.1.14519.5.2.1.7009.2403.871108593056125491804754960339 ``` #### StudyInstanceUIDs You can open more than one study in the Viewer by adding the `StudyInstanceUIDs` ```js /viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095722.1&StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095258.1 ``` :::tip You can use this feature to open a current and prior study in the Viewer. Read more in the [Hanging Protocol Module](../platform/extensions/modules/hpModule.md#matching-on-prior-study-with-uid) section. You can also use commas to separate values. ::: #### SeriesInstanceUIDs Sometimes you need to only retrieve a specific series in a study, you can do that by providing series level QIDO query parameters in the URL such as SeriesInstanceUIDs. This does NOT work with instance or study level parameters. For example: ```js http://localhost:3000/viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095438.5&SeriesInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095449.8 ``` This will only open the viewer with one series (one displaySet) loaded, and no queries made for any other series. Sometimes you need to only retrieve a subset of series in a study, you can do that by providing more than one series, separated by commas. For example: ```js http://localhost:3000/viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095438.5&SeriesInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095449.8,1.3.6.1.4.1.25403.345050719074.3824.20170125095506.10 ``` This will only open the viewer with two series (two displaySets) loaded, and no queries made for any other series. #### initialSeriesInstanceUID Alternatively, sometimes you want to just open the study on a specified series, but allowing other series to be present too. This is the same behavior can be achieved by using the `initialSeriesInstanceUID` parameter. For example: ```js http://localhost:3000/viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095438.5&initialSeriesInstanceUID=1.3.6.1.4.1.25403.345050719074.3824.20170125095449.8 ``` This will open all the series in the study, but the viewer will start with the series specified by the `initialSeriesInstanceUID` parameter. Note that you can combine these, if you want to load a specific set of series plus show an initial one as the first one selected, for example: ```js http://localhost:3000/viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095438.5&SeriesInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095449.8,1.3.6.1.4.1.25403.345050719074.3824.20170125095506.10&initialSeriesInstanceUID=1.3.6.1.4.1.25403.345050719074.3824.20170125095506.10 ``` #### initialSopInstanceUID You can also specify the initial SOP Instance to be displayed by using the `initialSopInstanceUID` parameter. For example: ```js http://localhost:3000/viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095438.5&SeriesInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095449.8&initialSopInstanceUID=1.3.6.1.4.1.25403.345050719074.3824.20170125095501.9 ``` This will open the study with the filtered series, and navigate to the slice 101 which happens to be the SOP Instance specified by the `initialSopInstanceUID` Note: again you can mix and match ```js http://localhost:3000/viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095438.5&SeriesInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095449.8,1.3.6.1.4.1.25403.345050719074.3824.20170125095506.10&initialSeriesInstanceUID=1.3.6.1.4.1.25403.345050719074.3824.20170125095506.10&initialSopInstanceUID=1.3.6.1.4.1.25403.345050719074.3824.20170125095510.8 ``` You can even load the whole study and only specify the initial SOP Instance to be displayed. Although it will take more time to match, but it works as expected. ```js http://localhost:3000/viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095438.5&initialSopInstanceUID=1.3.6.1.4.1.25403.345050719074.3824.20170125095510.8 ``` #### hangingProtocolId You can select the initial hanging protocol to apply by using the hangingProtocolId parameter. The selected parameter must be available in a hangingProtocolModule registration, but does not have to be active. For instance for loading a specific study in mpr mode from start you can use: ```js http://localhost:3000/viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095438.5&hangingProtocolId=@ohif/mnGrid ``` #### token Although not recommended, you can use the token param in the URL which will inject the token into the Authorization header of the request. --- ## DataSources ### Configuration UI Source: https://docs.ohif.org/llm/configuration/dataSources/configuration-ui.md #### Configuration UI OHIF provides for a generic mechanism for configuring a data source. This is most useful for those organizations with several data sources that share common (path) hierarchies. For example, an organization may have several DICOM stores in the Google Cloud Healthcare realm where each is organized into various projects, location, data sets and DICOM stores. By implementing the `BaseDataSourceConfigurationAPI` and `BaseDataSourceConfigurationAPIItem` in an [OHIF extension](../../platform/extensions/index.md), a data source can be made configurable via the generic UI as is depicted below for a Google Cloud Healthcare data source. ![Data source configuration UI](../../assets/img/data-source-configuration-ui.png) :::tip A datasource root URI can be [fully or partially specified](../../deployment/google-cloud-healthcare.md#configuring-google-cloud-healthcare-as-a-datasource-in-ohif) in the OHIF configuration file. ::: #### `BaseDataSourceConfigurationAPIItem` interface Each (path) item of a data source is represented by an instance of this interface. At the very least each of these items must expose two properties: |Property |Description| |---------|-----------| |id|a string that uniquely identifies the item| |name|a human readable name for the item| Note that information such as where in the path hierarchy the item exists has been omitted, but can be added in any concrete class that might implement this interface. For example, the the Google Cloud Healthcare implementation of this interface (`GoogleCloudDataSourceConfigurationAPIItem`) adds an `itemType` (i.e. projects, locations, datasets, or dicomStores) and `url`. #### `BaseDataSourceConfigurationAPI` interface The implementation of this interface is at the heart of the configuration process. It possesses several methods for building up a data source path based on various `BaseDataSourceConfigurationAPIItem` objects that are set via calls to the `setCurrentItem` method. The constructor for the concrete class implementation should accept whatever parameters are necessary for configuring the data source. One argument to the constructor must be the string identifying the name of the data source to be configured. Furthermore, considering that the `ExtensionManager` possesses API to configure and update data sources, it too will likely be an argument to the constructor. See [Creation via Customization Module](#creation-via-customization-module) for more information on how the constructor is invoked via a factory method. For an example implementation of this interface see `GoogleCloudDataSourceConfigurationAPI`. #### Interface Methods Each of the following subsections lists a method of the interface with a description detailing what the method should do. #### `getItemLabels` Gets the i18n labels (i.e. the i18n lookup keys) for each of the configurable items of the data source configuration API. For example, for the Google Cloud Healthcare API, this would be `['Project', 'Location', 'Data set', 'DICOM store']`. Besides the configurable item labels themselves, several other string look ups are used base on EACH of the labels returned by this method. For instance, for the label `{itemLabel}`, the following strings are fetched for translation... 1. No `{itemLabel}` available - used to indicate no such items are available - for example, for Google, No Project available would be 'No projects available' 2. Select `{itemLabel}` - used to direct selection of the item - for example, for Google, Select Project would be 'Select a project' 3. Error fetching `{itemLabel}` list - used to indicate an error occurred fetching the list of items - usually accompanied by the error itself - for example, for Google, Error fetching Project list would be 'Error fetching projects' 4. Search `{itemLabel}` list - used as the placeholder text for filtering a list of items - for example, for Google, Search Project list would be 'Search projects' #### `initialize` Initializes the cloud server API and returns the top-level sub-items that can be chosen to begin the process of configuring a data source. For example, for the Google Cloud Healthcare API, this would perform the initial request to fetch the top level projects for the logged in user account. #### `setCurrentItem` Sets the current path item that is passed as an argument to the method and returns the sub-items of that item that can be further chosen to configure a data source. When setting the last configurable item of the data source (path), this method returns an empty list AND configures the active data source with the selected items path. For example, for the Google Cloud Healthcare API, this would take the current item (say a data set) and queries and returns its sub-items (i.e. all of the DICOM stores contained in that data set). Furthermore, whenever the item to set is a DICOM store, the Google Cloud Healthcare API implementation would update the OHIF data source associated with this instance to point to that DICOM store. #### `getConfiguredItems` Gets the list of items currently configured for the data source associated with this API instance. The resultant array must be the same length as the result of `getItemLabels`. Furthermore the items returned should correspond (index-wise) with the labels returned from `getItemLabels`. #### Creation via Customization Module The generic UI (i.e. `DataSourceConfigurationComponent`) uses the [OHIF UI customization service](../../platform/services/customization-service/customizationService.md) to instantiate the `BaseDataSourceConfigurationAPI` instance to configure a data source. A UI configurable data source should have a `configurationAPI` field as part of its `configuration` in the OHIF config file. The `configurationAPI` value is the customization id of the customization module that provides the factory method to instantiate the `BaseDataSourceConfigurationAPI` instance. For example, the following is a snippet of a Google Cloud Healthcare data source configuration. ```js dataSources: [ { namespace: '@ohif/extension-default.dataSourcesModule.dicomweb', sourceName: 'google-dicomweb', configuration: { name: 'GCP', wadoUriRoot: 'https://healthcare.googleapis.com/v1/projects/ohif-cloud-healthcare/locations/us-east4/...', ... configurationAPI: 'ohif.dataSourceConfigurationAPI.google', ... }, }, ] ``` This suggests that the factory method is provided by the `'ohif.dataSourceConfigurationAPI.google'` customization module. That customization module is provided by the `default` extension's `getCustomizationModule` and looks something like the following snippet of code. Notice that the factory method's name MUST be `factory` and accept one argument - the data source name. Furthermore note how the constructor is invoked with anything required by the concrete configuration API class. ```js export default function getCustomizationModule({ servicesManager, extensionManager, }) { return [ { name: 'default', value: [ { // The factory for creating an instance of a BaseDataSourceConfigurationAPI for Google Cloud Healthcare id: 'ohif.dataSourceConfigurationAPI.google', factory: (dataSourceName: string) => new GoogleCloudDataSourceConfigurationAPI( dataSourceName, servicesManager, extensionManager ), }, ], }, ]; } ``` --- ### DICOM JSON Source: https://docs.ohif.org/llm/configuration/dataSources/dicom-json.md #### DICOM JSON You can launch the OHIF Viewer with a JSON file which points to a DICOMWeb server as well as a list of study and series instance UIDs along with metadata. An example would look like `https://viewer.ohif.org/viewer/dicomjson?url=https://ohif-dicom-json-example.s3.amazonaws.com/LIDC-IDRI-0001.json` As you can see the url to the location of the JSON file is passed in the query after the `dicomjson` string, which is `https://ohif-dicom-json-example.s3.amazonaws.com/LIDC-IDRI-0001.json` (this json file has been generated by OHIF team and stored in an amazon s3 bucket for the purpose of the guide). #### DICOM JSON sample Here we are using the LIDC-IDRI-0001 case which is a sample of the LIDC-IDRI dataset. Let's have a look at the JSON file: #### Metadata JSON file stores the metadata for the study level, series level and instance level. A JSON launch file should follow the same structure as the one below. :::tip You can use our script to generate the JSON file from a hosted endpoint. See `.scripts/dicom-json-generator.js` You could run it like this: ```bash node .scripts/dicom-json-generator.js '/path/to/study/folder' 'url/to/dicom/server/folder' 'json/output/file.json' ``` Some modalities require additional metadata to be added to the JSON file. You can read more about the minimum amount of metadata required for the viewer to work [here](../../faq/technical#what-are-the-list-of-required-metadata-for-the-ohif-viewer-to-work). We will handle this in the script. For example, the script will add the CodeSequences for SR in order to display the measurements in the viewer. ::: Note that at the instance level metadata we are storing both the `metadata` and also the `url` for the dicom file on the dicom server. In this case we are referring to `dicomweb:https://ohif-dicom-json-example.s3.amazonaws.com/LIDC-IDRI-0001/01-01-2000-30178/3000566.000000-03192/1-001.dcm` which is stored in another directory in our s3. (You can actually try downloading the dicom file by opening the url in your browser). The URL to the script in the given example is `https://ohif-dicom-json-example.s3.amazonaws.com/LIDC-IDRI-0001/01-01-2000-30178`. This URL serves as the parent directory that contains all the series within their respective folders. ```json { "studies": [ // first study metadata { "StudyInstanceUID": "1.3.6.1.4.1.14519.5.2.1.6279.6001.298806137288633453246975630178", "StudyDate": "20000101", "StudyTime": "", "PatientName": "", "PatientID": "LIDC-IDRI-0001", "AccessionNumber": "", "PatientAge": "", "PatientSex": "", "series": [ // first series metadata { "SeriesInstanceUID": "1.3.6.1.4.1.14519.5.2.1.6279.6001.179049373636438705059720603192", "SeriesNumber": 3000566, "Modality": "CT", "SliceThickness": 2.5, "instances": [ // first instance metadata { "metadata": { "Columns": 512, "Rows": 512, "InstanceNumber": 1, "SOPClassUID": "1.2.840.10008.5.1.4.1.1.2", "PhotometricInterpretation": "MONOCHROME2", "BitsAllocated": 16, "BitsStored": 16, "PixelRepresentation": 1, "SamplesPerPixel": 1, "PixelSpacing": [0.703125, 0.703125], "HighBit": 15, "ImageOrientationPatient": [1, 0, 0, 0, 1, 0], "ImagePositionPatient": [-166, -171.699997, -10], "FrameOfReferenceUID": "1.3.6.1.4.1.14519.5.2.1.6279.6001.229925374658226729607867499499", "ImageType": ["ORIGINAL", "PRIMARY", "AXIAL"], "Modality": "CT", "SOPInstanceUID": "1.3.6.1.4.1.14519.5.2.1.6279.6001.262721256650280657946440242654", "SeriesInstanceUID": "1.3.6.1.4.1.14519.5.2.1.6279.6001.179049373636438705059720603192", "StudyInstanceUID": "1.3.6.1.4.1.14519.5.2.1.6279.6001.298806137288633453246975630178", "WindowCenter": -600, "WindowWidth": 1600, "SeriesDate": "20000101" }, "url": "dicomweb:https://ohif-dicom-json-example.s3.amazonaws.com/LIDC-IDRI-0001/01-01-2000-30178/3000566.000000-03192/1-001.dcm" }, // second instance metadata { "metadata": { "Columns": 512, "Rows": 512, "InstanceNumber": 2, "SOPClassUID": "1.2.840.10008.5.1.4.1.1.2", "PhotometricInterpretation": "MONOCHROME2", "BitsAllocated": 16, "BitsStored": 16, "PixelRepresentation": 1, "SamplesPerPixel": 1, "PixelSpacing": [0.703125, 0.703125], "HighBit": 15, "ImageOrientationPatient": [1, 0, 0, 0, 1, 0], "ImagePositionPatient": [-166, -171.699997, -12.5], "FrameOfReferenceUID": "1.3.6.1.4.1.14519.5.2.1.6279.6001.229925374658226729607867499499", "ImageType": ["ORIGINAL", "PRIMARY", "AXIAL"], "Modality": "CT", "SOPInstanceUID": "1.3.6.1.4.1.14519.5.2.1.6279.6001.512235483218154065970649917292", "SeriesInstanceUID": "1.3.6.1.4.1.14519.5.2.1.6279.6001.179049373636438705059720603192", "StudyInstanceUID": "1.3.6.1.4.1.14519.5.2.1.6279.6001.298806137288633453246975630178", "WindowCenter": -600, "WindowWidth": 1600, "SeriesDate": "20000101" }, "url": "dicomweb:https://ohif-dicom-json-example.s3.amazonaws.com/LIDC-IDRI-0001/01-01-2000-30178/3000566.000000-03192/1-002.dcm" } // ..... other instances metadata ] } // ... other series metadata ], "NumInstances": 133, "Modalities": "CT" } // second study metadata ] } ``` ![](../../assets/img/dicom-json.png) #### Local Demo You can run OHIF with a JSON data source against you local datasets (given that their JSON metadata is extracted). First you need to put the JSON file and the folder containing the dicom files inside your `public` folder. Since files are served from your local server the `url` for the JSON file will be `http://localhost:3000/LIDC-IDRI-0001.json` and the dicom files will be `dicomweb:http://localhost:3000/LIDC-IDRI-0001/01-01-2000-30178/3000566.000000-03192/1-001.dcm`. After `yarn install --frozen-lockfile` and running `yarn dev` and opening the browser at `http://localhost:3000/viewer/dicomjson?url=http://localhost:3000/LIDC-IDRI-0001.json` will display the viewer. Download JSON file from [here](https://www.dropbox.com/sh/zvkv6mrhpdze67x/AADLGK46WuforD2LopP99gFXa?dl=0) Sample DICOM files can be downloaded from [TCIA](https://wiki.cancerimagingarchive.net/display/Public/LIDC-IDRI) or directly from [here](https://www.dropbox.com/sh/zvkv6mrhpdze67x/AADLGK46WuforD2LopP99gFXa?dl=0) Your public folder should look like this: ![](../../assets/img/dicom-json-public.png) :::tip It is important to URL encode the `url` query parameter especially if the `url` parameter itself also contains query parameters. So for example, `http://localhost:3000/viewer/dicomjson?url=http://localhost:3000/LIDC-IDRI-0001.json?key0=val0&key1=val1` should be... `http://localhost:3000/viewer/dicomjson?url=http://localhost:3000/LIDC-IDRI-0001.json?key0=val0%26key1=val1` Notice the ampersand (`&`) is encoded as `%26`. ::: :::note When hosting the DICOM JSON files, it is important to be aware that certain providers do not automatically handle the 404 error and fallback to index.html. For example, Netlify handles this, but Azure does not. Consequently, when you attempt to access a link with a specific URL, a 404 error will be displayed. This issue also occurs locally, where the http-server does not handle it. However, if you utilize the `serve` package (npx serve ./dist -c ../public/serve.json), it effectively addresses this problem. ::: --- ### DICOMweb Proxy Source: https://docs.ohif.org/llm/configuration/dataSources/dicom-web-proxy.md #### DICOMweb Proxy You can launch the OHIF Viewer with a url that returns a JSON file which contains a DICOMWeb configuration. The DICOMweb Proxy constructs a DICOMweb datasource and delegates subsequent requests for metadata and images to that. Usage is similar to that of the [DICOM JSON](./dicom-json.md) datasource and might look like `https://viewer.ohif.org/viewer/dicomwebproxy?url=https://ohif-dicom-json-example.s3.amazonaws.com/dicomweb.json` The url to the location of the JSON file is passed in the query after the `dicomwebproxy` string, which is `https://ohif-dicom-json-example.s3.amazonaws.com/dicomweb.json` (this json file does not exist at the moment of this writing). #### DICOMweb JSON configuration sample The json returned by the url in this example contains a dicomweb configuration (see [DICOMweb](dicom-web.md)), in a "servers" object, which is then used to construct a dynamic DICOMweb datasource to delegate requests to. Here is an example configuration that might be returned using the url parameter. ```json { "servers": { "dicomWeb": [ { "name": "DCM4CHEE", "wadoUriRoot": "https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/wado", "qidoRoot": "https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/rs", "wadoRoot": "https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/rs", "qidoSupportsIncludeField": true, "supportsReject": true, "imageRendering": "wadors", "thumbnailRendering": "wadors", "enableStudyLazyLoad": true, "supportsFuzzyMatching": true, "supportsWildcard": true } ] } } ``` The DICOMweb Proxy expects the json returned by the url parameter it is invoked with to include a servers object which contains a "dicomWeb" configuration array as above. It will only consider the first array item in the dicomWeb configuration. --- ### DICOMweb Source: https://docs.ohif.org/llm/configuration/dataSources/dicom-web.md #### DICOMweb #### Set up a local DICOM server ATTENTION! Already have a remote or local server? Skip to the [configuration section](#configuration-learn-more) below. While the OHIF Viewer can work with any data source, the easiest to configure are the ones that follow the [DICOMWeb][dicom-web] spec. 1. Choose and install an Image Archive 2. Upload data to your archive (e.g. with DCMTK's [storescu][storescu] or your archive's web interface) 3. Keep the server running For our purposes, we will be using `Orthanc`, but you can see a list of [other Open Source options](#open-source-dicom-image-archives) below. #### Requirements - Docker - [Docker for Mac](https://docs.docker.com/docker-for-mac/) - [Docker for Windows (recommended)](https://docs.docker.com/docker-for-windows/) - [Docker Toolbox for Windows](https://docs.docker.com/toolbox/toolbox_install_windows/) _Not sure if you have `docker` installed already? Try running `docker --version` in command prompt or terminal_ > If you are using `Docker Toolbox` you need to change the _PROXY_DOMAIN_ > parameter in _platform/app/package.json_ to http://192.168.99.100:8042 or > the ip docker-machine ip throws. This is the value [`WebPack`][webpack-proxy] > uses to proxy requests #### Open Source DICOM Image Archives There are a lot of options available to you to use as a local DICOM server. Here are some of the more popular ones: | Archive | Installation | | --------------------------------------------- | ---------------------------------- | | [DCM4CHEE Archive 5.x][dcm4chee] | [W/ Docker][dcm4chee-docker] | | [Orthanc][orthanc] | [W/ Docker][orthanc-docker] | | [DICOMcloud][dicomcloud] (**DICOM Web only**) | [Installation][dicomcloud-install] | | [OsiriX][osirix] (**Mac OSX only**) | Desktop Client | | [Horos][horos] (**Mac OSX only**) | Desktop Client | _Feel free to make a Pull Request if you want to add to this list._ Below, we will focus on `DCM4CHEE` and `Orthanc` usage: #### Running Orthanc _Start Orthanc:_ ```bash #### Runs orthanc so long as window remains open yarn run orthanc:up ``` _Upload your first Study:_ 1. Navigate to [Orthanc's web interface](http://localhost:8042/ui/app/index.html#/) at `http://localhost:8042/ui/app/index.html#/` in a web browser. 2. In the left you can see the upload button where you can drag and drop your DICOM files #### Orthanc: Learn More You can see the `docker-compose.yml` file this command runs at [`/platform/app/.recipes/Nginx-Orthanc`][orthanc-docker-compose], and more on Orthanc for Docker in [Orthanc's documentation][orthanc-docker]. #### Connecting to Orthanc Now that we have a local Orthanc instance up and running, we need to configure our web application to connect to it. Open a new terminal window, navigate to this repository's root directory, and run: ```bash #### If you haven't already, enable yarn workspaces yarn config set workspaces-experimental true #### Restore dependencies yarn install --frozen-lockfile #### Run our dev command, but with the local orthanc config yarn run dev:orthanc ``` #### Configuration: Learn More > For more configuration fun, check out the > [Essentials Configuration](../configurationFiles.md) guide. Let's take a look at what's going on under the hood here. `yarn run dev:orthanc` is running the `dev:orthanc` script in our project's `package.json` (inside `platform/app`). That script is: ```js cross-env NODE_ENV=development PROXY_TARGET=/dicom-web PROXY_DOMAIN=http://localhost:8042 APP_CONFIG=config/docker-nginx-orthanc.js webpack-dev-server --config .webpack/webpack.pwa.js -w ``` - `cross-env` sets three environment variables - PROXY_TARGET: `/dicom-web` - PROXY_DOMAIN: `http://localhost:8042` - APP_CONFIG: `config/docker-nginx-orthanc.js` - `webpack-dev-server` runs using the `.webpack/webpack.pwa.js` configuration file. It will watch for changes and update as we develop. `PROXY_TARGET` and `PROXY_DOMAIN` tell our development server to proxy requests to `Orthanc`. This allows us to bypass CORS issues that normally occur when requesting resources that live at a different domain. The `APP_CONFIG` value tells our app which file to load on to `window.config`. By default, our app uses the file at `/platform/app/public/config/default.js`. Here is what that configuration looks like: ```js window.config = { routerBasename: null, extensions: [], modes: [], showStudyList: true, dataSources: [ { namespace: '@ohif/extension-default.dataSourcesModule.dicomweb', sourceName: 'dicomweb', configuration: { friendlyName: 'dcmjs DICOMWeb Server', name: 'DCM4CHEE', wadoUriRoot: 'https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/wado', qidoRoot: 'https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/rs', wadoRoot: 'https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/rs', qidoSupportsIncludeField: true, supportsReject: true, imageRendering: 'wadors', thumbnailRendering: 'wadors', enableStudyLazyLoad: true, supportsFuzzyMatching: true, supportsWildcard: true, }, }, ], defaultDataSourceName: 'dicomweb', }; ``` #### Data Source Configuration Options The following properties can be added to the `configuration` property of each data source. #### `dicomUploadEnabled` A boolean indicating if the DICOM upload to the data source is permitted/accepted or not. A value of true provides a link on the OHIF work list page that allows for DICOM files from the local file system to be uploaded to the data source :::tip The [OHIF plugin for Orthanc](https://book.orthanc-server.com/plugins/ohif.html) by default utilizes the DICOM JSON data source and it has been discovered that only those studies uploaded to Orthanc AFTER the plugin has been installed are available as DICOM JSON. As such, if the OHIF plugin for Orthanc is desired for studies uploaded prior to installing the plugin, then consider switching to using [DICOMweb instead](https://book.orthanc-server.com/plugins/ohif.html#using-dicomweb). ::: ![toolbarModule-layout](../../assets/img/uploader.gif) Don't forget to add the customization to the config as well ```js customizationService: { dicomUploadComponent: '@ohif/extension-cornerstone.customizationModule.cornerstoneDicomUploadComponent', }, ``` #### `singlepart` A comma delimited string specifying which payloads the data source responds with as single part. Those not listed are considered multipart. Values that can be included here are `pdf`, `video`, `bulkdata`, `thumbnail` and `image`. For DICOM video and PDF it has been found that Orthanc delivers multipart, while DCM4CHEE delivers single part. Consult the DICOM conformance statement for your particular data source to determine which payload types it delivers. To learn more about how you can configure the OHIF Viewer, check out our [Configuration Guide](../configurationFiles.md). #### `thumbnailRendering` Optional. Controls how thumbnail images are requested. | Value | Behavior | | ----- | -------- | | `wadors` (default) | Uses WADO-RS retrieval for thumbnail image content | | `thumbnailDirect` | Uses the thumbnail URL directly as the image source. Use this only when the archive serves that URL without auth headers | | `thumbnail` | Uses the WADO-RS `.../thumbnail` endpoint | | `rendered` | Uses the WADO-RS `.../rendered` endpoint | Use `thumbnail` or `rendered` when the archive supports dedicated thumbnail/rendered responses. If either is selected, `thumbnailRequestStrategy` controls how the image data is fetched. #### `thumbnailRequestStrategy` Optional. Controls how the app retrieves the data for various thumbnails (e.g. side study panel study browser and study list preview panel) when `thumbnailRendering` is `thumbnail` or `rendered`. It does not apply to `wadors` or `thumbnailDirect`. | Value | Behavior | | ----- | -------- | | `bulkDataRetrieve` (default) | Uses the DICOMweb client's bulk data retrieve API, consistent with other bulk data reads | | `fetch` | Performs an authenticated HTTP `GET` to the WADO-RS `.../thumbnail` or `.../rendered` URL and builds a blob URL from the JPEG response. Prefer this when the archive serves a plain image body and bulk data retrieve is incompatible or unreliable. | Example (Orthanc-style plain fetch for thumbnails): ```js thumbnailRendering: 'rendered', thumbnailRequestStrategy: 'fetch', ``` #### `queryLimit` Optional. The maximum number of studies requested from the server for the study list, passed as the `limit` query parameter to data sources that honor it. Paging is handled in the OHIF client, so this value caps how many studies a single search returns. When not specified, it defaults to `101`. ```js queryLimit: 101, ``` #### DICOM PDF See the [`singlepart`](#singlepart) data source configuration option. #### DICOM Video See the [`singlepart`](#singlepart) data source configuration option. #### BulkDataURI The `bulkDataURI` configuration option alters how the datasource uses the bulkdata end points for retrieving metadata if the data was originally not included in the response from the server. This is useful for the metadata information that are big and can/should be retrieved in a separate request. In case the bulkData URI is relative (instead of absolute) the `relativeResolution` option can be used to specify the resolution of the relative URI. The possible values are `studies`, `series`. The default value is shown below (this will be added if not included in the config). ```js bulkDataURI: { enabled: true, relativeResolution: 'series', }, ``` The other options allowed are: * transform - to take the string and return an updated string * startsWith and prefixWith - to remove a standard prefix and add an optional prefix * Used primarily for a reverse proxy or change in URL naming * relativeResolution - used to set bulkdata paths to studies resolution for incorrect bulkdata paths #### Running DCM4CHEE dcm4che is a collection of open source applications for healthcare enterprise written in Java programming language which implements DICOM standard. dcm4chee (extra 'e' at the end) is dcm4che project for an Image Manager/Image Archive which provides storage, retrieval and other functionalities. You can read more about dcm4chee in their website [here](https://www.dcm4che.org/) DCM4chee installation is out of scope for these tutorials and can be found [here](https://github.com/dcm4che/dcm4chee-arc-light/wiki/Run-minimum-set-of-archive-services-on-a-single-host) An overview of steps for running OHIF Viewer using a local DCM4CHEE is shown below:

[dcm4chee]: https://github.com/dcm4che/dcm4chee-arc-light [dcm4chee-docker]: https://github.com/dcm4che/dcm4chee-arc-light/wiki/Running-on-Docker [orthanc]: https://www.orthanc-server.com/ [orthanc-docker]: http://book.orthanc-server.com/users/docker.html [dicomcloud]: https://github.com/DICOMcloud/DICOMcloud [dicomcloud-install]: https://github.com/DICOMcloud/DICOMcloud#running-the-code [osirix]: http://www.osirix-viewer.com/ [horos]: https://www.horosproject.org/ [default-config]: https://github.com/OHIF/Viewers/blob/master/platform/app/public/config/default.js [html-templates]: https://github.com/OHIF/Viewers/tree/master/platform/app/public/html-templates [config-files]: https://github.com/OHIF/Viewers/tree/master/platform/app/public/config [storescu]: http://support.dcmtk.org/docs/storescu.html [webpack-proxy]: https://webpack.js.org/configuration/dev-server/#devserverproxy --- ### Data Source Introduction Source: https://docs.ohif.org/llm/configuration/dataSources/introduction.md #### Data Source The internal data structure of OHIF’s metadata follows naturalized DICOM JSON, a format pioneered by `dcmjs`. In short DICOM metadata headers with DICOM Keywords instead of tags and sequences as arrays, for easy development and clear code. Here in this section we will discuss couple of data sources that are commonly used and OHIF has provided the implementation for them. #### Custom Data Source Do you have a custom data source? or a custom data that you want to use in OHIF? You can easily write a data source to map your data to OHIF’s native format. You can read more in the [Data Source Module](../../platform/extensions/modules/data-source.md) --- ### Static DICOMweb Files Source: https://docs.ohif.org/llm/configuration/dataSources/static-files.md #### Static DICOMweb Files for Enhanced Performance This section describes how to generate and serve static DICOMweb files, significantly improving the performance of your OHIF Viewer setup. These files are pre-processed and compressed, minimizing storage space and reducing serving time to the bare minimum (disk read and HTTP stream write). #### Static-DICOMWeb Project The core tool for this process is the `static-wado` project, available on GitHub: [static-wado]: https://github.com/RadicalImaging/Static-DICOMWeb This project contains two main components: * **`static-wado-creator`:** Converts raw DICOM files into a DICOMweb-compliant directory structure, optimizing them for efficient serving. * **`static-wado-webserver`:** A simple web server specifically designed to serve the generated static DICOMweb files. #### Prerequisites - Node.js and npm (or yarn) installed on your system. #### Installation 1. **Clone the Repository:** ```bash git clone https://github.com/RadicalImaging/Static-DICOMWeb cd Static-DICOMWeb ``` 2. **Install Dependencies:** ```bash yarn install --frozen-lockfile ``` #### Generating Static DICOMweb Files 1. **Prepare your DICOM data:** Organize your DICOM files into a directory. For example `/Users/alireza/dicom/test-static-script/ACRIN-CT`. 2. **Convert to DICOMweb Structure:** Use the `mkdicomweb.js` script from the `static-wado-creator` package to create the DICOMweb directory: ```bash node packages/static-wado-creator/bin/mkdicomweb.js '/Users/alireza/dicom/test-static-script/ACRIN-CT' -o '/Users/alireza/dicom/test-static-script/output' ``` * **Replace:** * `/Users/alireza/dicom/test-static-script/ACRIN-CT` with the path to your directory of DICOM files. * `/Users/alireza/dicom/test-static-script/output` with your desired output directory for the DICOMweb structure. This command will generate a directory structure similar to this in your output location: ![alt text](../../assets/img/static-dicom-web.png) #### Serving Static Files with the Web Server 1. **Start the Server:** Run the `dicomwebserver.mjs` script from the `static-wado-webserver` package, specifying the port and the DICOMweb directory: ```bash node packages/static-wado-webserver/bin/dicomwebserver.mjs -p 3001 -o /Users/alireza/dicom/test-static-script/output ``` * **`-p 3001`:** Sets the server to listen on port 3001. You can change this if needed. * **`-o /Users/alireza/dicom/test-static-script/output`:** Specifies the path to your generated DICOMweb directory. :::info The `-p` (port) and `-o` (output directory) flags are used to configure the server. ::: #### Running OHIF Viewer with Static Data 1. **Use the `local_static.js` Configuration:** Start the OHIF Viewer in development mode using the provided `local_static.js` configuration file: ```bash yarn dev:static ``` 2. **Configuration Details:** The `local_static.js` configuration file is pre-configured to point to: ```js qidoRoot: 'http://localhost:3001/dicomweb', wadoRoot: 'http://localhost:3001/dicomweb', ``` This matches the default port (3001) used by the `static-wado-webserver`. :::info If you change the port or output directory when running the `static-wado-webserver`, you **must** also update the `qidoRoot` and `wadoRoot` values in your `local_static.js` configuration file accordingly to ensure the OHIF Viewer can access the data. ::: --- # Deployment ## Authorization and Authentication Source: https://docs.ohif.org/llm/deployment/authorization.md #### Authorization and Authentication The OHIF Viewer can be configured to work with authorization servers that support one or more of the OpenID-Connect authorization flows. The Viewer finds it's OpenID-Connect settings on the oidc configuration key. You can set these values in your configuration files. For instance you can take a look at our `google.js` configuration file. ```js oidc: [ { // ~ REQUIRED authority: 'https://accounts.google.com', client_id: '723928408739-k9k9r3i44j32rhu69vlnibipmmk9i57p.apps.googleusercontent.com', redirect_uri: '/callback', response_type: 'id_token token', scope: 'email profile openid https://www.googleapis.com/auth/cloudplatformprojects.readonly https://www.googleapis.com/auth/cloud-healthcare', // email profile openid // ~ OPTIONAL post_logout_redirect_uri: '/logout-redirect.html', revoke_uri: 'https://accounts.google.com/o/oauth2/revoke?token=', automaticSilentRenew: true, revokeAccessTokenOnSignout: true, }, ], ``` You need to provide the following information: - authority: The URL of the authorization server. - client_id: The client id of your application (provided by the authorization server). - redirect_uri: The callback URL of your application. - response_type: The response type of the authorization flow (e.g. id_token token, [learn more about different flows](https://darutk.medium.com/diagrams-of-all-the-openid-connect-flows-6968e3990660)). - scope: The scopes that your application needs to access - post_logout_redirect_uri: The URL that the user will be redirected to after logout. - revoke_uri: The URL that the user will be redirected to after logout. - automaticSilentRenew: If true, the user will be automatically logged in after the token expires. - revokeAccessTokenOnSignout: If true, the access token will be revoked on logout. #### How it works The Viewer uses the `userAuthenticationService` to set the OpenID-Connect settings. The `userAuthenticationService` is a singleton service that is responsible for authentication and authorization. It is initialized by the app and you can grab it from the `servicesManager` ```js const userAuthenticationService = servicesManager.services.userAuthenticationService; ``` Then the userAuthenticationService will inject the token as Authorization header in the requests that are sent to the server (both metadata and pixelData). #### Token based authentication in URL Sometimes (although not recommended), some servers like to send the token in the query string. In this case, the viewer will automatically grab the token from the query string and add it to the userAuthenticationService and remove it from the query string (to prevent it from being logged in the console in future requests). and example would be ```js http://localhost:3000/viewer?StudyInstanceUIDs=1.2.3.4.5.6.6.7&token=e123125jsdfahsdf ``` #### Securing dynamic datasource URLs When using `dicomwebproxy` or `dicomjson` data sources with a runtime `?url=...` query parameter, configure explicit trust boundaries to prevent credential exfiltration. Use these datasource configuration options: - `dangerouslyAllowedOriginsForAuthenticatedEnvironments`: Origin allowlist used only when the viewer is running in an authenticated environment. Entries may use `http://` or `https://` and can include localhost origins. Allowed entry format for `dangerouslyAllowedOriginsForAuthenticatedEnvironments`: - Must be a bare origin only: `scheme://host[:port]` - `http://` and `https://` are both allowed - Localhost is allowed when explicitly listed (for example, `http://localhost:5000`) - Must not include username/password, path, query string, or hash - Invalid entries are ignored and logged as misconfigured Policy summary: - In unauthenticated environments, any HTTP(S) `?url=` origin is allowed. - In authenticated environments, same-origin `?url=` values are allowed by default. - In authenticated environments, cross-origin `?url=` values must be present in `dangerouslyAllowedOriginsForAuthenticatedEnvironments`, otherwise loading fails closed. - In unauthenticated environments, cross-origin config URLs are fetched with: - `method: 'GET'` - `mode: 'cors'` - `credentials: 'omit'` - `redirect: 'error'` - `referrerPolicy: 'no-referrer'` - In unauthenticated environments, same-origin config URLs use a plain `fetch()` call (browser default `credentials: 'same-origin'`). - Same-origin config URLs are fetched using simple fetch behavior (so same-origin session/cookie auth is preserved). - In authenticated environments, allowlisted cross-origin config URLs are fetched using simple fetch behavior. - Returned datasource configuration payloads are consumed as-is (no additional URL/config scrubbing). Example: ```js dataSources: [ { namespace: '@ohif/extension-default.dataSourcesModule.dicomwebproxy', sourceName: 'dicomwebproxy', configuration: { name: 'dicomwebproxy', dangerouslyAllowedOriginsForAuthenticatedEnvironments: [ 'https://config.example.com', 'http://localhost:5000', ], }, }, ] ``` #### Implicit Flow vs Authorization Code Flow The Viewer supports both the Implicit Flow and the Authorization Code Flow. The Implicit Flow is the default currently, as it is easier to set up and use. However, you can opt for better security by using the Authorization Code Flow. To do so, add `useAuthorizationCodeFlow` to the configuration and change the `response_type` from `id_token token` to `code`. Read more about Implicit Flow vs Authorization Code Flow [here](https://documentation.openiddict.com/guides/choosing-the-right-flow.html#:~:text=The%20implicit%20flow%20is%20similar,when%20using%20response_mode%3Dform_post%20) and [here](https://medium.com/@alysachan830/the-basics-of-oauth-2-0-authorization-code-implicit-flow-state-and-pkce-ed95d3478e1c) ```js oidc: [ { authority: 'https://accounts.google.com', client_id: '723928408739-k9k9r3i44j32rhu69vlnibipmmk9i57p.apps.googleusercontent.com', redirect_uri: '/callback', scope: 'email profile openid', post_logout_redirect_uri: '/logout-redirect.html', revoke_uri: 'https://accounts.google.com/o/oauth2/revoke?token=', revokeAccessTokenOnSignout: true, automaticSilentRenew: true, // CHANGE THESE ***************************** response_type: 'code', useAuthorizationCodeFlow: true, }, ], ``` In fact, since browsers are blocking third-party cookies, the Implicit Flow will cease functioning in the future (not specific to OHIF). Read more [here](https://support.okta.com/help/s/article/FAQ-How-Blocking-Third-Party-Cookies-Can-Potentially-Impact-Your-Okta-Environment?language=en_US). It is recommended to use the Authorization Code Flow and begin migrating to it. :::note For the Authorization Code Flow, when authenticating against Google, you must add the `client_secret` to the configuration as well. Unfortunately, this seems to occur only with Google. ::: --- ## Microsoft Azure Integration Source: https://docs.ohif.org/llm/deployment/azure.md #### Microsoft Azure This guide explains how to configure a DICOM datasource in OHIF using Azure Healthcare APIs. It focuses on the configuration details and parameters necessary for integration. --- #### Configuring Azure Healthcare APIs as a DICOMweb Data Source Follow these steps to set up Azure as a DICOM datasource for the OHIF Viewer. --- #### Azure AD Registration: 1. Navigate to the Azure Portal. 2. Select **"Azure Active Directory"** > **"App registrations"** > **"New registration"**. 3. Name your application. 4. Under **"Supported account types"**, select **"Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)"**. 5. Enter the following values in your redirect URI tab: ![Redirect URI](../assets/img/azure4.png) --- #### API Permissions: 1. Under your registered application, go to **"API permissions"**. 2. Click **"Add a permission"**. 3. Choose the Azure API for DICOM (**Dicom.ReadWrite**). If you can't find it, refer to the "Configure Azure DICOMWEB Service" section and then return to this step. ![API Permissions](../assets/img/azure1.png) --- #### Authentication: 1. Under **"Authentication"**, check the **"ID tokens"** box since we are using OpenID Connect. --- #### App Client ID and Tenant ID: 1. Copy your app client ID and tenant ID to prepare for use in configuring an OHIF datasource. --- #### Consent: 1. The first time a user logs in, they will be prompted to consent to the permissions your application has requested. 2. Once they grant consent, your application can use the obtained access token to call the specific Microsoft API on behalf of the user. ![Consent](../assets/img/azure5.png) --- #### Configure Azure DICOMWEB Service: 1. **Create a Health Data Services workspace**: ![Create Workspace](../assets/img/azure6.png) 2. Visit the newly created workspace and press **"Deploy DICOM Service"**: ![Deploy DICOM Service](../assets/img/azure7.png) 3. After the DICOM service is deployed, visit the **"CORS headers"** section: ![CORS Headers](../assets/img/azure8.png) 4. Set the headers and origins to `*` and specify the HTTP methods you'd like to use: ![Set Headers](../assets/img/azure9.png) 5. Save the changes. 6. Add the Microsoft emails of the users you'd like to grant access to your DICOM service in the **"Access control"** section and assign them the **"DICOM Data Owner"** role (or other roles depending on your requirements): ![Access Control](../assets/img/azure10.png) 7. Copy your DICOM service URL to prepare it for usage in OHIF as a datasource: ![DICOM Service URL](../assets/img/azure3.png) 8. Upload your DICOM files to your service. --- #### 1. Configure OIDC Authentication Azure uses OpenID Connect (OIDC) for authentication. Update the OIDC section in your configuration file with the following parameters: ```json "oidc": [ { "redirect_uri": "/callback", "response_type": "id_token token", "scope": "openid https://dicom.healthcareapis.azure.com/Dicom.ReadWrite", "post_logout_redirect_uri": "/logout-redirect.html", "automaticSilentRenew": false, "revokeAccessTokenOnSignout": true, "loadUserInfo": false, "authority": "https://login.microsoftonline.com/{tenant-id}/v2.0/", "client_id": "{client-id}" } ] ``` #### Parameters: - **redirect_uri**: The URL where users are redirected after successful authentication. - **response_type**: Specifies the authentication response type (id_token and token). - **scope**: Defines the level of access. Use `Dicom.ReadWrite` to allow read and write access to DICOM data. - **post_logout_redirect_uri**: The URL users are redirected to after logout. - **automaticSilentRenew**: Automatically renews tokens without user interaction. Set to `false` for manual renewal. - **revokeAccessTokenOnSignout**: Revokes access tokens upon logout for added security. - **loadUserInfo**: Disables loading additional user information; set to `false` for Azure as it is not supported. - **authority**: The Azure AD tenant URL for OIDC authorization. - **client_id**: The application’s client ID from Azure AD. --- #### 2. Add the Data Source Configuration Update the data source configuration file with your Azure Healthcare APIs details: ```json { "namespace": "@ohif/extension-default.dataSourcesModule.dicomweb", "sourceName": "ohif_azure", "friendlyName": "ohif_azure", "configuration": { "singlepart": "bulkdata,pdf,video", "imageRendering": "wadors", "thumbnailRendering": "wadors", "supportsWildcard": true, "enableStudyLazyLoad": true, "supportsFuzzyMatching": false, "supportsStow": true, "qidoRoot": "https://{your-dicom-instance}.dicom.azurehealthcareapis.com/v2", "wadoUriRoot": "https://{your-dicom-instance}.dicom.azurehealthcareapis.com/v2", "wadoRoot": "https://{your-dicom-instance}.dicom.azurehealthcareapis.com/v2" } } ``` #### Parameters: - **qidoRoot**: Base URL for QIDO-RS queries. - **wadoUriRoot**: Base URL for WADO-URI requests. - **wadoRoot**: Base URL for WADO-RS requests. --- #### 3. Running the Viewer with Azure Configuration 1. Save the above configurations in your OHIF Viewer configuration file. 2. Run the viewer: ```bash cd OHIFViewer yarn install --frozen-lockfile APP_CONFIG=config/azure.js yarn run dev ``` Replace `config/azure.js` with the path to your configuration file. --- #### Additional Notes - Ensure that the Azure Healthcare API is enabled for your subscription and that the necessary permissions (e.g., `Dicom.ReadWrite`) are assigned to the OIDC client. - The `qidoRoot`, `wadoUriRoot`, and `wadoRoot` should point to your Azure DICOM service URL. Replace `{your-dicom-instance}` with your actual instance name. This setup allows OHIF to interact seamlessly with Azure's Healthcare APIs, enabling robust DICOM management and visualization. --- ## Build for Production Source: https://docs.ohif.org/llm/deployment/build-for-production.md #### Build for Production #### Build Machine Requirements - [Node.js & NPM](https://nodejs.org/en/download/) - [Yarn](https://yarnpkg.com/lang/en/docs/install/) - [Git](https://www.atlassian.com/git/tutorials/install-git) #### Getting the Code _With Git:_ ```bash #### Clone the remote repository to your local machine git clone https://github.com/OHIF/Viewers.git ``` More on: _[`git clone`](https://git-scm.com/docs/git-clone), [`git checkout`](https://git-scm.com/docs/git-checkout)_ _From .zip:_ [OHIF/Viewers: master.zip](https://github.com/OHIF/Viewers/archive/master.zip) #### Restore Dependencies & Build Open your terminal, and navigate to the directory containing the source files. Next run these commands: ```bash #### If you haven't already, enable yarn workspaces yarn config set workspaces-experimental true #### Restore dependencies yarn install --frozen-lockfile #### Build source code for production yarn run build ``` If everything worked as expected, you should have a new `dist/` directory in the `platform/app/dist` folder. It should roughly resemble the following: ```bash title="platform/app/dist/" ├── app-config.js ├── app.bundle.js ├── app.css ├── index.html ├── manifest.json ├── service-worker.js └── ... ``` By default, the build output will connect to OHIF's publicly accessible PACS. If this is your first time setting up the OHIF Viewer, it is recommended that you test with these default settings. After testing, you can find instructions on how to configure the project for your own imaging archive below. #### Configuration The configuration for our viewer is in the `platform/app/public/config` directory. Our build process knows which configuration file to use based on the `APP_CONFIG` environment variable. By default, its value is [`config/default.js`][default-config]. The majority of the viewer's features, and registered extension's features, are configured using this file. The easiest way to apply your own configuration is to modify the `default.js` file. For more advanced configuration options, check out our [configuration essentials guide](../configuration/configurationFiles.md). #### Next Steps #### Deploying Build Output _Drag-n-drop_ - [Netlify: Drop](./static-assets#netlify-drop) _Easy_ - [Surge.sh](./static-assets#surgesh) - [GitHub Pages](./static-assets#github-pages) _Advanced_ - [AWS S3 + Cloudfront](./static-assets#aws-s3--cloudfront) - [GCP + Cloudflare](./static-assets#gcp--cloudflare) - [Azure](./static-assets#azure) #### Testing Build Output Locally A quick way to test your build output locally is to spin up a small webserver. You can do this by running the following commands in the `dist/` output directory: ```bash #### Install http-server as a globally available package yarn global add http-server #### Change the directory to the platform/app cd platform/app #### Serve the files in our current directory npx serve ./dist -c ../public/serve.json ``` #### Automating Builds and Deployments If you found setting up your environment and running all of these steps to be a bit tedious, then you are in good company. Thankfully, there are a large number of tools available to assist with automating tasks like building and deploying web application. For a starting point, check out this repository's own use of: - [CircleCI][circleci]: [config.yaml][circleci-config] - [Netlify][netlify]: [netlify.toml][netlify.toml] | [build-deploy-preview.sh][build-deploy-preview.sh] [circleci]: https://circleci.com/gh/OHIF/Viewers [circleci-config]: https://github.com/OHIF/Viewers/blob/master/.circleci/config.yml [netlify]: https://app.netlify.com/sites/ohif/deploys [netlify.toml]: https://github.com/OHIF/Viewers/blob/master/platform/app/netlify.toml [build-deploy-preview.sh]: https://github.com/OHIF/Viewers/blob/master/.netlify/build-deploy-preview.sh --- ## Cross-Origin Resource Sharing Source: https://docs.ohif.org/llm/deployment/cors.md #### Cross-Origin Information for OHIF This document describes various security configurations, settings and environments/contexts needed to fully leverage OHIF’s capabilities. One may need some configurations while others might need ALL of them - it all depends on the environment OHIF is expected to run in. In particular, three of OHIF’s features depend on these configurations: - [Embedding OHIF in an iframe](#embedding-ohif-in-an-iframe) - [XMLHttpRequests to fetch data from data sources](#cors-in-ohif) #### Embedding OHIF in an iframe As described [here](./iframe.md), there are cases where OHIF will be embedded in an iframe. The following links provide more information for setting up and configuring OHIF to work in an iframe: - [OHIF iframe documentation](./iframe.md#static-build) - [OHIF as a Cross-origin Resource in an iframe](#ohif-as-a-cross-origin-resource-in-an-iframe) #### Secure Context MDN defines a secure context as [“a Window or Worker for which certain minimum standards of authentication and confidentiality are met.“](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) Any local URL is considered secure. The following are some examples of local URLs that are considered secure… - http://localhost - http://127.0.0.1:3000 URLs that are NOT local must be delivered over `https://` or `wss://` (i.e. TLS) to be considered secure. See [When is a context considered secure](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts#when_is_a_context_considered_secure) in MDN for more information. #### iframes A page embedded in an iframe is considered secure if it itself and every one of its embedding ancestors are delivered securely. Otherwise it is deemed insecure. #### Configuring/setting up a secure context [Local URLs are considered secure](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts#when_is_a_context_considered_secure), and as such whenever OHIF is accessed via a local URL (e.g. http://localhost:3000) it is running in a secure context. For example, in a development environment using the default webpack setup, OHIF can be deployed and accessed in a secure context at http://localhost:3000. The best alternative is to host OHIF over HTTPS. :::tip OHIF can be served over HTTPS in a variety of ways (these are just some examples). - Website hosting services that offer HTTPS deployment (e.g,. Netlify) or offer HTTPS load balancers (AWS, Google Cloud etc.) - Setting up a reverse proxy (e.g. `nginx`) with a self-signed certificate that forwards requests to the OHIF server - [An OHIF Docker image can be set up this way](./docker/docker.md#ssl). ::: #### Origin Definition According to [MDN](https://developer.mozilla.org/en-US/docs/Glossary/Origin), a Web content’s origin is defined by the scheme (protocol), hostname (domain), and port of the URL used to access it. Two objects have the same origin only when the scheme, hostname, and port all match. #### CORS - Cross-Origin Resource Sharing A cross-origin resource is a resource (e.g. image, JSON, etc) that is served by one origin and used/referenced by a different origin. CORS is the protocol utilized by web servers and browsers whereby a server of one origin identifies and/or restricts which of its resources that other origins (i.e. other than its own) a browser should allow access to. By default a browser does not permit cross-origin resource sharing. The CORS mechanism relies on the HTTP response headers from the server to indicate if a resource can be shared with a different origin. See the [MDN CORS article](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) for more information. #### CORS HTTP Headers The header that mostly concerns OHIF is listed below and should be configured accordingly on the DICOMweb server or any data source that OHIF would make XMLHttpRequests to for its data. ```http Access-Control-Allow-Origin: `` | * ``` :::tip The `Access-Control-Allow-Origin` header specifies which origins can access the served resource embedded in the response. Either a single, specific origin (i.e. ``) can be specified or ALL origins (i.e. *) See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#access-control-allow-origin) for more information. ::: #### CORS in OHIF OHIF fetches and displays data and images from data sources. It invokes XMLHttpRequests to some data sources such as DICOMweb data sources to fetch the information to render. Typically, a DICOMweb server is hosted on a completely different origin than the one serving OHIF. As such, those XMLHttpRequests use CORS. #### Troubleshooting CORS in OHIF The following is an example screenshot of the browser console when one of OHIF’s DICOMweb data source servers is not configured for CORS. ![CORS browser console errors](../assets/img/cors-browser-console-errors.png) And the following is what is in the accompanying network tab. ![CORS browser network panel errors](../assets/img/cors-network-panel-errors.png) :::info Setting the appropriate CORS header varies per server or service that is hosting the data source. What follows below is just one example to remedy the problem. ::: :::tip If Orthanc is the data source running in a Docker container composed with/behind nginx. And OHIF is being served at localhost:3000. The issue can be remedied by adding either of the following to Orthanc’s Docker container nginx.conf file. ```nginx add_header 'Access-Control-Allow-Origin' 'http://localhost:3000' always; ``` Or ```nginx add_header 'Access-Control-Allow-Origin' '*' always; ``` ::: #### Header Values (see [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy#usage) for more information) |Value|Description| |-----|-----------| |same-site|Only requests from the same site can read the resource.| |same-origin|Only requests from the same origin can read the resource.| |cross-origin|Requests from any origin can read the resource. The value is useful and [exists](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy#relationship_to_cross-origin_embedder_policy_coep) primarily for letting documents with the [COEP require-corp value](#header-values-pertinent-to-ohif-see-mdn-for-more-information-1) know that the resource is ok to be embedded| #### OHIF and CORP #### PDF from a Cross Origin DICOMweb Data Source There are some DICOMweb data sources (e.g. dcm4chee) whereby OHIF uses the data source’s `/rendered` endpoint to embed a DICOM PDF document in the OHIF DOM using an `