ComfyUI-EnglishAnnotator

A ComfyUI custom node that draws colored bounding boxes and English word labels onto an image — designed for building vocabulary learning cards.

Pairs naturally with kijai/ComfyUI-Florence2: use Florence-2 in od, dense_region_caption, or caption_to_phrase_grounding mode to produce per-object bounding boxes and English labels, then feed them into this node to render a study-ready image.

---

What it does

Inputs:

• An image (e.g. a scene generated by SDXL / Flux / Z-Image-Turbo)
• A list of bounding boxes [[x1, y1, x2, y2], ...]
• A list of English labels ["apple", "chair", ...]

Output:

• The same image with a colored rectangle around each detected object and the English word printed in a colored label box (above / inside / below the bbox)

A built-in 8-color palette keeps adjacent labels visually distinct. The node is permissive about input shape — it accepts flat lists, batch-wrapped lists, or lists of {"bbox":..., "label":...} dicts, so it works across Florence-2 wrapper versions.

---

Install

cd ComfyUI/custom_nodes
git clone https://github.com/aadebuger/ComfyUI-EnglishAnnotator.git
cd ComfyUI-EnglishAnnotator

# inside ComfyUI's venv
uv pip install -r requirements.txt

Restart ComfyUI. The node appears under category 📚 English Annotator as 📚 English Word Annotator.

See INSTALL_NOTES.md for environment-specific notes (Ubuntu + uv, HF cache redirect, etc.).

---

Node reference

| Input | Type | Default | Notes | |---|---|---|---| | image | IMAGE | — | The source image | | bboxes | any | — | Bounding boxes (typically from Florence-2) | | labels | any | — | Labels (typically from Florence-2) | | font_size | INT | 36 | Label text size in pixels | | box_width | INT | 4 | Bounding box outline width | | label_position | enum | above | above / inside_top / below, auto-fallback when out of bounds | | font_path | STRING (optional) | "" | Explicit TTF/OTF path (overrides defaults) | | text_color | STRING (optional) | #FFFFFF | Hex color for label text | | max_labels | INT (optional) | 0 | Cap the number of objects to annotate (0 = no limit) |

Returns: IMAGE.

Fonts: the node walks a built-in candidate list — DejaVu (Linux), Helvetica/Arial (macOS), Arial (Windows). On a fresh Ubuntu box install fonts-dejavu-core if labels render as boxes.

---

Example workflow

The flow is:

CheckpointLoader → KSampler → VAEDecode ──┐
                                          ├→ EnglishWordAnnotator → SaveImage
              Florence2ModelLoader → Florence2Run ──┘

See example_workflows/classroom.json for an API-format workflow you can submit via /prompt, or generate one with the CLI's --dump-workflow flag.

Florence-2 task suggestions

| Task | When to use | |---|---| | od | Clean COCO-style category names — best for beginner-level vocab | | caption_to_phrase_grounding | You supply your own word list; Florence-2 locates exactly those words | | dense_region_caption | Natural-language regions like "red apple on table" |

For a fixed vocabulary pipeline (e.g. a daily 16-word list), caption_to_phrase_grounding is by far the most reliable.

---

CLI

A self-contained CLI is bundled under cli/. It uses ComfyUI's WebSocket API to submit a workflow end-to-end and download the annotated image:

uv run cli/english_card_cli.py \
    "flat vector illustration of a tidy classroom: desk, chair, blackboard, books, pencil, backpack, clock, globe, computer" \
    --ip 10.8.0.12 --steps 25

With a fixed vocabulary (uses caption_to_phrase_grounding):

uv run cli/english_card_cli.py \
    "a sunny kitchen scene, flat vector illustration" \
    --words "apple,banana,knife,cutting board,bowl,kettle,faucet,refrigerator" \
    --ip 10.8.0.12

See cli/README.md for full argument reference.

---

Use case: daily vocabulary card pipeline

This node was built for an automated daily English vocabulary card workflow:

1. A daily JSON of 16 target words (with definitions and example sentences)
2. Scene generation via SDXL / Z-Image-Turbo
3. Florence-2 caption_to_phrase_grounding locks bboxes onto exactly those 16 words
4. This node renders the annotated image
5. VoxCPM2 TTS for per-word audio
6. ffmpeg assembles the final card video

---

License

MIT