Spaces:
Running
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
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. | |