eminmeydanoglu/agentseg-label

agentseg로 시퀀스 레이블링하기

객체를 한 번 세그먼트하면 SAM 3이 모든 프레임을 추적하고, 백엔드는 잘못된 것으로 보이는 프레임("issues")을 플래그로 표시합니다. 당신의 작업은 좋은 첫 번째 마스크를 제공한 다음, 문제를 검사하고 실제로 잘못된 것만 수정하는 것입니다. 대부분의 시퀀스는 0–3회 수정이 필요합니다.

CLI는 프로젝트 루트에서 .venv/bin/agentseg … (또는 uv run agentseg …)으로 실행합니다. 모든 명령은 하나의 JSON 객체를 출력합니다. 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)로 결정합니다. 전체 시퀀스 동안 안정적으로 유지하세요.

첫 번째 마스크 전에 프로젝트의 레이블 목록에 등록하세요 (이것은 웹 UI에서 사람이 선택하는 동일한 목록이며, 기존 레이블이 객체를 이미 명명하는 경우 재사용하세요):

agentseg labels                     # 기존 레이블
agentseg labels --add <결정된_레이블>

3. 첫 번째 마스크

agentseg view <f> --grid                          # 좌표 읽기를 위한 50px 라벨링된 그리드
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은 종종 색상 또는 빛 경계에서 멈춥니다: 햇빛 반쪽, 그림자 반쪽, 두 가지 색상의 차량).
• 범위: 사용자가 의미하는 객체를 정확히 포함하세요: "보드"는 스탠드 없이, "자동차"는 트레일러 없이.
• 최대 4번 시도하세요. 객체의 2/3만 덮는 키프레임은 아예 없는 것보다 나쁩니다: 추적기가 모든 프레임에 복사하고 상태 검사가 이를 볼 수 없습니다. 이 프레임에서 객체 전체를 얻을 수 없으면 다른 프레임을 선택하세요. 그런 다음:

agentseg track create --label <결정된_레이블> --preview <preview_id>
agentseg track propagate <track_id>               # 500프레임당 약 1분; issues 반환

나중에 추가된 키프레임의 경우 segment에 --track T를 전달하세요: 확대 이미지가 트랙의 가장 가까운 키프레임도 표시하므로 동일한 객체인지 확인할 수 있습니다.

3b. 추적이 객체를 놓쳤을 때

SAM 3은 일반적으로 객체가 잠시 사라진 후 스스로 다시 찾으므로 짧은 간격은 아무 조치가 필요 없습니다. propagate는 마스크가 60프레임 연속으로 비어 있어야만 추적을 중단하고 lost를 반환합니다:

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

더 일반적인 실패는 그 반대입니다: 간격 후 SAM이 다른 유사한 객체로 돌아오는 경우입니다. 빈 프레임 후 트랙이 다시 나타나는 곳(시트에서 빨간색 sheet --track)에서는 view <갭 후 첫 번째 프레임> --track T --zoom으로 정체성을 확인하세요.

issues보다 먼저 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. issues 검토

propagate (및 refine, absent, keyframes --rm)는 현재 issue 목록을 반환합니다:

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

각 issue에 대해 worst_frame을 확인하세요:

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

보기에서 트랙 마스크는 자홍색에 윤곽선이 있습니다. 노란색 박스는 키프레임을, 시안색 박스는 전파된 프레임을 표시합니다. 틴트는 객체의 색상을 숨깁니다. 정체성이나 범위에 관한 것은 클로즈업을 사용하세요:

agentseg view <f> --track <T> --zoom     # [가장 가까운 키프레임] [프레임] [프레임 + 윤곽선], 채움 없음

정체성. 가려짐, 터널, 카메라 컷 또는 빠른 패닝 후 SAM은 종종 근처의 유사한 객체로 점프합니다. 키프레임 패널과 비교하세요: 동일한 색상, 동일한 차체 유형(SUV vs 세단, 해치백 vs 트렁크), 동일한 세부 사항? "올바른 위치에 있는 어두운 차량"으로는 충분하지 않습니다. reasons에 dino_low(마스크가 키프레임과 다름)가 있는 모든 issue는 검토 전에 확대 비교가 필요합니다. 다른 객체인 경우, 실제 객체는 다른 곳에 있거나(segment + track refine) 보이지 않습니다(track absent).

보이는 상황	조치
마스크가 정확함; 객체가 단지 작아지거나, 커지거나, 회전하거나 빠르게 움직인 경우	Checked로 표시: 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로 범위를 찾으세요.
객체는 보이지만 마스크가 없음 (시트에서 빨간색 "empty")	객체가 명확히 보이는 프레임에서 segment → track refine

규칙:

• 미리보기를 먼저 확인하지 않고 refine하지 마세요. 잘못된 키프레임은 많은 프레임에 대해 추적기를 오염시킵니다.
• 추가한 키프레임이 상황을 악화시킨 경우: agentseg track keyframes T --rm <f>.
• 일괄 수정: 마지막 refine 또는 absent를 제외한 모든 명령에 --no-propagate를 추가하거나, 이후에 하나의 agentseg track propagate T로 실행하세요. 각 전파는 30–60초가 소요됩니다.
• absent의 경우 경계를 확인하세요. 범위 주변에서 sheet --track T --frames a-b를 사용하고 객체가 실제로 보이지 않는 프레임만 표시하세요 (이미지 가장자리의 조각도 여전히 보이는 것으로 간주).
• 동일한 issue가 2회 수정 후에도 여전히 존재하면 → 수정을 중단하고, 열어두고 (검토하지 마세요) 보고서에 언급하세요. 열린 issue는 사람이 나중에 확인합니다.
• 프레임을 확인한 후에만 issue를 review하세요. 긴 issue의 경우, worst_frame만이 아니라 범위의 sheet --track T --frames a-b를 확인하세요. 여러 건의 확인된 issue를 한 번에: track review T 2,3,5 --note ..., 단 동일한 종류의 issue만 해당하며, 메모는 포함된 모든 id에 대해 사실이어야 합니다. lost issue(빈 프레임)를 "mask correct"로 검토하지 마세요.
• 예산: 시퀀스당 약 10회 수정 및 약 40개 이미지 보기. 범위를 스캔할 때 여러 번의 view보다 하나의 sheet를 선호하세요.

5. 최종 확인 및 내보내기

agentseg sheet --track T                 # 테두리 색상: 노란색 키프레임, 녹색 OK,
                                        # 주황색 검토, 회색 absent, 빨간색 마스크 없음
agentseg export                          # YOLO-seg (기본값); --format yolo-detect|coco

최종 시트를 확인하세요. 주황색 프레임은 아직 열려 있는 issue에 속합니다: 확인하고 review하거나, 수정하거나, 의도적으로 사람을 위해 열어둡니다. 빨간색 프레임은 주의가 필요합니다. 단, 객체가 실제로 그곳에 없는 경우는 제외합니다. 그런 경우 absent로 표시하세요.

6. 사용자에게 보고

짧게:

• 트랙 ID 및 레이블
• 프레임 수
• 키프레임 (프레임 및 이유)
• absent 범위
• 문제없음으로 검토된 issues, 한 줄 이유 포함
• 해결되지 않은 issues
• 내보내기 경로
• 최종 시트 경로

참조

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": "..."}를 출력하고 0이 아닌 종료 코드로 종료됩니다. 메시지를 읽으세요. 일반적으로 수정 방법을 알려줍니다.