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
metadata
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 — 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 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. 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

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.