Getting Started#

This guide gets a new user to a working SWC-Studio install and a first successful run.

Installation paths#

There are three supported ways to install:

Method

Best for

Models bundled?

Option 1 — bundled desktop app

end users who want a double-clickable application

yes, inside the app

Option 2 — pip install swcstudio

researchers using SWC-Studio in scripts / Python

yes, inside the wheel

Option 3 — install from source

developers who want to modify the code itself

yes, in the local checkout

Supported Python versions#

Options 2 and 3 require Python 3.10, 3.11, or 3.12 already installed on your system.

Python 3.12 is the recommended default. Newer Python releases are added only after the compiled scientific dependencies and the pinned model runtime have been validated together.

Option 1 (the bundled app) ships its own Python runtime — no separate Python install needed.

Option 1 — Bundled desktop app#

Use this path if you only need the desktop application and don’t want to deal with Python.

  1. open Mio0v0/SWC-Studio

  2. download SWC-Studio-vX.Y.Z-macOS.zip (Mac) or SWC-Studio-vX.Y.Z-Windows.zip (Windows)

  3. extract and launch:

    • macOS — drag SWC-Studio.app into /Applications, then double-click. First launch may need xattr -cr /Applications/SWC-Studio.app (or right-click → Open) because the bundle is not yet code-signed.

    • Windows — extract anywhere, run the .exe inside.

The auto-typing models are bundled inside the app, so the first auto-label call works without any download. Release executables are intended to be portable CPU builds. Use a pip or source install for GPU acceleration.

Option 2 — pip install from PyPI#

Use this path for the desktop GUI, scripts, Jupyter notebooks, batch processing, or any Python workflow. Create a new virtual environment so the python, pip, swcstudio, and swcstudio-gui commands all refer to the same installation.

macOS / Linux#

python3.12 -m venv ~/swcstudio-env
source ~/swcstudio-env/bin/activate
python -m pip install --upgrade pip
python -m pip install swcstudio
swcstudio doctor
swcstudio-gui

Windows PowerShell#

py -3.12 -m venv $HOME\swcstudio-env
& $HOME\swcstudio-env\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install swcstudio
swcstudio doctor
swcstudio-gui

That single python -m pip install swcstudio command installs every Python runtime requirement: the scientific stack, PyTorch and torch-geometric, XGBoost and scikit-learn, PySide6, VisPy, pyqtgraph, and the history/provenance libraries. The wheel also contains all runtime JSON configuration and all eight production models. There is no separate requirements file, model download, or [gui] extra.

The CI release gate installs the built wheel into an empty virtual environment and runs model deserialization, GUI imports, and inference on Windows, macOS, and Linux with Python 3.10, 3.11, and 3.12.

To upgrade later: python -m pip install --upgrade swcstudio. The new wheel installs the matching code, configuration, and production models.

If swcstudio doctor reports an executable outside the environment you created, run the commands by absolute environment path, for example ~/swcstudio-env/bin/swcstudio-gui on macOS/Linux or $HOME\swcstudio-env\Scripts\swcstudio-gui.exe on Windows.

Option 3 — Source install (development)#

Use this path if you want to modify the swcstudio code itself. The -e flag installs in editable mode, meaning edits to local .py files take effect on the next python run — no reinstall needed.

Clone the repository:

git clone https://github.com/Mio0v0/SWC-Studio.git
cd SWC-Studio

One command installs everything — the CLI, the desktop GUI, the auto-typing engine (sklearn + torch + torch_geometric), and the bundled model files:

macOS / Linux#

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

The editable install includes the complete scientific, ML, desktop GUI, visualization, and history runtime. New users do not need to install a separate requirements file or GUI extra.

Windows PowerShell#

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

Conda#

conda create -n swc-studio python=3.12 -y
conda activate swc-studio
python -m pip install --upgrade pip
python -m pip install -e .

Optional developer extras#

For maintainers who need PyInstaller (release packaging) and Sphinx (docs build):

python -m pip install -e ".[dev]"

End users do not need this.

Updating#

How you update depends on how you installed:

Install method

How to update

Option 1 (bundled app)

Help → Check for Updates in the GUI. The in-app updater downloads only the changed layer (~5 MB code or ~80 MB models), no full re-download.

Option 2 (pip)

python -m pip install --upgrade swcstudio installs the matching code, dependencies, configuration, and bundled models.

Option 3 (source)

git pull followed by python -m pip install -e . to pick up any new dependencies or metadata.

Internally, each release is split into three independent layers — runtime, code, and models — so most updates only re-fetch the small ones. See packaging/MODULAR_BUILD.md for the architecture details.

Verify installation#

swcstudio --help
swcstudio doctor
swcstudio models status
swcstudio gpu-status
swcstudio-gui --help

If a console script is not on your path, fall back to module mode:

python -m swcstudio.cli.cli --help
python -m swcstudio.gui.main

swcstudio models status is worth running once after install: it prints the auto-labeling engine’s model search path and confirms the bundled model files are reachable. You should see the labeling files cell_type_classifier.pkl, branch_classifier.pkl, gnn_apical_basal.pt, gnn_branch3_rescue.pt, the QC gate qc_gate.pkl, and the flag-scoring files flag_model_pyramidal.joblib, flag_model_interneuron.joblib, and flag_model_all.joblib listed as [FOUND].

swcstudio gpu-status is optional. It explains whether the active pip or source environment can use CUDA, and what is missing when it cannot. The GUI exposes the same check under Help -> GPU Readiness. For setup details, see GPU Setup.

First CLI checks#

Start with a read-only inspection command:

swcstudio check cell.swc
swcstudio validate cell.swc

Then try an edit command:

swcstudio auto-label cell.swc
swcstudio set-type cell.swc --node-id 14169 --new-type 3
swcstudio simplify cell.swc
swcstudio connect cell.swc --start-id 10 --end-id 22

Single-file edit commands update the source SWC directly and record the operation in <stem>_history.swcstudio next to the file. No separate --write flag is required.

auto-label always applies soma / axon / basal labeling, detects apical labels when appropriate, and can flag cells whose predicted labels look unreliable. Use --cell-type pyramidal or --cell-type interneuron when you already know the cell type; leave it unknown to run Stage 1.

First GUI checks#

Launch the GUI:

swcstudio-gui

Then:

  1. open an SWC file

  2. review the automatically generated issue list

  3. select an issue and let the app route you to the matching repair tool

  4. save or close the file to keep the original SWC updated and record the operation in history

Default outputs#

For a source file:

  • <folder>/<stem>.swc

the default single-file output directory is:

  • <folder>/<stem>_swc_studio_output/

That legacy-compatible directory is used mainly for explicitly requested single-file validation reports and report-only exports.

Other materialized outputs use their operation-specific location:

  • batch split creates a timestamped batch output directory

  • history checkout writes the requested output path (or its documented default)

  • history checkpoint writes a labeled SWC next to the source

GUI and mutating CLI edits are recorded in the per-file history archive next to the SWC:

  • <stem>_history.swcstudio