eminmeydanoglu/agentseg-label

Rotulando uma sequência com agentseg

Você segmenta o objeto uma vez, o SAM 3 rastreia-o através de cada quadro, e o backend sinaliza quadros que parecem errados ("problemas"). Seu trabalho é dar uma boa primeira máscara, depois inspecionar problemas e corrigir apenas o que está realmente errado. A maioria das sequências precisa de 0 a 3 correções.

Execute o CLI a partir da raiz do repositório como .venv/bin/agentseg … (ou uv run agentseg …). Cada comando imprime um objeto JSON; leia ok, error e next. Imagens são escritas como arquivos PNG e retornadas como "image": "<caminho>". Abra esse caminho com sua ferramenta de leitura de arquivos para vê-lo. Você não pode julgar uma máscara sem olhar.

Convenções: coordenadas de pixels, caixas x0,y0,x1,y1, pontos x,y, quadros são índices baseados em 0 na ordem de imagens do projeto. Intervalos de quadros são escritos como 120-139,150.

0. Serviços

agentseg status            # backend + sam_server + projeto aberto
agentseg up                # inicia o que está parado (sam_server leva ~1–2 min)

Se up falhar, leia o caminho do log que ele imprime. Não mate outros processos GPU. Nunca execute agentseg down durante uma execução: o backend hospeda você, e pará-lo encerra sua execução. A GPU pode ser compartilhada, então um comando pode falhar com um erro sam_server (CUDA sem memória). Aguarde 30–60 s e tente novamente; agentseg up só inicia o que está parado. Se continuar falhando, pare e relate.

1. Abra o projeto e encontre o objeto

agentseg project open <pasta_de_imagens>     # ou um diretório de projeto existente (tem agentseg.db)
agentseg sheet                           # ~24 miniaturas por toda a sequência

project open retorna frames e image_size. Olhe a planilha. Escolha um quadro de prompt onde o objeto está completamente visível, grande e nítido, não necessariamente o quadro 0. O rastreamento é executado tanto para frente quanto para trás a partir dos quadros chave.

2. Resolva o rótulo antes da primeira máscara

Escolha o nome do rótulo antes de chamar segment ou criar uma trilha. Use o nome do objeto da solicitação do usuário; quando não for explícito, infira um nome curto e específico da imagem e declare essa escolha na execução. Nunca deixe o rótulo como unknown, uma string vazia ou um placeholder. Se houver vários objetos plausíveis e a escolha mudar o alvo da anotação, pergunte ao usuário antes de executar o SAM. O nome resolvido é carregado na primeira chamada track create e em todos os relatórios posteriores.

Por exemplo, para "rotuleie o torpedo" resolva torpedo; para "rotuleie a placa nesta pasta" resolva board (ou torpedo_board quando essa for a identidade clara do objeto). Mantenha-o estável por toda a sequência.

Registre-o na lista de rótulos do projeto antes da primeira máscara (esta é a mesma lista que uma pessoa escolhe na interface web; reutilize um rótulo existente quando um já nomeia o objeto):

agentseg labels                     # rótulos existentes
agentseg labels --add <rótulo_resolvido>

3. Primeira máscara

agentseg view <f> --grid                          # grade rotulada de 50 px para ler coordenadas
agentseg segment <f> --box x0,y0,x1,y1            # apenas pré-visualização, nada salvo

Caixas: ajustadas, ao redor de todo o objeto. Na grade, encontre os pixels mais à esquerda, direita, superior e inferior do objeto (para-choque a para-choque, rodas, teto), depois adicione uma pequena margem (cerca de 5–10% do seu tamanho). Não mais: uma caixa com muito espaço permite que o SAM capture a sombra do objeto ou o chão ao seu redor, e o rastreador então copia isso para todos os quadros.

• Leia check: segment também tenta uma caixa 20% maior. Um WARNING de que a máscara cresce com a caixa maior significa que sua caixa cortou o objeto. Se o zoom dessa máscara maior mostrar o objeto inteiro, use seu padded_preview_id; caso contrário, redesenhe a caixa ao redor de todo o objeto. Nunca ignore e re-execute a mesma caixa.
• segment retorna image (quadro inteiro, preenchimento amarelo) e zoom (close-up, apenas contorno, ciano = a caixa usada). Abra o zoom e percorra o contorno: cada extremidade do objeto deve estar dentro dele.
• Muito? O contorno deve seguir a própria borda do objeto. Se ele correr para a sombra abaixo ou ao lado do objeto, a estrada ou um vizinho, re-execute com --neg x,y nessa parte (e uma caixa mais ajustada).
• Ainda uma máscara parcial? Não re-execute a mesma caixa: ela dá a mesma máscara. Coloque --pos x,y na parte que está faltando (SAM geralmente para em um limite de cor ou luz: metade ensolarada, metade sombreada, veículo de dois tons).
• Escopo: inclua exatamente o objeto que o usuário quer: "a placa" sem seu suporte, "o carro" sem o reboque.
• Até 4 tentativas. Um quadro chave que cobre 2/3 do objeto é pior que nenhum: o rastreador copia-o para todos os quadros e a integridade não pode vê-lo. Se você não conseguir obter o objeto inteiro neste quadro, escolha outro quadro. Então:

agentseg track create --label <rótulo_resolvido> --preview <id_da_pré-visualização>
agentseg track propagate <id_da_trilha>               # ~1 min por 500 quadros; retorna problemas

Para quadros chave adicionados depois, passe --track T para segment: o zoom também mostra o quadro chave mais próximo da trilha, para que você possa verificar se é o mesmo objeto.

3b. Quando o rastreamento perde o objeto

