timothy/mapper
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit of my folder

Browse Source
This commit is contained in:
Timothy
2026-03-10 20:41:46 +00:00
parent 37becee76a
commit 7ad88804f3
1225 changed files with 238706 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
openspec/changes/mpvj-headless-control-center/.openspec.yaml Normal file
View File

@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-03-10

39
openspec/changes/mpvj-headless-control-center/design.md Normal file
View File

@ -0,0 +1,39 @@
## Context
The project aims to modernize the control interface for `ofxPiMapper` on the Raspberry Pi 3B. Currently, users rely on legacy PHP scripts (PocketVJ) or a local monitor/keyboard. The Pi 3B has significant resource constraints (1GB RAM, older CPU), requiring a highly efficient headless solution.
## Goals / Non-Goals
**Goals:**
- Provide a responsive, headless mapping UI accessible via browser.
- Enable real-time remote manipulation of mapping surfaces via OSC.
- Implement a robust system for media management and system monitoring.
- Ensure the system is lightweight enough to run alongside `ofxPiMapper` on a Pi 3B.
**Non-Goals:**
- **Automatic Calibration**: Computer-vision based auto-mapping is explicitly out of scope for this version.
- **Multi-Projector Sync**: Synchronizing multiple Pi units is not part of this design.
- **Advanced Video Effects**: Real-time shaders or complex video processing beyond what `ofxPiMapper` provides.
## Decisions
### 1. Technology Stack
- **Frontend**: React (using Vite for fast development and lean production builds).
- **Backend**: Node.js with Express. Node.js is chosen for its excellent asynchronous handling of WebSockets and its mature OSC libraries (`node-osc`).
- **Communication**: WebSockets (Socket.io) will be used for the frontend-to-backend real-time vertex updates to minimize latency compared to REST.
### 2. OSC Bridge Architecture
The Node.js server will act as a transparent bridge. It will listen for WebSocket events from the UI and immediately translate them into UDP OSC packets directed at `localhost:9999` where `ofxPiMapper` is listening.
### 3. Headless Networking
- **mDNS**: `avahi-daemon` will be configured to provide `mpvj.local` access.
- **Access Point**: `hostapd` and `dnsmasq` will be managed via shell scripts triggered by the Node.js API to allow the user to toggle between AP and Client modes.
### 4. Media Storage
Media will be stored in `/home/pi/media`. The Node.js API will provide a file-browser endpoint and handle `multipart/form-data` uploads.
## Risks / Trade-offs
- **[Risk] RAM Exhaustion on Pi 3B** → **Mitigation**: We will use a "lite" version of the React frontend (potentially Preact) and keep Node.js dependencies to a minimum. We will also monitor memory usage via the dashboard.
- **[Risk] WiFi Latency in AP Mode** → **Mitigation**: We will prioritize WebSocket traffic for vertex movements and use binary formats if necessary to reduce overhead.
- **[Risk] ofxPiMapper Crash** → **Mitigation**: The Node.js API will monitor the process and provide a "Restart Mapper" button in the UI.

29
openspec/changes/mpvj-headless-control-center/proposal.md Normal file
View File

@ -0,0 +1,29 @@
## Why
PocketVJ-CP-v3 is an essential tool for projection mapping on the Raspberry Pi, but its reliance on legacy PHP 5 and a "page-refresh" architecture makes it difficult to use for modern, real-time mapping. There is a clear opportunity to create a "Modern PocketVJ" (MPVJ) that provides a responsive, touch-friendly, and resource-efficient headless interface specifically optimized for the Raspberry Pi 3B and `ofxPiMapper`.
## What Changes
- **New Headless UI**: A React-based web interface served from the Pi, allowing users to perform mapping and media management from any phone or laptop browser.
- **Real-Time Mapping Control**: Implementation of a "Virtual Canvas" that allows dragging vertices and surfaces on the remote UI, with changes reflected instantly on the projection via OSC.
- **Modern Backend Bridge**: A Node.js-based API that replaces the legacy PHP scripts to handle OSC communication, media file management, and system commands.
- **Hybrid Networking**: Automated setup of a WiFi Access Point (AP) for standalone use, with the ability to switch to Client Mode for existing venue networks.
- **System Monitoring**: Integrated dashboard for tracking Pi 3B resource usage (CPU, RAM, Temperature) to ensure stability during high-resolution playback.
## Capabilities
### New Capabilities
- `headless-mapping-ui`: A responsive React web application providing a virtual stage for remote surface manipulation and layout control.
- `osc-bridge-api`: A high-performance Node.js service that translates UI interactions into standard `ofxPiMapper` OSC commands.
- `media-manager`: An integrated system for uploading, previewing, and assigning media files (videos, images) to specific mapping surfaces.
- `hybrid-network-control`: A system-level capability to toggle between Access Point and WiFi Client modes via the web interface.
### Modified Capabilities
- (None)
## Impact
- **ofxPiMapper**: Direct integration via OSC port 9999 for real-time control.
- **Networking**: Requires `hostapd`, `dnsmasq`, and `avahi-daemon` for AP and mDNS support.
- **Resource Management**: Tight constraints on Pi 3B (1GB RAM) require a lightweight Node.js environment and optimized React build.
- **File System**: Management of media assets in `/home/pi/media`.

