eminmeydanoglu/agentseg-label

Étiqueter une séquence avec agentseg

Vous segmentez l'objet une fois, SAM 3 le suit sur toutes les images, et le serveur signale les images qui semblent erronées (« problèmes »). Votre travail consiste à fournir un bon premier masque, puis à inspecter les problèmes et à corriger uniquement ce qui est effectivement erroné. La plupart des séquences nécessitent 0 à 3 corrections.

Exécutez la CLI depuis la racine du dépôt comme .venv/bin/agentseg … (ou uv run agentseg …). Chaque commande affiche un objet JSON ; lisez ok, error et next. Les images sont écrites sous forme de fichiers PNG et renvoyées comme "image": "<chemin>". Ouvrez ce chemin avec votre outil de lecture de fichier pour le voir. Vous ne pouvez pas juger un masque sans le regarder.

Conventions : coordonnées en pixels, boîtes x0,y0,x1,y1, points x,y, les images sont des indices basés sur 0 dans l'ordre des images du projet. Les plages d'images sont écrites comme 120-139,150.

0. Services

agentseg status            # backend + sam_server + projet ouvert
agentseg up                # démarre ce qui est arrêté (sam_server prend ~1–2 min)

Si up échoue, lisez le chemin du journal qu'il affiche. Ne tuez pas d'autres processus GPU. N'exécutez jamais agentseg down pendant une session : le backend vous héberge, et l'arrêter met fin à votre session. Le GPU peut être partagé, donc une commande peut échouer avec une erreur sam_server (CUDA out of memory). Attendez 30–60 s et réessayez ; agentseg up ne démarre que ce qui est arrêté. Si cela continue d'échouer, arrêtez-vous et signalez-le.

1. Ouvrir le projet et trouver l'objet

agentseg project open <dossier_images>     # ou un répertoire de projet existant (contient agentseg.db)
agentseg sheet                           # ~24 vignettes sur toute la séquence

project open renvoie frames et image_size. Regardez la feuille. Choisissez une image d'incitation où l'objet est complètement visible, grand et net, pas nécessairement l'image 0. Le suivi s'effectue à la fois en avant et en arrière à partir des images clés.

2. Résoudre l'étiquette avant le premier masque

Choisissez le nom d'étiquette avant d'appeler segment ou de créer une piste. Utilisez le nom d'objet de la demande de l'utilisateur ; lorsqu'il n'est pas explicite, déduisez un nom court et spécifique à partir de l'image et indiquez ce choix dans la session. Ne laissez jamais l'étiquette comme unknown, une chaîne vide ou un espace réservé. S'il y a plusieurs objets plausibles et que le choix change la cible d'annotation, demandez à l'utilisateur avant d'exécuter SAM. Le nom résolu est reporté dans le premier appel track create et dans chaque rapport ultérieur.

Par exemple, pour « étiqueter le torpilleur », résolvez torpilleur ; pour « étiqueter le tableau dans ce dossier », résolvez tableau (ou tableau_torpilleur lorsque c'est l'identité évidente de l'objet). Gardez-le stable pour toute la séquence.

Enregistrez-le dans la liste d'étiquettes du projet avant le premier masque (c'est la même liste qu'une personne choisit dans l'interface Web ; réutilisez une étiquette existante lorsqu'elle nomme déjà l'objet) :

agentseg labels                     # étiquettes existantes
agentseg labels --add <étiquette_résolue>

3. Premier masque

agentseg view <f> --grid                          # grille étiquetée de 50 px pour lire les coordonnées
agentseg segment <f> --box x0,y0,x1,y1            # aperçu seulement, rien n'est sauvegardé

Boîtes : ajustées, autour de l'objet entier. Sur la grille, trouvez les pixels les plus à gauche, à droite, en haut et en bas de l'objet (pare-chocs à pare-chocs, roues, toit), puis ajoutez une petite marge (environ 5–10 % de sa taille). Pas plus : une boîte avec beaucoup d'espace laisse SAM prendre l'ombre de l'objet ou le sol autour, et le tracker copie cela sur chaque image.

