webknossos.skeleton.group ¶

Group ¶

A hierarchical container for organizing trees and subgroups in WEBKNOSSOS skeleton annotations.

The Group class provides a way to organize skeleton trees into logical collections, supporting nested hierarchies of groups and trees. Groups can contain both trees (collections of connected nodes) and other groups, enabling flexible organization of complex annotations.

Attributes:

name (str) –

Name of the group.
id (int) –

Read-only unique identifier for the group.
children (Iterator[GroupOrTree]) –

Iterator over all immediate children (both groups and trees).
groups (Iterator[Group]) –

Iterator over immediate subgroups.
trees (Iterator[Tree]) –

Iterator over immediate trees.

The group hierarchy supports

Nested organization (groups within groups)
Tree management (adding, removing, retrieving trees)
Node access across all contained trees
Flattened views of the hierarchy

Examples:

Create a hierarchical structure:

# Create groups for different neuron parts
neuron = skeleton.add_group("neuron_42")
dendrites = neuron.add_group("dendrites")
axons = neuron.add_group("axons")

# Add trees to groups
basal = dendrites.add_tree("basal_dendrite")
apical = dendrites.add_tree("apical_dendrite", color=(1, 0, 0, 1))
axon_tree = axons.add_tree("main_axon")

# Work with the hierarchy
print(f"Total nodes: {neuron.get_total_node_count()}")
for tree in dendrites.trees:
    print(f"Dendrite tree: {tree.name}")

# Access nodes across all trees
node = neuron.get_node_by_id(123)

Copy existing trees:

# Copy a tree to another group
template = existing_group.get_tree_by_id(42)
copy = new_group.add_tree(template, color=(0, 1, 0, 1))

Notes

Groups maintain unique IDs for all contained elements
Use flattened_* methods to access nested elements recursively
Trees should be added using add_tree rather than created directly
The group hierarchy is part of a Skeleton instance

children `property` ¶

children: Iterator[GroupOrTree]

Returns an iterator over all immediate children (groups and trees).

This property provides access to both groups and trees that are direct children of this group, in no particular order. For nested access, use flattened_trees() or flattened_groups().

Returns:

Iterator[GroupOrTree] –

Iterator[GroupOrTree]: Iterator yielding all immediate child groups and trees.

Examples:

# Print all immediate children
for child in group.children:
    if isinstance(child, Tree):
        print(f"Tree: {child.name}")
    else:
        print(f"Group: {child.name}")

groups `property` ¶

groups: Iterator[Group]

Returns all (immediate) group children as an iterator. Use flattened_groups if you need also need groups within subgroups.

id `property` ¶

id: int

Read-only property.

name `instance-attribute` ¶

name: str

trees `property` ¶

trees: Iterator[Tree]

Returns all (immediate) tree children as an iterator. Use flattened_trees if you also need trees within subgroups.

add_group ¶

add_group(name: str, _enforced_id: int | None = None) -> Group

Creates and adds a new subgroup to this group.

Parameters:

name (str) –

Name for the new group.
_enforced_id (int | None, default: None ) –

Optional specific ID for the group (internal use).

Returns:

Group ( Group ) –

The newly created group.

Examples:

# Create nested group hierarchy
dendrites = neuron.add_group("dendrites")
basal = dendrites.add_group("basal")
apical = dendrites.add_group("apical")

add_tree ¶

add_tree(name_or_tree: str | Tree, color: Vector4 | Vector3 | None = None, _enforced_id: int | None = None, metadata: dict[str, str | int | float | Sequence[str]] = {}) -> Tree

Adds a new tree or copies an existing tree to this group.

This method supports two ways of adding trees: 1. Creating a new tree by providing a name 2. Copying an existing tree from another location

Parameters:

name_or_tree (str | Tree) –

Either a string name for a new tree or an existing Tree instance to copy.
color (Vector4 | Vector3 | None, default: None ) –

Optional RGBA color tuple (r, g, b, a) or RGB tuple (r, g, b). If an RGB tuple is provided, alpha will be set to 1.0.
_enforced_id (int | None, default: None ) –