22
openspec/changes/mpvj-headless-control-center/specs/headless-mapping-ui/spec.md Normal file
View File

@ -0,0 +1,22 @@
## ADDED Requirements
### Requirement: Remote Virtual Canvas
The system SHALL provide a web-based "Virtual Canvas" that represents the projection area and allows the user to manipulate mapping surfaces (Quads and Triangles).
#### Scenario: Dragging a vertex
- **WHEN** the user drags a vertex on the web UI
- **THEN** the UI SHALL calculate the normalized (0.0 to 1.0) coordinates and send them to the backend API
### Requirement: Surface Selection
The system SHALL allow the user to select, add, and delete mapping surfaces (Quads and Triangles) from the remote interface.
#### Scenario: Adding a new Quad
- **WHEN** the user clicks the "Add Quad" button in the UI
- **THEN** the UI SHALL send a command to the backend to create a new quad surface in `ofxPiMapper`
### Requirement: Real-time Feedback
The web UI SHALL provide visual feedback for the selected surface and vertex to ensure the user knows which part of the mapping is being edited.
#### Scenario: Selecting a surface
- **WHEN** the user taps on a surface in the virtual canvas
- **THEN** the UI SHALL highlight that surface and display its specific transformation controls

22
openspec/changes/mpvj-headless-control-center/specs/hybrid-network-control/spec.md Normal file
View File

@ -0,0 +1,22 @@
## ADDED Requirements
### Requirement: Automated Access Point Creation
The system SHALL create a password-protected WiFi Access Point (AP) if no other network connection is established.
#### Scenario: AP Mode Activation
- **WHEN** the Raspberry Pi 3B boots and no configured WiFi Client networks are found
- **THEN** the system SHALL start `hostapd` and `dnsmasq` to create a `MPVJ-3B-XXXX` network
### Requirement: WiFi Client Connection
The system SHALL provide a web-based UI to scan for available WiFi networks and allow the user to join an existing network.
#### Scenario: Switching to Client Mode
- **WHEN** the user selects a WiFi SSID from the UI and provides a password
- **THEN** the system SHALL update the `/etc/wpa_supplicant/wpa_supplicant.conf` file and restart the network interface to join that network
### Requirement: mDNS Support
The system SHALL be accessible via the `mpvj.local` address on any local network it is connected to.
#### Scenario: Navigating to the UI
- **WHEN** the user types `http://mpvj.local` in their browser on a connected device
- **THEN** the system SHALL resolve to the Raspberry Pi's IP address and load the mapping interface

15
openspec/changes/mpvj-headless-control-center/specs/media-manager/spec.md Normal file
View File

@ -0,0 +1,15 @@
## ADDED Requirements
### Requirement: Media Upload
The system SHALL provide a web-based media upload feature to allow users to transfer videos and images from their mobile devices or laptops to the Raspberry Pi.
#### Scenario: Successful video upload
- **WHEN** the user selects a `.mp4` file and clicks "Upload"
- **THEN** the system SHALL save the file to `/home/pi/media` and make it available for mapping
### Requirement: Surface Source Assignment
The system SHALL allow the user to assign a specific media file from the library to a selected mapping surface in real-time.
#### Scenario: Assigning an image
- **WHEN** the user selects an image from the "Media Library" in the UI
- **THEN** the backend SHALL send an `/ofxPiMapper/source/set <filename>` OSC message to update the projection