O SAM 3 geralmente recupera o objeto sozinho depois que ele fica ausente por um tempo, então lacunas curtas não exigem nada. propagate para o rastreamento em uma direção somente depois que a máscara fica vazia por 60 quadros consecutivos, e retorna lost:

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

A falha mais comum é o oposto: após uma lacuna, o SAM retorna em um objeto diferente e similar. Onde quer que a trilha reapareça após quadros vazios (vermelho em sheet --track), verifique a identidade com view <primeiro quadro após a lacuna> --track T --zoom.

Lide com lost antes dos problemas. Olhe o que realmente acontece a partir de lost_from: agentseg sheet --frames <lost_from-5>-<lost_from+40> (sem --track, então você vê os quadros simples).

• O objeto se foi (túnel, atrás de um prédio, câmera desvia, um corte): encontre onde ele retorna, track absent T <lost_from>-<último_quadro_ausente> --no-propagate, depois segment + track refine em um quadro claro onde ele está de volta.
• O objeto ainda está visível: o rastreador o soltou. segment + track refine em um quadro claro logo após lost_from.
• Ele nunca retorna antes do fim: marque o resto como absent.

Cada correção re-propaga; repita até que não haja lost.

Use o nome do rótulo que o usuário deu, ou um descritivo curto como torpedo_board.

4. Revise problemas

propagate (e refine, absent, keyframes --rm) retornam a lista de problemas atual:

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

Para cada problema, olhe seu worst_frame:

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

Na visualização, a máscara da trilha é magenta com um contorno. Uma caixa amarela marca um quadro chave e uma caixa ciano um quadro propagado. O tom esconde a cor do objeto; para qualquer coisa sobre identidade ou cobertura, use o close-up:

agentseg view <f> --track <T> --zoom     # [quadro chave mais próximo] [quadro] [quadro + contorno], sem preenchimento

Identidade. Após uma oclusão, um túnel, um corte de câmera ou uma panorâmica rápida, SAM frequentemente salta para um objeto similar próximo. Compare com o painel do quadro chave: mesma cor, mesmo tipo de carroceria (SUV vs sedan, hatchback vs tronco), mesmos detalhes? "Um carro escuro no lugar certo" não é suficiente. Qualquer problema cujo reasons tenha dino_low (a máscara parece diferente do quadro chave) precisa de uma comparação de zoom antes que você possa revisá-lo. Se for outro objeto, o real está em outro lugar (segment + track refine nele) ou não visível (track absent).

O que você vê	Ação
A máscara está correta; o objeto apenas ficou menor, maior, girou ou moveu-se rapidamente	Marque como verificado: agentseg track review T <id_do_problema> --note "<uma linha de motivo>". Seus quadros mudam de revisão para aprovados.
A máscara transborda para o fundo ou outros objetos, ou tem manchas soltas distantes (bbox enorme)	segment nesse quadro com uma caixa justa (+ --neg no transbordo), depois track refine T <f> --preview P
A máscara cobre apenas parte do objeto (verifique o zoom), ou está no objeto errado (compare com o painel do quadro chave)	Mesmo: segment → track refine
O objeto não está visível (fora do quadro, totalmente ocluído), mas uma máscara existe	track absent T <intervalo>. Encontre o intervalo primeiro com sheet --track T --frames a-b.
O objeto está visível, mas não há máscara (vermelho "vazio" na planilha)	segment → track refine em um quadro onde ele esteja claramente visível

Regras:

• Nunca refine sem olhar a pré-visualização primeiro. Um quadro chave ruim envenena o rastreador por muitos quadros.
• Se um quadro chave que você adicionou piorou as coisas: agentseg track keyframes T --rm <f>.
• Correções em lote: adicione --no-propagate a todos, exceto o último refine ou absent, ou siga-os com um agentseg track propagate T. Cada propagação custa 30–60 s.
• Para absent, verifique os limites. Use sheet --track T --frames a-b ao redor do intervalo e marque apenas quadros onde o objeto realmente não está visível (uma fatia na borda da imagem ainda conta como visível).
• Se o mesmo problema ainda estiver lá após 2 correções → pare de corrigi-lo, deixe-o aberto (não review) e mencione no seu relatório. Problemas abertos são o que uma pessoa verifica depois.
• Apenas review um problema depois de olhar seus quadros. Para um problema longo, verifique um sheet --track T --frames a-b do intervalo, não apenas worst_frame. Vários problemas verificados de uma vez: track review T 2,3,5 --note ..., mas apenas problemas do mesmo tipo que você realmente verificou; a nota deve ser verdadeira para cada id nela. Nunca revise um problema lost (quadros vazios) como "máscara correta".
• Orçamento: cerca de 10 correções e cerca de 40 imagens visualizadas por sequência. Prefira um sheet em vez de muitos views ao escanear um intervalo.

5. Verificação final e exportação

agentseg sheet --track T                 # cores da borda: quadro chave amarelo, verde ok,
                                        # laranja revisão, cinza ausente, vermelho sem máscara
agentseg export                          # YOLO-seg (padrão); --format yolo-detect|coco

Olhe a planilha final. Quadros laranja pertencem a problemas ainda abertos: verifique e review eles, corrija-os, ou deixe-os abertos intencionalmente para uma pessoa. Quadros vermelhos precisam de atenção, a menos que o objeto esteja realmente ausente lá; então marque-os como absent.

6. Relate ao usuário

Curto:

• id da trilha e rótulo
• número de quadros
• quadros chave (quadros e porquê)
• intervalos ausentes
• problemas revisados como bons, com motivos de uma linha
• problemas deixados não resolvidos
• caminho de exportação
• caminho da planilha final

Referência

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 os comandos aceitam --help. Erros imprimem {"ok": false, "error": "..."} e saem com código não zero; leia a mensagem, pois geralmente nomeia a correção.