Module Reference#

This section covers backend modules by subsystem for developers.

Core Modules#

Feature config JSON helpers.

Each feature keeps a JSON file under:

swcstudio/tools/<tool>/configs/<feature>.json

swcstudio.core.config.merge_config(base, overrides)[source]#

Recursively merge config dictionaries without mutating inputs.

Parameters:

  • base (dict[str, Any])

  • overrides (dict[str, Any] | None)

Return type:

dict[str, Any]

Shared text report builders and file writers.

All interfaces (CLI + GUI) should use these helpers so generated log text stays consistent regardless of entry point.

Shared validation engine.

swcstudio.core.validation_engine.consolidate_complex_somas_array(arr)[source]#

Collapse connected soma groups without renumbering surviving node IDs.

Each connected type-1 soma component is reduced to one anchor soma node with updated centroid/radius. Non-anchor soma nodes are removed, and any child that pointed to a removed soma node is rewired to the surviving anchor ID. Surviving node IDs are preserved; no global reindexing is performed here.

Parameters:

arr (ndarray)

Return type:

dict[str, Any]

Structured validation result models.

class swcstudio.core.validation_results.PreCheckItem(key: 'str', label: 'str', source: 'str', severity: 'Severity', params: 'dict[str, Any]'=<factory>, enabled: 'bool' = True)[source]#

Bases: object

Parameters:

  • key (str)

  • label (str)

  • source (str)

  • severity (str)

  • params (dict[str, Any])

  • enabled (bool)

class swcstudio.core.validation_results.CheckResult(key: 'str', label: 'str', passed: 'bool', severity: 'Severity', message: 'str', failing_node_ids: 'list[int]' = <factory>, failing_section_ids: 'list[int]' = <factory>, metrics: 'dict[str, Any]'=<factory>, source: 'str' = 'native', params_used: 'dict[str, Any]'=<factory>, thresholds_used: 'dict[str, Any]'=<factory>, status: 'Status' = 'pass')[source]#

Bases: object

Parameters:

  • key (str)

  • label (str)

  • passed (bool)

  • severity (str)

  • message (str)

  • failing_node_ids (list[int])

  • failing_section_ids (list[int])

  • metrics (dict[str, Any])

  • source (str)

  • params_used (dict[str, Any])

  • thresholds_used (dict[str, Any])

  • status (str)

class swcstudio.core.validation_results.ValidationReport(profile: 'str', precheck: 'list[PreCheckItem]' = <factory>, results: 'list[CheckResult]' = <factory>)[source]#

Bases: object

Parameters:

Validation check registry.

class swcstudio.core.validation_registry.CheckDefinition(key: 'str', label: 'str', source: 'str', runner: 'ValidationCheckCallable')[source]#

Bases: object

Parameters:

  • key (str)

  • label (str)

  • source (str)

  • runner (Callable[[Any, dict[str, Any]], Any])

swcstudio.core.validation_registry.register_plugin_check(*, key, label, runner)[source]#

Register custom user-defined checks in the shared validation registry.

Parameters:

  • key (str)

  • label (str)

  • runner (Callable[[Any, dict[str, Any]], Any])

Return type:

None

Shared validation label/category catalog used by GUI and CLI.

Auto-typing / rule-batch implementation moved to core.

This module contains the rule-based auto-typing logic formerly located in swcstudio.gui.rule_batch_processor. It is kept in swcstudio.core so both GUI and CLI can use the same implementation.

swcstudio.core.auto_typing_impl.get_config()[source]#

Return the active configuration dict (loaded from JSON if available).

Return type:

dict

swcstudio.core.auto_typing_impl.save_config(cfg)[source]#

Save rule settings into the batch auto-typing feature config.

Parameters:

cfg (dict)

Return type:

None

class swcstudio.core.auto_typing_impl.RuleBatchOptions(soma: 'bool' = False, axon: 'bool' = False, apic: 'bool' = False, basal: 'bool' = False, rad: 'bool' = False, zip_output: 'bool' = False)[source]#

