NiiVue Streamlit Component

A modern Streamlit component for visualizing neuroimaging data using NiiVue, built with TypeScript, Preact, and Vite.

🚀 Quick Start

Simple Installation & Usage

Install the component:

pip install --index-url https://test.pypi.org/simple/ --no-deps niivue-streamlit

Use in your Streamlit app:

import streamlit as st
from niivue_component import niivue_viewer

uploaded_file = st.file_uploader("Choose a NIFTI file", type=["nii", "nii.gz"])

if uploaded_file is not None:
    result = niivue_viewer(
        nifti_data=uploaded_file.getvalue(),
        filename=uploaded_file.name,
        height=700
    )

    # Handle click events
    if result:
        st.write(f"Clicked voxel: {result['voxel']}, Value: {result['value']}")

✨ Features

🎨 Two Component Modes:
- StyledViewer: Full-featured viewer with interactive menu and controls
- UnstyledCanvas: Minimal canvas-only viewer for embedding
🔄 Multiple View Modes:
- Axial, Coronal, Sagittal slices
- 3D render view
- Multiplanar view with render
📊 Advanced Capabilities:
- Multiple overlay images with custom colormaps
- Surface mesh rendering (FreeSurfer pial, white, inflated, GIfTI, STL, OBJ, etc.)
- Mesh overlays (curvature, thickness, annotations)
- Combined volume + mesh visualization
- Configurable display settings (crosshair, radiological convention, colorbar, interpolation)
- Bidirectional communication (click events from viewer to Python)
- DICOM support

📖 Advanced Usage

With Overlays

from niivue_component import niivue_viewer

result = niivue_viewer(
    nifti_data=main_image_bytes,
    filename="brain.nii.gz",
    overlays=[
        {
            "data": overlay_bytes,
            "name": "activation.nii.gz",
            "colormap": "hot",
            "opacity": 0.7
        }
    ],
    view_mode="multiplanar",
    styled=True,
    settings={
        "crosshair": True,
        "radiological": False,
        "colorbar": True,
        "interpolation": True
    },
    height=800
)

With Mesh Surfaces

from niivue_component import niivue_viewer

# Load a FreeSurfer surface mesh
mesh_data = open("lh.pial", "rb").read()

result = niivue_viewer(
    meshes=[{
        "data": mesh_data,
        "name": "lh.pial",
    }],
    view_mode="3d",
    height=700
)

Mesh with Overlays (Curvature, Thickness)

mesh_data = open("lh.pial", "rb").read()
thickness_data = open("lh.thickness", "rb").read()

result = niivue_viewer(
    meshes=[{
        "data": mesh_data,
        "name": "lh.pial",
        "overlays": [{
            "data": thickness_data,
            "name": "lh.thickness",
            "colormap": "redyell",
            "opacity": 0.7
        }]
    }],
    view_mode="3d",
    height=700
)

Volume with Mesh

# Display a volume image alongside a surface mesh
volume_data = open("brain.nii.gz", "rb").read()
mesh_data = open("lh.pial", "rb").read()

result = niivue_viewer(
    nifti_data=volume_data,
    filename="brain.nii.gz",
    meshes=[{
        "data": mesh_data,
        "name": "lh.pial",
    }],
    view_mode="3d",
    height=700
)

# Perfect for embedding in complex layouts
result = niivue_viewer(
    nifti_data=image_bytes,
    filename="scan.nii",
    styled=False,  # Hide menu
    view_mode="axial",
    height=400
)

📚 API Reference

`niivue_viewer()`

Parameters:

nifti_data (bytes, optional): Raw NIFTI file data
filename (str): Displayed filename
overlays (list[dict], optional): Overlay images list
- data (bytes): Overlay data
- name (str): Overlay name
- colormap (str): Colormap (default: 'red')
- opacity (float): 0-1 (default: 0.5)
meshes (list[dict], optional): Mesh surfaces list
- data (bytes): Mesh file data
- name (str): Mesh filename (must include extension, e.g. 'lh.pial', 'brain.gii')
- overlays (list[dict], optional): Mesh overlays (curvature, thickness, etc.)
  - data (bytes): Overlay data
  - name (str): Overlay filename
  - colormap (str): Colormap (default: 'redyell')
  - opacity (float): 0-1 (default: 0.7)
