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
See Also
- Tree: Class representing connected node structures
- Node: Class representing individual 3D points
- Skeleton: Root container for all annotation data
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}")
property
¶
groups: Iterator[Group]
Returns all (immediate) group children as an iterator. Use flattened_groups if you need also need groups within subgroups.
property
¶
trees: Iterator[Tree]
Returns all (immediate) tree children as an iterator. Use flattened_trees if you also need trees within subgroups.
add_graph(name: str, color: Optional[Union[Vector4, Vector3]] = None, _enforced_id: Optional[int] = None) -> Tree
Deprecated, please use add_tree.
add_group(name: str, _enforced_id: Optional[int] = None) -> Group
Creates and adds a new subgroup to this group.
Parameters:
-
name(str) –Name for the new group.
-
_enforced_id(Optional[int], 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(name_or_tree: Union[str, Tree], color: Optional[Union[Vector4, Vector3]] = None, _enforced_id: Optional[int] = None) -> 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(Union[str, Tree]) –Either a string name for a new tree or an existing Tree instance to copy.
-
color(Optional[Union[Vector4, Vector3]], 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(Optional[int], 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() -> 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() -> Iterator[Group]
Returns an iterator of all groups within this group (and its subgroups).
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(group_id: int) -> Group
Returns the group which has the specified group 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() -> int
Returns the highest tree id of all trees within this group (and its subgroups).
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() -> 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(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(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}")
- Get Help
- Community Forums
- Email Support