eminmeydanoglu/agentseg-label

Etiquetar una secuencia con agentseg

Segmentas el objeto una vez, SAM 3 lo rastrea en cada fotograma, y el backend marca los fotogramas que parecen incorrectos ("incidencias"). Tu trabajo es dar una buena primera máscara, luego inspeccionar las incidencias y corregir solo lo que realmente está mal. La mayoría de las secuencias necesitan 0–3 correcciones.

Ejecuta la CLI desde la raíz del repositorio como .venv/bin/agentseg … (o uv run agentseg …). Cada comando imprime un objeto JSON; lee ok, error y next. Las imágenes se escriben como archivos PNG y se devuelven como "image": "<ruta>". Abre esa ruta con tu herramienta de lectura de archivos para verla. No puedes juzgar una máscara sin mirarla.

Convenciones: coordenadas de píxeles, cuadros x0,y0,x1,y1, puntos x,y, los fotogramas son índices basados en 0 en el orden de imágenes del proyecto. Los rangos de fotogramas se escriben como 120-139,150.

0. Servicios

agentseg status            # backend + sam_server + proyecto abierto
agentseg up                # inicia lo que esté caído (sam_server tarda ~1–2 min)

Si up falla, lee la ruta del registro que imprime. No mates otros procesos de GPU. Nunca ejecutes agentseg down durante una sesión: el backend te aloja, y detenerlo termina tu sesión. La GPU puede estar compartida, por lo que un comando puede fallar con un error de sam_server (CUDA sin memoria). Espera 30–60 s y reinténtalo; agentseg up solo inicia lo que está caído. Si sigue fallando, detente e informa.

1. Abre el proyecto y encuentra el objeto

agentseg project open <carpeta_imagenes>     # o un directorio de proyecto existente (tiene agentseg.db)
agentseg sheet                               # ~24 miniaturas a lo largo de toda la secuencia

project open devuelve frames y image_size. Mira la hoja. Elige un fotograma de referencia donde el objeto esté completamente visible, grande y nítido, no necesariamente el fotograma 0. El rastreo avanza tanto hacia adelante como hacia atrás desde los fotogramas clave.

2. Resuelve la etiqueta antes de la primera máscara

Elige el nombre de la etiqueta antes de llamar a segment o crear un seguimiento. Usa el nombre del objeto de la solicitud del usuario; cuando no sea explícito, infiere un nombre corto y específico de la imagen y declara esa elección en la ejecución. Nunca dejes la etiqueta como unknown, una cadena vacía o un marcador de posición. Si hay varios objetos plausibles y la elección cambia el objetivo de anotación, pregunta al usuario antes de ejecutar SAM. El nombre resuelto se transfiere a la primera llamada track create y a cada informe posterior.

Por ejemplo, para "etiqueta el torpedo" resuelve torpedo; para "etiqueta el tablero en esta carpeta" resuelve tablero (o tablero_torpedo cuando esa es la identidad clara del objeto). Mantenlo estable para toda la secuencia.

Regístralo en la lista de etiquetas del proyecto antes de la primera máscara (esta es la misma lista que una persona elige en la interfaz web; reutiliza una etiqueta existente si ya nombra el objeto):

agentseg labels                     # etiquetas existentes
agentseg labels --add <etiqueta_resuelta>

3. Primera máscara

agentseg view <f> --grid                          # cuadrícula etiquetada de 50 px para leer coordenadas
agentseg segment <f> --box x0,y0,x1,y1            # solo vista previa, nada guardado

Cuadros: ajustados, alrededor de todo el objeto. En la cuadrícula, encuentra los píxeles más a la izquierda, derecha, arriba y abajo del objeto (de parachoques a parachoques, ruedas, techo), luego agrega un pequeño margen (aproximadamente 5–10% de su tamaño). No más: un cuadro con mucho espacio permite que SAM capte la sombra del objeto o el suelo a su alrededor, y el rastreador copia eso a cada fotograma.