height (int): Height in pixels (default: 600)
view_mode (str): 'axial', 'coronal', 'sagittal', '3d', 'multiplanar' (default)
styled (bool): Show menu (default: True)
settings (dict, optional):
- crosshair (bool): default True
- radiological (bool): default False
- colorbar (bool): default False
- interpolation (bool): default True
key (str, optional): Component key

Returns:

dict or None with click event data:

type: 'voxel_click'
voxel: [x, y, z]
mm: [x, y, z]
value: float
filename: str

🛠️ Development

Dev mode (live reload)

In dev mode, the Python package points to a local Vite dev server instead of built files.

Terminal 1 — start the frontend dev server (port 3001):

pnpm dev

Terminal 2 — run the example app with the dev flag:

NIIVUE_DEV=1 streamlit run app.py

The frontend hot-reloads on changes.

Production mode (built files)

Build the frontend first, then run Streamlit normally:

pnpm build
streamlit run app.py

_RELEASE = True (the default) serves from niivue_component/frontend/build/.

Running Examples

# Simple example
streamlit run app.py

# Advanced example with all features
streamlit run app_advanced.py

📁 Supported Formats

Volume-based: NIFTI (.nii, .nii.gz), DICOM (.dcm), MINC (.mnc, .mnc.gz), MHA/MHD, NRRD, MGH/MGZ
Mesh-based: GIfTI (.gii), FreeSurfer (pial, white, inflated), MZ3 (.mz3), STL (.stl), Wavefront OBJ (.obj), PLY (.ply), BrainSuite DFS (.dfs), Legacy VTK (.vtk)
Mesh Overlays: GIfTI (.gii), CIfTI-2 (.nii), MZ3 (.mz3), FreeSurfer (CURV, ANNOT), SMP, STC
Tractography: TCK (.tck), TRK (.trk), TRX (.trx), VTK (.vtk)

🏗️ Architecture

niivue_component/
├── __init__.py                 # Python API
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── StyledViewer.tsx
│   │   │   └── UnstyledCanvas.tsx
│   │   ├── types.ts
│   │   └── utils.ts
│   ├── vite.config.ts
│   └── package.json
└── build/                      # Compiled assets (generated, not in git)

🔧 Building for Distribution

Build files are not committed to git. To prepare the Python package for release:

pnpm build
python -m build

This compiles frontend assets into niivue_component/frontend/build/, which is then bundled into the Python package.

📄 License

BSD-2-Clause

🙏 Credits

Built on top of:

Release files for niivue-streamlit 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for niivue-streamlit 0.3.0
File	Size	Uploaded
niivue_streamlit-0.3.0.tar.gz	1.2 MB	May 17, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for niivue-streamlit 0.3.0
File	Interpreter	ABI	Platform	Reset
niivue_streamlit-0.3.0-py3-none-any.whl 1.2 MB May 17, 2026	Python 3	none	any	Details

Total release size: 2.5 MB

Release files / niivue_streamlit-0.3.0.tar.gz

Download URL	niivue_streamlit-0.3.0.tar.gz
Size	1.2 MB
Tags	Source
SHA-256 checksum How to use checksums	`c8c3135091237e44da24ab8b323ed52025e6bcb5b0975676c2e9bb87c3835723`
BLAKE2b-256 checksum How to use checksums	`ad0a037159eba5f4e68a642e217d4d3bd9729012fffaa264d5625793247a7fe9`
Upload date	May 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.15`

Release files / niivue_streamlit-0.3.0-py3-none-any.whl

Download URL	niivue_streamlit-0.3.0-py3-none-any.whl
Size	1.2 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`01e83b5ea2823636fb3d367b65f0d028c764ee4d113f1fe01a1ab9e34fe521d7`
BLAKE2b-256 checksum How to use checksums	`a7cb3bb25392513318d9c167883c475bd7f3a4d0d906b032e2735ef4fad635f2`
Upload date	May 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.15`