freeview 0.0.2

Interactive FreeSurfer Stats Dashboard

freeview: Interactive FreeSurfer Stats Dashboard

Quick install (recommended)

Use a Python 3.10+ interpreter when creating the virtual environment.

Install freeview:

• Linux / macOS:

# ensure you pick a 3.10+ interpreter (3.12 recommended)
python3.12 -m venv freeviewer
./freeviewer/bin/python -m pip install --upgrade pip
./freeviewer/bin/python -m pip install freeview
./freeviewer/bin/freeview cert
./freeviewer/bin/freeview serve

• Windows (PowerShell):

py -3.12 -m venv freeviewer
.\freeviewer\Scripts\python.exe -m pip install --upgrade pip
.\freeviewer\Scripts\python.exe -m pip install freeview
.\freeviewer\Scripts\freeview.exe cert
.\freeviewer\Scripts\freeview.exe serve

Key Note: If mkcert is not available, freeview cert and freeview serve will print installation hints and will not start until valid, trusted certs exist. freeview will call mkcert -install and then mkcert -ecdsa to generate localhost.pem and localhost-key.pem in the per-user cert directory.

Setup local certificates (important)

Certificates are required for the recommended https only local setup

• freeview requires HTTPS for localhost. The CLI command freeview cert will create and trust a local CA using mkcert (explicit consent is requested) and generate ECDSA P-256 certs.
• Generated certs are stored per-user:
  • macOS / Linux: $XDG_DATA_HOME/freeview/certs or ~/.local/share/freeview/certs
  • Windows: %APPDATA%\\freeview\\certs

(Dependency) Install mkcert to create local certificates:

• Linux:

sudo apt install -y mkcert libnss3-tools 

• macOS:

brew install mkcert 

• Windows (Admin PowerShell):

choco install mkcert -y
# mkcert -install

For other linux distros see mkcert's official guidelines: Use your distro package or download the binary from https://github.com/FiloSottile/mkcert and run mkcert -install.

After installing mkcert, create the local certificates

Create local certificates

./freeviewer/bin/freeview cert   # to create local certificates

INSTALLATION COMPLETE

Launch freeview dashboard

./freeviewer/bin/freeview serve --port 8501   # when using a local venv

Note: The viewer should be running in the default URL: https://localhost:8501

---

Troubleshooting

• ERROR: Package 'freeview' requires a different Python: your venv Python is older than 3.10 — recreate the venv with a 3.10+ interpreter (for example python3.12 -m venv freeviewer).
• no such file or directory: ./freeviewer/bin/freeview: the package failed to install into that venv (or you typed an extra dot like freeview..). Re-run the install steps above.
• Browser certificate warnings: run mkcert -install (or freeview cert), then restart the browser.
• Upgrade pip inside the venv if you see pip warnings:

./freeviewer/bin/python -m pip install --upgrade pip

Install from a local wheel (developer / offline)

Build a wheel in the project root (requires the build package):

./freeviewer/bin/python -m pip install --upgrade pip build
./freeviewer/bin/python -m build
./freeviewer/bin/python -m pip install *.whl

Replace ./freeviewer/bin/python with the interpreter you used to create the venv (or python3.12 if you are not in a venv yet).

Alternate launch method with Streamlit directly (advanced / debugging):

python -m streamlit run path/to/freeview/streamlit_app.py -- \\
	./output/consolidated_stats.csv ./output/summary.csv

When running Streamlit directly and wanting HTTPS you must pass --server.sslCertFile and --server.sslKeyFile.

CSV conversion

freeview stats2csv --stats-dir /path/to/A_T1/stats --out-dir ./output

---

Copyright © 2026 Kishore Kumar Tarafdar

Released under the GNU General Public License v3.0 — see LICENSE