Bases: object

Parameters:

  • soma (bool)

  • axon (bool)

  • apic (bool)

  • basal (bool)

  • rad (bool)

  • zip_output (bool)

class swcstudio.core.auto_typing_impl.RuleBatchResult(folder: 'str', out_dir: 'str', zip_path: 'str | None', files_total: 'int', files_processed: 'int', files_failed: 'int', total_nodes: 'int', total_type_changes: 'int', total_radius_changes: 'int', failures: 'list[str]', per_file: 'list[str]', log_path: 'str | None')[source]#

Bases: object

Parameters:

  • folder (str)

  • out_dir (str)

  • zip_path (str | None)

  • files_total (int)

  • files_processed (int)

  • files_failed (int)

  • total_nodes (int)

  • total_type_changes (int)

  • total_radius_changes (int)

  • failures (list[str])

  • per_file (list[str])

  • log_path (str | None)

class swcstudio.core.auto_typing_impl.RuleFileResult(input_file: 'str', output_file: 'str | None', nodes_total: 'int', type_changes: 'int', radius_changes: 'int', out_type_counts: 'dict[int, int]', failures: 'list[str]', change_details: 'list[str]', log_path: 'str | None', headers: 'list[str]', rows: 'list[dict[str, Any]]', types: 'list[int]', radii: 'list[float]')[source]#

Bases: object

Parameters:

  • input_file (str)

  • output_file (str | None)

  • nodes_total (int)

  • type_changes (int)

  • radius_changes (int)

  • out_type_counts (dict[int, int])

  • failures (list[str])

  • change_details (list[str])

  • log_path (str | None)

  • headers (list[str])

  • rows (list[dict[str, Any]])

  • types (list[int])

  • radii (list[float])

Tool Feature Modules#

Batch Processing#

Batch validation feature for Batch Processing.

SWC splitter feature for Batch Processing.

Auto typing feature for Batch Processing.

Radii cleaning feature for Batch Processing.

This module is the shared backend used by: - Batch GUI radii cleaning tab - Validation GUI radii cleaning tab - CLI batch/validation radii-clean commands

Validation#

Structured validation runner feature.

Auto-fix validation feature.

This feature runs the shared validation backend and returns the sanitized SWC content that can be written back to disk.

Single-file auto typing for Validation tool.

Uses the same core rule engine and JSON config as Batch Processing -> Auto Typing.

Validation radii-cleaning feature.

This is a thin wrapper over the shared Batch Processing radii-clean backend so GUI/CLI/Validation all use exactly the same cleaning implementation.

Visualization#

Mesh editing feature backend.

This module provides a reusable backend payload that both GUI and CLI can use for mesh-related operations without duplicating parsing logic.

Morphology Editing#

Dendrogram editing backend utilities.

Provides data-level operations used by interactive dendrogram editors.

Smart decimation wrapper for morphology editing.

Plugin System Internals#

Plugin contract models for swcstudio.

This module defines a minimal, versioned contract for external plugins.

class swcstudio.plugins.contracts.PluginManifest(plugin_id, name, version, api_version='1', description='', author='', capabilities=(), entrypoint='')[source]#

Bases: object

Structured plugin metadata required by the swcstudio plugin loader.

Parameters:

  • plugin_id (str)

  • name (str)

  • version (str)

  • api_version (str)

  • description (str)

  • author (str)

  • capabilities (tuple[str, ...])

  • entrypoint (str)

swcstudio.plugins.contracts.parse_plugin_manifest(raw)[source]#

Validate and normalize a plugin manifest dictionary.

Parameters:

raw (dict[str, Any])

Return type:

PluginManifest

swcstudio.plugins.contracts.plugin_manifest_to_dict(manifest)[source]#

Serialize a PluginManifest into JSON-friendly dictionary.

Parameters:

manifest (PluginManifest)

Return type:

dict[str, Any]

Dynamic plugin loader for swcstudio.

