From 5d5223db9f04af23d098f4acfd5afbd75ee2ba21 Mon Sep 17 00:00:00 2001 From: hacklab Date: Mon, 27 Jul 2026 01:16:37 +0200 Subject: [PATCH] Docs del mapping (Fase 1+2) + gitignore de runtime MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/mapping.md: guia del projection mapping (activar, superficies con malla para curvar, mascaras, editar arrastrando desde el panel, dónde se guarda, limitaciones). Enlazada desde docs/README.md y el README principal. - .gitignore: ignora data/pm-fijado/ (runtime de projectM). El mapper funcional (esquinas + malla + mascaras, para Butterchurn/Hydra/ Shaders/Mezclador) ya estaba en main (Fase 1 y 2). La via de captura para projectM nativo se retira por ahora; se retoma mas adelante. Co-Authored-By: Claude Opus 4.8 (1M context) --- .gitignore | 1 + README.md | 9 ++++++ docs/README.md | 4 +++ docs/mapping.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 91 insertions(+) create mode 100644 docs/mapping.md diff --git a/.gitignore b/.gitignore index 619f3db..81f1b7a 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,7 @@ data/videos/* # Config de runtime (por instalacion): no va al repo data/mapping.json data/pm-favoritos.json +data/pm-fijado/ # Temporales *.log diff --git a/README.md b/README.md index a1c336e..e1f675a 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,8 @@ La carpeta [`docs/`](docs/) tiene la guía completa: - [Conectarse al panel](docs/conexion.md) — el código QR, `fosfeno.local` y el router. - [Uso del panel](docs/uso.md) — cómo se maneja y qué hace cada motor. +- [Projection mapping](docs/mapping.md) — deformar las visuales para encajarlas + en superficies físicas (malla, máscaras) desde el panel. - [Solución de problemas](docs/problemas.md) — qué hacer cuando algo falla. El panel además lleva un botón de información en cada apartado: explica qué @@ -63,6 +65,13 @@ Visuales de ejemplo — el motor Hydra con su editor de código en vivo: Hydra +## Projection mapping + +Las visuales web (Butterchurn, Hydra, Shaders y Mezclador) se pueden **deformar +para encajarlas en superficies físicas** desde el panel: superficies con malla +(curvas), varias a la vez y máscaras para tapar zonas, arrastrando con el ratón +o el dedo. Se guarda solo en `data/mapping.json`. Guía: [docs/mapping.md](docs/mapping.md). + ## Hardware necesario - Raspberry Pi 5 o Pi 4 + fuente oficial + microSD/SSD diff --git a/docs/README.md b/docs/README.md index efd62df..4b524f3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,6 +23,10 @@ para consultarse a saltos después. Cómo se maneja desde el móvil, qué hace cada motor de visuales y cómo se configura cada opción. +- [Projection mapping](mapping.md) + Cómo deformar las visuales para encajarlas en superficies físicas: malla, + máscaras y edición desde el panel arrastrando con el ratón o el dedo. + - [Solución de problemas](problemas.md) Qué hacer cuando algo no arranca, no se ve o no suena. Incluye cómo leer los mensajes de error que aparecen en el propio panel. diff --git a/docs/mapping.md b/docs/mapping.md new file mode 100644 index 0000000..682e3eb --- /dev/null +++ b/docs/mapping.md @@ -0,0 +1,77 @@ +# Projection mapping + +FOSFENO puede **deformar las visuales** para encajarlas en superficies físicas +(una pared en ángulo, cajas, un objeto, varias zonas de una fachada) en vez de +proyectar un simple rectángulo. Todo se hace **desde el panel**, arrastrando con +el ratón o el dedo, y se **guarda solo**. + +Se aplica a los motores que corren en el navegador: **Butterchurn, Hydra, +Shaders y Mezclador**. (projectM nativo aún no; ver [Limitaciones](#limitaciones).) + +## En 4 pasos + +1. Elige un motor que **no** sea projectM (Butterchurn, Hydra, Shaders o Mezcla). +2. En el panel, sección **Mapping**, marca **Activar mapping**. +3. Pulsa **+ Superficie**. Aparece un recuadro con las visuales en la + previsualización del panel (y en el proyector). +4. En la **previsualización** del panel, **arrastra los puntos** para encajar la + forma sobre tu superficie real. Se ve en el proyector al instante. + +## La sección Mapping del panel + +- **Activar mapping** — enciende/apaga la deformación. +- **Modo edición** — muestra u oculta los tiradores en la **ventana de las + visuales** (por si prefieres ajustar ahí con un ratón). Para el uso normal no + hace falta: con la previsualización del panel basta. +- **+ Superficie** — añade una superficie nueva (un cuadrilátero). +- **+ Máscara** — añade una **máscara**: un recuadro **negro** que tapa una zona + (útil para recortar el derrame de luz fuera de la superficie física). +- **Reset** — borra todas las superficies y máscaras. +- **Previsualización** — el recuadro donde arrastras los puntos (ratón o dedo). + Muestra una rejilla dentro de cada superficie para que veas cómo se deforma. +- **Lista** — cada superficie y máscara con su tamaño de malla y un botón **✕** + para borrarla. + +## Superficies con malla (curvar) + +Una superficie nueva es un cuadrilátero de 4 esquinas (corrección de +perspectiva / *keystone*). Para superficies **curvas**: + +1. Selecciona la superficie (toca dentro de ella en la previsualización). +2. Aparece **− malla / + malla**: cada **+ malla** la subdivide (2×2, 3×3… + hasta 6×6). +3. Ahora puedes arrastrar **cualquier punto** de la rejilla (no solo las + esquinas) para curvarla y adaptarla a superficies no planas. + +Puedes crear **varias superficies** y mapear la misma imagen en distintas zonas. + +## Máscaras + +Una máscara es un cuadrilátero **negro** que se pinta encima de todo. Sirve para +**tapar** lo que no quieres que se vea (bordes, derrames de luz, huecos entre +superficies). Añádelas con **+ Máscara** y arrastra sus esquinas igual que una +superficie. + +## Dónde se guarda + +La configuración se guarda sola en `data/mapping.json` y se mantiene al +reiniciar. Es **por instalación** (no se sube al repositorio). Para empezar de +cero, usa **Reset** o borra ese archivo. + +## Editar en la ventana de las visuales (opcional) + +Con **Modo edición** activo, los tiradores también aparecen sobre las propias +visuales. Ahí, además, funcionan atajos de teclado: + +- **doble clic** en un hueco: crea una superficie nueva. +- **+ / −**: subdivide/reduce la malla de la superficie seleccionada. +- **Supr**: borra la superficie o máscara seleccionada. + +## Limitaciones + +- **projectM nativo no se mapea todavía.** projectM corre en su propia ventana + fuera del navegador, así que el mapper (que trabaja sobre las visuales web) no + lo alcanza. Para mapear el mismo tipo de gráficos, usa **Butterchurn** + (MilkDrop en el navegador). El soporte de projectM está en estudio. +- El mapping es una capa de deformación sobre la imagen final; no cambia el + contenido de cada motor.