• Lisez check : segment essaie aussi une boîte 20 % plus grande. Un AVERTISSEMENT que le masque s'agrandit avec la boîte plus grande signifie que votre boîte a coupé l'objet. Si le zoom de ce masque plus grand montre l'objet entier, utilisez son padded_preview_id ; sinon redessinez la boîte autour de tout l'objet. Ne l'ignorez jamais et ne réexécutez pas la même boîte.
• segment renvoie image (image entière, remplissage jaune) et zoom (gros plan, contour uniquement, cyan = la boîte utilisée). Ouvrez le zoom et parcourez le contour : chaque extrémité de l'objet doit être à l'intérieur.
• Trop ? Le contour doit suivre le bord propre de l'objet. S'il empiète sur l'ombre en dessous ou à côté de l'objet, la route ou un voisin, réexécutez avec --neg x,y sur cette partie (et une boîte plus ajustée).
• Encore un masque partiel ? Ne réexécutez pas la même boîte : elle donne le même masque. Mettez --pos x,y sur la partie manquante (SAM s'arrête souvent à une limite de couleur ou de lumière : moitié ensoleillée, moitié ombragée, véhicule bicolore).
• Périmètre : incluez exactement l'objet que l'utilisateur veut : « le tableau » sans son support, « la voiture » sans la remorque.
• Jusqu'à 4 tentatives. Une image clé qui couvre 2/3 de l'objet est pire qu'aucune : le tracker la copie sur chaque image et la santé ne peut pas la voir. Si vous ne pouvez pas obtenir l'objet entier sur cette image, choisissez une autre image. Ensuite :

agentseg track create --label <étiquette_résolue> --preview <id_aperçu>
agentseg track propagate <id_piste>               # ~1 min par 500 images ; renvoie les problèmes

Pour les images clés ajoutées plus tard, passez --track T à segment : le zoom affiche alors également l'image clé la plus proche de la piste, afin que vous puissiez vérifier qu'il s'agit du même objet.

3b. Lorsque le suivi perd l'objet

SAM 3 retrouve généralement l'objet tout seul après une absence temporaire, donc les courtes lacunes ne nécessitent rien. propagate arrête le suivi dans une direction uniquement lorsque le masque a été vide pendant 60 images consécutives, et renvoie lost :

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

L'échec le plus courant est l'inverse : après une lacune, SAM revient sur un objet différent mais similaire. Partout où la piste réapparaît après des images vides (en rouge dans sheet --track), vérifiez l'identité avec view <première image après la lacune> --track T --zoom.

Traitez lost avant les problèmes. Regardez ce qui se passe réellement à partir de lost_from : agentseg sheet --frames <lost_from-5>-<lost_from+40> (sans --track, pour voir les images brutes).

• L'objet a disparu (tunnel, derrière un bâtiment, la caméra regarde ailleurs, un cut) : trouvez où il revient, track absent T <lost_from>-<dernière image disparue> --no-propagate, puis segment + track refine sur une image claire où il est de retour.
• L'objet est toujours visible : le tracker l'a perdu. segment + track refine sur une image claire juste après lost_from.
• Il ne revient jamais avant la fin : marquez le reste comme absent.

Chaque correction re-propage ; répétez jusqu'à ce qu'il n'y ait plus de lost.

Utilisez le nom d'étiquette donné par l'utilisateur, ou un nom court et descriptif comme tableau_torpilleur.

4. Examiner les problèmes

propagate (et refine, absent, keyframes --rm) renvoient la liste actuelle des problèmes :

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

Pour chaque problème, regardez son worst_frame :

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

Dans la vue, le masque de la piste est magenta avec un contour. Une boîte jaune marque une image clé et une boîte cyan une image propagée. La teinte cache la couleur de l'objet ; pour tout ce qui concerne l'identité ou la couverture, utilisez le gros plan :

agentseg view <f> --track <T> --zoom     # [image clé la plus proche] [image] [image + contour], sans remplissage

Identité. Après une occlusion, un tunnel, un cut de caméra ou un panoramique rapide, SAM saute souvent sur un objet similaire à proximité. Comparez avec le panneau d'image clé : même couleur, même type de carrosserie (SUV vs berline, hayon vs coffre), mêmes détails ? « Une voiture sombre au bon endroit » ne suffit pas. Tout problème dont les reasons contiennent dino_low (le masque ne ressemble pas à l'image clé) nécessite une comparaison en gros plan avant de pouvoir le réviser. S'il s'agit d'un autre objet, le vrai se trouve soit ailleurs (segment + track refine dessus), soit n'est pas visible (track absent).

