Viewers

[

About Copy Chapter

The OHIF Viewer can retrieve
and load images from most sources and formats, render sets in 2D, 3D, and
reconstructed representations; allows for the manipulation, annotation, and
serialization of observations; supports internationalization, OpenID Connect,
offline use, hotkeys, and many more features.

Almost everything offers some degree of customization and configuration. If it
doesn't support something you need, we accept pull requests and have an ever
improving Extension System.

Why Choose Us Copy Chapter

Community & Experience Copy Section

The OHIF Viewer is a collaborative effort that has served as the basis for many
active, production, and FDA Cleared medical imaging viewers. It benefits from
our extensive community's collective experience, and from the sponsored
contributions of individuals, research groups, and commercial organizations.

Built to Adapt Copy Section

After more than 8-years of integrating with many companies and organizations,
The OHIF Viewer has been rebuilt from the ground up to better address the
varying workflow and configuration needs of its many users. All of the Viewer's
core features are built using its own extension system. The same extensibility
that allows us to offer:

• 2D and 3D medical image viewing
• Multiplanar Reconstruction (MPR)
• Maximum Intensity Project (MIP)
• Whole slide microscopy viewing
• PDF and Dicom Structured Report rendering
• Segmentation rendering as labelmaps and contours
• User Access Control (UAC)
• Context specific toolbar and side panel content
• and many others

Can be leveraged by you to customize the viewer for your workflow, and to add
any new functionality you may need (and wish to maintain privately without
forking).

Support Copy Section

• Report a Bug 🐛
• Request a Feature 🚀
• Ask a Question 🤗
• Slack Channel

For commercial support, academic collaborations, and answers to common
questions; please use Get Support to contact
us.

Developing Copy Chapter

Branches Copy Section

`master` branch - The latest dev (beta) release

• master - The latest dev release

This is typically where the latest development happens. Code that is in the master branch has passed code reviews and automated tests, but it may not be deemed ready for production. This branch usually contains the most recent changes and features being worked on by the development team. It's often the starting point for creating feature branches (where new features are developed) and hotfix branches (for urgent fixes).

Each package is tagged with beta version numbers, and published to npm such as @ohif/[email protected]

`release/*` branches - The latest stable releases Copy Section

Once the master branch code reaches a stable, release-ready state, we conduct a comprehensive code review and QA testing. Upon approval, we create a new release branch from master. These branches represent the latest stable version considered ready for production.

For example, release/3.5 is the branch for version 3.5.0, and release/3.6 is for version 3.6.0. After each release, we wait a few days to ensure no critical bugs. If any are found, we fix them in the release branch and create a new release with a minor version bump, e.g., 3.5.1 in the release/3.5 branch.

Each package is tagged with version numbers and published to npm, such as @ohif/[email protected]. Note that master is always ahead of the release branch. We publish docker builds for both beta and stable releases.

Here is a schematic representation of our development workflow:

Requirements Copy Section

• Yarn 1.20.0+
• Node 18+
• Yarn Workspaces should be enabled on your machine:
  • yarn config set workspaces-experimental true

Getting Started Copy Section

1. Fork this repository
2. Clone your forked repository
   • git clone https://github.com/YOUR-USERNAME/Viewers.git
3. Navigate to the cloned project's directory
4. Add this repo as a remote named upstream
   • git remote add upstream https://github.com/OHIF/Viewers.git
5. yarn install --frozen-lockfile to restore dependencies and link projects

:::danger
In general run yarn install with the --frozen-lockfile flag to help avoid
supply chain attacks by enforcing reproducible dependencies. That is, if the
yarn.lock file is clean and does NOT reference compromised packages, then
no compromised packages should land on your machine by using this flag.
:::

To Develop

From this repository's root directory:

# Enable Yarn Workspaces
yarn config set workspaces-experimental true

# Restore dependencies
yarn install --frozen-lockfile

Cornerstone3D Integration Testing Copy Section

OHIF's Playwright end-to-end tests can run against a CS3D branch or a
published CS3D version, allowing changes that span both repositories to be
validated together before merging.

Setting up an integration build

1. Add the ohif-integration label to your OHIF pull request.
2. In the PR body, add a line specifying the CS3D ref:
   text Copy

   CS3D_REF: feat/my-feature

   • Version ref (e.g. 4.19+, 4.18.2) — the workflow resolves it to an
     exact published version and swaps the CS3D dependency via npm.
   • Branch ref (e.g. main, cornerstonejs:feat/foo) — the workflow
     clones the branch, builds CS3D from source with bun run build:esm, and
     symlinks the built packages into OHIF's node_modules.
   • For forks, use the <owner>: format
     (e.g. myGithubUser:feat/foo).
   • If no CS3D_REF is specified, the default is 4.19+.
3. The workflow can also be triggered manually via workflow_dispatch with a
   cs3d_ref input.

What happens in CI

The Playwright workflow runs two jobs:

Testing changes that span both repos

If a feature requires changes in both Cornerstone3D and OHIF:

1. Create your feature branch in CS3D and push it.
2. Create a matching branch in OHIF.
3. Add the ohif-integration label to the OHIF pull request.
4. In the PR body, add: CS3D_REF: <your-cs3d-branch>.
5. Playwright tests will build CS3D from source, link it, and run the full
   suite. The merge guard will block merge until you switch to a published
   version — but you can see the test results and the preview deploy while
   iterating.
6. Once the CS3D side is merged and published, update the PR body to reference
   the published version (e.g. CS3D_REF: 4.19+). The tests will run against
   the registry version and the merge guard will pass.

Preview deploys

When ohif-integration is active, the Playwright workflow also builds the OHIF
viewer and deploys it to Netlify as a preview. This gives you a live URL to
manually test the combined CS3D + OHIF changes without running anything locally.

For details on linking CS3D locally for development, see the
Cornerstone3D README.

Commands Copy Chapter

These commands are available from the root directory. Each project directory
also supports a number of commands that can be found in their respective
README.md and package.json files.

* - For more information on different builds, check out our Deploy
Docs

Which config each command uses Copy Section

The dev server and the production build select a different default
configuration file when APP_CONFIG is not set explicitly:

• config/dev.js is the full-featured local-development config: every data
  source is enabled, the ?customization= URL feature is turned on (via
  customizationUrlPrefixes), and it is kept at parity with the public demo
  (config/netlify.js) so customizations behave locally the same way they do on
  the demo.
• config/netlify.js is the public demo / Netlify deploy config
  (build:viewer:ci), with the same full data-source set and ?customization=
  enabled.
• config/default.js is a locked-down baseline and is now only the
  default for a plain production build (build with no APP_CONFIG): a single
  read-only demo data source and ?customization= off.

Any explicit APP_CONFIG overrides the default, e.g.
APP_CONFIG=config/default.js pnpm run dev or
APP_CONFIG=config/netlify.js pnpm run build.

Project Copy Chapter

The OHIF Medical Image Viewing Platform is maintained as a
monorepo. This means that this repository, instead of containing a
single project, contains many projects. If you explore our project structure,
you'll see the following:

.
├── extensions               #
│   ├── _example             # Skeleton of example extension
│   ├── default              # basic set of useful functionalities (datasources, panels, etc)
│   ├── cornerstone       # image rendering and tools w/ Cornerstone3D
│   ├── cornerstone-dicom-sr # DICOM Structured Report rendering and export
│   ├── cornerstone-dicom-sr # DICOM Structured Report rendering and export
│   ├── cornerstone-dicom-seg # DICOM Segmentation rendering and export
│   ├── cornerstone-dicom-rt # DICOM RTSTRUCT rendering
│   ├── cornerstone-microscopy # Whole Slide Microscopy rendering
│   ├── dicom-pdf # PDF rendering
│   ├── dicom-video # DICOM RESTful Services
│   ├── measurement-tracking # Longitudinal measurement tracking
│   ├── tmtv # Total Metabolic Tumor Volume (TMTV) calculation
|

│
├── modes                    #
│   ├── _example             # Skeleton of example mode
│   ├── basic-dev-mode       # Basic development mode
│   ├── longitudinal         # Longitudinal mode (measurement tracking)
│   ├── tmtv       # Total Metabolic Tumor Volume (TMTV) calculation mode
│   └── microscopy          # Whole Slide Microscopy mode
│
├── platform                 #
│   ├── core                 # Business Logic
│   ├── i18n                 # Internationalization Support
│   ├── ui                   # React component library
│   ├── docs                 # Documentation
│   └── viewer               # Connects platform and extension projects
│
├── ...                      # misc. shared configuration
├── lerna.json               # MonoRepo (Lerna) settings
├── package.json             # Shared devDependencies and commands
└── README.md                # This file

Acknowledgments Copy Chapter

To acknowledge 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

Open-Access on Pubmed Central:
https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7259879/

or, for 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

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.

This work is supported primarily by the National Institutes of Health, National
Cancer Institute, Informatics Technology for Cancer Research (ITCR) program,
under a
grant to Dr. Gordon Harris at Massachusetts General Hospital (U24 CA199460).

NCI Imaging Data Commons (IDC) project supported the development of new features and bug fixes marked with "IDC:priority",
"IDC:candidate" or "IDC:collaboration". NCI Imaging Data Commons is supported by contract number 19X037Q from
Leidos Biomedical Research under Task Order HHSN26100071 from NCI. IDC Viewer is a customized version of the OHIF Viewer.

This project is tested with BrowserStack. Thank you for supporting open-source!

License Copy Chapter

MIT © OHIF