reflex-niivue

A Reflex component wrapping NiiVue, the WebGL2 viewer for medical images: NIfTI, NRRD, MHA/MHD, MGH, DICOM, meshes (GIfTI, MZ3, OBJ, ...), tractography, connectomes and drawings.

• One general-purpose niivue.view(...) component: volumes and overlays, label maps, meshes with layers, multiplanar and 3D render views, clip planes, drawing, synced viewers.
• Props map 1:1 to NiiVue methods; volumes and meshes are diffed by url, so changing an opacity or a colormap never downloads the image again.
• NiiVue events (on_location, on_image_loaded, ...) arrive in your Reflex state.
• Imperative actions (save_image, undo_draw, move_crosshair_to_mm, ...) are events you return or yield from a handler.
• NiiVue itself (@niivue/niivue 0.69.0) comes from npm when your app builds; nothing is vendored. No image data passes through Reflex state: NiiVue fetches the files itself.

Requires Python 3.11+, Reflex 0.10+ and a browser with WebGL2.

Install

uv add reflex-niivue    # or: pip install reflex-niivue

Quick start

import reflex as rx
from reflex_niivue import label_colormap, niivue

IMAGES = "https://niivue.com/demos/images/"


class State(rx.State):
    opacity: float = 0.7
    mm: list[float] = []

    @rx.event
    def located(self, mm: list[float], vox: list[int], values: list[dict], frac: list[float]):
        self.mm = mm

    @rx.event
    def save(self):
        yield niivue.save_image("mask.nii.gz")  # the drawing, as NIfTI

    @rx.var
    def volumes(self) -> list[dict]:
        return [
            {"url": IMAGES + "mni152.nii.gz", "name": "t1"},
            {
                "url": IMAGES + "hippo.nii.gz",
                "name": "hippocampus",
                "opacity": self.opacity,
                "colormap_label": label_colormap({9: ("hippocampus", (255, 70, 70))}),
            },
        ]


def index():
    return rx.vstack(
        niivue.view(
            volumes=State.volumes,
            slice_type="multiplanar",
            drawing_enabled=True,
            pen_value=1,
            on_location=State.located,
            height="500px",
        ),
        rx.text(State.mm.to_string()),
        rx.hstack(
            rx.button("Undo", on_click=niivue.undo_draw()),
            rx.button("Save drawing", on_click=State.save),
        ),
    )


app = rx.App()
app.add_page(index)

Props

niivue_options(**props) shows the constructor options a set of literal props produces.

Volume descriptors

{
    "url": "https://.../t1.nii.gz",  # required (NIfTI, NRRD, MHA, MGH, ...)
    "name": "t1",  # display name (shown in on_location values)
    "colormap": "gray",  # see colormaps()
    "opacity": 1.0,
    "visible": True,  # False = opacity 0, the volume stays loaded
    "cal_min": 0,
    "cal_max": 100,  # display range
    "colormap_label": label_colormap({1: ("liver", (255, 0, 0))}),  # label map
    # any other NiiVue ImageFromUrlOptions, camelCase or snake_case:
    "colormap_negative": "winter",
    "frame_4d": 0,
    "headers": {"Authorization": "..."},
}

The first volume is the background. Volumes are matched by url (or name): changing a property updates the loaded volume; adding volumes after the existing ones appends them; replacing the background or reordering reloads the list.

Mesh descriptors

{
    "url": "https://.../BrainMesh_ICBM152.lh.mz3",
    "name": "lh",
    "rgba255": [200, 200, 200, 255],
    "opacity": 1.0,
    "visible": True,
    "layers": [
        {"url": ".../lh.motor.mz3", "colormap": "warm", "cal_min": 2, "cal_max": 5, "opacity": 0.7}
    ],
}

Events

Imperative helpers

Each returns an event: use it as an event trigger, or return/yield it from a handler. id picks the viewer (its id prop); without it the most recently mounted viewer is used.

rx.button("Undo", on_click=niivue.undo_draw(id="main"))


@rx.event
def save(self):
    yield niivue.save_image("mask.nii.gz", id="main")

Arguments may be state Vars: niivue.move_crosshair_to_mm(State.target).

Colormaps

from reflex_niivue import colormaps, label_colormap

colormaps()  # ["actc", ..., "gray", "hot", ..., "x_rain"]: NiiVue's built-in names

label_colormap({1: ("liver", (255, 0, 0)), 2: ("spleen", "#00ff0080")})
# {"R": [0, 255, 0], "G": [0, 0, 255], "B": [0, 0, 0], "A": [0, 255, 128],
#  "I": [0, 1, 2], "labels": ["background", "liver", "spleen"]}

Demo

git clone https://github.com/ecrespo/reflex-niivue && cd reflex-niivue
uv sync
cd niivue_demo && uv run reflex run

Tabs: volume + label overlay (colormap, opacity, label/heat), multiplanar vs 3D render (camera, clip plane), drawing (pen, undo, clear, save, load), meshes with a scalar layer, two synced viewers, 4D frames and the imperative helpers, and a panel showing on_location from Python state. It uses NiiVue's demo images and falls back to a synthetic phantom (numpy + nibabel, written to niivue_demo/assets/) when they cannot be downloaded; NIIVUE_DEMO_OFFLINE=1 forces the offline data.

Development

uv sync
uv run pre-commit run --all-files
uv run playwright install chromium   # once, for the browser checks
uv run pytest                        # or: uv run pytest -m "not browser"
uv build

Releasing

Releases are published from GitHub Actions with Trusted Publishing (no API tokens):

git tag v0.1.0rc1 && git push origin v0.1.0rc1   # pre-release
git tag v0.1.0 && git push origin v0.1.0         # release

License

Apache-2.0 (see LICENSE and NOTICE). NiiVue is BSD-2-Clause and is installed from npm.