manage-annotations

name	manage-annotations
description	MUST READ before creating, modifying, or querying annotations. Contains parameter names, coordinate model, and API quirks.

Manage Annotations Workflow

Creating Annotations

create_annotation(
    parent_path='/path/to/network',
    mode='annotate',     # 'annotate' (title bar), 'comment', or 'networkbox'
    title='My Group',
    text='Description of this group',
    x=..., y=..., width=..., height=...,
    color=[r, g, b],     # Optional, floats 0-1
    opacity=0.5           # Optional
)

Always favor annotations over OP comments for documenting operators or groups.

Enclosing Operators

To create an annotation that encloses a group of operators:

1. Get positions: get_network_layout on the parent COMP (includes all operator positions and bounding box)
2. Calculate bounding box: Find min_x, max_x, min_y, max_y (max includes operator width/height: max_x = max(op_x + op_w), max_y = max(op_y + op_h))
3. Add padding: 70 units on left/right/bottom, 170 units on top (title bar + body text)
4. Set coordinates:
   • nodeX = min_x - 70
   • nodeY = min_y - 70 (BELOW operators, not above!)
   • nodeWidth = max_x - min_x + 140
   • nodeHeight = max_y - min_y + 240 (70 bottom + 170 top)

Coordinate Model

• nodeX/nodeY = bottom-left corner, width/height extend rightward and upward
• Title bar renders at the top of the rectangle
• Common mistake: Setting nodeY above the operators. nodeY must be BELOW (less than) the lowest operator's Y.

Querying

• get_annotations — list all annotations in a COMP with properties and enclosed operators
• get_enclosed_ops — get operators enclosed by an annotation, or annotations enclosing an operator
• set_annotation — modify text, title, color, opacity, position, or size

annotateCOMP Quirks

• utility property: True from TD UI, False from code. Set ann.utility = True to match TD behavior.
• .type returns 'annotate' (not 'annotateCOMP')
• findChildren(type=annotateCOMP) requires the class object, not the string
• Cannot be reliably renamed after creation