class swcstudio.plugins.loader.PluginRegistrar(plugin_id)[source]#

Bases: object

Registrar object passed to external plugins during registration.

Parameters:

plugin_id (str)

swcstudio.plugins.loader.load_plugin_module(module_name, *, force_reload=False)[source]#

Load one plugin module and register its methods.

Expected plugin contract: 1) PLUGIN_MANIFEST dict (or get_plugin_manifest()) 2) register_plugin(registrar) function OR PLUGIN_METHODS attribute

Parameters:

  • module_name (str)

  • force_reload (bool)

Return type:

dict[str, Any]

swcstudio.plugins.loader.load_plugins(modules)[source]#

Load multiple plugin modules and return per-module results.

Parameters:

modules (Iterable[str])

Return type:

list[dict[str, Any]]

swcstudio.plugins.loader.autoload_plugins_from_environment(env_var='SWCSTUDIO_PLUGINS')[source]#

Autoload plugin modules from comma-separated environment variable.

Parameters:

env_var (str)

Return type:

list[dict[str, Any]]

Plugin registry for swcstudio.

Supports: 1) Legacy flat keys (register(“name”, func) / get(“name”)) 2) Feature method keys (register_method(“tool.feature”, “method_name”, func)) 3) Plugin-aware registration with versioned manifest metadata

The feature-based API is preferred for modular override of algorithms used by CLI and GUI layers.

swcstudio.plugins.registry.register(name, func)[source]#

Register a callable under a flat legacy key.

Parameters:

  • name (str)

  • func (Callable)

Return type:

None

swcstudio.plugins.registry.get(name)[source]#

Retrieve a flat legacy callable or None.

Parameters:

name (str)

Return type:

Callable | None

swcstudio.plugins.registry.clear()[source]#

Clear all registry content (legacy + feature methods).

Return type:

None

swcstudio.plugins.registry.register_builtin_method(feature_key, method_name, func)[source]#

Register an internal builtin method for a feature.

Parameters:

  • feature_key (str)

  • method_name (str)

  • func (Callable)

Return type:

None

swcstudio.plugins.registry.register_plugin_manifest(manifest)[source]#

Register and validate a plugin manifest.

Parameters:

manifest (PluginManifest | dict[str, Any])

Return type:

PluginManifest

swcstudio.plugins.registry.unregister_plugin(plugin_id)[source]#

Remove plugin manifest and all methods owned by this plugin.

Parameters:

plugin_id (str)

Return type:

None

swcstudio.plugins.registry.register_plugin_method(plugin_id, feature_key, method_name, func)[source]#

Register a feature method owned by a named plugin.

Parameters:

  • plugin_id (str)

  • feature_key (str)

  • method_name (str)

  • func (Callable)

Return type:

None

swcstudio.plugins.registry.register_method(feature_key, method_name, func, *, plugin_id=None)[source]#

Register a user/plugin method that overrides builtins with same name.

Parameters:

  • feature_key (str)

  • method_name (str)

  • func (Callable)

  • plugin_id (str | None)

Return type:

None

swcstudio.plugins.registry.resolve_method(feature_key, method_name, fallback=None)[source]#

Resolve method by priority: plugin override -> builtin -> fallback.

Parameters:

  • feature_key (str)

  • method_name (str)

  • fallback (Callable | None)

Return type:

Callable

swcstudio.plugins.registry.list_feature_methods(feature_key)[source]#

Return plugin + builtin method names for a feature.

Parameters:

feature_key (str)

Return type:

dict

swcstudio.plugins.registry.list_all_feature_methods()[source]#

Return all feature method registrations.

Return type:

dict

swcstudio.plugins.registry.list_plugins()[source]#

Return registered plugin manifests.

Return type:

list[dict[str, Any]]

swcstudio.plugins.registry.get_plugin(plugin_id)[source]#

Return one plugin manifest as dictionary.

Parameters:

plugin_id (str)

Return type:

dict[str, Any] | None