rotoscopia-lab / source /README.md
Segizu's picture
Fix: vídeo de ejemplo como blob (CDN cross-origin) y CSP img-src para miniaturas
6fc6a41 verified
|
Raw History Blame Contribute Delete
12.1 kB
---
title: Rotoscopia Lab
emoji: ✂️
colorFrom: indigo
colorTo: pink
sdk: static
app_file: index.html
pinned: false
license: apache-2.0
short_description: Segmenta por clic/caja y sigue objetos en vídeo (SAM 3)
custom_headers:
cross-origin-embedder-policy: credentialless
cross-origin-opener-policy: same-origin
models:
- onnx-community/sam3-tracker-ONNX
- facebook/sam3
tags:
- mask-generation
- image-segmentation
- interactive-segmentation
- video-object-segmentation
- sam3
- transformers.js
- onnx
- webgpu
- wasm
- spanish
- español
---
# Rotoscopia Lab
Space **estático** (HTML/JS, sin servidor de inferencia) de **segmentación interactiva**: haces clic sobre un objeto
(puntos «incluir» / «excluir») o dibujas una caja y obtienes su **máscara a nivel de píxel**; puedes descargarla como PNG,
como imagen superpuesta o como **recorte con fondo transparente**. Con un **vídeo corto**, marcas el objeto en el primer
fotograma y la app lo **sigue** en los siguientes (rotoscopia asistida) y exporta un WebM con la máscara.
La inferencia es **real** y corre **en tu navegador** (Web Worker; WebGPU si está disponible, si no WASM/CPU).
Proyecto comunitario independiente. **No** es un producto oficial de Meta ni de Hugging Face.
## Qué hace (y qué no)
| Función | Cómo funciona |
|---|---|
| Clic / caja → máscara | Codificador de imagen de SAM 3 **una vez por imagen** (lento) + decodificador de prompts **por cada clic** (rápido, ~0,1–0,3 s en CPU). El modelo propone 3 máscaras candidatas con una puntuación de calidad (IoU predicho); se muestra la mejor y las 3 puntuaciones. |
| Puntos negativos | Mayús+clic o herramienta «excluir» para quitar zonas. |
| Seguimiento en vídeo | **Heurística de esta app**, no el rastreador con memoria de SAM 3: cada fotograma muestreado se codifica de nuevo y se re-pregunta al decodificador con la caja de la máscara anterior ampliada un 10 % + un punto interior de esa máscara. Si el modelo dice «objeto ausente» (logit < 0) o el área salta ×4, el fotograma se marca **perdido** (rojo) y se reutiliza el último prompt bueno. |
| Exportar | PNG superpuesto, máscara binaria PNG, recorte PNG con transparencia; WebM del seguimiento (MediaRecorder). |
| No hace | Segmentación por **texto** (la parte «concept/detector» de SAM 3 no está en esta conversión ONNX); identificación de personas; nada se sube a ningún servidor. |
## Modelo, versiones fijadas y licencias
| Elemento | Valor |
|---|---|
| Modelo base | [`facebook/sam3`](https://huggingface.co/facebook/sam3) — SAM 3 «Segment Anything with Concepts», Meta, **noviembre de 2025** (no es un lanzamiento de esta semana; es un modelo reciente y estable). Aquí sólo se usa la parte *tracker* (segmentación por puntos/cajas). |
| Conversión ONNX | [`onnx-community/sam3-tracker-ONNX`](https://huggingface.co/onnx-community/sam3-tracker-ONNX) revisión **`429305c8a5b3de597243d919a07e4e6bdcd00ef7`** (2025-11-19) |
| Licencia de modelo y pesos | **SAM License** (Meta, «Last Updated: November 19, 2025»). Copia íntegra en [`SAM_LICENSE.txt`](./SAM_LICENSE.txt). Concede licencia no exclusiva, mundial y gratuita para usar, reproducir, distribuir y modificar (1.a); exige distribuir con copia del acuerdo (1.b.i), cumplir leyes de privacidad y controles de exportación y **prohíbe usos militares, nucleares, de espionaje o armas** (1.b.iii–v). Una demo pública no comercial como ésta es compatible. La tarjeta de la conversión ONNX no declara licencia propia: al ser derivado de los SAM Materials, aplica la SAM License. Los pesos **no** se redistribuyen en este Space: tu navegador los descarga del Hub. |
| Runtime | `@huggingface/transformers` **4.3.2** (Apache-2.0), que incluye `onnxruntime-web` **1.31.0-dev.20260914-8d85527a0** (MIT); los binarios WASM se sirven desde este mismo Space (`wasm/`), no desde un CDN de terceros. |
| Código de esta app | Apache-2.0 (`LICENSE`, `NOTICE`). Copia del código fuente en `source/`. |
### Descarga inicial (bytes reales en la revisión fijada, sha256 LFS verificado)
| Variante (selector «Pesos») | Archivos | Total |
|---|---|---|
| **q4f16** (por defecto; ideal con WebGPU) | `vision_encoder_q4f16.onnx` (1 307 816 B) + `.onnx_data` (295 622 656 B) + `prompt_encoder_mask_decoder_q4f16.onnx` (243 598 B) + `.onnx_data` (5 121 024 B) | **302 295 094 B ≈ 302,3 MB** |
| **int8** (`*_quantized`) | encoder 1 560 787 + 527 113 216 B; decoder 290 416 + 9 776 128 B | **538 740 547 B ≈ 538,7 MB** |
Más ~6 kB de configuración y el runtime WASM del propio Space: `ort-wasm-simd-threaded.wasm` (14,3 MB) en modo WASM o
`…asyncify.wasm` (26,9 MB) en modo WebGPU. Después todo queda en la caché del navegador.
En CPU el codificador int8 fue ~1,9× más rápido que q4f16 en nuestra prueba (ver abajo), a cambio de +236 MB de descarga.
## Privacidad: tus imágenes no salen del navegador
- Las imágenes/vídeos se leen con `createImageBitmap` / `<video>` local y se pasan al Web Worker como píxeles; **no hay
ningún `fetch`/`XMLHttpRequest`/formulario que envíe datos**. Las únicas peticiones de red son `GET` de archivos del
propio Space y de los pesos del modelo en `huggingface.co` / `*.hf.co`.
- Lo refuerza una **Content-Security-Policy** en `index.html`: `connect-src 'self' blob: data: https://huggingface.co https://*.huggingface.co https://*.hf.co`
y `form-action 'none'` (las miniaturas de ejemplo pueden cargarse desde `*.hf.co`, el CDN al que redirige el Space), así que el navegador bloquearía cualquier conexión a otro destino.
- Verificado con Chrome headless (ver «Verificación»): sólo se contactaron el origen del Space y hosts de Hugging Face, y **0 peticiones
que no fueran GET/HEAD**.
## Límites
| Límite | Valor |
|---|---|
| Imagen | JPG/PNG/WebP, ≤ 15 MB, ≤ 24 MP; se reduce a ≤ 1600 px de lado para trabajar (SAM 3 redimensiona internamente a 1008×1008) |
| Vídeo | MP4/WebM/MOV/OGG que tu navegador pueda decodificar, ≤ 60 MB; se procesan como máximo los **primeros 20 s** y **60 fotogramas** (muestreo 2/5/10 fps), a ≤ 960 px de lado |
| Puntos | ≤ 12 por objeto; una sola caja; **un objeto a la vez** |
| Concurrencia | Un trabajo a la vez por pestaña (codificar, decodificar o seguir); todo ocurre en tu equipo, así que no hay cola compartida entre usuarios |
| Memoria | Chrome llegó a ~4,4 GB de RAM en modo WASM con q4f16 en nuestra prueba; equipos con < 8 GB o móviles pueden fallar. Con WebGPU hace falta VRAM suficiente y, para q4f16, preferiblemente la extensión `shader-f16` |
| Hilos WASM | Hasta 4 si la página está aislada (`crossOriginIsolated`, cabeceras COOP/COEP de este Space). Dentro del iframe de huggingface.co puede no estarlo → 1 hilo (mucho más lento); abre la URL directa `https://segizu-rotoscopia-lab.static.hf.space` |
## Ejemplos (un clic cada uno, con el modelo cargado)
| Botón | Prompt precargado | Resultado esperado |
|---|---|---|
| **Frutero · 1 clic** | 1 punto «incluir» en (1125, 787) | Sólo la mandarina de abajo a la derecha (~4,3 % de la imagen) |
| **Escritorio · caja** | caja (181, 0)–(819, 659) | El portátil entero (pantalla + teclado), sin taza ni lápices (~23 %) |
| **Bicicleta · 3 clics** | 3 puntos «incluir»: sillín, cuadro, rueda | La bicicleta completa (~17–18 %); el interior de la rueda delantera queda relleno (limitación) |
| **Vídeo sintético · seguir la taza** | caja + 1 clic sobre la taza en el fotograma 0; luego «Seguir objeto» | La taza resaltada en todos los fotogramas mientras la «cámara» se desplaza y acerca |
Procedencia: `examples/ATTRIBUTION.json` — 3 fotos **CC0 1.0** de Wikimedia Commons (Hans Braxmeier, Wilfredor,
Lauren Mancke; copias = miniatura de 1280 px, sha256 incluido). El vídeo `example-desk-pan.mp4` es **sintético**: un paneo/zoom
determinista sobre la foto CC0 del escritorio generado con `scripts/make-example-video.mjs` (sin edición generativa);
`examples/video-pan.json` guarda el recorte exacto de cada fotograma.
## Verificación realizada (sin GPU)
Hardware: Intel Xeon (8 vCPU, AVX-512), 16 GB RAM, Linux, **sin GPU** → la ruta WebGPU **no se ha medido**.
1. **Tests unitarios** (`npm test`, Vitest): post-proceso de máscaras (área, bbox, IoU, contorno, recorte), construcción de
prompts con las formas que espera el procesador, propagación entre fotogramas (con modelo simulado), límites, pines,
licencias, CSP.
2. **Inferencia real en Node** (`npm run evidence`): transformers.js 4.3.2 + onnxruntime-node 1.30.0 (CPU), mismos archivos q4f16
y el mismo código `src/sam.js`/`src/lib.js` que usa el navegador.
3. **Inferencia real en Chrome headless** (`scripts/smoke-browser.mjs`): la app compilada, modo WASM (4 hilos), descarga real del modelo.
| Ejemplo | Área máscara (Node) | IoU caja de máscara vs caja esperada (anotada a mano) | Codificador q4f16: Node CPU · ORT-web WASM 4h (Node) · Chrome WASM 4h | Decodificador por clic (Chrome) |
|---|---|---|---|---|
| Frutero (1 clic) | 52 372 px (4,3 %) | 0,969 | 7,2 s · 50,7 s · 50,9 s | 0,30 s |
| Escritorio (caja) | 253 854 px (23,3 %) | 0,989 | 7,0 s · 50,2 s · 50,3 s | 0,26 s |
| Bicicleta (3 clics) | 192 176 px (17,6 %) | 0,994 | 6,5 s · 49,7 s · 49,1 s | 0,23 s |
- Paridad: la máscara con onnxruntime-web (WASM) coincide con la de onnxruntime-node (IoU de máscara 0,9999–1,0 en q4f16; 0,997–0,999 en int8).
En Chrome el área difiere < 0,3 % (el navegador decodifica el JPEG de forma ligeramente distinta).
- int8 en ORT-web WASM 4 hilos: codificador 26,6–27,0 s (≈1,9× más rápido que q4f16).
- **Vídeo sintético** (Node, 20 fotogramas a 5 fps): IoU de máscara frente a la verdad geométrica **media 0,980, mínima 0,976**, 0 fotogramas perdidos,
~6,8 s/fotograma en Node CPU. En Chrome WASM (2 fps, 8 fotogramas): 0 perdidos, ~49 s/fotograma.
- Onnxruntime-node usa kernels nativos (AVX-512) y por eso es ~7× más rápido que WASM en el mismo CPU: **la cifra realista para el navegador sin GPU es la de WASM**.
«Verdad geométrica» del vídeo: la taza se segmenta una vez sobre la foto completa y se proyecta con el recorte conocido de cada
fotograma; se compara con la máscara seguida (IoU de máscara). Son medidas de **esta** demo en **este** hardware, no benchmarks del modelo.
Con WebGPU se espera que el codificador sea bastante más rápido que en WASM, pero **no lo hemos medido**.
## Ejecutar en local / duplicar
```bash
git clone https://huggingface.co/spaces/Segizu/rotoscopia-lab && cd rotoscopia-lab/source
npm ci # instala transformers.js 4.3.2 exacta (package-lock)
npm test # tests unitarios
npm run dev # http://127.0.0.1:43134 (cabeceras COOP/COEP incluidas)
npm run build # genera dist/ (lo que se publica en el Space)
npm run evidence # inferencia real en Node (descarga ~302 MB)
```
Para duplicar: botón «Duplicate this Space» (SDK static, gratis) o sube el contenido de `dist/` a un Space estático propio.
Mantén `SAM_LICENSE.txt` y `NOTICE`.
## Limitaciones conocidas
- **Lento en CPU**: ~50 s por imagen (codificador) en WASM con 4 hilos en un Xeon de servidor; en 1 hilo o en portátiles modestos puede pasar de varios minutos. Cada clic posterior sí es rápido.
- El seguimiento en vídeo **re-codifica cada fotograma** (≈ coste de una imagen por fotograma) y no usa la memoria temporal de SAM 3: puede perder el objeto con oclusiones, cortes de plano o movimientos rápidos, o saltar a un objeto parecido.
- Un objeto por vez; sin refinado de bordes (la máscara sale de una predicción 288×288 reescalada) y objetos con huecos (ruedas, rejas) suelen salir rellenos.
- q4f16 en WebGPU necesita `shader-f16`; si la carga falla se reintenta automáticamente en WASM. Safari/Firefox con WebGPU no se han probado.
- La búsqueda de fotogramas depende del decodificador de vídeo del navegador (algunos MOV/HEVC no se abren).
- No uses la app para identificar personas ni para inferir atributos sensibles; respeta la SAM License y la privacidad de terceros.