Skip to content

webknossos.skeleton.tree

Tree 

Tree(name: str, group: Group, skeleton: Skeleton, color: Vector4 | None = None, enforced_id: int | None = None, metadata: dict[str, str | int | float | Sequence[str]] = {})

Bases: Graph

Contains a collection of nodes and edges in a graph structure.

Despite the name, trees may contain cycles. This class inherits from networkx.Graph and provides additional functionality specific to neural annotation tasks.

Parameters:

  • name (str) –

    The name of the tree.

  • group (Group) –

    The group this tree belongs to.

  • skeleton (Skeleton) –

    The skeleton this tree is part of.

  • color (Vector4 | None, default: None ) –

    RGBA color values for the tree. Defaults to None.

  • enforced_id (int | None, default: None ) –

    Specific ID to use for the tree. Defaults to None.

Returns:

  • Tree –

    A new Tree instance that represents a collection of nodes and edges.

Raises:

  • ValueError –

    If the tree name is empty or if the group or skeleton is None.

  • TypeError –

    If the color value is not a valid Vector4 type when provided.

Note

It is recommended to create trees using Skeleton.add_tree or Group.add_tree instead of instantiating this class directly. This ensures proper parent-child relationships are maintained.

Examples:

Create a new tree with nodes and edges: 

# First create a skeleton (parent object)
skeleton = Skeleton("example_skeleton")

# Add a new tree to the skeleton
tree = skeleton.add_tree("dendrite_1")

# Add nodes with 3D positions
soma = tree.add_node(position=(0, 0, 0), comment="soma")
branch1 = tree.add_node(position=(100, 0, 0), comment="branch1")
branch2 = tree.add_node(position=(0, 100, 0), comment="branch2")

# Connect nodes with edges
tree.add_edge(soma, branch1)
tree.add_edge(soma, branch2)

# Access node positions
positions = tree.get_node_positions()  # Returns numpy array of all positions

For additional graph operations, see the networkx documentation.

To create a tree, it is recommended to use Skeleton.add_tree or Group.add_tree. That way, the newly created tree is automatically attached as a child to the object the method was called on.

color instance-attribute 

color = color

group instance-attribute 

group = group

id property 

id: int

The unique identifier of the tree.

Returns:

  • int ( int ) –

    A unique identifier for this tree instance.

Note

This is a read-only property that is set during tree creation.

metadata instance-attribute 

metadata = metadata

name instance-attribute 

name = name

node_dict_factory class-attribute instance-attribute 

node_dict_factory = _NodeDict

add_node 

add_node(position: Vec3IntLike, comment: str | None = None, radius: float | None = None, rotation: Vector3 | None = None, inVp: int | None = None, inMag: int | None = None, bitDepth: int | None = None, interpolation: bool | None = None, time: int | None = None, is_branchpoint: bool = False, branchpoint_time: int | None = None, _enforced_id: int | None = None) -> Node

Add a new node to the tree.

Creates a new node at the specified position and adds it to the tree.

Parameters:

  • position (Vec3IntLike) –

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

  • comment (str | None, default: None ) –

    A text comment associated with the node. Visible in the WEBKNOSSOS UI. Defaults to None.

  • radius (float | None, default: None ) –

    Node radius for visualization. Defaults to None.

  • rotation (Vector3 | None, default: None ) –

    3D rotation vector for the node. Defaults to None.

  • inVp (int | None, default: None ) –

    Viewport information. Defaults to None.

  • inMag (int | None, default: None ) –

    Magnification level. Defaults to None.

  • bitDepth (int | None, default: None ) –

    Bit depth for node data. Defaults to None.

  • interpolation (bool | None, default: None ) –

    Whether to use interpolation. Defaults to None.

  • time (int | None, default: None ) –

    Timestamp for the node. Defaults to None.

  • is_branchpoint (bool, default: False ) –

    Whether this node is a branch point. Defaults to False.

  • branchpoint_time (int | None, default: None ) –

    Timestamp for branch point creation. Defaults to None.

  • _enforced_id (int | None, default: None ) –

    Internal use only. Forces a specific node ID. Defaults to None.

Returns:

  • Node ( Node ) –

    The newly created and added node.

Examples:

# Add a simple node with just position
node1 = tree.add_node(position=(100, 200, 300))

# Add a node with additional properties
node2 = tree.add_node(
    position=(150, 250, 350),
    comment="Dendrite branch point",
    radius=2.5,
    is_branchpoint=True
)

adjlist_inner_dict_factory 

adjlist_inner_dict_factory() -> _AdjDict

adjlist_outer_dict_factory 

adjlist_outer_dict_factory() -> _AdjDict

get_max_node_id 

get_max_node_id() -> int

Get the highest node ID in the tree.

Returns:

  • int ( int ) –

    The maximum node ID present in the tree. Returns 0 if the tree has no nodes.

get_node_by_id 

get_node_by_id(node_id: int) -> Node

Retrieve a node using its unique identifier.

Parameters:

  • node_id (int) –

    The unique identifier of the node to retrieve.

Returns:

  • Node ( Node ) –

    The node with the specified ID.

Raises:

  • KeyError –

    If no node exists with the given ID in this tree.

get_node_positions 

get_node_positions() -> ndarray

Get positions of all nodes in the tree.

Returns:

  • ndarray –

    np.ndarray: A numpy array of shape (N, 3) containing the 3D positions of all N nodes in the tree. Each row represents a node's (x, y, z) coordinates.