eminmeydanoglu/agentseg-label

Labeln einer Sequenz mit agentseg

Du segmentierst das Objekt einmal, SAM 3 verfolgt es durch jeden Frame, und das Backend markiert Frames, die falsch aussehen („Issues“). Deine Aufgabe ist es, eine gute erste Maske zu liefern, dann Issues zu inspizieren und nur das zu korrigieren, was tatsächlich falsch ist. Die meisten Sequenzen benötigen 0–3 Korrekturen.

Führe das CLI aus dem Repository-Root aus als .venv/bin/agentseg … (oder uv run agentseg …). Jeder Befehl gibt ein JSON-Objekt aus; lies ok, error und next. Bilder werden als PNG-Dateien geschrieben und als "image": "<pfad>" zurückgegeben. Öffne diesen Pfad mit deinem Dateilesetool, um es zu sehen. Du kannst eine Maske nicht beurteilen, ohne sie anzusehen.

Konventionen: Pixelkoordinaten, Boxen x0,y0,x1,y1, Punkte x,y, Frames sind 0-basierte Indizes in der Bildreihenfolge des Projekts. Frambereiche werden wie 120-139,150 geschrieben.

0. Dienste

agentseg status            # Backend + sam_server + offenes Projekt
agentseg up                # startet, was heruntergefahren ist (sam_server braucht ~1–2 Min)

Wenn up fehlschlägt, lies den Log-Pfad, den es ausgibt. Töte keine anderen GPU-Prozesse. Führe während eines Laufs niemals agentseg down aus: Das Backend hostet dich, und das Stoppen beendet deinen Lauf. Die GPU wird möglicherweise gemeinsam genutzt, daher kann ein Befehl mit einem sam_server-Fehler fehlschlagen (CUDA out of memory). Warte 30–60 s und wiederhole ihn; agentseg up startet nur, was heruntergefahren ist. Wenn es immer wieder fehlschlägt, stoppe und melde es.

1. Das Projekt öffnen und das Objekt finden

agentseg project open <bilder_ordner>     # oder ein vorhandenes Projektverzeichnis (hat agentseg.db)
agentseg sheet                           # ~24 Thumbnails über die gesamte Sequenz

project open gibt frames und image_size zurück. Sieh dir das Sheet an. Wähle einen Prompt-Frame, in dem das Objekt vollständig sichtbar, groß und scharf ist, nicht unbedingt Frame 0. Das Tracking läuft von Keyframes aus sowohl vorwärts als auch rückwärts.

2. Das Label vor der ersten Maske auflösen

Wähle den Labelnamen aus, bevor du segment aufrufst oder einen Track erstellst. Verwende den Objektnamen aus der Anfrage des Benutzers; wenn er nicht explizit ist, leite einen kurzen, spezifischen Namen aus dem Bild ab und gib diese Wahl im Lauf an. Lasse das Label niemals als unknown, einen leeren String oder einen Platzhalter. Wenn es mehrere plausible Objekte gibt und die Wahl das Annotationsziel ändert, frage den Benutzer vor dem Ausführen von SAM. Der aufgelöste Name wird in den ersten track create-Aufruf und jeden späteren Bericht übernommen.

Zum Beispiel: für „Label den Torpedo“ löse torpedo auf; für „Label das Board in diesem Ordner“ löse board auf (oder torpedo_board, wenn dies die klare Objektidentität ist). Halte es für die gesamte Sequenz stabil.

Registriere es in der Label-Liste des Projekts vor der ersten Maske (dies ist die gleiche Liste, aus der eine Person in der Weboberfläche auswählt; verwende ein vorhandenes Label wieder, wenn es das Objekt bereits benennt):

agentseg labels                     # vorhandene Labels
agentseg labels --add <aufgelöstes_label>

3. Erste Maske

agentseg view <f> --grid                          # 50 px beschriftetes Gitter zum Ablesen von Koordinaten
agentseg segment <f> --box x0,y0,x1,y1            # nur Vorschau, nichts gespeichert

Boxen: eng, um das gesamte Objekt herum. Finde auf dem Gitter die linkesten, rechtesten, obersten und untersten Pixel des Objekts (Stoßstange zu Stoßstange, Räder, Dach), dann füge einen kleinen Rand hinzu (etwa 5–10 % seiner Größe). Nicht mehr: eine Box mit viel Platz lässt SAM den Schatten des Objekts oder den Boden darum herum aufnehmen, und der Tracker kopiert das dann in jeden Frame.

