API Reference

Public API

swctools package scaffolding.

Public API is evolving; currently exposes SWC parsing, models, geometry, and visualization utilities.

class swctools.SWCRecord(n: int, t: int, x: float, y: float, z: float, r: float, parent: int, line: int)

Bases: object

One SWC row.

n

Node id (unique within file)

Type:

int

t

Tag index

Type:

int

x, y, z

Coordinates (usually micrometers)

Type:

float

r

Radius

Type:

float

parent

Parent id; -1 indicates root

Type:

int

line

1-based line number in the source file/string

Type:

int

n: int

t: int

x: float

y: float

z: float

r: float

parent: int

line: int

__init__(n: int, t: int, x: float, y: float, z: float, r: float, parent: int, line: int) → None

class swctools.SWCParseResult(records: Dict[int, SWCRecord], reconnections: List[Tuple[int, int]], header: List[str])

Bases: object

Parsed SWC content.

records: Dict[int, SWCRecord]

reconnections: List[Tuple[int, int]]

header: List[str]

__init__(records: Dict[int, SWCRecord], reconnections: List[Tuple[int, int]], header: List[str]) → None

swctools.parse_swc(source: str | PathLike | Iterable[str] | TextIOBase, *, strict: bool = True, validate_reconnections: bool = True, float_tol: float = 1e-09) → SWCParseResult

Parse an SWC file or text stream.

Parameters:

• source – Path to an SWC file, a file-like object, an iterable of lines, or a string containing SWC content.

• strict – If True, enforce 7-column rows and validate parent references exist.

• validate_reconnections – If True, ensure reconnection node pairs share identical (x, y, z, r).

• float_tol – Tolerance used when comparing floating-point coordinates/radii.

Returns:

Parsed records, reconnection pairs, and header lines.

Return type:

SWCParseResult

Raises:

• ValueError – If parsing or validation fails.

• FileNotFoundError – If a string path is provided that does not exist.

class swctools.SWCModel(*args, backend=None, **kwargs)

Bases: DiGraph

SWC morphology graph representing a valid directed tree structure.

SWCModel conforms to the SWC format specification, which requires a directed tree structure (no cycles). The underlying storage is a directed nx.DiGraph that preserves the original parent -> child relationships from the SWC format.

Nodes are keyed by SWC id n and store attributes: - t: int (tag) - x, y, z: float (coordinates) - r: float (radius) - line: int (line number in source; informational)

For graphs with cycles (e.g., after applying reconnections), use make_cycle_connections() which returns a standard nx.Graph instead of SWCModel.

Methods like to_swc_file() rely on the tree structure and will only work correctly for valid SWC trees.

__init__() → None

Initialize a graph with edges, name, or graph attributes.

Parameters:

• incoming_graph_data (input graph (optional, default: None)) – Data to initialize graph. If None (default) an empty graph is created. The data can be an edge list, or any NetworkX graph object. If the corresponding optional Python packages are installed the data can also be a 2D NumPy array, a SciPy sparse array, or a PyGraphviz graph.

• attr (keyword arguments, optional (default= no attributes)) – Attributes to add to graph as key=value pairs.

See also

convert

Examples

>>> G = nx.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G = nx.Graph(name="my graph")
>>> e = [(1, 2), (2, 3), (3, 4)]  # list of edges
>>> G = nx.Graph(e)

Arbitrary graph attribute pairs (key=value) may be assigned

>>> G = nx.Graph(e, day="Friday")
>>> G.graph
{'day': 'Friday'}

classmethod from_parse_result(result: SWCParseResult) → SWCModel

Build a model from a parsed SWC result.

classmethod from_records(records: Mapping[int, SWCRecord] | Iterable[SWCRecord]) → SWCModel

Build a model from SWC records.

Accepts either a mapping of id->record or any iterable of SWCRecord.

classmethod from_swc_file(source: str | PathLike[str] | Iterable[str], *, strict: bool = True, validate_reconnections: bool = True, float_tol: float = 1e-09) → SWCModel

