Skip to content

Controlling the viewer

View as Markdown

NiiVueModel is your handle on the viewer. It keeps a Swift copy of the viewer’s settings and loaded images, and sends your changes to the page. SwiftUI views that read it update by themselves.

Changing settings with SwiftUI controls

Bind a setting straight to a control:

Toggle("Colorbar", isOn: model.binding(\.isColorbarVisible))
Slider(value: model.binding(\.azimuth), in: 0...360)

Settings with named choices, such as the view type, have their own bindings and Swift enums:

Picker("View", selection: model.sliceTypeBinding) {
ForEach(SliceType.allCases) { Text($0.label).tag($0) }
}

You can also set them from code:

model.sliceType = .axial
model.isColorbarVisible.value = true

Changes go both ways. When the viewer changes a setting itself, for example when the user turns the 3D view with the mouse, the model follows and so do your controls. A change that came from the viewer is not sent back to it.

What you can change

  • The layout: the view type (sliceType), how multiplanar tiles are arranged (multiplanarType), when the 3D render joins them (showRender), the size of the large tile (heroFraction), mosaics (mosaicString), custom layouts (customLayout) and radiological orientation (isRadiological). The layout guide explains what each one does.
  • What is drawn over the image: the colorbar, orientation cube and labels, 3D crosshair, cross lines, ruler and legend. Each is an on or off switch named like isRulerVisible. meshXRayEnabled draws the crosshair and meshes faintly through a 3D render, so they stay easy to find.
  • The scene: the background color (backgroundColor), gamma, and the 3D camera angles azimuth and elevation.

sliceType, multiplanarType, showRender and meshXRayEnabled each have a matching binding, such as showRenderBinding.

A custom layout is a list of tiles. Each tile’s position is [left, top, width, height], from 0 to 1:

model.customLayout.value = [
CustomLayoutTile(sliceType: .sagittal, position: [0, 0, 0.5, 1]),
CustomLayoutTile(sliceType: .render, position: [0.5, 0, 0.5, 1]),
]

Loading images

try await model.loadVolume(url: scanURL)
try await model.loadVolume(url: overlayURL, add: true)

The first call replaces everything shown, volumes, meshes and signals alike. With add: true the file goes on top instead. Despite the name, loadVolume loads meshes and signals too: NiiVue goes by the file extension. See the loading guide for the formats it reads.

For a file already in memory, give it a name with the right extension:

try await model.loadVolume(data: bytes, name: "scan.nii.gz")

The call throws if nothing could be loaded. The whole file is read into memory and sent to the page in one message.

Files the user picks with fileImporter or drops on your app are outside your sandbox. Call url.startAccessingSecurityScopedResource() before loading one, and stop when you are done.

Seeing what is loaded

model.volumes lists the loaded volumes, background first. Each has a name, a colormap, a display range (calMin, calMax), an opacity and a size (dims, with voxel sizes in pixDims). model.meshes lists meshes by name, and model.hasSignal says whether a signal is loaded. All three update by themselves when something is loaded or removed, from Swift or on the page.

ForEach(model.volumes, id: \.name) { volume in
Text("\(volume.name): \(volume.colormap)")
}

model.isReady turns true once the page is ready, which is handy for disabling buttons until then.

Changing how an image looks

await model.setVolume(SetVolumePayload(index: 1, colormap: "warm", calMin: 3, calMax: 6))

Index 0 is the background. Anything you leave out stays as it is, and opacity can be set the same way. model.colormaps holds the names of the colormaps the viewer knows, ready for a picker.

To take an image away, use await model.removeVolume(at: 1) or await model.removeMesh(at: 0).

These calls do not throw. If one fails, the reason goes to model.lastStatus, a short status line you can show in your app.

Following the crosshair

model.locationText is a ready-made description of the crosshair position, or a dash before there is one:

Text(model.locationText)
.font(.caption.monospacedDigit())

To format it yourself, model.locationMM holds the position in millimeters, and model.locationValues the name and value of each volume at that point.

Switching between WebGL2 and WebGPU

await model.setBackend(.webgpu)

Loaded images stay loaded. If WebGPU is not available, NiiVue may fall back to WebGL2, so read model.currentBackend to see which one is in use. model.isSwitchingBackend is true while a switch is under way; use it to disable your picker until it is done.

Syncing a setting the model does not have

The model covers the settings above, but you can add any other NiiVue setting. Make a property for it and pass it in when you create the model:

let crosshairColor = NiiVueProp<[Double]>(path: "crosshairColor", initial: [1, 0, 0, 1])
let model = NiiVueModel(bridge: bridge, extraCells: [crosshairColor])
crosshairColor.value = [0, 1, 0, 1]

Passing it at creation, rather than adding it later with registerExtra, means it picks up the viewer’s current value as soon as the page is ready.

The page has to allow the setting too, so this needs your own page. Add the name to the page’s allow-list, as described in Web bridge.