From dd02c2c36a349def943b95e3ff79b516a1a0b9fa Mon Sep 17 00:00:00 2001 From: Ben Stull Date: Thu, 4 Jun 2026 06:12:09 -0700 Subject: [PATCH] docs: revise design + roadmap for single pano projector MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Operator decision (2026-06-04): single panoramic projector spanning the three walls showing the real selected video (nature-video focus), replacing four projectors + a procedural side-wall renderer. - Design spec: revision banner; updated §1, §6 (one pano projector), §7 (procedural side walls REMOVED), §10 layout, §12 open questions. - ROADMAP: sub-project 5 marked Dropped; diagram + dependency order updated; §3 player drives one pano output; cross-cutting decisions reconciled. - Sub-project-2 spec: follow-up note updated to past tense (design spec done). dominant_color's only consumer was the side walls, so it stays optional/opt-in in the sub-project-2 tooling (already specced). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/ROADMAP.md | 62 ++++++++------- ...26-06-04-human-experience-filter-design.md | 78 +++++++++++++------ .../2026-06-04-ingest-tagging-review-tools.md | 10 +-- 3 files changed, 93 insertions(+), 57 deletions(-) diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 5db4a6d..0fa72d9 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -17,10 +17,12 @@ Design reference: [`specs/2026-06-04-human-experience-filter-design.md`](./super | 2 | Ingest & Tagging / Review tools | ⏳ Next | a real library | | 3 | Player Runtime (Pi) | ◻ Not started | the room runs | | 4 | Arduino Firmware (control panel)| ◻ Not started | real knobs | -| 5 | Procedural Side Walls | ◻ Not started | full immersion | +| 5 | ~~Procedural Side Walls~~ | ❌ Dropped | — (superseded) | **Dependency order:** 1 → 2, and 1 → 3. Sub-projects 3 and 4 share a serial -protocol contract and can then proceed in parallel. 5 depends on 3. +protocol contract and can then proceed in parallel. Sub-project 5 was **dropped** +(2026-06-04): the move to a single panoramic projector showing real video across +the three walls removes the procedural side walls — see the design spec §6/§7. ``` ┌─────────────────────────┐ @@ -29,15 +31,17 @@ protocol contract and can then proceed in parallel. 5 depends on 3. │ ┌───────────┴───────────┐ ▼ ▼ -┌───────────────┐ ┌─────────────────┐ -│ 2. Ingest / │ │ 3. Player │ -│ Review │─────▶│ Runtime (Pi) │ -└───────────────┘ feeds└───┬─────────┬────┘ - (fills catalog) │ │ - serial ▼ ▼ mood+color - ┌────────────────┐ ┌──────────────────┐ - │ 4. Firmware │ │ 5. Side Walls │ - └────────────────┘ └──────────────────┘ +┌───────────────┐ ┌─────────────────────┐ +│ 2. Ingest / │ │ 3. Player Runtime │ +│ Review │─────▶│ (Pi) → 1 pano │ +└───────────────┘ feeds│ projector │ + (fills catalog) └──────────┬──────────┘ + serial ▼ + ┌────────────────┐ + │ 4. Firmware │ + └────────────────┘ + +(5. Procedural Side Walls — dropped 2026-06-04, single pano projector) ``` --- @@ -91,7 +95,7 @@ files on the drive. ## 3. Player Runtime (Pi) ◻ **Goal:** the thing that makes the room run — read the controls, pick media, play -it on the primary wall. +it across the single panoramic projector. **Delivers (`player/`):** @@ -99,8 +103,8 @@ it on the primary wall. - Call `hef.selection.select()` on each change; loop the chosen 5–15 min segment until the knobs move; **crossfade** on change. - `None` mode → fade to black + silence. -- Drive the **primary** projector; emit current `dominant_color` + dark/light to - the side-wall renderer (sub-project 5). +- Drive the **single panoramic projector** spanning the three walls with the real + selected video (no primary/side split; no side-wall feed — sub-project 5 dropped). **Depends on:** sub-project 1 (`select`); a populated catalog from sub-project 2 to be meaningful, but can be developed against a hand-authored catalog and a @@ -134,20 +138,17 @@ a serial monitor) and the Pi player reacts. --- -## 5. Procedural Side Walls ◻ +## 5. ~~Procedural Side Walls~~ ❌ Dropped (2026-06-04) -**Goal:** make the mood axis physically felt in peripheral vision. +**Superseded.** The move to a single panoramic projector showing the real selected +video across the three walls (design spec §6/§7) removes the procedural ambient +renderer entirely — the mood axis is felt through the chosen content itself. With +it goes the only consumer of `dominant_color`, which becomes optional/opt-in in +the ingest tooling (sub-project 2 spec §5.2). -**Delivers (`sidewalls/`):** - -- Render a slow color wash on the three non-primary walls: **hue** from the - playing piece's `dominant_color`, **brightness** from the dark/light knobs. -- Fade to black in `None` mode. - -**Depends on:** sub-project 3 emitting current `dominant_color` + mood state. -**Done when:** given a color + mood input stream, the wash renders and tracks -changes — testable headless by snapshotting rendered frames. -**Open decisions:** runs on the primary Pi's extra outputs vs. a second Pi. +> *Original goal (for the record): render a slow color wash on the three +> non-primary walls — hue from the playing piece's `dominant_color`, brightness +> from the dark/light knobs — to make the mood axis felt in peripheral vision.* --- @@ -156,7 +157,10 @@ changes — testable headless by snapshotting rendered frames. Carried from the design spec's open-questions list — none block sub-project 2: - **Serial protocol framing** between Arduino and Pi (needed before 3 ⇄ 4). -- **Player stack** on the Pi (mpv / ffmpeg / custom). -- **Side walls** on the primary Pi vs. a second Pi. +- **Player stack** on the Pi (mpv / ffmpeg / custom) and how the single panoramic + output is driven. - **`approved`-only enforcement** in the player. -- **Media storage layout** on the drive (how `file_path` values are rooted). +- ~~**Side walls** on the primary Pi vs. a second Pi~~ — resolved: side walls dropped. +- ~~**Media storage layout** on the drive~~ — settled by the sub-project-2 spec + §6.3: media under a `media-root`, `file_path` stored relative to it; the player + joins it with its drive mount. diff --git a/docs/superpowers/specs/2026-06-04-human-experience-filter-design.md b/docs/superpowers/specs/2026-06-04-human-experience-filter-design.md index 7391026..8ae31fb 100644 --- a/docs/superpowers/specs/2026-06-04-human-experience-filter-design.md +++ b/docs/superpowers/specs/2026-06-04-human-experience-filter-design.md @@ -4,15 +4,26 @@ **Status:** Approved design (pre-implementation) **Repo:** `human-experience-filter-art` +> **Revision — 2026-06-04 (display architecture):** the display moved from *four +> projectors (one per wall) + a procedural side-wall renderer* to a **single +> panoramic projector spanning the three walls the viewer faces, showing the real +> selected video** (launch content focus: **nature video**). This supersedes the +> original §6 (four projectors) and **removes §7 (procedural side walls)**, and +> reshapes the roadmap's sub-project 3 (player drives one pano output) and +> sub-project 5 (procedural side walls — **dropped**). Affected sections below are +> updated in place and marked. The coordinate model (§2), selection (§3), and +> catalog (§4) are unchanged. + --- ## 1. What this is -A single-viewer immersive art installation. One person sits in a chair at the -center of a small room with four walls, each fronted by a projector. A DJ-style -control panel lets them "tune" their experience along a small set of felt axes; -the system finds the public-domain media nearest that tuning and plays it. The -piece is an *experience filter*: the viewer dials in how they want to feel and +A single-viewer immersive art installation. One person sits in a chair in a small +room; a **single panoramic projector wraps the real selected video across the +three walls they face**. A DJ-style control panel lets them "tune" their +experience along a small set of felt axes; the system finds the public-domain +media nearest that tuning and plays it (launch content focus: **nature video**). +The piece is an *experience filter*: the viewer dials in how they want to feel and think, and the room answers with found human artifacts that match. Design constraints that shaped everything below: @@ -160,24 +171,37 @@ cannot decode HD video or drive projectors. - **Raspberry Pi 5 (or small mini-PC) — brain + player.** Holds the catalog, reads the Arduino's serial stream, runs the selection algorithm, and plays media. **The hard drive plugs into the Pi**, not the Arduino. -- **Projectors.** The Pi drives the **primary** wall (the wall the viewer faces) - with real content. The three **side walls** show procedural ambient (§7), - driven from the same Pi's additional outputs or a second cheap Pi. +- **Projector (single, panoramic).** *Revised 2026-06-04.* The Pi drives **one + panoramic projector that spans the three walls the viewer faces**, showing the + real selected video across the whole field. There is no longer a primary/side + split and no procedural side-wall renderer (the former §7). This both simplifies + the hardware (one output, one projector) and removes the need to *compute* + `dominant_color` for ambient walls. -Parts delta vs. the original sketch: add a ~$80 Pi; everything else -(Arduino, knobs, hard drive, projectors) stays. +Parts delta vs. the original sketch: add a ~$80 Pi and use a single panoramic +(ultra-wide / short-throw) projector instead of four; everything else (Arduino, +knobs, hard drive) stays. --- -## 7. Procedural side walls +## 7. ~~Procedural side walls~~ — REMOVED (2026-06-04) -The three non-primary walls render a slow gradient / color wash: +**Superseded by the §6 single-panoramic-projector revision.** The three walls the +viewer faces now show the **real** selected video (the pano projector spans them), +so there is no separate procedural ambient renderer. The mood axis is felt through +the chosen content itself rather than a synthetic side-wall wash. -- **Hue** comes from the playing piece's `dominant_color`. -- **Brightness** tracks the Dark / Light knobs. +Consequences: -This costs near-zero storage and makes the mood axis physically felt in -peripheral vision. In `None` mode the side walls also fade to black. +- **Sub-project 5 (procedural side walls) is dropped** from the roadmap. +- `dominant_color` loses its only consumer; computing it becomes **optional / + opt-in** in the ingest tooling (sub-project 2 spec §5.2) rather than a required + mechanical tag. The field stays in the catalog schema (unused-but-harmless, + default `""`) for a possible future ambient/lighting use. + +> *Original intent (for the record): the three non-primary walls rendered a slow +> color wash — hue from the playing piece's `dominant_color`, brightness from the +> Dark/Light knobs — to make the mood axis felt in peripheral vision.* --- @@ -218,14 +242,18 @@ defensible. ## 10. Repo layout ``` +hef/ shared library: catalog model + selection (sub-project 1, built) catalog/ the tagged content catalog (JSONL) -player/ selection algorithm + media player (runs on the Pi) +player/ media player driving the single panoramic projector (runs on the Pi) firmware/ Arduino sketch (reads knobs/selector → USB serial) -sidewalls/ procedural ambient renderer -tools/ sourcing/ingest, dominant-color, license checker, review tool +tools/ sourcing/ingest, mechanical tagging, review tool (sub-project 2) docs/ this spec + operator/build guide ``` +*(Revised 2026-06-04: `sidewalls/` removed with §7; the selection algorithm +shipped in the shared `hef/` package, not under `player/`, since the tools import +it too — see the sub-project-1 plan.)* + --- ## 11. Explicitly out of scope (YAGNI) @@ -240,9 +268,13 @@ docs/ this spec + operator/build guide ## 12. Open implementation questions (for the plan, not blockers) -- Player stack on the Pi (e.g. mpv/ffmpeg-based vs. a custom renderer) and how - crossfades are handled. +- Player stack on the Pi (e.g. mpv/ffmpeg-based vs. a custom renderer), how + crossfades are handled, and how a single wide/panoramic output is driven (one + ultra-wide surface vs. spanned displays). - Exact serial protocol/framing between Arduino and Pi. -- Whether side walls run on the primary Pi's extra outputs or a second Pi. -- Ingest tooling language and where the per-archive downloaders live. - Whether the player hard-restricts to `approved` records. +- ~~Whether side walls run on the primary Pi's extra outputs or a second Pi~~ — + resolved: no procedural side walls (§7 removed). +- ~~Ingest tooling language and where the per-archive downloaders live~~ — + resolved by the sub-project-2 spec: Python under `tools/`, per-archive fetchers + in `tools/ingest/`. diff --git a/docs/superpowers/specs/2026-06-04-ingest-tagging-review-tools.md b/docs/superpowers/specs/2026-06-04-ingest-tagging-review-tools.md index 29b180d..3d3359b 100644 --- a/docs/superpowers/specs/2026-06-04-ingest-tagging-review-tools.md +++ b/docs/superpowers/specs/2026-06-04-ingest-tagging-review-tools.md @@ -538,11 +538,11 @@ needed for the done-criteria. decision to use a **single panoramic projector spanning all three walls, showing real nature video**, supersedes the design spec's §6 (four projectors) / §7 (procedural side-wall renderer) and reshapes sub-projects **3** (player drives one -pano output, not primary + side feed) and **5** (procedural side walls likely -dropped). The design spec -(`2026-06-04-human-experience-filter-design.md`) and ROADMAP should be updated to -reflect this in a separate pass; it is **out of scope for the sub-project-2 spec**, -whose only affected element is the now-optional `dominant_color` (§5.2). +pano output, not primary + side feed) and **5** (procedural side walls +**dropped**). The design spec +(`2026-06-04-human-experience-filter-design.md` §6/§7) and ROADMAP were updated +this session to reflect this. The only element affecting the sub-project-2 spec +itself is the now-optional `dominant_color` (§5.2). ---