Parse an SWC source then build a model.

The source is passed through to parse_swc, which supports a path, a file-like object, a string with the full contents, or an iterable of lines.

roots() → list[int]

Return nodes with no parent in the original SWC tree.

parent_of(n: int) → int | None

Return the parent id of node n from the original SWC tree (or None).

children_of(node_id: int) → list[int]

Return list of child node IDs in the original SWC tree.

Parameters:

node_id (int) – Node ID to query.

Returns:

List of node IDs that have node_id as their parent.

Return type:

list[int]

path_to_root(n: int) → list[int]

Return the path from node n up to its root, inclusive.

Example: For edges 1->2->3, path_to_root(3) returns [3, 2, 1].

get_node_xyz(node_id: int, as_array: bool = False) → tuple[float, float, float] | ndarray

Get xyz coordinates for a node.

Parameters:

• node_id (int) – Node ID to query.

• as_array (bool) – If True, return as numpy array. If False (default), return as tuple.

Returns:

The (x, y, z) coordinates of the node.

Return type:

tuple[float, float, float] | np.ndarray

Raises:

• KeyError – If node_id is not in the graph.

• ValueError – If the node is missing x, y, or z attributes.

get_node_radius(node_id: int) → float

Get radius for a node.

Parameters:

node_id (int) – Node ID to query.

Returns:

The radius of the node. Returns 0.0 if ‘r’ attribute is not present.

Return type:

float

Raises:

KeyError – If node_id is not in the graph.

set_node_xyz(node_id: int, x: float | None = None, y: float | None = None, z: float | None = None, *, xyz: tuple[float, float, float] | list[float] | ndarray | None = None) → None

Set xyz coordinates for a node.

Parameters:

• node_id (int) – Node ID to update.

• x (float | None) – New coordinates as separate arguments.

• y (float | None) – New coordinates as separate arguments.

• z (float | None) – New coordinates as separate arguments.

• xyz (tuple | list | np.ndarray | None) – New coordinates as a sequence (x, y, z). If provided, takes precedence over separate x, y, z arguments.

Raises:

• KeyError – If node_id is not in the graph.

• ValueError – If neither (x, y, z) nor xyz is provided, or if xyz has wrong length.

set_node_radius(node_id: int, radius: float) → None

Set radius for a node.

Parameters:

• node_id (int) – Node ID to update.

• radius (float) – New radius value.

Raises:

KeyError – If node_id is not in the graph.

get_node_tag(node_id: int) → int

Get tag for a node.

Parameters:

node_id (int) – Node ID to query.

Returns:

The tag of the node. Returns 0 if ‘t’ attribute is not present.

Return type:

int

Raises:

KeyError – If node_id is not in the graph.

set_node_tag(node_id: int, tag: int) → None

Set tag for a node.

Parameters:

• node_id (int) – Node ID to update.

• tag (int) – New tag value.

Raises:

KeyError – If node_id is not in the graph.

get_edge_length(u: int, v: int) → float

Compute Euclidean distance between two nodes.

Parameters:

• u (int) – Node IDs. They do not need to be connected by an edge.

• v (int) – Node IDs. They do not need to be connected by an edge.

Returns:

Euclidean distance between the nodes.

Return type:

float

Raises:

• KeyError – If either node is not in the graph.

• ValueError – If either node is missing coordinate attributes.

update_radii(radii_dict: dict[int, float]) → None

Update radii for multiple nodes at once.

Parameters:

radii_dict (dict[int, float]) – Mapping of node_id -> new radius value.

Raises:

KeyError – If any node_id is not in the graph.

update_tags(tags_dict: dict[int, int]) → None

Update tags for multiple nodes at once.

Parameters:

tags_dict (dict[int, int]) – Mapping of node_id -> new tag value.

Raises:

KeyError – If any node_id is not in the graph.

leaves() → list[int]

Return leaf nodes (nodes with no children in the original SWC tree).

Returns:

List of node IDs that have no children.

Return type:

list[int]

