Projection Mapping für den MacBook-Beamer-Einsatz – als echte Mac-App in Rust, ohne Browser und ohne Server. Gezeichnet wird über Metal (wgpu), die Bedienoberfläche ist mit egui gebaut. Open Source (MIT).
Die Web-Version liegt weiter unter HOAI-droid/Projection-Mapping; Projektdateien (JSON) lassen sich zwischen beiden Versionen austauschen.
- Zwei Fenster: Steuerung auf dem Mac, Ausgabe auf dem Beamer (auf den Beamer ziehen, F = Vollbild – beim nächsten Start erscheint die Ausgabe dort automatisch wieder)
- Flächen: Viereck mit exaktem Corner Pin (Perspektive pro Pixel), Kreis, Dreieck und Verzerrungsgitter (bis 16×16, weich interpoliert) für gewölbte Objekte
- Masken auf Masken wie in MadMapper: Flächenmasken (hinzufügen / ausschneiden / Schnittmenge, mit weicher Kante) wandern mit der Fläche mit; Masken-Ebenen schneiden aus allen Ebenen darunter aus
- Freihand zeichnen oder Punkt für Punkt, Snap (standardmäßig an) an Ecken, Punkten, Kanten und Bildrand
- Raster über den Flächen mit einstellbarer Linienstärke, Testbild auf der Fläche, Kalibriergitter und Weißbild
- 41 Effekte (Feuer, Lichter, Strobe, Disco, Laser, Kantenlauf, Wasser, Matrix, Musik-Visualisierungen …)
- Bilder (auch HEIC vom iPhone) und Videos (Hardware-Dekodierung), Einpassen/Füllen/Strecken
- Live-Kamera (MacBook-Kamera, iPhone über Continuity, USB-/HDMI-Grabber)
- Audio-Reaktivität: Mikrofon/Audio-Eingang (auch BlackHole für den Mac-Ton) oder eingebauter Player; Spektrum, Beat-Erkennung, Tempo, Tap; jeder Effekt-Regler und die Deckkraft lassen sich an die Musik koppeln
- Milkdrop – die originalen Winamp-Visualisierungen über projectM (~10 000 Presets per Knopfdruck)
- Preset-Browser: Effekte nach Kategorien, Milkdrop nach Themen ▸ Unterthemen, Suche, Favoriten ★ und „Empfohlen“ (Klassiker + je ein Beispiel pro Unterthema); automatisches Weiterschalten innerhalb eines Bereichs
- Ausgabeauflösung je Projekt: automatisch (nach Beamer) oder fest (720p … 4K oder eigene Größe) – siehe unten
- Mischmodi, Deckkraft, Blackout, Gesamthelligkeit, Rückgängig/Wiederholen, automatisches Sichern
- Für Agenten: alle Funktionen als Befehle – Kommandozeile, lokaler Steuerkanal und MCP-Server (siehe unten)
- Neues Design im Stil professioneller Grafikprogramme (Menüleiste, Options-, Werkzeug- und Statusleiste, Panels mit Reitern, Schrift Inter, Linien-Icons, Adobe-Blau)
- Browser für Effekte und Milkdrop-Presets mit Themen, Unterthemen, Favoriten und „Empfohlen“
- Ausgabeauflösung im Projekt (Datei → Projekteinstellungen oder Klick auf die Auflösung unten links)
- Befehlsregister, Kommandozeile, Steuerkanal und MCP-Server für Agenten
-
Unter Releases → neueste Version
ProjectionMapping-macOS.zipherunterladen und entpacken. -
„Projection Mapping.app“ in den Ordner Programme ziehen.
-
Die App ist nicht von Apple notarisiert (dafür bräuchte es ein kostenpflichtiges Entwicklerkonto). Beim ersten Start daher einmal im Terminal:
xattr -dr com.apple.quarantine "/Applications/Projection Mapping.app"(alternativ: Rechtsklick → Öffnen, bzw. Systemeinstellungen → Datenschutz & Sicherheit → „Trotzdem öffnen“).
-
Für Videos, Kamera und den Musik-Player wird ffmpeg gebraucht (einmalig):
brew install ffmpeg
projectM (Milkdrop) ist in der App enthalten.
Voraussetzungen: Xcode-Kommandozeilenwerkzeuge (xcode-select --install), Rust (https://rustup.rs),
brew install cmake ffmpeg.
git clone https://github.com/HOAI-droid/Projection-Mapping-Native.git
cd Projection-Mapping-Native
./scripts/build-macos.sh
open "dist/Projection Mapping.app"
Zum Entwickeln reicht cargo run --release (Milkdrop dann mit
PM_PROJECTM_LIB=build/projectm/lib/libprojectM-4.dylib, nachdem das Skript projectM einmal gebaut hat).
Tests: cargo test (inkl. GPU-Tests, die echte Szenen zeichnen und Pixel prüfen; alle Shader werden auch nach
Metal übersetzt). Die GitHub-Action baut die App auf einem Mac, testet sie dort mit Metal und legt sie unter
„Releases“ ab.
| Taste | Wirkung |
|---|---|
| E | Bearbeiten ↔ Show (Umrisse/Griffe auf der Ausgabe ein/aus) |
| F | Ausgabe öffnen / Vollbild |
| V / M | Werkzeug Fläche / Maske |
| S | Snap ein/aus (⌥ beim Ziehen: ohne Snap) |
| G / ⇧G | Raster auf den Flächen / Kalibriergitter über das ganze Bild |
| B | Blackout |
| T | Tap-Tempo |
| Pfeile | Ecke/Fläche/Punkt 1 px (mit ⇧ 10 px) |
| Tab | nächste Ecke bzw. nächster Maskenpunkt |
| Entf / Enter / Esc | Punkt löschen / Maske fertig / Auswahl aufheben |
| ⌘Z / ⇧⌘Z | Rückgängig / Wiederholen |
| ⌘S / ⇧⌘S / ⌘O | Speichern / Speichern unter / Öffnen |
| Pinch / ⌥ + Scrollen | gewählte Fläche skalieren / drehen |
Bilder, Videos und Musik lassen sich einfach ins Fenster ziehen.
Ton vom Mac (Spotify, Apple Music, YouTube …) als Quelle: brew install blackhole-2ch, in der
Audio-MIDI-Konfiguration ein Multi-Ausgabegerät aus Lautsprechern + „BlackHole 2ch“ anlegen und es als Ausgabe
wählen; in der App unter Audio → Eingang „BlackHole 2ch“ wählen.
Unter Datei → Projekteinstellungen (oder Klick auf die Auflösung in der Statusleiste):
- Automatisch – das Projekt richtet sich nach dem Ausgabefenster bzw. Beamer.
- Fest – z. B. 1920 × 1080, 1280 × 800 (WXGA), 1024 × 768 (XGA), 4K oder eine eigene Größe. Das Bild wird in jedes Ausgabefenster eingepasst; passt das Seitenverhältnis nicht, bleiben schwarze Ränder, und die Statusleiste weist darauf hin. „Beamer übernehmen“ setzt die Größe des geöffneten Ausgabefensters.
- Ändert sich das Seitenverhältnis, behalten die Flächen wahlweise ihre Form (Kreise bleiben rund) oder werden mitgestreckt. Die Einstellung wird im Projekt gespeichert und lässt sich jederzeit ändern (Rückgängig geht auch).
Alles, was die App kann, gibt es als benannten Befehl mit JSON-Parametern (87 Befehle, z. B.
surface.add, surface.setCorners, content.setEffect, mask.add, presets.list, output.render).
Menüs und Tastenkürzel benutzen dieselben Befehle; jeder Befehl ist ein Rückgängig-Schritt. Koordinaten sind
normiert (0…1, oben links = 0,0), mit "units": "px" in Ausgabepixeln. Flächen lassen sich per ID oder Name
ansprechen.
APP="/Applications/Projection Mapping.app/Contents/MacOS/projection-mapping"
"$APP" commands # alle Befehle (mit --json maschinenlesbar)
Kommandozeile ohne Fenster – Projekt öffnen, Befehle ausführen, speichern, Bild rendern (je Befehl eine JSON-Zeile als Ergebnis):
"$APP" run show.json -c surface.add '{"name":"Wand"}' \
-c content.setEffect '{"id":"Wand","effect":"plasma"}' --save --render vorschau.png
"$APP" run show.json --script befehle.txt # eine Zeile je Befehl: name {json}
"$APP" render show.json bild.png --width 1920
Steuerkanal zur laufenden App – standardmäßig aus. Einschalten unter Hilfe → Steuerung durch Agenten
erlauben (oder App mit --control starten). Er lauscht nur lokal (127.0.0.1) und verlangt ein zufälliges
Token aus control.json im Datenordner (nur für den eigenen Benutzer lesbar). Protokoll: eine JSON-Zeile je
Anfrage {"id":1,"token":"…","cmd":"…","params":{…}}. Am einfachsten:
"$APP" control app.state
"$APP" control surface.setCorner '{"id":"Wand","index":2,"point":{"x":1600,"y":900},"units":"px"}'
"$APP" control ui.screenshot '{"path":"steuerung.png"}'
MCP-Server (für Claude Desktop, Claude Code und andere MCP-Clients) – jeder Befehl ist ein Werkzeug
(surface_add, output_render …; Bilder kommen als Bild zurück). Läuft die App mit Steuerkanal, steuert der
Agent sie live; sonst rechnet der Server ohne Fenster (--headless, --project datei.json).
claude mcp add projection-mapping -- "/Applications/Projection Mapping.app/Contents/MacOS/projection-mapping" mcp
Claude Desktop (claude_desktop_config.json):
{ "mcpServers": { "projection-mapping": {
"command": "/Applications/Projection Mapping.app/Contents/MacOS/projection-mapping", "args": ["mcp"] } } }Alles liegt in ~/Library/Application Support/Projection Mapping/: der zuletzt bearbeitete Stand
(autosave.json), importierte Medien (media/), Milkdrop-Presets (presets/), Einstellungen (inkl. Favoriten)
und – solange der Steuerkanal an ist – control.json.
| Datei | Inhalt |
|---|---|
src/model.rs |
Datenmodell (Projektformat 4, kompatibel zur Web-Version) |
src/geometry.rs |
Homographie, Dreieck, Verzerrungsgitter, Umrisse |
src/state.rs |
Bearbeitungszustand, Rückgängig, alle Bearbeitungsaktionen |
src/render/ |
wgpu-Renderer (WGSL), Masken-Rasterung, Testbild |
src/effects.rs + assets/effects.json |
Effekt-Bibliothek (GLSL, über naga nach Metal) |
src/engine.rs |
verbindet alles: pro Bild Inhalte aktualisieren und Zeichenliste bauen |
src/media/ |
Medienbibliothek, Video und Kamera (ffmpeg) |
src/audio/ |
Audio-Eingang, Player, Analyse (FFT, Beat, BPM) |
src/milkdrop/ |
projectM (zur Laufzeit geladen) mit eigenem OpenGL-Kontext |
src/commands.rs |
Befehlsregister (alle Aktionen als Befehle mit JSON-Parametern) |
src/agent/ |
Kommandozeile, Betrieb ohne Fenster, Steuerkanal, MCP-Server |
src/milkdrop/catalog.rs |
Preset-Katalog: Themen, Unterthemen, Empfohlen |
src/ui/ |
Steuerfenster (Design in theme.rs, Browser in browser.rs), Ausgabefenster, Editor |
Eigener Code: MIT. Schrift Inter: SIL Open Font License (assets/fonts/Inter-LICENSE.txt). Icons: Phosphor (MIT).
projectM: LGPL-2.1 (als eigene Bibliothek mitgeliefert, Quelltext:
https://github.com/projectM-visualizer/projectm). Milkdrop-Presets: siehe Lizenz der jeweiligen Sammlung.