manage-annotations

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

Deleting Annotations

Delete via delete_op, never via raw .destroy() in execute_python. delete_op resolves utility annotations, purges any tracking, and arms an auto-save checkpoint that re-exports the parent TDXN COMP's .tdxn without the annotation -- the deletion is durable. A raw .destroy() leaves the stale annotations: entry in the parent's .tdxn on disk, and the next reimport of that COMP (import_network, manager Reload, or cold open) resurrects the annotation with its pre-delete text.