branch_points() → list[int]

Return branch point nodes (nodes with more than one child).

Returns:

List of node IDs with out-degree > 1 (branch points in the directed tree).

Return type:

list[int]

get_subtree(root_id: int) → list[int]

Return all node IDs in the subtree rooted at root_id.

Uses the original SWC tree parent relationships to traverse descendants.

Parameters:

root_id (int) – Root node of the subtree.

Returns:

List of all node IDs in the subtree, including root_id.

Return type:

list[int]

Raises:

KeyError – If root_id is not in the graph.

iter_edges_with_data()

Iterate edges with node attributes for both endpoints.

Yields:

tuple[int, int, dict] – For each edge (u, v), yields (u, v, data_dict) where data_dict contains: - ‘u_xyz’: tuple of (x, y, z) for node u - ‘v_xyz’: tuple of (x, y, z) for node v - ‘u_r’: radius of node u - ‘v_r’: radius of node v - ‘u_t’: tag of node u - ‘v_t’: tag of node v - ‘length’: Euclidean distance between u and v

validate(strict: bool = True) → list[str]

Validate the model and return list of issues found.

Parameters:

strict (bool) – If True, perform stricter validation checks.

Returns:

List of validation issue descriptions. Empty list if no issues found.

Return type:

list[str]

print_attributes(*, node_info: bool = False, edge_info: bool = False) → None

Print graph attributes and optional node/edge details.

Parameters:

• node_info (bool) – If True, print per-node attributes (t, x, y, z, r, line where present).

• edge_info (bool) – If True, print all edges (u – v) with edge attributes if any.

copy() → SWCModel

Return a shallow copy of this model (nodes/edges/attributes).

to_swc_file(path: str | PathLike[str], *, precision: int = 6, header: Iterable[str] | None = None) → None

Write the model to an SWC file.

The output uses the standard 7-column SWC format per row: “n T x y z r parent” with floats formatted to the requested precision.

Parameters:

• path (str | os.PathLike[str]) – Destination file path.

• precision (int) – Decimal places for floating-point fields (x, y, z, r). Default 6.

