web-bridge
@niivue/web-bridge connects a NiiVue viewer in a web page to the native
app that shows the page. The app can load images, change settings and
follow the crosshair, and the page tells the app what changed.
It is one half of a pair. This package runs in the page. The Swift half,
NiiVueKit, runs in a SwiftUI app that shows the
page in a WKWebView. Both sides speak the same small JSON messages, so
you do not write new glue code for each app.
Do you need it?
- You are writing the web page for a Swift app: yes. The page creates a NiiVue viewer and hands it to the bridge. The medgfx app in this repository works this way.
- You only write Swift: maybe not. NiiVueKit can serve a ready-made page built from medgfx’s web app, which already uses this package. See the viewer page in the Swift docs.
- You are building an ordinary website: no. Use NiiVue directly.
Adding it to a project
The package is not on npm. It lives in this monorepo, and other projects in
the monorepo use it through the workspace. Add it to your project’s
package.json, next to NiiVue:
"dependencies": { "@niivue/niivue": "workspace:*", "@niivue/web-bridge": "workspace:*"}Then run bun install from the repository root.
Each part has its own import path, such as @niivue/web-bridge/bridge or
@niivue/web-bridge/niivue-controller. A Vite dev server reads the
package’s source directly, so there is nothing to build first. A production
build uses the compiled files, so build the package before your app
(bunx nx build niivue-web-bridge, or let Nx do it by making your app’s
build depend on ^build).
The smallest page that works
import NiiVue from '@niivue/niivue'import { createBridge } from '@niivue/web-bridge/bridge'import { wireNiiVueToBridge } from '@niivue/web-bridge/niivue-controller'
const nv = new NiiVue({ backgroundColor: [0, 0, 0, 1] })const bridge = createBridge()wireNiiVueToBridge(nv, bridge)await nv.attachToCanvas(document.getElementById('gl1') as HTMLCanvasElement)bridge.emit('ready', { backend: nv.backend })Three things happen here:
createBridge()opens the line to the app.wireNiiVueToBridgelets the app drive this viewer and reports changes back to it.readytells the app the page is set up. Send it last, after the viewer is attached.
Do not skip ready. Until it arrives, the Swift side holds back every
message it wants to send. NiiVueKit then asks the page for the current
settings and the list of loaded images.
What the app can do with the viewer
Once the viewer is wired, the app can:
- Load a file. The app sends the file’s bytes. The file replaces everything in the scene (volumes, meshes and signals), or is added on top when the app asks for that. If nothing loads, the old scene stays and the app gets an error.
- Change viewer settings. The default list covers things like the layout (slice type, multiplanar arrangement, mosaics, custom layouts, radiological view), the on-screen extras (colorbar, orientation cube and labels, crosshair lines, ruler, legend) and the scene (background color, gamma, 3D camera angle). When page code sets one of these, the page tells the app, so the app’s controls stay in step. That includes turning the 3D view with the mouse. A change the app made itself is not sent back.
- Adjust each volume. Set a volume’s colormap, contrast range and opacity, or remove volumes and meshes. The page sends what the app needs to draw its own controls: each volume’s colormap and its colors, its contrast and data range, its size and voxel size, and the names of the colormaps to choose from.
- Switch between WebGPU and WebGL2. If WebGPU is not available, NiiVue may fall back to WebGL2, and the page reports the one actually in use.
- Follow along. The page tells the app when an image finishes loading, whenever the lists of volumes, meshes or signals change, and every time the crosshair moves, with its position in millimeters and voxels and the image values there.
The message names and payloads are in niivue-controller.ts, if you need to talk to the page without NiiVueKit.
Trying the page in a browser
Outside a web view there is no app on the other end. The bridge notices and
writes each outgoing message to the console instead, starting with
[niivue-web-bridge:niivue]. So you can open the page from your dev server
and watch what it would send. Calls the page makes to the app never get an
answer there, so their promises never settle.
Letting the app change another setting
The app can only change settings on the page’s allow-list. To add one, pass your own list. Your list replaces the default one, so copy the default into it:
import { DEFAULT_PROP_ALLOWLIST } from '@niivue/web-bridge/prop-allowlist'
wireNiiVueToBridge(nv, bridge, { allowlist: { ...DEFAULT_PROP_ALLOWLIST, crosshairColor: { kind: 'rgba' } },})kind says how the incoming value is converted before it is set:
boolean,numberorstringfor plain values.enumfor a setting NiiVue stores as a number, such assliceType.rgbafor a color, sent as[r, g, b]or[r, g, b, a]with values from 0 to 1. A missing alpha becomes 1.jsonfor a structured value, such as a custom layout. It is passed through unchanged.
Changes to the setting on the page are reported to the app unless you add
emitOnChange: false.
The Swift side needs a matching entry with the same name:
let crosshair = NiiVueProp<[Double]>(path: "crosshairColor", initial: [1, 0, 0, 1])let model = NiiVueModel(bridge: bridge, extraCells: [crosshair])Pass it when you create the model, so it is filled in from the page on
ready.
Adding your own messages
Settings cover most needs. For anything else, such as calling a NiiVue
method or sending a result back to the app, add your own message. There are
four ways to talk, and the Swift Bridge has the same four:
// The app asks, the page answersbridge.handle('stepCrosshair', (payload) => { const { di, dj, dk } = payload as { di: number; dj: number; dk: number } nv.moveCrosshairInVox(di, dj, dk) return { ok: true }})
// The page tells the app, no answer expectedbridge.emit('drawingStarted', { label: 1 })
// The app tells the pagebridge.on('theme', (payload) => console.log(payload))
// The page asks, the app answersconst answer = await bridge.call('confirm', { message: 'Discard the drawing?' })A few rules:
- Messages and answers must be plain JSON. Send binary data as base64 text, the way file loading does.
- A handler can be async. The answer is sent when it finishes.
- If a handler throws, the app’s call fails with the error message. A call to a name with no handler fails too.
- Each name can have only one handler, and registering it twice throws.
wireNiiVueToBridgealready uses names such asloadVolumeandsetProp, so pick others. onreturns a function that stops listening.
Handling files dropped on the page
When someone drops files on the viewer, loadDroppedFiles loads them with
the same replace-or-add rule the app uses. Turn off NiiVue’s own drag and
drop first: it replaces the scene for each file and ignores modifier keys.
NiiVue still accepts the drop on its canvas, so the browser does not open
the file itself. This example adds to the scene while Cmd or Ctrl is held,
as medgfx does:
import { loadDroppedFiles } from '@niivue/web-bridge/niivue-controller'
const nv = new NiiVue({ isDragDropEnabled: false })document.addEventListener('drop', (event) => { const files = Array.from(event.dataTransfer?.files ?? []) const add = event.metaKey || event.ctrlKey if (files.length > 0) void loadDroppedFiles(nv, files, add)})All dropped files are added first and the old scene is removed afterwards,
so dropping several files at once gives a background image plus overlays.
A file that fails is logged and the rest still load. If nothing new loads,
the old scene stays. For a single file there is loadFile, which throws
when nothing loads. The loading guide lists the formats
NiiVue reads.
When something does not work
- The app’s messages never arrive. The page must send
readyafter the viewer is attached. Until then the Swift side keeps everything in a queue. - Nothing reaches the app, and the console shows
[niivue-web-bridge:...]lines inside the app. The bridge could not find the app’s message handler, so the names on the two sides do not match. By default both sides useniivue. If you change it on one side, change it on the other:createBridge({ handlerName: 'viewer' })pairs with a SwiftBridgeConfig(handlerName: "viewer"). - The app gets
property '...' is not in the allow-list. The app tried to change a setting the page does not allow. Add it to the allow-list. - The page throws
handler already registered. A message name was registered twice, often by callingwireNiiVueToBridgetwice on one bridge. - The web view stays blank. See when the viewer stays blank in the Swift docs.
Source and a full example
The code is in
packages/niivue-web-bridge.
For a complete page, see medgfx’s
main.ts.
Run the tests with bunx nx test niivue-web-bridge.