File size: 12,100 Bytes
87b5db3
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
6fc6a41
87b5db3
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
---
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.