agentseg によるシーケンスのラベル付け
オブジェクトを 1 回セグメンテーションすると、SAM 3 が全フレームを追跡し、バックエンドが不適切と思われるフレームを「イシュー」としてフラグ付けします。あなたの仕事は、良好な最初のマスクを提供し、イシューを検査して、実際に間違っているものだけを修正することです。ほとんどのシーケンスでは 0～3 回の修正が必要です。
リポジトリルートから CLI を .venv/bin/agentseg …（または uv run agentseg …）として実行します。すべてのコマンドは JSON オブジェクトを 1 つ出力します；ok、error、next を読み取ってください。画像は PNG ファイルとして書き込まれ、"image": "<path>" として返されます。そのパスをファイル読み取りツールで開いて確認してください。 マスクは見ないと判断できません。
規則：ピクセル座標、ボックス x0,y0,x1,y1、ポイント x,y、フレームはプロジェクトの画像順における 0 ベースのインデックスです。フレーム範囲は 120-139,150 のように記述します。
0. サービス
agentseg status # バックエンド + sam_server + 開かれているプロジェクト
agentseg up # 停止しているものを起動（sam_server は約 1～2 分）
up が失敗した場合は、出力されたログパスを読んでください。他の GPU プロセスを終了しないでください。実行中は agentseg down を決して実行しないでください：バックエンドがあなたをホストしており、停止すると実行が終了します。GPU は共有されている可能性があるため、コマンドが sam_server エラー（CUDA メモリ不足）で失敗することがあります。30～60 秒待ってから再試行してください；agentseg up は停止しているものだけを起動します。それでも失敗し続ける場合は、停止して報告してください。
1. プロジェクトを開いてオブジェクトを見つける
agentseg project open <image_folder> # または既存のプロジェクトディレクトリ（agentseg.db があるもの）
agentseg sheet # シーケンス全体の約 24 枚のサムネイル
project open は frames と image_size を返します。シートを見てください。オブジェクトが 完全に見え、大きく、鮮明 なプロンプトフレームを選んでください。フレーム 0 である必要はありません。追跡はキーフレームから前方および後方に実行されます。
2. 最初のマスクの前にラベルを解決する
segment を呼び出したりトラックを作成する前に、ラベル名を選択してください。ユーザーのリクエストにあるオブジェクト名を使用します；明示的でない場合は、画像から短く具体的な名前を推測し、その選択を実行時に明示してください。ラベルを unknown、空文字列、プレースホルダーのままにしないでください。いくつかの妥当なオブジェクトがあり、選択によってアノテーション対象が変わる場合は、SAM を実行する前にユーザーに確認してください。解決された名前は、最初の track create 呼び出しとその後のすべてのレポートに引き継がれます。
たとえば、「魚雷をラベル付けして」の場合は torpedo に解決します；「このフォルダのボードをラベル付けして」の場合は board（または、それが明確なオブジェクト識別子である場合は torpedo_board）に解決します。シーケンス全体で安定した名前に保ってください。
最初のマスクの前に、プロジェクトのラベルリストに登録します（これは Web UI でユーザーが選択するリストと同じです；既存のラベルがオブジェクトをすでに命名している場合は、それを再利用します）：
agentseg labels # 既存のラベル
agentseg labels --add <resolved_label>
3. 最初のマスク
agentseg view <f> --grid # 座標読み取り用の 50 px ラベル付きグリッド
agentseg segment <f> --box x0,y0,x1,y1 # プレビューのみ、保存はされない
ボックス：ぴったりと、オブジェクト全体を囲むように。 グリッド上で、オブジェクトの左端、右端、上端、下端（バンパーからバンパー、ホイール、屋根）を見つけ、そのサイズの約 5～10% の小さなマージンを追加します。それ以上は不要です：余裕がありすぎるボックスは、SAM がオブジェクトの 影 やその周囲の地面を取り込み、トラッカーがそれをすべてのフレームにコピーすることになります。
checkを読んでください：segmentは 20% 大きいボックスも試します。大きいボックスでマスクが拡大するというWARNINGは、ボックスがオブジェクトを切り取ったことを意味します。その大きなマスクのズームがオブジェクト全体を示している場合は、そのpadded_preview_idを使用します；そうでない場合は、オブジェクト全体を囲むようにボックスを描き直します。決して無視して同じボックスを再実行しないでください。segmentはimage（全体フレーム、黄色の塗りつぶし）とzoom（クローズアップ、輪郭のみ、シアン = 使用したボックス）を返します。ズームを開いて、輪郭を一周歩いてください：オブジェクトのすべての端がその内側にある必要があります。- 多すぎる？ 輪郭はオブジェクト自体のエッジに沿っている必要があります。輪郭がオブジェクトの下や横の影、道路、隣接オブジェクトにまで及んでいる場合は、その部分に
--neg x,yを付けて（よりぴったりとしたボックスで）再実行してください。 - それでも部分的なマスク？ 同じボックスを再実行しないでください：同じマスクになります。欠落している部分に
--pos x,yを指定してください（SAM は色や光の境界で止まることがよくあります：日が当たっている半分、影になっている半分、2 トーンの車両など）。 - 範囲： ユーザーが意図するオブジェクトだけを含めてください：「ボード」は台座を含まず、「車」はトレーラーを含みません。
- 最大 4 回の試行。オブジェクトの 2/3 しかカバーしないキーフレームは、まったくないよりも悪いです：トラッカーはそれをすべてのフレームにコピーし、健全性チェックでは検出できません。このフレームでオブジェクト全体を取得できない場合は、別のフレームを選んでください。その後：
agentseg track create --label <resolved_label> --preview <preview_id>
agentseg track propagate <track_id> # 500 フレームあたり約 1 分；イシューを返す
後でキーフレームを追加する場合は、segment に --track T を渡します：ズームにはトラックの最も近いキーフレームも表示されるため、同じオブジェクトであることを確認できます。
3b. 追跡がオブジェクトを見失った場合
SAM 3 は通常、しばらく見えなくなった後にオブジェクトを自動的に再検出するため、短いギャップは対処不要です。propagate は、マスクが 60 フレーム連続で空になった場合にのみ、その方向での追跡を停止し、lost を返します：
"lost": [{"keyframe": 420, "direction": "forward", "lost_from": 579, "stopped_at": 638, "untracked": [639, 999]}]
より一般的な失敗は逆です：ギャップの後、SAM が 別の、類似したオブジェクトに戻ってしまうことです。空のフレームの後（シート --track で赤色）にトラックが再出現した場所では、view <ギャップ後の最初のフレーム> --track T --zoom で同一性を確認してください。
イシューの 前に lost に対処してください。lost_from から実際に何が起こっているかを確認します：agentseg sheet --frames <lost_from-5>-<lost_from+40>（--track なしで、プレーンなフレームを見る）。
- オブジェクトが消えている（トンネル、建物の陰、カメラが別の方向を向いている、カット）：オブジェクトが再出現する場所を見つけ、
track absent T <lost_from>-<最後に消えていたフレーム> --no-propagateを実行し、次に再出現した明確なフレームでsegment+track refineを実行します。 - オブジェクトがまだ見えている：トラッカーがドロップしたものです。
lost_fromの直後の明確なフレームでsegment+track refineを実行します。 - 終了まで再出現しない：残りを
absentとしてマークします。
各修正で再伝播されます；lost がなくなるまで繰り返します。
ユーザーが指定したラベル名、または torpedo_board などの短く説明的な名前を使用します。
4. イシューのレビュー
propagate（および refine、absent、keyframes --rm）は現在のイシューリストを返します：
{"id": 9, "start": 210, "end": 228, "worst_frame": 218, "kind": "drift", "n_frames": 19, "reasons": {...}}
各イシューについて、その worst_frame を確認します：
agentseg view <worst_frame> --track <T> --grid
ビューでは、トラックマスクはマゼンタ色で輪郭が表示されます。黄色のボックスはキーフレーム、シアンのボックスは伝播されたフレームを示します。色合いによってオブジェクトの色が隠れるため、同一性やカバレッジについてはクローズアップを使用します：
agentseg view <f> --track <T> --zoom # [最も近いキーフレーム] [フレーム] [フレーム+輪郭]、塗りつぶしなし
同一性。 オクルージョン、トンネル、カメラカット、高速パンの後、SAM は近くの 類似した オブジェクトにジャンプすることがよくあります。キーフレームパネルと比較してください：同じ色、同じボディタイプ（SUV 対セダン、ハッチバック対トランク）、同じ詳細ですか？「適切な場所にある暗い車」では不十分です。reasons に dino_low（マスクがキーフレームと似ていない）があるイシューは、レビューする前にズーム比較が必要です。別のオブジェクトの場合、実際のオブジェクトは別の場所にある（segment + track refine）か、見えない（track absent）かのどちらかです。
| 見えるもの | アクション |
|---|---|
| マスクは正しい；オブジェクトが単に小さくなったり、大きくなったり、回転したり、速く動いただけ | チェック済みとしてマーク： agentseg track review T <issue_id> --note "<一行で理由>"。そのフレームがレビューから承認に変わります。 |
| マスクが背景や他のオブジェクトにはみ出している、または遠くに飛び散った斑点がある（巨大な bbox） | segment でそのフレームにタイトなボックス（+ はみ出し部分に --neg）を使用し、次に track refine T <f> --preview P |
| マスクがオブジェクトの一部のみをカバーしている（ズームで確認）、または間違ったオブジェクトにある（キーフレームパネルと比較） | 同じ：segment → track refine |
| オブジェクトがまったく見えない（フレーム外、完全にオクルード）が、マスクが存在する | track absent T <範囲>。まず sheet --track T --frames a-b で範囲を見つけます。 |
| オブジェクトが見えるがマスクがない（シートで赤い「空」） | 明確に見えるフレームで segment → track refine |
ルール：
- プレビューを最初に見ずに refine しないでください。 悪いキーフレームは、多くのフレームでトラッカーを汚染します。
- 追加したキーフレームが状況を悪化させた場合：
agentseg track keyframes T --rm <f>。 - バッチ修正： 最後の
refineまたはabsent以外には--no-propagateを追加するか、それらに続いて 1 回のagentseg track propagate Tを実行します。各伝播には 30～60 秒かかります。 absentについては、境界を確認してください。範囲の前後でsheet --track T --frames a-bを使用し、オブジェクトが本当に見えないフレームのみをマークしてください（画像端のわずかな部分も可視と見なします）。- 2 回修正しても同じイシューが残る場合 → 修正をやめ、オープンのままにし（
reviewしない）、レポートに記載します。オープンイシューは後で人間がチェックします。 - フレームを確認した後にのみイシューを
reviewしてください。長いイシューの場合は、worst_frameだけでなく、範囲のsheet --track T --frames a-bを確認してください。複数のイシューを一度にチェック：track review T 2,3,5 --note ...ですが、実際にチェックした同じ種類のイシューのみで、メモはすべての ID に当てはまる必要があります。lostイシュー（空のフレーム）を「マスク正しい」としてレビューしないでください。 - 予算：シーケンスあたり約 10 回の修正と約 40 枚の画像表示。範囲をスキャンするときは、多くの
viewよりも 1 枚のsheetを優先します。
5. 最終チェックとエクスポート
agentseg sheet --track T # 境界色：黄色=キーフレーム、緑=OK、
# オレンジ=レビュー、灰色=欠落、赤=マスクなし
agentseg export # YOLO-seg（デフォルト）；--format yolo-detect|coco
最終シートを確認します。オレンジ色のフレームはまだオープンのイシューに属します：確認して review するか、修正するか、あるいは意図的にオープンのままにして人間に任せます。赤色のフレームは注意が必要ですが、オブジェクトが本当に存在しない場合は、absent としてマークします。
6. ユーザーへのレポート
簡潔に：
- トラック ID とラベル
- フレーム数
- キーフレーム（フレームと理由）
- 欠落範囲
- 問題なしとしてレビューされたイシュー（一行理由付き）
- 未解決のイシュー
- エクスポートパス
- 最終シートパス
リファレンス
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]
すべてのコマンドは --help を受け付けます。エラーは {"ok": false, "error": "..."} を出力し、非ゼロで終了します；メッセージは通常、修正方法を示しているので読んでください。