Skip to content

uikit

View as Markdown

@niivue/uikit draws controls and measuring tools inside the NiiVue canvas, in the same frame as the image. Buttons, toggles, sliders, menus, text fields, dialogs, rulers and crosshairs all render on NiiVue’s own graphics backend, WebGL2 or WebGPU, and they see the pointer before NiiVue does.

Use it when the controls belong on the image: a toolbar floating over a full-screen viewer, a settings dialog in a kiosk, a ruler between two points. If ordinary HTML controls beside the canvas do the job, prefer them. Tab does not move between canvas widgets, and screen readers cannot see them.

Install

Terminal window
npm install @niivue/uikit@next @niivue/niivue@next

UIKit draws into a NiiVue viewer you create yourself, so install NiiVue alongside it.

A first button

import NiiVue from '@niivue/niivue'
import { loadDefaultFont, UIKitButtonOverlay } from '@niivue/uikit'
const nv = new NiiVue()
await nv.attachToCanvas(document.getElementById('gl1'))
await nv.loadVolumes([{ url: '/volumes/mni152.nii.gz' }])
const font = await loadDefaultFont()
const buttons = new UIKitButtonOverlay(font, { cssUnits: true })
nv.registerOverlayRenderer(buttons)
buttons.attach(nv)
buttons.addButton({
id: 'colorbar',
label: 'Colorbar',
x: 12,
y: 12,
onClick: () => {
nv.isColorbarVisible = !nv.isColorbarVisible
},
})

Three steps connect a widget to the viewer, and every widget uses them:

  • loadDefaultFont() prepares the font that comes with UIKit. Load it once and give it to every widget you make.
  • nv.registerOverlayRenderer(buttons) asks NiiVue to draw the buttons at the end of every frame.
  • buttons.attach(nv) sends clicks on the canvas to the buttons first. A click on a button stops there, so it never moves the crosshair or starts a drag.

Call attach after attachToCanvas has finished. Before that there is no canvas to listen to, and attach throws an error.

Positions, sizes and colors

Positions are measured from the top-left corner of the canvas. With cssUnits: true they are CSS pixels, the same units as the rest of your page, and UIKit scales them up on high-density screens. Without it they are the canvas’s own pixels, so on a 2x laptop screen everything comes out half the size.

Buttons, menus and drop-down lists size themselves to fit their text; give width or height to fix a size. Sliders always need a width. To place one widget after another, ask for the first one’s box:

const box = buttons.getLayout('colorbar')
buttons.addButton({ id: 'reset', label: 'Reset', x: box.x + box.width + 8, y: 12 })

Colors are [red, green, blue, alpha] lists with values from 0 to 1, as everywhere else in NiiVue.

Responding to the user

Widgets tell you about changes through the same few callbacks:

  • onInput runs on every change, for example at each step while a slider is dragged.
  • onChange runs once the change is finished: the drag ends, or Enter is pressed in a field.
  • onSubmit runs when Enter is pressed in a text field, even if the text did not change.

Buttons have onClick, and menu items onSelect. Each callback gets the widget’s id as its last argument, so one function can serve several widgets.

Changing a widget from your code, with setValue, setChecked and the like, never runs these callbacks. That lets you keep a slider and a number field in step without each one setting off the other.

Changing the look

Every style setting has a default. Pass style when you create an overlay to change it for all of its widgets, or pass it to one widget to change only that one:

const buttons = new UIKitButtonOverlay(font, {
cssUnits: true,
style: { radius: 12, textSizePx: 14 },
})
buttons.addButton({
id: 'delete',
label: 'Delete',
x: 12,
y: 12,
style: { fill: [0.55, 0.1, 0.12, 0.95] },
})

The defaults are exported too, such as DEFAULT_BUTTON_STYLE and DEFAULT_SLIDER_STYLE. Print one to see every setting you can change.

What else is in the package

  • Several controls on one canvas: toggles, sliders, menus, drop-down lists and segmented controls. See Buttons, sliders and menus.
  • Typing, colors, files and dialogs: number and text fields, notes, a color picker, opening and saving files, and pop-up dialogs. See Text fields, files and dialogs.
  • Measuring and marking the image: a ruler, a crosshair with a scale, labels pinned to a point, and extras for whole-slide images. See Rulers, crosshairs and labels.

When something does not work

  • Nothing appears. Register the widget with nv.registerOverlayRenderer. After moving a ruler or a crosshair, call nv.drawScene() so the new position is drawn.
  • attach throws “UIKit: host has no canvas to attach to”. Wait for nv.attachToCanvas to finish first.
  • The widgets are tiny on a laptop screen. Create the overlay with cssUnits: true.
  • A click on a control also moves the crosshair. The control is drawn but not attached. Call attach(nv) on it, or on the control layer that holds it.
  • Keys do nothing. A widget takes the keyboard when it is clicked. Clicking anywhere else on the page gives the keys back to the page, and keys typed into an HTML input on the page never reach UIKit.

Source and demos

The source is in the uikit folder of the NiiVue repository. In a checkout, bunx nx dev uikit serves the package’s demo pages, including one with every control on a single canvas.