docs(03-02): complete animation library plan
- Add 03-02-SUMMARY.md with 7 animation types documented - Advance STATE.md to plan 3/3 in phase 03 - Mark ANI-01, ANI-02 complete in REQUIREMENTS.md - Update ROADMAP.md phase 3 progress (2/3 plans done)
This commit is contained in:
Claude
107
.planning/phases/03-communication-protocol/03-02-SUMMARY.md
Normal file
107
.planning/phases/03-communication-protocol/03-02-SUMMARY.md
Normal file
@@ -0,0 +1,107 @@
|
||||
---
|
||||
phase: 03-communication-protocol
|
||||
plan: "02"
|
||||
subsystem: animations
|
||||
tags: [animation, rendering, tdd, python, fire2012, rainbow, chase, strobe, pulse]
|
||||
dependency_graph:
|
||||
requires: []
|
||||
provides: [lightsync.animations, ANIMATION_REGISTRY, create_animation, AnimationBase]
|
||||
affects: [phase-04-timeline-editor, phase-05-live-execution]
|
||||
tech_stack:
|
||||
added: [colorsys (stdlib), math (stdlib), abc (stdlib), random (stdlib)]
|
||||
patterns: [ABC inheritance, factory registry, TDD red-green, pure functions]
|
||||
key_files:
|
||||
created:
|
||||
- lightsync/animations/__init__.py
|
||||
- lightsync/animations/base.py
|
||||
- lightsync/animations/solid_color.py
|
||||
- lightsync/animations/chase.py
|
||||
- lightsync/animations/pulse.py
|
||||
- lightsync/animations/rainbow.py
|
||||
- lightsync/animations/strobe.py
|
||||
- lightsync/animations/color_wipe.py
|
||||
- lightsync/animations/fire.py
|
||||
- tests/test_animations.py
|
||||
modified: []
|
||||
decisions:
|
||||
- "chase reverse detection uses offset-not-multiple-of-period for reliable test assertion"
|
||||
- "FireAnimation lazy-initializes heat array per led_count to support variable strip lengths"
|
||||
- "speed parameter mapped differently per animation: pulse maps to period, strobe to Hz, chase/wipe to px/sec"
|
||||
metrics:
|
||||
duration: "3 min"
|
||||
completed: "2026-04-06"
|
||||
tasks_completed: 1
|
||||
files_changed: 10
|
||||
requirements: [ANI-01, ANI-02]
|
||||
---
|
||||
|
||||
# Phase 03 Plan 02: Animation Library Summary
|
||||
|
||||
**One-liner:** 7 animation types (solid_color, chase, pulse, rainbow, strobe, color_wipe, fire) as pure renderers with AnimationBase ABC, ANIMATION_REGISTRY, and create_animation() factory — all via TDD red-green cycle.
|
||||
|
||||
## What Was Built
|
||||
|
||||
The `lightsync/animations/` package provides all animation rendering for the LightSync system. Animations are pure computation: `render(t, led_count) -> list[tuple]`. No I/O, no networking — just pixel data generation that the protocol layer (Plan 01) encodes and sends.
|
||||
|
||||
### AnimationBase ABC
|
||||
|
||||
`lightsync/animations/base.py` defines the contract:
|
||||
- `render(t: float, led_count: int) -> list[tuple]` — render at time t, returns list of (R,G,B) tuples
|
||||
- `from_params(params: dict) -> AnimationBase` — construct from CueModel.params dict
|
||||
|
||||
### 7 Animation Types
|
||||
|
||||
| Animation | Algorithm | Key Params |
|
||||
|-----------|-----------|------------|
|
||||
| solid_color | Uniform fill | color, white |
|
||||
| chase | Moving segment, modulo pattern | color, bg_color, speed, size, spacing, reverse |
|
||||
| pulse | Sine-wave brightness oscillation | color, speed (maps to period 0.1-5.0s), min/max_brightness |
|
||||
| rainbow | HSV hue cycle via colorsys | speed, period |
|
||||
| strobe | On/off at 1-20 Hz | color, speed, duty_cycle |
|
||||
| color_wipe | Progressive fill from start/end | color, speed, reverse |
|
||||
| fire | Fire2012: cool+drift+spark+heat-color | cooling, sparking, speed |
|
||||
|
||||
### Registry and Factory
|
||||
|
||||
`ANIMATION_REGISTRY` maps all 7 names to classes. `create_animation(name, params)` raises `ValueError` for unknown types.
|
||||
|
||||
## TDD Execution
|
||||
|
||||
**RED phase:** `tests/test_animations.py` (24 tests) committed before any implementation. Tests failed with `ModuleNotFoundError`.
|
||||
|
||||
**GREEN phase:** Implemented all 9 files. One test required a fix: `test_chase_reverse` initially used `t=1.5` which caused `offset % period == 0`, making fwd and rev identical. Fixed to use `t=0.05` (offset=3, not multiple of period=10).
|
||||
|
||||
**Result:** 24/24 tests passing.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] Chase reverse test used symmetrical t value**
|
||||
- **Found during:** TDD GREEN phase verification
|
||||
- **Issue:** At t=1.5 with speed=1.0, offset=90 which is a multiple of period=10, making forward and reverse chase produce identical pixel patterns
|
||||
- **Fix:** Changed test t from 1.5 to 0.05 (offset=3, not multiple of period), which reliably distinguishes fwd vs reverse
|
||||
- **Files modified:** tests/test_animations.py
|
||||
- **Commit:** f4da956
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None. All 7 animation types fully implemented and rendering real pixel data.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
Files:
|
||||
- FOUND: lightsync/animations/__init__.py
|
||||
- FOUND: lightsync/animations/base.py
|
||||
- FOUND: lightsync/animations/solid_color.py
|
||||
- FOUND: lightsync/animations/chase.py
|
||||
- FOUND: lightsync/animations/pulse.py
|
||||
- FOUND: lightsync/animations/rainbow.py
|
||||
- FOUND: lightsync/animations/strobe.py
|
||||
- FOUND: lightsync/animations/color_wipe.py
|
||||
- FOUND: lightsync/animations/fire.py
|
||||
- FOUND: tests/test_animations.py
|
||||
|
||||
Commits:
|
||||
- 920243f: test(03-02): add failing tests for animation library
|
||||
- f4da956: feat(03-02): implement animation library — 7 types with registry and factory
|
||||
Reference in New Issue
Block a user