---
name: manage-annotations
description: "MUST READ before creating, modifying, or querying annotations. Contains parameter names, coordinate model, and API quirks."
---
<!-- Generated by Embody/Envoy - Do not remove this comment -->

# 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
