FreeBrowse v2

🚧 Work in progress 🚧

FreeBrowse is a full-stack, web-based neuroimaging viewer and editor. It aspires to be a web-based version of the FreeSurfer tool FreeView.

Try out the 'serverless' version: https://freesurfer.github.io/freebrowse/

Frontend:

• React + TypeScript
• Vite (build tool)
• Tailwind CSS 4 + Radix UI components
• NiiVue (neuroimaging viewer)

Backend:

• FastAPI (Python web framework)
• Pixi (package manager)

This is a re-write of the initial FreeBrowse implementation, based off of the niivue fullstack demo.

Are you looking for the original FreeBrowse codebase? That now lives on the branch v1.

Install

Pre-requisites

Requirements:

• Node.js (for frontend environment)
• npm (for frontend environment)
• pixi (for backend environment)
• git

This should install all dependencies on an Ubuntu 24.04 system:

sudo apt update && sudo apt upgrade -y
sudo apt install nodejs npm git -y
curl -fsSL https://pixi.sh/install.sh | sh

Then clone the repo:

git clone git@github.com:freesurfer/freebrowse.git

If you want to use the example data, run get-example-volumes.sh in the data/ folder:

cd freebrowse/data
./get-example-volumes.sh

Frontend Setup

cd frontend
npm install

Backend Setup

cd backend
pixi install

Build

The frontend has several build targets:

Serverless (static deployment)

Builds a fully serverless frontend (no backend required) that can be deployed to any static file host:

cd frontend
npm run build:serverless

This creates a static build in frontend/dist/. You can set VITE_BASE_PATH to control the base URL path (defaults to /).

GitHub Pages

Builds the serverless version configured for GitHub Pages deployment:

cd frontend
npm run build:github

Output is in frontend/dist-github/.

JupyterLab

Builds the serverless version configured for embedding inside JupyterLab:

cd frontend
npm run build:jupyter

Output is in frontend/dist-jupyter/. It also gets copied to jupyter/jupyterlab_freebrowse/static/freebrowse/. See the Jupyter Integration for more information.

Single HTML file

Builds a single standalone HTML file that can be distributed alongside output of processing pipelines:

cd frontend
npm run build:singlefile

This creates a single standalone HTML file in frontend/dist-singlefile/ that is compatible with the file:// protocol. Users can use this to view local imaging data or self-contained NiiVue documents. The latest version of the standalone HTML file is available at

https://freesurfer.github.io/freebrowse/downloads/freebrowse-<version>.html

Where <version> is the current version of freebrowse

Full stack (with backend)

Builds the frontend for use with the FastAPI backend:

cd frontend
npm run build

Dev

Run the backend in development mode

This hot reloads the backend when changes are made to the code.

cd backend
pixi run dev

Run the frontend in development mode

cd frontend
npm run dev

Then navigate to http://localhost:5173/

Github Pages

To enable GitHub Pages:

1. Go to your repo on GitHub: Settings --> Pages
2. Under "Build and deployment", set Source to "GitHub Actions"
3. Push changes to main

You should then be able to view the 'serverless' version of your changes at https://{github-username.github.io/freebrowse/

Production

Build the frontend for production

cd frontend
npm run build

Jupyter Integration

FreeBrowse can be used as a NIfTI file viewer inside JupyterLab or Jupyter Notebook 7. Clicking a .nii, .nii.gz or .nvd (niivue document) file in the file browser opens it in FreeBrowse in a new browser tab.

Setup

Create and activate a conda environment with either JupyterLab or Notebook 7 and run pip install -e . from the jupyter/ directory.

The file jupyter/environment.yml contains a sample maximal environment that contains both JupyterLab, Jupyter Notebook and nodejs (for development) as well as ipyniivue to run niivue directly inside of Jupyter notebooks.

cd ./jupyter
conda env create -f environment.yml

Usage

Start JupyterLab or Notebook:

jupyter lab       # if using JupyterLab
jupyter notebook  # if using Notebook 7

Navigate to a directory containing .nii, .nii.gz or .nvd files, then either:

• Double-click a file to open it in FreeBrowse in a new browser tab
• Right-click a file and select Open in FreeBrowse

ipyniivue is also installed in the example freebrowse-jupyter environment. See the example notebooks repository for examples on how to use niivue directly inside jupyter

Development

If you make changes to the frontend, you will have to rebuild the jupyter before they become visible in Jupyter notebooks.

cd frontend
npm run build:jupyter

To re-install the JupyterLab extensions:

cd jupyter
jlpm install
jlpm build
pip install -e .

Acknowledgements

FreeBrowse was generously funded by Gates Ventures. The original implementation was performed by zuehlke.

Version 2 is based off of the niivue fullstack demo which was developed during a Google Summer of Code Project in close collaboration with the niivue team.