Repository navigation
feat: projector fixture kind, interleaved 12×2 layout, dormant projector control API - #152
Conversation
…tor control API Cannon | projector fixture kind in layout and routing (projectors must route to BEYOND; FB4 OSC colour is a persistent setting), interleavedLayout with a vertical stagger and the interleaved-12x2 preset, projector squares on the UI/desktop canvases, and a dormant BEYOND zone livecontrol + cue API behind OutputAdapter.sendProjector/sendCue with a server/receiver command relay.
|
I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".
|
|
Review complete. 🟠 1 high · 🟡 3 medium 💬 Inline comments (4)
The change introduces a new interleaved layout generator (
Reviewed commit: 871c274 |
There was a problem hiding this comment.
This PR adds interleaved projector+cannon layout generation with staggered rows, kind-aware unified routing validation, BEYOND projector-cue OSC encoding, shard-aware projector control re-basing in the receiver, and desktop UI rendering of projector fixtures.
Key findings
- 🟠 Projector controls leak across BEYOND targets — osc-adapters.ts:537
- 🟡 Validate
firstkind ininterleavedLayout— generators.ts:134 - 🟡 NaN projector controls clamp to range minimum — osc-adapters.ts:197
- 🟡 Malformed cue command falls through to StopAllNow — server.ts:910
| const other: FixtureKind = first === 'cannon' ? 'projector' : 'cannon'; | ||
| const cx = (cols - 1) / 2; | ||
| const cy = (rows - 1) / 2; | ||
| const raw: RawFixture[] = []; | ||
| for (let r = 0; r < rows; r++) { | ||
| for (let c = 0; c < cols; c++) { | ||
| const kind = c % 2 === 0 ? first : other; | ||
| const drop = kind === 'projector' ? stagger : 0; | ||
| raw.push({ x: c - cx, y: r - cy + drop, row: r, col: c, label: `${r}:${c}`, kind }); |
There was a problem hiding this comment.
🟡 bug · medium
Validate first kind in interleavedLayout
interleavedLayout validates cols/rows/stagger but never validates first (packages/layout/src/generators.ts:134): any string other than exactly 'cannon' makes other compute to 'cannon' while even columns silently receive the raw value as their Fixture.kind. Since resolveLayout forwards spec.first straight from user-authored JSON config or IPC (packages/layout/src/presets.ts:98-105), a typo like "cannonn" persists an invalid kind into every even-column fixture, and downstream === 'projector' checks misclassify them.
📋 Prompt for AI Agents
In packages/layout/src/generators.ts, inside interleavedLayout (around lines 129-133), add a validation immediately after the stagger check: throw an Error when first is neither 'cannon' nor 'projector', mirroring the message style of the stagger validation. This is needed because first arrives from unvalidated config JSON via resolveLayout (packages/layout/src/presets.ts ~line 98), and without the check a typo like 'cannonn' becomes the kind of every even-column fixture, leaking an invalid FixtureKind into layouts, receivers, and the UI.
| function clamp(v: number, [lo, hi]: [number, number]): number { | ||
| if (!Number.isFinite(v)) return lo; | ||
| return Math.min(hi, Math.max(lo, v)); | ||
| } |
There was a problem hiding this comment.
🟡 bug · medium
NaN projector controls clamp to range minimum
clamp returns lo for any non-finite value (packages/osc/src/osc-adapters.ts:197-200), so a non-finite control produced upstream (pattern math, or an unvalidated wire value reaching the receiver) is encoded as the most extreme command in its range: posx: NaN emits -32768 slamming the scanning head to a corner, size: NaN sends -400, scanrate: NaN sends 10, and a NaN fx slot becomes -1, which stops a running BEYOND effect (osc-adapters.ts:219, 223). These are valid, physically meaningful commands, so the corruption is invisible at the protocol level and reaches the projector.
📋 Prompt for AI Agents
In packages/osc/src/osc-adapters.ts, change the encoding loop in encodeBeyondProjectorMessages (lines 216-225): for scalar controls (lines 217-219), skip the field with continue when !Number.isFinite(v) instead of calling clamp (which currently maps NaN to the range minimum, e.g. size -400, scanrate 10). For fx slots (lines 222-224), skip the slot when !Number.isFinite(v) before the Math.round/clamp, since NaN currently clamps to -1 which stops a running BEYOND effect. Keep clamping for finite out-of-range values.
| case 'projector_cue': | ||
| if (msg.command && typeof msg.command === 'object') { | ||
| broadcastCommand({ action: 'projector_cue', command: msg.command }); | ||
| } |
There was a problem hiding this comment.
🟡 bug · medium
Malformed cue command falls through to StopAllNow
The server relays projector_cue after only checking typeof msg.command === 'object' (packages/server/src/server.ts:910-913), and the receiver passes it straight to BeyondOscOutput.sendCue. In encodeBeyondCueMessage (osc-adapters.ts:231-238), any object matching none of the three variants — e.g. {foo: 1} or {cueDown: {}} with missing fields — falls through to the StopAllNow branch, immediately stopping every laser in the show, and a cueDown with non-numeric page/cue sends NaN int32 args. A malformed client message therefore has a destructive default instead of being rejected.
📋 Prompt for AI Agents
In packages/server/src/server.ts around lines 910-913, in the case 'projector_cue': handler, replace the bare typeof msg.command === 'object' check with structural validation: accept only {cueDown:{page:number,cue:number}}, {stopZone:number}, or {stopAllNow:true} with finite numbers, and ignore anything else (optionally export an isValidProjectorCueCommand guard from @wavegrid/osc next to ProjectorCueCommand and use it in both server and receiver). This prevents a malformed command from falling through encodeBeyondCueMessage's default branch in packages/osc/src/osc-adapters.ts:231-238, which sends a destructive /beyond/general/StopAllNow.
| sendProjector(controls: Record<number, ProjectorControl>): void { | ||
| const filtered: Record<number, ProjectorControl> = {}; | ||
| for (const [key, control] of Object.entries(controls)) { | ||
| const idx = Number(key); | ||
| if (this.projectorIndices.has(idx)) filtered[idx] = control; | ||
| } | ||
| if (Object.keys(filtered).length === 0) return; | ||
| for (const adapter of this.beyondAdapters) adapter.sendProjector(filtered); | ||
| } |
There was a problem hiding this comment.
🟠 bug · high
Projector controls leak across BEYOND targets
RoutedOscOutput.sendProjector filters controls by a single global projectorIndices set and broadcasts the filtered map to ALL beyond adapters (packages/osc/src/osc-adapters.ts:537-545); each adapter re-filters only by its own projectorMap (osc-adapters.ts:287). With two BEYOND targets, a control intended for a projector on target A is also delivered to target B whenever B has any route with the same logical index — including an ordinary cannon route, whose logical index is in B's projectorMap — so B's zone receives livecontrol size/posx/rotz commands meant for a different fixture on a different machine.
📋 Prompt for AI Agents
In packages/osc/src/osc-adapters.ts, RoutedOscOutput (constructor lines 482-507 and sendProjector lines 537-545): replace the flat projectorIndices: Set<number> with a per-target mapping, e.g. projectorIndicesByTarget: Map<string, Set<number>>, populated in the constructor only when cannon.kind === 'projector' AND the cannon lands in beyondMaps[cannon.target]. In sendProjector, for each beyond target, build the filtered subset of controls whose logical index is in that target's projector set and pass only that subset to that target's adapter (store the target name alongside each adapter). Update the projectorLogicals getter accordingly.
|
Local test drive (Electron desktop + browser artist UI + real loopback UDP OSC listener on 127.0.0.1:8000; no laser hardware).
OSC captured on the wire:
|
A wide layout (12x2) now fills the canvas width and keeps its row spacing instead of being stretched to a square, so the 24 fixtures sit in one contiguous finger-paintable band. Projector stagger default drops from 0.35 to 0.15 cells so the rows read as two rows, not four.
Summary
First step for mixed cannon + projector shows (Nu-Salt NSL-2000 Model Z, Pangolin FB4-XE). Plan: constructive-planning #2501 (this PR = #2502 + #2503).
Fixture kind.
FixtureKind = 'cannon' | 'projector'on layoutFixture.kind(defaultcannon, so every existing preset/layout is unchanged) and onUnifiedCannon/DeviceCannon/CannonRoute.kind, carried through routing generation to the receiver.validateUnifiedRoutingnow rejects a projector on anfb4target: the FB4color_*OSC addresses are the box's persistent colour-balance settings, not live colour, and would silently detune a calibrated projector. Projectors route to BEYOND like everything else — colour + brightness already work through the existing/beyond/zone/{n}/livecontrol/{red,green,blue,alpha,Brightness}path, so the HSB pipeline (server, receiver, UI tabs) is untouched.Interleaved layout for Saturday.
interleavedLayout({ cols, rows, stagger = 0.15, first = 'cannon' }): even columns one kind, odd columns the other, projectors offsetstaggercells below their row so the two kinds read apart while the rows still read as rows. Row-major indices,row/colare the plain grid's (topology: 'grid',hasGridCoords), so grid animations, shift and brush behave exactly as on a grid. Presetinterleaved-12x2(12 cannons + 12 projectors), shorthandinterleaved:12x2, spec{ kind: 'interleaved', cols, rows, stagger?, first? }.examples/routing-interleaved-12x2.json. The artist UIGridDisplay, the desktop light-map canvas andFixtureRowdraw projectors as rounded squares instead of orbs.Aspect-aware canvas.
GridDisplaynow sizes its canvas to the layout's aspect ratio when fixtures carry worldx/y(square grids and rings are unchanged, ±15% tolerance keeps them square). A 12×2 band fills the width and keeps its row spacing instead of being stretched to a square, so all 24 fixtures sit in one contiguous finger-paintable strip with the classic orb-to-cell ratio. Hit-testing and the rotate/flip inverse use the canvas height fory.Dormant projector control API (no UI). In
@wavegrid/osc:RoutedOscOutput.sendProjectordrops any index whose route is notkind: 'projector', so a cannon can never be resized/moved. Wire: client{ type: 'projector', indices, control }/{ type: 'projector_cue', command }→ server keeps onlylayout.fixtures[i].kind === 'projector'→commandrelay → receiver re-bases global indices to its shard →output.sendProjector. Documented indocs/command-api.md.EnableLaserOutput/DisableLaserOutput/BlackOutdeliberately not exposed.Tests: interleaved generator (counts, kinds, stagger, indices), spec parsing/preset, routing kind carry-through + projector-on-FB4 error, projector/cue encoders with clamping, routed filter. Runtime test drive with loopback OSC in the PR comments.
Link to Devin session: https://app.devin.ai/sessions/e6939c79261649988b8277ba34725160
Open in Devin Desktop: https://app.devin.ai/desktop/session/e6939c79261649988b8277ba34725160?variant=devin
Requested by: @pyramation