TutorDraw

Explain what you draw, one step at a time.

TutorDraw is a Python library for authoring visual tutorials using DrawCV. DrawCV supplies drawing objects and rendering; TutorDraw attaches teaching annotations and organizes them into independent lesson steps.

Status

Published alpha 0.1.0a11. TutorDraw provides the tutorial workflow described below. Licensed under MIT, authored by Nuh Yamin. See the compatibility notes before relying on it in production.

0.1.0a11 is a large step from the previous release 0.1.0a3: it adds complete lesson save/load, AI revision support, deterministic timed playback, video export, annotation text beyond ASCII, per-step artwork changes, animation between beats, timed annotation reveals, and optional Thai and Arabic. Versions a4 to a10 were development milestones and were never uploaded.

Implemented:

• Register existing DrawCV objects or groups as teaching targets.

• Attach labels with optional straight leader lines.

• Configure bounds anchors, gap, offset, padding, and font scale.

• Keep labels attached when targets move, including through group transforms.

• Define independent steps and render them to DrawCV canvases and PNG images.

• Preserve source content and undo history, including on rendering failure.

• Add step-local wrapped callouts, rectangular highlights, and group-aware dimming.

• Customize shared typography, spacing, and colors through an immutable theme.

• Export ordered PNGs with collision checks and partial-failure reporting.

• Validate references/options and warn about off-canvas annotations.

• save/reopen complete versioned JSON lessons with stable IDs and validated references.

• step durations, trailing pauses, direct time seeking, and streaming frames; see Timing.

• encode a timed lesson to a video file with collision-safe, all-or-nothing replacement; see Video.

• annotate in Latin, Greek, Cyrillic or CJK and use technical symbols such as µm, °C, α, ½ and ×; see Text.

• move, recolour, fade or hide a target for one step, so a lesson can show change rather than describe it; see Restyle.

• teach in Thai or Arabic with pip install "tutordraw[typography]" and a font you supply; see Text.

• ease a step into its new state instead of cutting to it; see Animation.

• delay a label or explanation so a narrated beat introduces one thing at a time; see Reveal.

Timed captions, interactive playback, and automatic collision avoidance remain planned.

Install the alpha

python -m pip install tutordraw==0.1.0a11

The exact version selects this prerelease explicitly. Requires Python 3.12+.

Develop from this repository

Requires Python 3.12+. From the repository root:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe examples/cell_tutorial.py

On macOS/Linux, use .venv/bin/python instead. Windows/Python 3.12 passes 171 tests (one symlink test skips without symlink privileges). Hosted CI passes on Windows, Linux, and macOS for Python 3.12–3.14. If python is unavailable, use the absolute path to an installed Python 3.12+ executable for the first command.

No DrawCV checkout is needed. TutorDraw pins the tested published dependency pydrawcv==0.10.0.post1, which imports as drawcv. A broader compatibility range is future work. Use an explicit version or --pre when selecting an alpha release.

Working example

from drawcv import Circle, Color, FillStyle, Point, Scene
from tutordraw import Tutorial

scene = Scene(640, 360, background=Color.white())
shape = Circle(
    center=Point(180, 180), radius=45,
    fill=FillStyle(color=Color(131, 151, 218)),
)
scene.add(shape)

tutorial = Tutorial(scene, title="Inside a cell")
nucleus = tutorial.target(shape, name="nucleus")
label = nucleus.label("Nucleus", anchor="top", leader=True)

intro = tutorial.step("Meet the nucleus").show(label)
intro.highlight(nucleus)
intro.explain(nucleus, "The nucleus contains the cell's DNA.", max_width=220)
tutorial.step("Review the drawing")

tutorial.render_step(0).save("output/nucleus.png")
tutorial.render_step(1).save("output/plain.png")
# Batch export refuses existing files unless overwrite=True is explicit.
tutorial.export_steps("output/readme", overwrite=True)

Each step starts from the current source scene. The second step has no labels because it does not explicitly show any. Rendering order does not affect results. Tutorial and step titles are metadata; add DrawCV text if you want visible titles.

Run the cell example for a composed diagram. It writes output/cell/step-001.png through step-003.png. Rerunning explicitly overwrites these example images. The nested-group example illustrates focusing a child while dimming its siblings.

Continue a lesson with another AI

In the development checkout, use tutorial.save_json("lesson.tutordraw.json") and later Tutorial.load_json("lesson.tutordraw.json"). Named targets, annotation IDs, themes, and all step presentation settings survive the round trip.

Run python examples/save_and_revise.py for the complete workflow. See AI authoring and persistence.

Export a timed lesson to video

In the development checkout, give each step a duration and encode the result:

lesson.steps[0].set_timing(duration=2, pause=1)
lesson.export_video("output/video/lesson.mp4", fps=30)

Run python examples/video_lesson.py for the complete workflow. It encodes the 10-second cell lesson at 12 fps, then decodes the file to report its frame count. See video export for codec limits and failure behavior.

Current limits

• Labels are single line; callouts add newlines and measured word wrapping. Latin, Greek, Cyrillic, CJK and common symbols work out of the box. Thai and Arabic need the optional typography extra and a font you supply. Hebrew, Indic scripts and emoji are refused with an error naming the character; see Text.
• Anchors use transformed axis-aligned get_bounds() results, including supported shape strokes but excluding post-processing effect extents.
• Labels stay upright and spacing uses canvas pixels. Automatic collision avoidance and routed leaders are deferred.
• Off-canvas annotations issue LayoutWarning and may be clipped. Callout widths measure the text area; padding adds to the panel width.
• Dimming multiplies artwork opacity, not the background. Complex masks, blend modes, and occlusion are not pixel-level spotlight isolation. Hidden or zero-opacity attention targets are rejected; clipping and masks are not used to infer visibility.
• Scenes must round-trip through DrawCV serialization; unsupported copying raises SceneCopyError. Arbitrary custom drawables/assets are not guaranteed supported.
• Rendering uses authored scene state without sampling a timeline. Concurrent source edits during rendering are unsupported.
• Video export is opaque only and uses hard cuts. Which codecs work depends on the host OpenCV build; an unavailable codec raises VideoExportError. Encoding is lossy, so decoded frames approximate render_step output.
• Missing registered targets fail rendering, even if their label is not shown in that step. Hidden artwork does not suppress an explicitly shown label.

Documentation and continuation

• Practical tutorial: build a lesson from a DrawCV scene.
• Per-step artwork: move, recolour, fade and hide targets per step.
• Animation: easing a step into its state instead of cutting.
• Reveal: delaying annotations so a beat unfolds as it is narrated.
• Video export: encoding contract, codecs, and limits.
• Text: which characters annotations accept, and why the rest are refused.
• API guide: implemented methods and errors.
• Compatibility: evidence, fonts, and alpha API expectations.
• Release procedure: exact artifact checks and manual publishing.
• Changelog: milestone history.
• Contributing: local development and installed-package checks.
• Product scope: intended tutorial capabilities.
• Architecture: foundation and future design.
• Roadmap: milestones and acceptance checks.
• AI handoff: current state, verification, and continuation prompt.
• Decisions: choices and remaining questions.
• Agent instructions: repository conventions.

To continue with another AI model, ask it to read AGENTS.md and docs/HANDOFF.md first. See the handoff for the latest release state. DrawCV remains a separate project.

License

MIT, copyright 2026 Nuh Yamin.