Skip to content

nv-ohif

View as Markdown

@niivue/nv-ohif is an extension for the OHIF Viewer. It adds a NiiVue viewport to OHIF, so a series can be shown by NiiVue instead of OHIF’s built-in Cornerstone viewport. Your users keep OHIF’s study list, panels and toolbar, and get NiiVue’s multiplanar and 3D views, clip planes, colormapped overlays and measurements.

Use it when you run your own OHIF app and want NiiVue to draw some or all of its viewports. It is tested with OHIF 3.13 and the 3.14 beta. If you are building a viewer from scratch, use NiiVue directly, or the React bindings.

Install

Install it in your OHIF app, together with NiiVue:

Terminal window
npm install @niivue/nv-ohif@next @niivue/niivue@next

OHIF already provides React (18 or 19 both work) and its own packages. The DICOM converter and the slide tools come along as regular dependencies.

Registering the extension

Add the package to the extensions list in your app’s pluginConfig.json, after the Cornerstone extension:

{
"extensions": [
{ "packageName": "@ohif/extension-default" },
{ "packageName": "@ohif/extension-cornerstone" },
{ "packageName": "@niivue/nv-ohif" }
]
}

The order matters. Registered after Cornerstone, NiiVue answers OHIF’s standard viewport commands (reset, zoom, window presets and so on) on its own viewports, and passes the rest on to Cornerstone.

Showing a series in NiiVue

A mode decides which viewport shows which series. The simplest setup swaps the Cornerstone viewport in your mode’s layout for the NiiVue one, so it takes OHIF’s ordinary image series:

viewports: [
{
namespace: '@niivue/nv-ohif.viewportModule.niivue',
displaySetsToDisplay: ['@ohif/extension-default.sopClassHandlerModule.stack'],
},
// ...your other viewports
],

Open a study in that mode and its series open in NiiVue, in the multiplanar view. A DICOM series is downloaded and converted in the browser first, so a large one takes a moment; the viewport says what it is doing.

What else it can do

  • See what it can open: NIfTI files, DICOM series and whole-slide microscopy. See What it can show.
  • Add NiiVue’s buttons to the toolbar: views, clip planes, window presets, colormaps and overlays. See Toolbar and controls.
  • Measure: OHIF’s measurement tools draw on NiiVue and fill the Measurements panel. See Measuring.

When something does not work

  • The viewport stays black. OHIF only hands a series to a viewport that lists its display-set handler in displaySetsToDisplay. Check that the series’ handler is listed on the NiiVue viewport.
  • “This series isn’t something NiiVue can load yet.” Segmentations, RT structures, reports and other non-image series are not converted. Show them in OHIF’s own viewports.
  • Only one series shows. A NiiVue viewport shows the first series it is given and names the rest in a note. To stack one series on another, add it as an overlay.
  • Crosshairs or Capture does not work. Cornerstone’s buttons do not work on a NiiVue viewport. Use NiiVue’s own.
  • Clicking a measurement opens it in another viewport. List @niivue/nv-ohif after the Cornerstone extension in pluginConfig.json.

Working on the extension

If you are changing nv-ohif itself, the repository has a small test page that behaves like OHIF and drives the real viewport. From the repository root, build the packages it uses, then start it:

Terminal window
bunx nx build nv-ohif
cd packages/nv-ohif && bun run dev

It opens on http://localhost:5183/ with a NIfTI brain. Add ?dicom to the URL for a DICOM series from a public server, or ?slide for a whole-slide image.

To try your changes in a real OHIF app, pack the packages you changed into tarballs with bun pm pack and install those. Do not symlink the repository into the app: its bundler then picks up a second copy of shared packages, which breaks OHIF.

The source is at https://github.com/niivue/mono/tree/main/packages/nv-ohif.