Skip to content

INSTALLATION.md

Latest commit

 

History

History
123 lines (97 loc) · 5.7 KB

INSTALLATION.md

File metadata and controls

123 lines (97 loc) · 5.7 KB
Raw

Python desktop installation

BrainNet Viewer 2.0.0 uses Python package version 2.0.0. Obtain brainnet_viewer-2.0.0-py3-none-any.whl from the accompanying GitHub or NITRC release and verify its SHA-256 against that release's SHA256SUMS. If the matching wheel is not yet available, use the source-installation section below; do not rename an older wheel. MATLAB and SPM are not required. Dependencies need Internet access unless supplied in a separate offline collection. Current source builds require Python 3.11 or newer on all platforms.

Apple Silicon macOS requires Python 3.11 or newer; Python 3.11 is the verified configuration. For new installations, use a supported Python version: 3.11 on Apple Silicon, or 3.12 on Windows. Python 3.10 reached end of support on 1 October 2026 (Python release schedule). A graphical desktop with working OpenGL and a writable folder is required. Selected desktop workflows have been tested on Windows x64 and Apple Silicon macOS. Linux Desktop and Intel Mac have not been verified. Install the pinned dependencies in a separate virtual environment.

Windows

Open PowerShell in the wheel directory:

py -3.11 -m venv .venv-bnv
$bnvPython = (Resolve-Path .venv-bnv/Scripts/python.exe).Path
$bnvWheel = (Resolve-Path brainnet_viewer-2.0.0-py3-none-any.whl).Path
$bnvWheelUrl = & $bnvPython -c "from pathlib import Path; import sys; print(Path(sys.argv[1]).resolve().as_uri())" $bnvWheel
& $bnvPython -m pip install "brainnet-viewer[desktop] @ $bnvWheelUrl"
& $bnvPython -m pip check
& $bnvPython -m brainnet_viewer

If py is unavailable, use the full Python 3.11 path for the first command. After installation, .venv-bnv/Scripts/brainnet-viewer.exe starts the graphical app without a new console. The module command above shows startup errors.

macOS and Linux

On the graphical desktop, open a terminal in the wheel directory:

python3.11 -m venv .venv-bnv
source .venv-bnv/bin/activate
BNV_WHEEL="$(pwd)/brainnet_viewer-2.0.0-py3-none-any.whl"
BNV_WHEEL_URL="$(python -c 'from pathlib import Path; import sys; print(Path(sys.argv[1]).resolve().as_uri())' "$BNV_WHEEL")"
python -m pip install "brainnet-viewer[desktop] @ $BNV_WHEEL_URL"
python -m pip check
brainnet-viewer

On Apple Silicon macOS, use the Python 3.11 command above. The package selects SciPy 1.17.1 for native ARM64 macOS; this dependency requires Python 3.11 or newer. Linux and Intel macOS retain SciPy 1.15.3. Never copy virtual environments between operating systems.

First use

Current source builds include fonts for Chinese and supported Unicode annotations. Unsupported glyphs are reported rather than silently omitted. Mixed Unicode node labels use the bundled fallback; ASCII labels retain their selected font family. Long titles fit within the heading strip. If a title cannot fit legibly, widen the canvas or shorten it. PDF fallback text is stored as glyph outlines.

Select your input files, adjust Visualization Settings and click Apply to render. Rotate, Pan and Zoom affect the selected view. Use Export Figure to save an image with its provenance record, or Save Scene to reopen the inputs and settings later. A preset stores display settings only. Use the shared tutorials and manual.

The wheel includes surface templates, atlas-network examples, tutorial data and the AAL/Brodmann Inspect tables. Use the installed Python environment to locate the resources:

python -c "from importlib.metadata import version; print(version('brainnet-viewer'))"
python -c "from pathlib import Path; import brainnet_viewer; print(Path(brainnet_viewer.__file__).parent / 'resources')"

On Windows replace python with & $bnvPython. Copy examples before editing them. For CLI export, use a same-edition Scene and the shared command-line tutorial.

Troubleshooting

  • Missing dependency: retain Python version, architecture, index and full pip error. Keep pins and global settings unchanged.
  • Missing dependencies for SOCKS support: pip may have inherited a SOCKS proxy. Confirm whether it is needed; temporarily clear unwanted proxy variables only in this terminal, or configure a working HTTP proxy.
  • Startup error: use this environment's module command, run pip check and confirm the desktop extra was installed.
  • Blank rendering: check drivers and the graphical session; include GPU/display scaling details with a reproducible report.

For browser use see Docker installation. Contact Mingrui Xia: mxia@bnu.edu.cn; mingruixia@gmail.com.

Install the current source

The source package version is 2.0.0. Earlier 2.0.0b1 wheels retain their original contents. For source installation, open a terminal at the complete repository root and use a new environment with Python 3.11 or newer; Python 3.12 is recommended on Windows. Python 3.10 is no longer supported by the current source because the patched Pillow dependency requires Python 3.11. Create a new environment rather than upgrading an existing beta environment.

Windows PowerShell:

py -3.12 -m venv .venv-bnv-source
$bnvPython = (Resolve-Path .venv-bnv-source/Scripts/python.exe).Path
& $bnvPython -m pip install "./src/python[desktop]"
& $bnvPython -m pip check
& $bnvPython -m brainnet_viewer

macOS/Linux Terminal:

python3.11 -m venv .venv-bnv-source
source .venv-bnv-source/bin/activate
python -m pip install './src/python[desktop]'
python -m pip check
brainnet-viewer

Keep the pinned dependencies. Source installation leaves existing wheel installations and downloaded packages unchanged. After installation, launch the application and render an example to check the graphics environment.