Optional specific ID for the tree (internal use).

Returns:

Tree ( Tree ) –

The newly created or copied tree.

Examples:

# Create new tree
tree = group.add_tree("dendrite_1", color=(1, 0, 0, 1))

# Copy existing tree
copy = group.add_tree(existing_tree)

Notes

When copying a tree, a new ID will be generated if the original ID already exists in this group.

as_nml_group ¶

as_nml_group() -> Group

Converts this group to its NML representation.

This method creates a lightweight representation of the group suitable for serialization in the NML format.

Returns:

Group –

wknml.Group: NML representation of this group.

Notes

This is primarily used internally for file I/O operations.

flattened_groups ¶

flattened_groups() -> Iterator[Group]

Returns an iterator of all groups within this group (and its subgroups).

flattened_trees ¶

flattened_trees() -> Iterator[Tree]

Returns an iterator of all trees in this group and its subgroups.

This method performs a recursive traversal of the group hierarchy, yielding all trees regardless of their nesting level.

Returns:

Iterator[Tree] –

Iterator[Tree]: Iterator yielding all contained trees.

Examples:

# Process all trees regardless of grouping
for tree in group.flattened_trees():
    print(f"Tree {tree.name} has {len(tree.nodes)} nodes")

get_group_by_id ¶

get_group_by_id(group_id: int) -> Group

Returns the group which has the specified group id.

get_max_node_id ¶

get_max_node_id() -> int

Returns the highest node id of all nodes of all trees within this group (and its subgroups).

get_max_tree_id ¶

get_max_tree_id() -> int

Returns the highest tree id of all trees within this group (and its subgroups).

get_node_by_id ¶

get_node_by_id(node_id: int) -> Node

Retrieves a node by its ID from any tree in this group or its subgroups.

Parameters:

node_id (int) –

The ID of the node to find.

Returns:

Node ( Node ) –

The node with the specified ID.

Raises:

ValueError –

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

Examples:

try:
    node = group.get_node_by_id(42)
    print(f"Found node at position {node.position}")
except ValueError:
    print("Node not found")

get_total_node_count ¶

get_total_node_count() -> int

Counts all nodes in all trees within this group and its subgroups.

Returns:

int ( int ) –

Total number of nodes across all contained trees.

Examples:

# Check total annotation points
count = group.get_total_node_count()
print(f"Total annotation points: {count}")

get_tree_by_id ¶

get_tree_by_id(tree_id: int) -> Tree

Retrieves a tree by its ID from this group or its subgroups.

Parameters:

tree_id (int) –

The ID of the tree to find.

Returns:

Tree ( Tree ) –

The tree with the specified ID.

Raises:

ValueError –

If no tree with the given ID exists.

Examples:

try:
    tree = group.get_tree_by_id(42)
    print(f"Found tree '{tree.name}'")
except ValueError:
    print("Tree not found")

has_tree_id ¶

has_tree_id(tree_id: int) -> bool

Checks if a tree with the given ID exists in this group or its subgroups.

Parameters:

tree_id (int) –

The ID to check for.

Returns:

bool ( bool ) –

True if a tree with the ID exists, False otherwise.

Examples:

if group.has_tree_id(42):
    tree = group.get_tree_by_id(42)
    print(f"Tree exists: {tree.name}")

remove_tree_by_id ¶

remove_tree_by_id(tree_id: int) -> None

webknossos.skeleton.group ¶

Group ¶

children property ¶

groups property ¶

id property ¶

name instance-attribute ¶

trees property ¶

add_group ¶

add_tree ¶

as_nml_group ¶

flattened_groups ¶

flattened_trees ¶

get_group_by_id ¶

get_max_node_id ¶

get_max_tree_id ¶

get_node_by_id ¶

get_total_node_count ¶

get_tree_by_id ¶

has_tree_id ¶

remove_tree_by_id ¶

children `property` ¶

groups `property` ¶

id `property` ¶

name `instance-attribute` ¶

trees `property` ¶