swcstudio 0.2.0__tar.gz

swcstudio-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SWC-Dash Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

swcstudio-0.2.0/MANIFEST.in

@@ -0,0 +1,13 @@
+# Source distribution manifest.
+#
+# Setuptools by default includes every git-tracked file in the sdist.
+# We exclude the model files from the sdist for the same reason
+# pyproject.toml's package-data is empty: SWC-Studio uses Pattern B —
+# code only ships via pip, models download from GitHub Releases on
+# first use. See packaging/MODULAR_BUILD.md.
+#
+# Result: a fresh `pip install --no-binary :all: swcstudio` (source
+# install) produces a model-less install; the first auto-label call
+# triggers swcstudio.core.updater to download models on demand.
+
+recursive-exclude swcstudio/data/models *

swcstudio-0.2.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: swcstudio
+Version: 0.2.0
+Summary: Modular SWC processing toolkit with shared core for CLI and GUI
+Author: SWC-Dash Contributors
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: morphio>=3.3
+Requires-Dist: neurom>=4.0
+Requires-Dist: scikit-learn<1.6,>=1.5
+Requires-Dist: torch>=2.1
+Requires-Dist: torch-geometric>=2.6
+Requires-Dist: PySide6>=6.6
+Requires-Dist: pyqtgraph>=0.14
+Requires-Dist: vispy>=0.14
+Provides-Extra: build
+Requires-Dist: PyInstaller>=6.11; extra == "build"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8.2; extra == "docs"
+Requires-Dist: pydata-sphinx-theme>=0.16; extra == "docs"
+Requires-Dist: myst-parser>=3.0; extra == "docs"
+Provides-Extra: all
+Requires-Dist: PyInstaller>=6.11; extra == "all"
+Requires-Dist: sphinx>=8.2; extra == "all"
+Requires-Dist: pydata-sphinx-theme>=0.16; extra == "all"
+Requires-Dist: myst-parser>=3.0; extra == "all"
+Dynamic: license-file
+
+# SWC-Studio
+
+`SWC-Studio` is a desktop, CLI, and Python toolkit for working with neuron morphology files in SWC format.
+
+It is designed for inspecting reconstructions, finding structural or annotation problems, repairing them, and running repeatable morphology-processing workflows from one shared backend.
+
+## Project Overview
+
+`SWC-Studio` includes:
+
+- a shared Python backend (`swcstudio`)
+- a command-line interface (`swcstudio`)
+- a desktop GUI (`swcstudio-gui`)
+
+Both the CLI and GUI use the same core feature logic.
+
+### Auto-labeling engine
+
+Auto-labeling uses a single ML pipeline: the **v9 engine**. It runs a four-stage process — cell-type detection, per-subtree axon/basal/apical classification, a GraphSAGE GNN apical-vs-basal re-decision, and topology refinement — and automatically chooses between 3-class (no apical) and 4-class output per file. All four stages are required and ship trained out of the box.
+
+The toolkit ships with bundled trained models. After `pip install -e .` the engine works out of the box; users can also retrain on their own labeled SWC corpus via `swcstudio train auto-typing` and have the toolkit pick up the new models automatically.
+
+## Documentation
+
+Project documentation lives on the docs website:
+
+- Live docs: [https://mio0v0.github.io/SWC-Studio/](https://mio0v0.github.io/SWC-Studio/)
+- All releases: [https://github.com/Mio0v0/SWC-Studio/releases](https://github.com/Mio0v0/SWC-Studio/releases)
+
+Use the docs site for:
+
+- installation and getting started
+- GUI and CLI workflows
+- validation, repair, and reporting behavior
+- the auto-typing engine and retraining workflow
+- tutorials
+- API and extension references
+
+### Release Assets
+
+Current GitHub Releases may include:
+
+- macOS application bundle
+- Windows executable package
+
+## Quick Start
+
+Option 1: download a packaged executable from the GitHub Releases page and run the app directly.
+
+- macOS: [SWC-Studio v0.1.0 for macOS](https://github.com/Mio0v0/SWC-Studio/releases/download/v0.1.0/SWC-Studio.v0.1.0.macOS.zip)
+- Windows: [SWC-Studio v0.1.0 for Windows](https://github.com/Mio0v0/SWC-Studio/releases/download/v0.1.0/SWC-Studio.v0.1.0.Windows.zip)
+- Download the zip for your platform, extract it, and launch the included application
+
+Option 2: install from source. Supported Python versions: 3.10, 3.11, 3.12, 3.13.
+
+macOS / Linux:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+swcstudio-gui
+```
+
+Windows PowerShell:
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -e .
+swcstudio-gui
+```
+
+A single `pip install -e .` pulls in everything: the CLI, the desktop GUI, the auto-typing engine (sklearn + torch + torch_geometric), and the bundled v9 model files. There are no extras to remember for normal use. Maintainers who need PyInstaller and Sphinx for release packaging and docs builds can use `pip install -e ".[all]"`.
+
+CLI help:
+
+```bash
+swcstudio --help
+swcstudio models status     # confirm the bundled auto-typing models are reachable
+```
+
+If the script entry point is not on your path, fall back to module mode:
+
+```bash
+python -m swcstudio.cli.cli --help
+python -m swcstudio.gui.main
+```
+
+## Core Capabilities
+
+- issue-driven SWC validation and repair
+- batch processing workflows
+- v9 ML auto-typing engine: Stage 1 cell-type detector + Stage 2 per-subtree classifier + Stage 2b GraphSAGE GNN apical-vs-basal head + Stage 3 topology refinement, with bundled trained models
+- automatic apical detection (3-class vs 4-class output chosen per file)
+- one-command retraining of the engine on user data (`swcstudio train auto-typing`)
+- radii cleaning
+- manual morphology and geometry editing
+- shared GUI, CLI, and Python integration surface
+
+## Train your own auto-typing models
+
+If you want models tuned to your own SWCs, the toolkit ships a one-command trainer:
+
+```bash
+swcstudio train auto-typing \
+    --data-dir path/to/labeled/dataset \
+    --output-dir path/to/save/models
+```
+
+The dataset directory must have `pyramidal/` and `interneuron/` subfolders of labeled `.swc` files (each SWC's `type` column is the per-node ground truth).
+
+To use the trained models afterwards:
+
+```bash
+# One-off: pass --model-dir per call
+swcstudio auto-label cell.swc --model-dir path/to/save/models
+
+# Or set the env var for the whole shell
+export SWCSTUDIO_MODEL_DIR=path/to/save/models      # macOS/Linux
+$env:SWCSTUDIO_MODEL_DIR = "path\to\save\models"    # Windows PowerShell
+
+# Or make them the persistent default by copying into the user data dir;
+# see the docs site for the per-platform path.
+```
+
+See the [Auto-Typing Engine](https://mio0v0.github.io/SWC-Studio/documentation/auto-typing-backends.html) page in the docs for the full retraining workflow, hyperparameter flags, and model resolution rules.
+
+## Recommended Workflow
+
+1. Open one SWC file in the GUI.
+2. Run validation and review the issue list.
+3. Apply the suggested repairs.
+4. Rerun validation.
+5. Save or export the cleaned result.
+
+## License
+
+Released under the MIT License. See `LICENSE`.

swcstudio-0.2.0/README.md

@@ -0,0 +1,139 @@
+# SWC-Studio
+
+`SWC-Studio` is a desktop, CLI, and Python toolkit for working with neuron morphology files in SWC format.
+
+It is designed for inspecting reconstructions, finding structural or annotation problems, repairing them, and running repeatable morphology-processing workflows from one shared backend.
+
+## Project Overview
+
+`SWC-Studio` includes:
+
+- a shared Python backend (`swcstudio`)
+- a command-line interface (`swcstudio`)
+- a desktop GUI (`swcstudio-gui`)
+
+Both the CLI and GUI use the same core feature logic.
+
+### Auto-labeling engine
+
+Auto-labeling uses a single ML pipeline: the **v9 engine**. It runs a four-stage process — cell-type detection, per-subtree axon/basal/apical classification, a GraphSAGE GNN apical-vs-basal re-decision, and topology refinement — and automatically chooses between 3-class (no apical) and 4-class output per file. All four stages are required and ship trained out of the box.
+
+The toolkit ships with bundled trained models. After `pip install -e .` the engine works out of the box; users can also retrain on their own labeled SWC corpus via `swcstudio train auto-typing` and have the toolkit pick up the new models automatically.
+
+## Documentation
+
+Project documentation lives on the docs website:
+
+- Live docs: [https://mio0v0.github.io/SWC-Studio/](https://mio0v0.github.io/SWC-Studio/)
+- All releases: [https://github.com/Mio0v0/SWC-Studio/releases](https://github.com/Mio0v0/SWC-Studio/releases)
+
+Use the docs site for:
+
+- installation and getting started
+- GUI and CLI workflows
+- validation, repair, and reporting behavior
+- the auto-typing engine and retraining workflow
+- tutorials
+- API and extension references
+
+### Release Assets
+
+Current GitHub Releases may include:
+
+- macOS application bundle
+- Windows executable package
+
+## Quick Start
+
+Option 1: download a packaged executable from the GitHub Releases page and run the app directly.
+
+- macOS: [SWC-Studio v0.1.0 for macOS](https://github.com/Mio0v0/SWC-Studio/releases/download/v0.1.0/SWC-Studio.v0.1.0.macOS.zip)
+- Windows: [SWC-Studio v0.1.0 for Windows](https://github.com/Mio0v0/SWC-Studio/releases/download/v0.1.0/SWC-Studio.v0.1.0.Windows.zip)
+- Download the zip for your platform, extract it, and launch the included application
+
+Option 2: install from source. Supported Python versions: 3.10, 3.11, 3.12, 3.13.
+
+macOS / Linux:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+swcstudio-gui
+```
+
+Windows PowerShell:
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -e .
+swcstudio-gui
+```
+
+A single `pip install -e .` pulls in everything: the CLI, the desktop GUI, the auto-typing engine (sklearn + torch + torch_geometric), and the bundled v9 model files. There are no extras to remember for normal use. Maintainers who need PyInstaller and Sphinx for release packaging and docs builds can use `pip install -e ".[all]"`.
+
+CLI help:
+
+```bash
+swcstudio --help
+swcstudio models status     # confirm the bundled auto-typing models are reachable
+```
+
+If the script entry point is not on your path, fall back to module mode:
+
+```bash
+python -m swcstudio.cli.cli --help
+python -m swcstudio.gui.main
+```
+
+## Core Capabilities
+
+- issue-driven SWC validation and repair
+- batch processing workflows
+- v9 ML auto-typing engine: Stage 1 cell-type detector + Stage 2 per-subtree classifier + Stage 2b GraphSAGE GNN apical-vs-basal head + Stage 3 topology refinement, with bundled trained models
+- automatic apical detection (3-class vs 4-class output chosen per file)
+- one-command retraining of the engine on user data (`swcstudio train auto-typing`)
+- radii cleaning
+- manual morphology and geometry editing
+- shared GUI, CLI, and Python integration surface
+
+## Train your own auto-typing models
+
+If you want models tuned to your own SWCs, the toolkit ships a one-command trainer:
+
+```bash
+swcstudio train auto-typing \
+    --data-dir path/to/labeled/dataset \
+    --output-dir path/to/save/models
+```
+
+The dataset directory must have `pyramidal/` and `interneuron/` subfolders of labeled `.swc` files (each SWC's `type` column is the per-node ground truth).
+
+To use the trained models afterwards:
+
+```bash
+# One-off: pass --model-dir per call
+swcstudio auto-label cell.swc --model-dir path/to/save/models
+
+# Or set the env var for the whole shell
+export SWCSTUDIO_MODEL_DIR=path/to/save/models      # macOS/Linux
+$env:SWCSTUDIO_MODEL_DIR = "path\to\save\models"    # Windows PowerShell
+
+# Or make them the persistent default by copying into the user data dir;
+# see the docs site for the per-platform path.
+```
+
+See the [Auto-Typing Engine](https://mio0v0.github.io/SWC-Studio/documentation/auto-typing-backends.html) page in the docs for the full retraining workflow, hyperparameter flags, and model resolution rules.
+
+## Recommended Workflow
+
+1. Open one SWC file in the GUI.
+2. Run validation and review the issue list.
+3. Apply the suggested repairs.
+4. Rerun validation.
+5. Save or export the cleaned result.
+
+## License
+
+Released under the MIT License. See `LICENSE`.

swcstudio-0.2.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "swcstudio"
+version = "0.2.0"
+description = "Modular SWC processing toolkit with shared core for CLI and GUI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "SWC-Dash Contributors"}]
+dependencies = [
+  # Core scientific stack
+  "numpy>=1.24",
+  "pandas>=2.0",
+  "scipy>=1.11",
+  "morphio>=3.3",
+  "neurom>=4.0",
+  # Auto-typing engine (v9 ML pipeline) — Stage 1 + Stage 2 sklearn
+  # ensembles, Stage 2b GraphSAGE GNN. Pinned to the 1.5.x series the
+  # bundled pickles were trained on; sklearn does not guarantee
+  # cross-minor pickle compatibility.
+  "scikit-learn>=1.5,<1.6",
+  "torch>=2.1",
+  "torch-geometric>=2.6",
+  # GUI — the desktop app is the primary user surface, so PySide6 and
+  # the visualization stack are required dependencies.
+  "PySide6>=6.6",
+  "pyqtgraph>=0.14",
+  "vispy>=0.14"
+]
+
+[project.optional-dependencies]
+build = [
+  "PyInstaller>=6.11"
+]
+docs = [
+  "sphinx>=8.2",
+  "pydata-sphinx-theme>=0.16",
+  "myst-parser>=3.0"
+]
+# Developer/maintainer extras — packaging tools + Sphinx for the docs.
+# Regular end users do not need this.
+all = [
+  "PyInstaller>=6.11",
+  "sphinx>=8.2",
+  "pydata-sphinx-theme>=0.16",
+  "myst-parser>=3.0"
+]
+
+[project.scripts]
+swcstudio = "swcstudio.cli.cli:main"
+swcstudio-gui = "swcstudio.gui.main:main"
+
+[tool.setuptools.packages.find]
+include = ["swcstudio*"]
+
+# Pattern B: lean wheel, models downloaded on first use.
+# Setuptools defaults to auto-including any non-Python file inside a
+# package directory as package-data ("include-package-data = true").
+# We opt out so the model pickles don't end up in the wheel.
+[tool.setuptools]
+include-package-data = false
+
+[tool.setuptools.package-data]
+# With include-package-data = false above, this empty mapping is the
+# only source of truth: no extra data files ship in the wheel.
+# Models are downloaded from GitHub Releases on first use by
+# swcstudio.core.updater. The bundled .app distribution still ships
+# models inside the bundle (see packaging/MODULAR_BUILD.md).
+"swcstudio" = []
+
+[tool.setuptools.exclude-package-data]
+# Belt-and-suspenders: even if some path drags model files in via
+# auto-discovery, this explicitly excludes them from the wheel.
+"swcstudio" = ["data/models/*"]

swcstudio-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

swcstudio-0.2.0/swcstudio/__init__.py

@@ -0,0 +1,19 @@
+"""swcstudio package entrypoint.
+
+Layers:
+- swcstudio.core: shared algorithm/data logic
+- swcstudio.tools: tool + feature modules
+- swcstudio.api: public Python API
+- swcstudio.cli: terminal interface
+- swcstudio.gui: desktop GUI interface
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("swcstudio")
+except PackageNotFoundError:
+    # Local source checkout before installation.
+    __version__ = "0.1.0"
+
+__all__ = ["api", "core", "tools", "plugins", "cli", "gui", "__version__"]

swcstudio-0.2.0/swcstudio/api.py

@@ -0,0 +1,130 @@
+"""Public library API for swcstudio.
+
+All interfaces (GUI, CLI, and external Python callers) should import these
+functions or the corresponding tool/feature modules.
+"""
+
+from __future__ import annotations
+
+from swcstudio.core.auto_typing import BatchOptions
+from swcstudio.plugins import (
+    autoload_plugins_from_environment,
+    get_plugin,
+    list_all_feature_methods,
+    list_feature_methods,
+    list_plugins,
+    load_plugin_module,
+    load_plugins,
+    register_method,
+    register_plugin_manifest,
+    register_plugin_method,
+    unregister_method,
+    unregister_plugin,
+)
+from swcstudio.tools.batch_processing.features.auto_typing import run_folder as batch_auto_typing
+from swcstudio.tools.batch_processing.features.index_clean import run_folder as batch_index_clean_folder
+from swcstudio.tools.batch_processing.features.simplification import (
+    run_folder as batch_simplify_folder,
+)
+from swcstudio.tools.batch_processing.features.batch_validation import (
+    validate_folder as batch_validate_folder,
+)
+from swcstudio.tools.batch_processing.features.radii_cleaning import (
+    clean_folder as batch_radii_cleaning,
+    clean_path as radii_clean_path,
+)
+from swcstudio.tools.batch_processing.features.swc_splitter import (
+    split_folder as batch_split_folder,
+)
+from swcstudio.tools.geometry_editing.features.operations import (
+    disconnect_branch as geometry_disconnect_branch,
+    delete_node as geometry_delete_node,
+    delete_subtree as geometry_delete_subtree,
+    insert_node_between as geometry_insert_node_between,
+    move_node_absolute as geometry_move_node_absolute,
+    move_subtree_absolute as geometry_move_subtree_absolute,
+    reconnect_branch as geometry_reconnect_branch,
+    reindex_dataframe_with_map as geometry_reindex_dataframe_with_map,
+)
+from swcstudio.tools.morphology_editing.features.dendrogram_editing import (
+    reassign_subtree_types,
+    reassign_subtree_types_in_file,
+)
+from swcstudio.tools.morphology_editing.features.manual_label import (
+    set_node_type_file as morphology_set_node_type_file,
+    set_node_type_text as morphology_set_node_type_text,
+)
+from swcstudio.tools.morphology_editing.features.manual_radii import (
+    set_node_radius_file as morphology_set_node_radius_file,
+    set_node_radius_text as morphology_set_node_radius_text,
+)
+from swcstudio.tools.morphology_editing.features.simplification import (
+    simplify_file as morphology_smart_decimation_file,
+    simplify_swc_text as morphology_smart_decimation_text,
+)
+from swcstudio.tools.validation.features.auto_fix import auto_fix_file, auto_fix_text
+from swcstudio.tools.validation.features.index_clean import (
+    index_clean_file as validation_index_clean_file,
+    index_clean_text as validation_index_clean_text,
+)
+from swcstudio.tools.validation.features.auto_typing import (
+    auto_label_file as validation_auto_label_file,
+    run_file as validation_auto_typing_file,
+)
+from swcstudio.tools.validation.features.run_checks import (
+    validate_file as validation_run_file,
+    validate_text as validation_run_text,
+)
+from swcstudio.tools.visualization.features.mesh_editing import (
+    build_mesh_from_file,
+    build_mesh_from_text,
+)
+
+__all__ = [
+    "BatchOptions",
+    "batch_validate_folder",
+    "batch_split_folder",
+    "batch_auto_typing",
+    "batch_simplify_folder",
+    "batch_index_clean_folder",
+    "batch_radii_cleaning",
+    "radii_clean_path",
+    "auto_fix_text",
+    "auto_fix_file",
+    "validation_index_clean_text",
+    "validation_index_clean_file",
+    "validation_auto_typing_file",
+    "validation_run_text",
+    "validation_run_file",
+    "build_mesh_from_text",
+    "build_mesh_from_file",
+    "reassign_subtree_types",
+    "reassign_subtree_types_in_file",
+    "morphology_set_node_type_text",
+    "morphology_set_node_type_file",
+    "morphology_set_node_radius_text",
+    "morphology_set_node_radius_file",
+    "validation_auto_label_file",
+    "morphology_smart_decimation_text",
+    "morphology_smart_decimation_file",
+    "geometry_move_node_absolute",
+    "geometry_move_subtree_absolute",
+    "geometry_reconnect_branch",
+    "geometry_disconnect_branch",
+    "geometry_delete_node",
+    "geometry_delete_subtree",
+    "geometry_insert_node_between",
+    "geometry_reindex_dataframe_with_map",
+    "load_plugin_module",
+    "load_plugins",
+    "autoload_plugins_from_environment",
+    "register_plugin_manifest",
+    "register_plugin_method",
+    "unregister_plugin",
+    "list_plugins",
+    "get_plugin",
+    "register_method",
+    "unregister_method",
+    "list_feature_methods",
+    "list_all_feature_methods",
+]

swcstudio-0.2.0/swcstudio/cli/__init__.py

@@ -0,0 +1,3 @@
+"""CLI package for swcstudio."""
+
+__all__ = ["cli"]