• Lies check: segment versucht auch eine 20 % größere Box. Eine WARNING, dass die Maske mit der größeren Box wächst, bedeutet, dass deine Box das Objekt abgeschnitten hat. Wenn der Zoom dieser größeren Maske das gesamte Objekt zeigt, verwende ihre padded_preview_id; andernfalls zeichne die Box neu um das gesamte Objekt. Ignoriere es niemals und führe die gleiche Box erneut aus.
• segment gibt image (gesamter Frame, gelbe Füllung) und zoom (Nahaufnahme, nur Umriss, Cyan = die verwendete Box) zurück. Öffne den Zoom und gehe um den Umriss herum: jedes Ende des Objekts muss darin sein.
• Zu viel? Der Umriss muss der eigenen Kante des Objekts folgen. Wenn er in den Schatten unter oder neben dem Objekt, die Straße oder einen Nachbarn hineinläuft, wiederhole mit --neg x,y an diesem Teil (und einer engeren Box).
• Immer noch eine Teilmaske? Führe nicht die gleiche Box erneut aus: sie ergibt die gleiche Maske. Setze --pos x,y auf den fehlenden Teil (SAM stoppt oft an einer Farb- oder Lichtgrenze: sonnige Hälfte, schattige Hälfte, zweifarbiges Fahrzeug).
• Umfang: schließe genau das Objekt ein, das der Benutzer meint: „das Board“ ohne seinen Ständer, „das Auto“ ohne den Anhänger.
• Bis zu 4 Versuche. Ein Keyframe, der 2/3 des Objekts abdeckt, ist schlechter als keiner: der Tracker kopiert es in jeden Frame, und die Integritätsprüfung kann es nicht sehen. Wenn du das vollständige Objekt in diesem Frame nicht erfassen kannst, wähle einen anderen Frame. Dann:

agentseg track create --label <aufgelöstes_label> --preview <preview_id>
agentseg track propagate <track_id>               # ~1 Min pro 500 Frames; gibt Issues zurück

Für später hinzugefügte Keyframes übergib --track T an segment: der Zoom zeigt dann auch den nächsten Keyframe des Tracks, sodass du überprüfen kannst, ob es dasselbe Objekt ist.

3b. Wenn das Tracking das Objekt verliert

SAM 3 nimmt das Objekt normalerweise von selbst wieder auf, nachdem es eine Weile weg war, daher sind kurze Lücken nicht nötig. propagate stoppt das Tracking in eine Richtung erst, wenn die Maske 60 Frames hintereinander leer war, und gibt lost zurück:

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

Der häufigere Fehler ist das Gegenteil: nach einer Lücke kommt SAM auf einem anderen, ähnlichen Objekt zurück. Wo auch immer der Track nach leeren Frames wieder auftaucht (rot in sheet --track), überprüfe die Identität mit view <erster Frame nach der Lücke> --track T --zoom.

Kümmere dich um lost vor den Issues. Sieh dir an, was wirklich ab lost_from passiert: agentseg sheet --frames <lost_from-5>-<lost_from+40> (ohne --track, damit du die reinen Frames siehst).

• Das Objekt ist weg (Tunnel, hinter einem Gebäude, Kamera schaut weg, ein Schnitt): finde heraus, wo es zurückkommt, track absent T <lost_from>-<letzter_verschwundener_Frame> --no-propagate, dann segment + track refine auf einem klaren Frame, wo es zurück ist.
• Das Objekt ist noch sichtbar: der Tracker hat es fallen gelassen. segment + track refine auf einem klaren Frame direkt nach lost_from.
• Es kommt vor dem Ende nie zurück: markiere den Rest als absent.

Jede Korrektur propagiert erneut; wiederhole, bis es kein lost mehr gibt.

Verwende den Labelnamen, den der Benutzer angegeben hat, oder einen kurzen beschreibenden wie torpedo_board.

4. Issues überprüfen

propagate (und refine, absent, keyframes --rm) geben die aktuelle Issue-Liste zurück:

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

Sieh dir für jedes Issue seinen worst_frame an:

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

In der Ansicht ist die Track-Maske magenta mit einem Umriss. Eine gelbe Box markiert einen Keyframe und eine Cyan-Box einen propagierten Frame. Der Farbton verbirgt die Farbe des Objekts; verwende für alles, was Identität oder Abdeckung betrifft, die Nahaufnahme:

agentseg view <f> --track <T> --zoom     # [nächster Keyframe] [Frame] [Frame + Umriss], keine Füllung

