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
@@ -23,8 +23,8 @@
|
||||
|
||||
### Animation Library
|
||||
|
||||
- [ ] **ANI-01**: Built-in animation types: chase, pulse, rainbow, strobe, color wipe, fire, solid color
|
||||
- [ ] **ANI-02**: Per-animation parameters: speed, primary color(s), secondary color(s), direction, length/density
|
||||
- [x] **ANI-01**: Built-in animation types: chase, pulse, rainbow, strobe, color wipe, fire, solid color
|
||||
- [x] **ANI-02**: Per-animation parameters: speed, primary color(s), secondary color(s), direction, length/density
|
||||
- [x] **ANI-03**: RGBW-aware color handling for SK6812 (separate W channel)
|
||||
- [x] **ANI-04**: RGB color handling for WS2801
|
||||
|
||||
|
||||
@@ -73,7 +73,7 @@ Plans:
|
||||
|
||||
Plans:
|
||||
- [x] 03-01-PLAN.md — Protocol encoders (DRGB/DRGBW/DNRGB + animation command), UDP sender, device stub completion
|
||||
- [ ] 03-02-PLAN.md — Animation library (7 built-in types with AnimationBase ABC, registry, factory)
|
||||
- [x] 03-02-PLAN.md — Animation library (7 built-in types with AnimationBase ABC, registry, factory)
|
||||
- [ ] 03-03-PLAN.md — UDP simulator, FastAPI integration, end-to-end protocol validation
|
||||
|
||||
### Phase 4: Timeline Editor
|
||||
@@ -154,7 +154,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7
|
||||
|-------|----------------|--------|-----------|
|
||||
| 1. Foundation | 4/4 | Complete | 2026-04-05 |
|
||||
| 2. Audio Engine | 3/3 | Complete | 2026-04-06 |
|
||||
| 3. Communication Protocol | 1/3 | In Progress| |
|
||||
| 3. Communication Protocol | 2/3 | In Progress| |
|
||||
| 4. Timeline Editor | 0/4 | Not started | - |
|
||||
| 5. Live Show Execution | 0/3 | Not started | - |
|
||||
| 6. AI Sync | 0/3 | Not started | - |
|
||||
|
||||
@@ -3,14 +3,14 @@ gsd_state_version: 1.0
|
||||
milestone: v1.0
|
||||
milestone_name: milestone
|
||||
status: executing
|
||||
stopped_at: Completed 03-communication-protocol/03-01-PLAN.md
|
||||
last_updated: "2026-04-06T21:43:45.010Z"
|
||||
stopped_at: Completed 03-communication-protocol/03-02-PLAN.md
|
||||
last_updated: "2026-04-06T21:48:33.912Z"
|
||||
last_activity: 2026-04-06
|
||||
progress:
|
||||
total_phases: 7
|
||||
completed_phases: 2
|
||||
total_plans: 10
|
||||
completed_plans: 8
|
||||
completed_plans: 9
|
||||
percent: 0
|
||||
---
|
||||
|
||||
@@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-04-05)
|
||||
## Current Position
|
||||
|
||||
Phase: 03 (communication-protocol) — EXECUTING
|
||||
Plan: 2 of 3
|
||||
Plan: 3 of 3
|
||||
Status: Ready to execute
|
||||
Last activity: 2026-04-06
|
||||
|
||||
@@ -60,6 +60,7 @@ Progress: [░░░░░░░░░░] 0%
|
||||
| Phase 02-audio-engine P03 | 8min | 2 tasks | 5 files |
|
||||
| Phase 02-audio-engine P03 | 4 | 9 tasks | 8 files |
|
||||
| Phase 03-communication-protocol P01 | 4min | 2 tasks | 8 files |
|
||||
| Phase 03-communication-protocol P02 | 3min | 1 tasks | 10 files |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
@@ -92,6 +93,8 @@ Recent decisions affecting current work:
|
||||
- [Phase 03-communication-protocol]: TDD approach for protocol encoders: tests committed RED before implementation, ensuring coverage is meaningful
|
||||
- [Phase 03-communication-protocol]: 0xAC animation command marker chosen well above WLED 0x01-0x04 range — no firmware collision
|
||||
- [Phase 03-communication-protocol]: UDPSender uses single shared asyncio DatagramTransport — no socket pool needed for UDP multi-device sends
|
||||
- [Phase 03-communication-protocol]: Chase reverse test uses offset-not-multiple-of-period for reliable assertion
|
||||
- [Phase 03-communication-protocol]: FireAnimation lazy-initializes heat array per led_count to support variable strip lengths
|
||||
|
||||
### Pending Todos
|
||||
|
||||
@@ -105,8 +108,8 @@ None yet.
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-04-06T21:43:45.002Z
|
||||
Stopped at: Completed 03-communication-protocol/03-01-PLAN.md
|
||||
Last session: 2026-04-06T21:48:33.906Z
|
||||
Stopped at: Completed 03-communication-protocol/03-02-PLAN.md
|
||||
Resume file: None
|
||||
|
||||
Next action: `/gsd:plan-phase 1`
|
||||
|
||||
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