• header (Iterable[str] | None) – Optional additional header comment lines (without leading ‘#’).

scale(scalar: float) → SWCModel

Return a new model with all node coordinates and radii scaled by scalar.

Multiplies each node’s x, y, z, and r by scalar on a copy.

set_tag_by_sphere(center: tuple[float, float, float] | list[float], radius: float, new_tag: int, old_tag: int | None = None, include_boundary: bool = True, copy: bool = False) → SWCModel

Override node ‘t’ values for points inside a sphere.

Sets the tag ‘t’ for all nodes whose Euclidean distance from center is less than radius (or equal if include_boundary is True).

If old_tag is specified, only nodes with that tag are modified.

Parameters:

• center (tuple[float, float, float] | list[float]) – Sphere center as (x, y, z).

• radius (float) – Sphere radius (same units as coordinates).

• new_tag (int) – Tag to assign to matching nodes.

• old_tag (int | None) – If specified, only nodes with this tag are modified.

• include_boundary (bool) – If True, include nodes exactly at distance == radius. Default True.

• copy (bool) – If True, operate on and return a copy; otherwise mutate in place and return self.

add_junction(node_id: int | None = None, *, t: int = 0, x: float = 0.0, y: float = 0.0, z: float = 0.0, r: float = 0.0, parent: int | None = None, **kwargs: Any) → int

Add a junction (node) to the model.

Parameters:

• node_id (int | None) – Node ID to use. If None, automatically assigns the next available ID.

• t (int) – Node tag. Default 0.

• x (float) – Node coordinates. Default 0.0.

• y (float) – Node coordinates. Default 0.0.

• z (float) – Node coordinates. Default 0.0.

• r (float) – Node radius. Default 0.0.

• parent (int | None) – Parent node ID. If specified, creates an edge to the parent. Default None (root node).

• **kwargs (Any) – Additional node attributes.

Returns:

The ID of the added node.

Return type:

int

remove_junction(node_id: int, *, reconnect_children: bool = False) → None

Remove a junction (node) from the model.

Parameters:

• node_id (int) – ID of the node to remove.

• reconnect_children (bool) – If True, reconnect children of the removed node to its parent. If False (default), children become orphaned (roots).

make_cycle_connections(*, validate_reconnections: bool = True, float_tol: float = 1e-09) → Graph

Return an undirected nx.Graph with reconnection pairs merged.

Uses reconnection pairs stored under self.graph[‘reconnections’] if present. Node attributes are merged; provenance kept under merged_ids and lines.

The returned graph may contain cycles and is no longer a valid SWC tree structure, so it returns nx.Graph instead of SWCModel. SWCModel should only represent valid directed tree structures conforming to the SWC format.

Returns:

Undirected graph with merged nodes and edges. Node attributes include x, y, z, r, t, merged_ids (list of original node IDs), and lines.

Return type:

nx.Graph

class swctools.Frustum(a: Tuple[float, float, float], b: Tuple[float, float, float], ra: float, rb: float, tag: int = 0)

Bases: object

Oriented frustum between endpoints a and b.

a, b

Endpoints in model/world coordinates.

Type:

Point3

ra, rb

Radii at a and b.

Type:

float

tag

Optional tag for the frustum.

Type:

int

a: Tuple[float, float, float]

b: Tuple[float, float, float]

ra: float

rb: float

tag: int = 0

vector() → Tuple[float, float, float]

length() → float

midpoint() → Tuple[float, float, float]

scale(scalar: float) → Frustum

Return a new Frustum uniformly scaled by scalar (positions and radii).

__init__(a: Tuple[float, float, float], b: Tuple[float, float, float], ra: float, rb: float, tag: int = 0) → None

swctools.frustum_mesh(seg: Frustum, *, sides: int = 16, end_caps: bool = False) → Tuple[List[Tuple[float, float, float]], List[Tuple[int, int, int]]]

Generate a frustum mesh for a single Frustum.

Returns:

• vertices: List[Point3]

• faces: List[Face], each = (i, j, k) indexing into vertices

Return type:

(vertices, faces)

swctools.batch_frusta(frusta: Iterable[Frustum], *, sides: int = 16, end_caps: bool = False) → Tuple[List[Tuple[float, float, float]], List[Tuple[int, int, int]]]

Batch multiple frusta into a single mesh.

Returns a concatenated list of vertices and faces with the proper index offsets.

class swctools.PointSet(vertices: List[Tuple[float, float, float]], faces: List[Tuple[int, int, int]], points: List[Tuple[float, float, float]], base_radius: float, stacks: int, slices: int)

Bases: object

A batched mesh of small spheres placed at given 3D points.

vertices: List[Tuple[float, float, float]]

faces: List[Tuple[int, int, int]]

points: List[Tuple[float, float, float]]

base_radius: float

stacks: int

slices: int

classmethod from_points(points: Sequence[Tuple[float, float, float]], *, base_radius: float = 1.0, stacks: int = 6, slices: int = 12) → PointSet

Build a batched low-res spheres mesh from a list of 3D points.

Parameters:

• points (sequence of (x, y, z)) – Sphere centers.

• base_radius (float) – Sphere radius used when building the mesh (scaled later via scaled()).

• stacks (int) – Sphere tessellation parameters (>=2 and >=3 respectively).

• slices (int) – Sphere tessellation parameters (>=2 and >=3 respectively).

classmethod from_txt_file(path: str | PathLike, *, base_radius: float = 1.0, stacks: int = 6, slices: int = 12, comments: str = '#') → PointSet

to_mesh3d_arrays() → Tuple[List[float], List[float], List[float], List[int], List[int], List[int]]

Return Plotly Mesh3d arrays (x, y, z, i, j, k) for this point set.

to_txt_file(path: str | PathLike) → None

scaled(radius_scale: float) → PointSet

Return a new PointSet with all sphere radii scaled by radius_scale.

scale(scalar: float) → PointSet

Return a new PointSet with coordinates and radii scaled by scalar.

project_onto_frusta(frusta: FrustaSet, include_end_caps: bool | None = None) → PointSet

Project each point to the nearest surface of the nearest frustum.

Parameters:

• frusta (FrustaSet) – Set of oriented frusta (as `Frustum`s) to project onto.

• include_end_caps (Optional[bool]) – If None (default), follow frusta.end_caps. If True/False, explicitly include or ignore projections to the circular end caps.

Returns:

A new PointSet whose points have been moved onto the closest surface points of the closest frusta; sphere mesh is rebuilt.

Return type:

PointSet

Notes

For each input point, the algorithm iterates all frusta and evaluates the squared distance to: - The lateral surface: project the point to the frustum axis (clamped

t in [0,1]), interpolate radius r(t), then move along the radial direction to the mantle.

• The end caps (optional): orthogonal distance to each cap plane; if the projected point falls outside the disk, distance to the rim is used.

Degenerate frusta (zero length) are treated as a sphere of radius max(ra, rb) centered at the endpoint. Complexity is O(N_points × N_frusta), implemented in pure Python.

__init__(vertices: List[Tuple[float, float, float]], faces: List[Tuple[int, int, int]], points: List[Tuple[float, float, float]], base_radius: float, stacks: int, slices: int) → None

class swctools.FrustaSet(vertices: List[Tuple[float, float, float]], faces: List[Tuple[int, int, int]], sides: int, end_caps: bool, n_frusta: int, frusta: List[Frustum], edge_uvs: List[Tuple[int, int]] | None = None)

Bases: object

A batched frusta mesh derived from a SWCModel.

vertices

Concatenated vertices for all frusta.

Type:

List[Point3]

faces

Triangular faces indexing into vertices.

Type:

List[Face]

sides

Circumferential resolution used per frustum.

Type:

int

end_caps

Whether end caps were included during construction.

Type:

bool

n_frusta

Number of frusta used (one per graph edge).

Type:

int

frusta

The frusta used to construct the mesh (stored as axis `Frustum`s).

Type:

List[Frustum]

edge_uvs

Optional labels preserving which (u, v) edge generated each frustum, in the same order.

Type:

Optional[List[Tuple[int, int]]]

vertices: List[Tuple[float, float, float]]

faces: List[Tuple[int, int, int]]

sides: int

end_caps: bool

n_frusta: int

frusta: List[Frustum]

edge_uvs: List[Tuple[int, int]] | None = None

classmethod from_swc_file(swc_file: str | PathLike[str], *, sides: int = 16, end_caps: bool = False, flip_tag_assignment: bool = False, **kwargs: Any) → FrustaSet

classmethod from_swc_model(model: SWCModel | Any, *, sides: int = 16, end_caps: bool = False, flip_tag_assignment: bool = False) → FrustaSet

Build a FrustaSet by converting each undirected edge into a frustum axis Frustum.

Accepts any NetworkX graph (SWCModel or nx.Graph) with nodes that have spatial coordinates and radii. Validates that all nodes have required attributes: x, y, z, r.

Parameters:

• model (SWCModel | nx.Graph) – Graph with nodes containing x, y, z, r attributes. Can be SWCModel or nx.Graph (e.g., from make_cycle_connections()).

• sides (int) – Number of sides per frustum.

• end_caps (bool) – Whether to include end caps.

• flip_tag_assignment (bool) – If True, assign tags from the child node to the parent node. Otherwise, assign tags from the parent node to the child node.

Raises:

ValueError – If any node is missing required attributes (x, y, z, r).

to_mesh3d_arrays() → Tuple[List[float], List[float], List[float], List[int], List[int], List[int]]

Return Plotly Mesh3d arrays: x, y, z, i, j, k.

scaled(radius_scale: float) → FrustaSet

Return a new FrustaSet with all frustum radii scaled by radius_scale.

This rebuilds vertices/faces from the stored frusta list.

scale(scalar: float) → FrustaSet

Return a new FrustaSet with coordinates and radii scaled by scalar.

nearest_frustum_index(xyz: Sequence[float]) → int

Return the index of the frustum whose axis is closest to xyz.

frustum_order_map() → dict[int, tuple[int, int] | tuple[Tuple[float, float, float], Tuple[float, float, float]]]

reordered(new_order: Sequence[int] | None = None, *, label_remap: Mapping[Tuple[int, int], int] | None = None) → FrustaSet

Return a new set with frusta reordered by index or (u, v) label mapping.

frustum_face_slices_map() → dict[int, tuple[int, int]]

frustum_axis_midpoints() → dict[int, Tuple[float, float, float]]

__init__(vertices: List[Tuple[float, float, float]], faces: List[Tuple[int, int, int]], sides: int, end_caps: bool, n_frusta: int, frusta: List[Frustum], edge_uvs: List[Tuple[int, int]] | None = None) → None

swctools.plot_centroid(swc_model: SWCModel, *, marker_size: float = 2.0, line_width: float = 2.0, show_nodes: bool = True, title: str | None = None, width: int = 1200, height: int = 900) → Figure

Plot centroid skeleton from an SWCModel.

Edges are drawn as line segments in 3D using Scatter3d.

Parameters:

• width (int) – Figure width in pixels (default: 1200).

• height (int) – Figure height in pixels (default: 900).

swctools.plot_frusta(frusta: FrustaSet, *, color: str = 'lightblue', opacity: float = 0.8, flatshading: bool = True, radius_scale: float = 1.0, tag_colors: dict[int, str] | None = None, title: str | None = None, width: int = 1200, height: int = 900) → Figure

Plot a FrustaSet as a Mesh3d figure.

Parameters:

• frusta (FrustaSet) – Batched frusta mesh to render.

• color (str) – Mesh color.

• opacity (float) – Mesh opacity.

• flatshading (bool) – Whether to enable flat shading.

• radius_scale (float) – Uniform scale applied to all frustum radii before meshing (1.0 = no change).

• tag_colors (dict[int, str] | None) – Optional mapping {tag: color}. If provided, each frustum is colored uniformly according to its tag (fallback to color if a tag is missing).

swctools.plot_frusta_with_centroid(swc_model: SWCModel, frusta: FrustaSet, *, color: str = 'lightblue', opacity: float = 0.8, flatshading: bool = True, radius_scale: float = 1.0, tag_colors: dict[int, str] | None = None, centroid_color: str = '#1f77b4', centroid_line_width: float = 2.0, show_nodes: bool = False, node_size: float = 2.0, title: str | None = None, width: int = 1200, height: int = 900) → Figure

Overlay frusta mesh with centroid skeleton from an SWCModel.

Parameters mirror plot_centroid and plot_frusta with an extra radius_scale.

swctools.plot_frusta_slider(frusta: FrustaSet, *, color: str = 'lightblue', opacity: float = 0.8, flatshading: bool = True, tag_colors: dict[int, str] | None = None, min_scale: float = 0.0, max_scale: float = 1.0, steps: int = 21, title: str | None = None, width: int = 1200, height: int = 900) → Figure

Interactive slider (0..1 default) controlling uniform radius_scale.

Precomputes frames at evenly spaced scales between min_scale and max_scale.

swctools.animate_frusta_timeseries(frusta: FrustaSet, time_domain: Sequence[float], amplitudes: Sequence[Sequence[float]], *, colorscale: str = 'Viridis', clim: tuple[float, float] | None = None, opacity: float = 0.8, flatshading: bool = True, radius_scale: float = 1.0, fps: int = 30, stride: int = 1, title: str | None = None, output_path: str | None = None, auto_open: bool = False)

Animate per-frustum values over time with interactive 3D controls.

Creates a Plotly animation with play/pause controls, time slider, and full 3D interactivity (rotate, zoom, pan). The animation is saved to an HTML file that can be opened in any web browser.

Parameters:

• frusta (FrustaSet) – Batched frusta mesh representing the neuron compartments.

• time_domain (Sequence[float]) – Time values for each frame. Length must match the time axis of amplitudes.

• amplitudes (Sequence[Sequence[float]]) – Time series V_i(t) shaped (T, N), where T = len(time_domain) and N = frusta.n_frusta. Each time step provides one scalar per frustum.

• colorscale (str) – Plotly colorscale name (default: “Viridis”). Examples: “Viridis”, “Plasma”, “Inferno”, “Jet”, “RdBu”, etc.

• clim (tuple[float, float] | None) – Color limits (vmin, vmax). If None, inferred from amplitudes.

• opacity (float) – Mesh opacity (default: 0.8).

• flatshading (bool) – Enable flat shading on the mesh (default: True).

• radius_scale (float) – Uniform radius scaling applied to frusta before meshing (default: 1.0).

• fps (int) – Frames per second for animation playback (default: 30).

• stride (int) – Temporal downsampling factor - use every stride time steps (default: 1).

• title (str | None) – Figure title. If None, defaults to “Frusta Animation”.

• output_path (str | None) – Path to save the HTML file. If None, defaults to “frusta_animation.html”.

• auto_open (bool) – If True, automatically open the HTML file in the default browser when saving (default: False).

Returns:

The Plotly figure object with animation frames.

Return type:

go.Figure

Notes

The resulting HTML file contains a fully interactive 3D visualization with: - Play/Pause buttons for animation control - Time slider to scrub through frames - Full 3D rotation, zoom, and pan controls - Colorbar showing value mapping

The file can be shared and opened on any system with a web browser, making it highly portable and robust across different OS and display configurations.

swctools.plot_model(*, swc_model: SWCModel | None = None, frusta: FrustaSet | None = None, show_frusta: bool = True, show_centroid: bool = True, title: str | None = None, sides: int = 16, end_caps: bool = False, color: str = 'lightblue', opacity: float = 0.8, flatshading: bool = True, tag_colors: dict[int, str] | None = None, radius_scale: float = 1.0, slider: bool = False, min_scale: float = 0.0, max_scale: float = 1.0, steps: int = 21, centroid_color: str = '#1f77b4', centroid_line_width: float = 2.0, show_nodes: bool = False, node_size: float = 2.0, point_set: PointSet | None = None, point_size: float = 1.0, point_color: str = '#d62728', output_path: str | None = None, auto_open: bool = False, width: int = 1200, height: int = 900) → Figure

Master visualization combining centroid, frusta, slider, and overlay points.

• If frusta is not provided and gm is, a FrustaSet is built from gm.

• If slider=True and show_frusta=True, a Plotly slider controls radius_scale.

• points overlays arbitrary xyz positions as small markers.

Parameters:

• output_path (str | None) – If provided, saves the figure to an HTML file at this path.

• auto_open (bool) – If True and output_path is provided, opens the HTML file in browser.

• width (int) – Figure width in pixels (default: 1200).

• height (int) – Figure height in pixels (default: 900).

swctools.plot_points(point_set: PointSet, *, color: str = '#ff7f0e', opacity: float = 1.0, size_scale: float = 1.0, title: str | None = None, width: int = 1200, height: int = 900) → Figure

Plot a PointSet as a collection of small spheres.

Parameters:

• point_set (PointSet) – Point set to visualize.

• color (str) – Color for all spheres.

• opacity (float) – Sphere opacity.

• size_scale (float) – Uniform scale applied to sphere radii (1.0 = no change).

• title (str | None) – Figure title.

Returns:

Plotly figure with Mesh3d trace.

Return type:

go.Figure

swctools.get_config() → VizConfig

Return the current visualization configuration (live object).

swctools.set_config(**kwargs: Any) → None

Update global visualization configuration.

Example:

set_config(width=800, height=600, scene_aspectmode=”cube”)

swctools.apply_layout(fig, *, title: str | None = None) → None

Apply global layout defaults to a Plotly figure in-place.