• Lee check: segment también prueba un cuadro un 20% más grande. Una ADVERTENCIA de que la máscara crece con el cuadro más grande significa que tu cuadro cortó el objeto. Si el zoom de esa máscara más grande muestra el objeto completo, usa su padded_preview_id; de lo contrario, redibuja el cuadro alrededor de todo el objeto. Nunca lo ignores y vuelvas a ejecutar el mismo cuadro.
• segment devuelve image (fotograma completo, relleno amarillo) y zoom (primer plano, solo contorno, cian = el cuadro usado). Abre el zoom y recorre el contorno: cada extremo del objeto debe estar dentro de él.
• ¿Demasiado? El contorno debe seguir el borde propio del objeto. Si se mete en la sombra debajo o al lado del objeto, la carretera o un vecino, vuelve a ejecutar con --neg x,y en esa parte (y un cuadro más ajustado).
• ¿Sigue siendo una máscara parcial? No vuelvas a ejecutar el mismo cuadro: da la misma máscara. Pon --pos x,y en la parte que falta (SAM a menudo se detiene en un límite de color o luz: mitad soleada, mitad sombreada, vehículo de dos tonos).
• Alcance: incluye exactamente el objeto que el usuario quiere: "el tablero" sin su soporte, "el coche" sin el remolque.
• Hasta 4 intentos. Un fotograma clave que cubre 2/3 del objeto es peor que ninguno: el rastreador lo copia a cada fotograma y la verificación de salud no puede verlo. Si no puedes obtener el objeto completo en este fotograma, elige otro fotograma. Luego:

agentseg track create --label <etiqueta_resuelta> --preview <id_vista_previa>
agentseg track propagate <id_seguimiento>               # ~1 min por 500 fotogramas; devuelve incidencias

Para fotogramas clave añadidos más tarde, pasa --track T a segment: el zoom también muestra el fotograma clave más cercano del seguimiento, para que puedas verificar que es el mismo objeto.

3b. Cuando el rastreo pierde el objeto

SAM 3 generalmente vuelve a recoger el objeto por sí solo después de que ha desaparecido por un tiempo, por lo que los espacios cortos no necesitan nada. propagate detiene el rastreo en una dirección solo cuando la máscara ha estado vacía durante 60 fotogramas seguidos, y devuelve lost:

"lost": [{"keyframe": 420, "direction": "forward", "lost_from": 579, "stopped_at": 638, "untracked": [639, 999]}]

El fallo más común es lo contrario: después de un espacio, SAM vuelve a aparecer en un objeto diferente y similar. Dondequiera que el seguimiento reaparezca después de fotogramas vacíos (rojo en sheet --track), verifica la identidad con view <primer fotograma después del espacio> --track T --zoom.

Trata lost antes que las incidencias. Mira lo que realmente sucede desde lost_from: agentseg sheet --frames <lost_from-5>-<lost_from+40> (sin --track, para que veas los fotogramas simples).

• El objeto ha desaparecido (túnel, detrás de un edificio, la cámara mira hacia otro lado, un corte): encuentra dónde vuelve a aparecer, track absent T <lost_from>-<último_fotograma_desaparecido> --no-propagate, luego segment + track refine en un fotograma claro donde esté de vuelta.
• El objeto sigue siendo visible: el rastreador lo soltó. segment + track refine en un fotograma claro justo después de lost_from.
• Nunca vuelve a aparecer antes del final: marca el resto como absent.

Cada corrección re-propaga; repite hasta que no haya lost.

Usa el nombre de etiqueta que el usuario dio, o uno descriptivo corto como tablero_torpedo.

4. Revisar incidencias

propagate (y refine, absent, keyframes --rm) devuelven la lista de incidencias actual:

{"id": 9, "start": 210, "end": 228, "worst_frame": 218, "kind": "drift", "n_frames": 19, "reasons": {...}}

Para cada incidencia, mira su worst_frame:

agentseg view <fotograma_peor> --track <T> --grid

En la vista, la máscara del seguimiento es magenta con un contorno. Un cuadro amarillo marca un fotograma clave y un cuadro cian un fotograma propagado. El tinte oculta el color del objeto; para cualquier cosa sobre identidad o cobertura, usa el primer plano:

agentseg view <f> --track <T> --zoom     # [fotograma clave más cercano] [fotograma] [fotograma + contorno], sin relleno

Identidad. Después de una oclusión, un túnel, un corte de cámara o un paneo rápido, SAM a menudo salta a un objeto similar cercano. Compara con el panel del fotograma clave: ¿mismo color, mismo tipo de carrocería (SUV vs sedán, hatchback vs maletero), mismos detalles? "Un coche oscuro en el lugar correcto" no es suficiente. Cualquier incidencia cuyos reasons tengan dino_low (la máscara no se parece al fotograma clave) necesita una comparación de zoom antes de que puedas revisarla. Si es otro objeto, el real está en otro lugar (segment + track refine sobre él) o no es visible (track absent).