Ce que vous voyez	Action
Le masque est correct ; l'objet est simplement devenu plus petit, plus grand, a tourné ou s'est déplacé rapidement	Marquez-le comme vérifié : agentseg track review T <id_problème> --note "<une ligne pourquoi>". Ses images passent de révision à approuvées.
Le masque déborde sur l'arrière-plan ou d'autres objets, ou a des taches isolées loin (énorme bbox)	segment de cette image avec une boîte serrée (+ --neg sur le débordement), puis track refine T <f> --preview P
Le masque ne couvre qu'une partie de l'objet (vérifiez le zoom), ou se trouve sur le mauvais objet (comparez avec le panneau d'image clé)	Idem : segment → track refine
L'objet n'est pas du tout visible (hors cadre, complètement occulté), mais un masque existe	track absent T <plage>. Trouvez d'abord la plage avec sheet --track T --frames a-b.
L'objet est visible mais il n'y a pas de masque (rouge « vide » dans la feuille)	segment → track refine sur une image où il est clairement visible

Règles :

• Ne jamais raffiner sans regarder l'aperçu d'abord. Une mauvaise image clé empoisonne le tracker sur de nombreuses images.
• Si une image clé que vous avez ajoutée a aggravé les choses : agentseg track keyframes T --rm <f>.
• Corrections par lots : ajoutez --no-propagate à tous sauf le dernier refine ou absent, ou suivez-les d'un seul agentseg track propagate T. Chaque propagation coûte 30–60 s.
• Pour absent, vérifiez les limites. Utilisez sheet --track T --frames a-b autour de la plage et marquez uniquement les images où l'objet n'est vraiment pas visible (un fragment au bord de l'image compte encore comme visible).
• Même problème toujours là après 2 corrections → arrêtez de le corriger, laissez-le ouvert (ne le review pas) et mentionnez-le dans votre rapport. Les problèmes ouverts sont ce qu'une personne vérifiera plus tard.
• review un problème seulement après avoir regardé ses images. Pour un long problème, vérifiez un sheet --track T --frames a-b de la plage, pas seulement worst_frame. Plusieurs problèmes vérifiés à la fois : track review T 2,3,5 --note ..., mais uniquement des problèmes du même type que vous avez réellement vérifiés ; la note doit être vraie pour chaque identifiant qu'elle contient. Ne review jamais un problème lost (images vides) comme « masque correct ».
• Budget : environ 10 corrections et environ 40 images consultées par séquence. Préférez une sheet à plusieurs view lors du balayage d'une plage.

5. Vérification finale et export

agentseg sheet --track T                 # couleurs de bordure : jaune image clé, vert ok,
                                        # orange révision, gris absent, rouge pas de masque
agentseg export                          # YOLO-seg (par défaut) ; --format yolo-detect|coco

Regardez la feuille finale. Les images orange appartiennent à des problèmes encore ouverts : vérifiez et review, corrigez-les, ou laissez-les ouverts exprès pour une personne. Les images rouges nécessitent une attention, sauf si l'objet est vraiment absent là ; marquez-les alors absent.

6. Rapport à l'utilisateur

Court :

• identifiant de la piste et étiquette
• nombre d'images
• images clés (images et pourquoi)
• plages absentes
• problèmes révisés comme corrects, avec raisons en une ligne
• problèmes laissés non résolus
• chemin d'export
• chemin de la feuille finale

Référence

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]

Toutes les commandes acceptent --help. Les erreurs affichent {"ok": false, "error": "..."} et se terminent avec un code non nul ; lisez le message, car il nomme généralement la correction.