timothy/mapper
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
mapper/openspec/changes/ofxpimapper-full-stack/proposal.md
Timothy Hofland 158e6a204f feat: add ofxpimapper-full-stack OpenSpec artifacts 
Comprehensive blueprint for a headless Raspberry Pi 3B projection mapping appliance:
- Unified installer with 2GB swap safety for C++ source builds.
- WebSocket-driven real-time vertex/surface manipulation.
- 5-tab responsive dashboard (Dashboard, Mapping, Media, Network, System).
- Media validation with ffprobe (H.264 check) and resource warnings.
- Throttled log streaming and explicit mapping persistence.
2026-03-10 22:34:02 +01:00

2.6 KiB
Raw Permalink Blame History

Why

Currently, setting up a Raspberry Pi for projection mapping requires manually piecing together the OS, the mapping engine (ofxPiMapper), and various control scripts. This is fragmented, difficult to manage headlessly, and lacks a modern "appliance" feel. ofxpimapper-full-stack aims to unify these into a single, polished, and professional product: the Modern PocketVJ (MPVJ). It provides an "it just works" experience for artists, from the initial setup script to the real-time web-based mapping remote.

What Changes

  • Unified Headless Installer: A single setup script that installs the entire stack, including the ofxPiMapper engine, Node.js backend, and React frontend.
  • Integrated Mapping Engine: Automated installation of ofxPiMapper (pre-compiled binary or source build) with a systemd service to launch fullscreen on boot.
  • Virtual Canvas 2.0: A responsive React/Tailwind web UI for real-time vertex/surface manipulation via WebSockets, with live feedback on the beamer.
  • Enhanced Media Vault: Complete media management (upload/delete/preview) with the ability to assign different sources (video/image/color) to individual surfaces.
  • Appliance Dashboard: Integrated monitoring of system health (CPU, RAM, Temp) and process status, with remote power and restart controls.
  • Hybrid Networking: A robust networking stack that maintains a permanent Access Point while allowing connection to external venue WiFi via a web interface.

Capabilities

New Capabilities

  • ofxpimapper-engine: The core C++ mapping engine, integrated into the system-wide process management.
  • web-remote-dashboard: A modern, responsive TUI-inspired web interface for full system control.
  • media-source-assignment: The ability to dynamically map specific files or colors to specific geometric surfaces.
  • live-logs-streaming: Real-time streaming of system and mapper logs to the web interface.

Modified Capabilities

  • headless-installer: Upgraded to handle the C++ engine installation and graphics driver configuration.
  • osc-bridge-api: Expanded to handle naming, surface selection highlighting, and source assignment.
  • hybrid-network-control: Updated with a scan-and-connect web UI while preserving the AP.

Impact

  • Hardware: Strictly optimized for the Raspberry Pi 3B (1GB RAM).
  • User Experience: Transition from a "CLI-first" or "Desktop-first" workflow to a "Web-Remote-first" workflow.
  • Performance: Heavy reliance on WebSockets and optimized C++ binaries to ensure low-latency interaction.
  • Stability: Automated swap management and process monitoring to prevent OOM crashes during high-resolution playback.