Lo que ves	Acción
La máscara es correcta; el objeto simplemente se hizo más pequeño, más grande, rotó o se movió rápido	Márcarlo como revisado: agentseg track review T <id_incidencia> --note "<línea de por qué>". Sus fotogramas pasan de revisión a aprobados.
La máscara se derrama sobre el fondo u otros objetos, o tiene motas sueltas lejanas (bbox enorme)	segment en ese fotograma con un cuadro ajustado (+ --neg en el derrame), luego track refine T <f> --preview P
La máscara cubre solo parte del objeto (revisa el zoom), o está en el objeto equivocado (compara con el panel del fotograma clave)	Igual: segment → track refine
El objeto no es visible en absoluto (fuera de cuadro, completamente ocluido), pero existe una máscara	track absent T <rango>. Encuentra el rango primero con sheet --track T --frames a-b.
El objeto es visible pero no hay máscara (rojo "vacío" en la hoja)	segment → track refine en un fotograma donde sea claramente visible

Reglas:

• Nunca refines sin mirar la vista previa primero. Un fotograma clave malo envenena el rastreador para muchos fotogramas.
• Si un fotograma clave que añadiste empeoró las cosas: agentseg track keyframes T --rm <f>.
• Correcciones por lotes: agrega --no-propagate a todos excepto el último refine o absent, o síguelas con un agentseg track propagate T. Cada propagación cuesta 30–60 s.
• Para absent, verifica los límites. Usa sheet --track T --frames a-b alrededor del rango y marca solo los fotogramas donde el objeto realmente no es visible (una astilla en el borde de la imagen aún cuenta como visible).
• Misma incidencia todavía presente después de 2 correcciones → deja de corregirla, déjala abierta (no le hagas review) y menciónala en tu informe. Las incidencias abiertas son lo que una persona verifica después.
• Solo haz review de una incidencia después de haber mirado sus fotogramas. Para una incidencia larga, revisa un sheet --track T --frames a-b del rango, no solo worst_frame. Varias incidencias revisadas a la vez: track review T 2,3,5 --note ..., pero solo incidencias del mismo tipo que realmente revisaste; la nota debe ser cierta para cada id en ella. Nunca revises una incidencia lost (fotogramas vacíos) como "máscara correcta".
• Presupuesto: alrededor de 10 correcciones y alrededor de 40 imágenes vistas por secuencia. Prefiere un sheet sobre muchos views al escanear un rango.

5. Verificación final y exportación

agentseg sheet --track T                 # colores de borde: fotograma clave amarillo, ok verde,
                                        # revisión naranja, ausente gris, rojo sin máscara
agentseg export                          # YOLO-seg (por defecto); --format yolo-detect|coco

Mira la hoja final. Los fotogramas naranjas pertenecen a incidencias aún abiertas: revísalas y haz review, corrígelas, o déjalas abiertas a propósito para una persona. Los fotogramas rojos necesitan atención, a menos que el objeto esté realmente ausente allí; entonces márcalos como absent.

6. Informe al usuario

Breve:

• id del seguimiento y etiqueta
• número de fotogramas
• fotogramas clave (fotogramas y por qué)
• rangos ausentes
• incidencias revisadas como correctas, con razones de una línea
• incidencias no resueltas
• ruta de exportación
• ruta de la hoja final

Referencia

agentseg status | up [--no-sam] [--no-ui] | down [--all]
agentseg project open <dir> [--name N] [--project-dir D]
agentseg labels [--add NAME]
agentseg view <f> [--track T] [--grid] [--preview P] [--zoom]
agentseg sheet [--track T] [--every N | --frames a-b,c]
agentseg segment <f> --box x0,y0,x1,y1 [--pos x,y]... [--neg x,y]... [--track T] [--no-grid]
agentseg track create --label L --preview P
agentseg track propagate T [--full] [--start a --end b] [--max-lost N] [--no-wait]
agentseg track issues T [--verbose]
agentseg track review T <ids|all> [--note TEXT]
agentseg track refine T <f> (--preview P | --box ... [--pos ..] [--neg ..]) [--no-propagate]
agentseg track keyframes T [--rm F] [--no-propagate]
agentseg track absent T <frames> [--no-propagate]
agentseg track list
agentseg export [--format yolo-seg|yolo-detect|coco] [--out DIR] [--approved-only] [--labels-only]

Todos los comandos aceptan --help. Los errores imprimen {"ok": false, "error": "..."} y salen con código distinto de cero; lee el mensaje, ya que normalmente nombra la solución.