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

To build a fully serverless frontend (no backend required at all), use the VITE_SERVERLESS environment variable:

cd frontend
VITE_SERVERLESS=true npm run build

This creates a static build in frontend/dist/ that can be deployed to GitHub Pages or any static file host.

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

or

cd frontend
VITE_SERVERLESS=true 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

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.