Identität. Nach einer Okklusion, einem Tunnel, einem Kameraschnitt oder einer schnellen Schwenkung springt SAM oft auf ein ähnliches Objekt in der Nähe. Vergleiche mit dem Keyframe-Panel: gleiche Farbe, gleicher Karosserietyp (SUV vs Limousine, Fließheck vs Stufenheck), gleiche Details? „Ein dunkles Auto an der richtigen Stelle“ reicht nicht. Jedes Issue, dessen reasons dino_low enthält (die Maske sieht anders aus als der Keyframe), benötigt einen Zoom-Vergleich, bevor du es überprüfen darfst. Wenn es ein anderes Objekt ist, befindet sich das echte entweder woanders (segment + track refine darauf) oder ist nicht sichtbar (track absent).

Was du siehst	Aktion
Maske ist korrekt; das Objekt wurde nur kleiner, größer, gedreht oder bewegte sich schnell	Als geprüft markieren: agentseg track review T <issue_id> --note "<einzeilige Begründung>". Die Frames wechseln von Prüfung zu genehmigt.
Maske läuft auf Hintergrund oder andere Objekte über, oder hat verstreute Punkte weit weg (riesige Bbox)	segment diesen Frame mit einer engen Box (+ --neg auf den Überlauf), dann track refine T <f> --preview P
Maske deckt nur einen Teil des Objekts ab (überprüfe den Zoom) oder sitzt auf dem falschen Objekt (vergleiche mit dem Keyframe-Panel)	Gleich: segment → track refine
Objekt ist überhaupt nicht sichtbar (außerhalb des Bildes, vollständig verdeckt), aber eine Maske existiert	track absent T <bereich>. Finde den Bereich zuerst mit sheet --track T --frames a-b.
Objekt ist sichtbar, aber es gibt keine Maske (rot „leer“ im Sheet)	segment → track refine auf einem Frame, wo es klar sichtbar ist

Regeln:

• Verfeinere niemals, ohne vorher die Vorschau anzusehen. Ein schlechter Keyframe vergiftet den Tracker für viele Frames.
• Wenn ein von dir hinzugefügter Keyframe die Situation verschlechtert hat: agentseg track keyframes T --rm <f>.
• Batch-Korrekturen: füge --no-propagate zu allen außer dem letzten refine oder absent hinzu, oder folge ihnen mit einem agentseg track propagate T. Jede Propagation kostet 30–60 s.
• Bei absent überprüfe die Grenzen. Verwende sheet --track T --frames a-b um den Bereich herum und markiere nur Frames, in denen das Objekt wirklich nicht sichtbar ist (ein Fitzel am Bildrand zählt noch als sichtbar).
• Gleiches Issue nach 2 Korrekturen noch vorhanden → höre auf, es zu korrigieren, lasse es offen (führe keine review durch) und erwähne es in deinem Bericht. Offene Issues sind das, was eine Person später überprüft.
• Führe eine review nur durch, nachdem du die Frames angesehen hast. Bei einem langen Issue überprüfe ein sheet --track T --frames a-b des Bereichs, nicht nur worst_frame. Mehrere gleichzeitig geprüfte Issues: track review T 2,3,5 --note ..., aber nur Issues der gleichen Art, die du tatsächlich überprüft hast; der Hinweis muss für jede ID darin wahr sein. Überprüfe niemals ein lost-Issue (leere Frames) als „Maske korrekt“.
• Budget: etwa 10 Korrekturen und etwa 40 angezeigte Bilder pro Sequenz. Bevorzuge ein sheet gegenüber vielen views, wenn du einen Bereich durchsuchst.

5. Endkontrolle und Export

agentseg sheet --track T                 # Randfarben: gelb = Keyframe, grün = ok,
                                        # orange = Prüfung, grau = abwesend, rot = keine Maske
agentseg export                          # YOLO-seg (Standard); --format yolo-detect|coco

Sieh dir das endgültige Sheet an. Orange Frames gehören zu noch offenen Issues: überprüfe sie und führe review durch, korrigiere sie, oder lasse sie absichtlich für eine Person offen. Rote Frames benötigen Aufmerksamkeit, es sei denn, das Objekt ist dort wirklich abwesend; dann markiere sie als absent.

6. Bericht an den Benutzer

Kurz:

• Track-ID und Label
• Anzahl der Frames
• Keyframes (Frames und warum)
• abwesende Bereiche
• als in Ordnung befundene Issues mit einzeiligen Begründungen
• ungelöste Issues
• Exportpfad
• Pfad des endgültigen Sheets

Referenz

agentseg status | up [--no-sam] [--no-ui] | down [--all]
agentseg project open <verz> [--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]

Alle Befehle akzeptieren --help. Fehler geben {"ok": false, "error": "..."} aus und beenden mit einem Fehlercode; lies die Meldung, da sie normalerweise die Korrektur benennt.