Spaces:
Running
Download source/README.md from Segizu/rotoscopia-lab: direct link, hf CLI and curl.
- Browser
- Download file 12.1 kB
-
https://huggingface.co/spaces/Segizu/rotoscopia-lab/resolve/main/source/README.md
- Command line
-
hf download hf://spaces/Segizu/rotoscopia-lab/source/README.md
-
curl -L -o README.md https://huggingface.co/spaces/Segizu/rotoscopia-lab/resolve/main/source/README.md
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únfetch/XMLHttpRequest/formulario que envíe datos. Las únicas peticiones de red sonGETde archivos del propio Space y de los pesos del modelo enhuggingface.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.coyform-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.
- 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. - 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ódigosrc/sam.js/src/lib.jsque usa el navegador. - 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.