22
openspec/changes/mpvj-headless-control-center/specs/osc-bridge-api/spec.md Normal file
View File

@ -0,0 +1,22 @@
## ADDED Requirements
### Requirement: OSC Command Translation
The system SHALL provide a backend API that receives HTTP/WebSocket commands from the frontend and translates them into OSC (Open Sound Control) messages for `ofxPiMapper`.
#### Scenario: Vertex movement command
- **WHEN** the API receives a `/vertex/move` request with (x, y) coordinates
- **THEN** it SHALL send an OSC message to `localhost:9999` using the `/ofxPiMapper/vertex/move` address
### Requirement: Service Management
The system SHALL provide endpoints to start, stop, and restart the `ofxPiMapper` application process.
#### Scenario: Starting the mapper
- **WHEN** the user triggers the "Start Mapper" action in the UI
- **THEN** the API SHALL execute the system-level command `ofxPiMapper -f` (fullscreen) and return the process status
### Requirement: Real-time Status Monitoring
The system SHALL monitor the Raspberry Pi 3B's system health (CPU, RAM, and temperature) and provide this data to the frontend for real-time visualization.
#### Scenario: Polling system health
- **WHEN** the API is requested for health status
- **THEN** it SHALL query `/proc/loadavg`, `/proc/meminfo`, and `/sys/class/thermal/thermal_zone0/temp` and return a JSON status object

31
openspec/changes/mpvj-headless-control-center/tasks.md Normal file
View File

@ -0,0 +1,31 @@
## 1. Backend Setup & OSC Bridge
- [x] 1.1 Initialize Node.js project and install dependencies (`express`, `node-osc`, `socket.io`, `systeminformation`).
- [x] 1.2 Implement the OSC Client to send messages to `localhost:9999`.
- [x] 1.3 Create WebSocket handlers for real-time vertex and surface manipulation events.
- [x] 1.4 Add API endpoints for `ofxPiMapper` process management (start/stop/restart).
## 2. Media & System API
- [x] 2.1 Implement the Media Manager API for listing, uploading, and deleting files in `/home/pi/media`.
- [x] 2.2 Create the System Monitor API to poll and return CPU, RAM, and Temperature data.
- [x] 2.3 Implement the OSC `/source/set` endpoint for remote media assignment.
## 3. Frontend Scaffolding & Virtual Canvas
- [x] 3.1 Scaffold React/Vite project with Tailwind CSS.
- [x] 3.2 Implement the "Virtual Canvas" component using HTML5 Canvas or SVG to represent the projection area.
- [x] 3.3 Add interactive surface manipulation (Quad/Triangle) with touch/drag support.
- [x] 3.4 Integrate Socket.io client to pipe vertex movements to the backend in real-time.
## 4. Networking & Headless Config
- [x] 4.1 Create shell scripts for toggling between Access Point and Client Mode.
- [x] 4.2 Implement the Networking UI in React for WiFi scanning and connection management.
- [x] 4.3 Configure `avahi-daemon` to provide `mpvj.local` mDNS access.
## 5. Integration & Deployment
- [x] 5.1 Create a `systemd` service for the MPVJ backend to ensure it starts on boot.
- [x] 5.2 Build the React frontend and configure Express to serve static files.
- [x] 5.3 Conduct end-to-end testing of mapping, media assignment, and WiFi switching.

20
openspec/config.yaml Normal file
View File

@ -0,0 +1,20 @@
schema: spec-driven
# Project context (optional)
# This is shown to AI when creating artifacts.
# Add your tech stack, conventions, style guides, domain knowledge, etc.
# Example:
# context: |
# Tech stack: TypeScript, React, Node.js
# We use conventional commits
# Domain: e-commerce platform
# Per-artifact rules (optional)
# Add custom rules for specific artifacts.
# Example:
# rules:
# proposal:
# - Keep proposals under 500 words
# - Always include a "Non-goals" section
# tasks:
# - Break tasks into chunks of max 2 hours