Lightbridge-KS/agent-skills

Referência de Linha de Comando do DCMTK

DCMTK é o OFIS DICOM Toolkit — uma implementação de referência madura, licenciada sob BSD, de grandes partes do padrão DICOM. Esta habilidade cobre suas ferramentas de linha de comando (a API C++ está fora do escopo aqui).

Se você pode fazer algo com DICOM, provavelmente existe um binário dcm* para isso. A pegadinha: o conjunto de ferramentas é grande (~70 binários em 12 módulos) e as convenções de flags (-x vs +x são flags diferentes) são surpreendentes. Esta habilidade existe para que um agente de IA possa escolher a ferramenta correta, escrever uma invocação correta na primeira tentativa e evitar os clássicos buracos do DCMTK.

Modelo mental

O DCMTK agrupa ferramentas em módulos pelo que elas manipulam:

dcmdata    arquivos DICOM no disco: analisar, despejar, modificar, codificar/decodificar (sem rede)
dcmnet     DIMSE sobre TCP: ECHO, STORE, FIND, MOVE, GET
dcmimage   renderizar dados de pixel DICOM para formatos de imagem comuns (PNG/PNM/BMP/TIFF)
dcmjpeg    compressão / descompressão JPEG (DCT) de dados de pixel DICOM
dcmjpls    compressão / descompressão JPEG-LS de dados de pixel DICOM
dcmsr      Relatórios Estruturados: despejar, renderizar, round-trip com XML
dcmqrdb    um pequeno servidor de banco de dados Q/R independente (PACS de teste) + indexador
dcmwlm     um pequeno servidor de Worklist de Modalidade independente
dcmsign    Assinaturas digitais DICOM (assinar / verificar / remover)
dcmrt      Inspeção de objetos de Radioterapia (RT Plan / Struct / Dose / etc.)
dcmpstat   Estados de apresentação + SCP/SCU de impressão (avançado; não abordado aqui)
dcmtls     Suporte TLS (usado por ferramentas dcmnet; não é uma ferramenta própria)

A nomenclatura da CLI é consistente quando você a entende: ferramentas que codificam começam com dcmc* (dcmcjpeg, dcmcjpls, dcmcrle); ferramentas que decodificam começam com dcmd* (dcmdjpeg, dcmdjpls, dcmdrle); SCUs terminam em *scu (cliente de rede) e SCPs terminam em *scp (servidor de rede).

O mapa de serviços DIMSE

   Classe de Serviço     Operação        Ferramenta SCU             Ferramenta SCP
   ─────────────────────────────────────────────────────────────────
   Verificação          C-ECHO           echoscu              storescp aceita
   Armazenamento        C-STORE          storescu, dcmsend    storescp, dcmrecv
   Consulta/Recuperação C-FIND           findscu              dcmqrscp
                        C-MOVE           movescu              dcmqrscp
                        C-GET            getscu               dcmqrscp
   Worklist             C-FIND           findscu (com -W)     wlmscpfs

Para um PACS real, você usaria Orthanc / DCM4CHEE / ConQuest como SCP. Os SCPs próprios do DCMTK (dcmqrscp, wlmscpfs) são para testes e estruturação de integração.

A convenção de prefixo de flags

  -x   SEMPRE uma escolha mutuamente exclusiva (um modo entre vários)
  +x   SEMPRE ativa um recurso ou adiciona algo
  --x  forma longa de -x ou +x; mesma semântica

Portanto, -xe (propor little-endian) e +e1 (codificar JPEG Baseline) não estão relacionados — prefixo diferente, família de ferramentas diferente, significado diferente.

Qual ferramenta para qual tarefa

Você quer …	Ferramenta	Referência
Verificar se um PACS está acessível	echoscu	dcmnet.md
Enviar arquivo(s) DICOM para um PACS	dcmsend (ou storescu para controle fino de TS)	dcmnet.md
Receber DICOM em uma pasta	storescp (ou dcmrecv)	dcmnet.md
Consultar um PACS (por PatientID / Data / Accession)	findscu	dcmnet.md
Puxar estudos de um PACS	movescu ou getscu	dcmnet.md
Mostrar todas as tags em um arquivo DICOM	dcmdump	dcmdata.md
Encontrar uma tag em um arquivo DICOM	dcmdump --search KEY	dcmdata.md
Anonimizar / modificar uma tag	dcmodify	dcmdata.md
Converter DICOM → JSON	dcm2json	dcmdata.md
Converter DICOM → XML	dcm2xml	dcmdata.md
Verificar se um arquivo é DICOM Part-10 válido	dcmftest	dcmdata.md
Construir um DICOMDIR para intercâmbio de mídia	dcmmkdir (apelido legado: dcmgpdir)	dcmdata.md
Alterar sintaxe de transferência (apenas não comprimido)	dcmconv	dcmdata.md
Comprimir DICOM com JPEG	dcmcjpeg	image-codecs.md
Descomprimir DICOM codificado em JPEG	dcmdjpeg	image-codecs.md
Comprimir / descomprimir com JPEG-LS	dcmcjpls / dcmdjpls	image-codecs.md
Comprimir / descomprimir com RLE	dcmcrle / dcmdrle	dcmdata.md
Renderizar DICOM → PNG / JPEG / TIFF / BMP / PNM	dcm2img	image-codecs.md
Redimensionar uma imagem DICOM	dcmscale	image-codecs.md
Empacotar JPEG/PNG/BMP/TIFF como DICOM	img2dcm	img-pdf-import.md
Empacotar um PDF (ou CDA/STL/OBJ) como DICOM encapsulado	dcmencap (apelido legado: pdf2dcm)	img-pdf-import.md
Extrair PDF/CDA/STL/OBJ embutido de um DICOM	dcmdecap (apelido legado: dcm2pdf)	img-pdf-import.md
Despejar a árvore de conteúdo de um Relatório Estruturado	dsrdump	dcmsr.md
Renderizar SR → HTML	dsr2html	dcmsr.md
Round-trip de SR através de XML	dsr2xml / xml2dsr	dcmsr.md
Montar um PACS de teste	dcmqrscp + dcmqridx	dcmqrdb-wlm.md
Montar um servidor de Worklist de Modalidade de teste	wlmscpfs	dcmqrdb-wlm.md
Assinar / verificar assinaturas digitais DICOM	dcmsign	dcmsign-dcmrt.md
Inspecionar objetos RT Plan / Struct / Dose	drtdump	dcmsign-dcmrt.md

Para flags compartilhadas (logging, rede, TLS, negociação de sintaxe de transferência, formato de arquivo), veja common-options.md. Para UIDs de sintaxe de transferência e as flags -x* / +t* correspondentes, veja transfer-syntax-uids.md.

Receitas principais

Os exemplos abaixo usam estes placeholders — substitua pelos valores reais para o ambiente alvo:

PACS_HOST       hostname ou IP do PACS de destino                  e.g. pacs.hospital.local
PACS_PORT       porta TCP DICOM do PACS de destino                 e.g. 104, 4242, 11112
PACS_AET        AE title chamado — deve corresponder à configuração do par   e.g. MAIN_PACS
MY_AET          nosso AE title de chamada                            e.g. ACME_SCU

1. Verificar se um PACS está acessível (C-ECHO)

echoscu -v PACS_HOST PACS_PORT -aec PACS_AET -aet MY_AET

O sucesso parece com Received Echo Response (Success). Se você vir Association Rejected, o par não conhece seu AE title -aec ou seu IP não está na lista de permissões de sua configuração.

2. Enviar arquivos DICOM para um PACS (C-STORE)

Arquivo único, controle total de TS:

storescu -v PACS_HOST PACS_PORT -aec PACS_AET -aet MY_AET input.dcm

Pasta, recursivamente, com renomeação por arquivo em caso de sucesso:

dcmsend -v PACS_HOST PACS_PORT -aec PACS_AET -aet MY_AET +sd +r /caminho/para/estudos/

Quando usar qual:

• storescu — testado em batalha, controle total -x* sobre negociação de TS, sem modo embutido de "escaneie uma pasta" além de +sd +r. Recorra a ele quando precisar de controle exato sobre quais TS serão propostas.
• dcmsend — mais novo, mais simples. Lida com escaneamento de diretório, resumo de status, renomeação .done / .bad. Recomendado como padrão para envios em lote para um par conhecido.

Falha comum: Association Aborted: presentation context not supported. O par não aceita a classe SOP ou a TS na qual o arquivo está codificado. Execute com -d para ver a negociação; os ACs oferecidos vs. os ACs aceitos tornam o problema óbvio.

3. Receber DICOM em uma pasta (C-STORE SCP)

storescp -v -aet MY_AET --output-directory /caminho/para/entrada/ \
         --sort-conc-studies study_ PACS_PORT

Os arquivos chegam em /caminho/para/entrada/study_<StudyInstanceUID>/.

Para modelos de nome de arquivo mais flexíveis e ganchos de pós-processamento por estudo, dcmrecv é a alternativa moderna — mesma ideia, configuração mais simples:

dcmrecv -v --output-directory /caminho/para/entrada/ PACS_PORT

4. Consultar um PACS (C-FIND)

Uma consulta C-FIND é construída a partir de chaves -k: cada -k ou restringe a pesquisa (-k "(0010,0020)=PATIENT_ID") ou solicita que aquele atributo seja retornado (-k "(0010,0010)" com valor vazio).

Todos os estudos para um paciente:

findscu -v -S \
  -k "(0008,0052)=STUDY" \
  -k "(0010,0020)=PATIENT_ID" \
  -k "(0010,0010)" \
  -k "(0020,000D)" \
  -k "(0008,0020)" \
  PACS_HOST PACS_PORT -aec PACS_AET -aet MY_AET

Flags para saber:

• -S modelo raiz de estudo (padrão e mais comum); -P raiz de paciente; -W worklist
• (0008,0052) QueryRetrieveLevel — deve corresponder ao modelo (STUDY/SERIES/IMAGE)
• Cada -k com um valor restringe; cada -k sem valor (apenas a tag) pede ao SCP para retorná-la

5. Recuperar estudos (C-MOVE)

C-MOVE pede ao SCP para enviar instâncias para um AE de destino — o que significa que o destino deve ser um storescp/dcmrecv em execução acessível pelo SCP, e o AE title de destino deve estar pré-registrado no SCP.

Terminal A — inicie o listener local:

storescp -v --output-directory ./recuperados/ -aet MY_AET 11112

Terminal B — emita o C-MOVE (destino = nosso MY_AET na porta 11112):

movescu -v -S \
  -k "(0008,0052)=STUDY" \
  -k "(0020,000D)=1.2.3.4.5.STUDY.UID" \
  -aem MY_AET \
  PACS_HOST PACS_PORT -aec PACS_AET -aet MY_AET

Se o PACS não tiver uma entrada para MY_AET em sua configuração, a movimentação falha com Move Destination Unknown. O próprio movescu também pode atuar como um listener subordinado com --port 11112 --output-directory ./out/ — útil para testes onde você não quer um terminal separado do storescp.

Para recuperação ponto a ponto onde o SCP não precisa saber sobre seu listener, C-GET (getscu) é mais simples:

getscu -v -S -k "(0008,0052)=STUDY" -k "(0020,000D)=1.2.3.4.5.STUDY.UID" \
       --output-directory ./recuperados/ \
       PACS_HOST PACS_PORT -aec PACS_AET

Mas muitos PACS de produção não suportam C-GET — C-MOVE é o padrão mais seguro.

6. Despejar tags de um arquivo

Arquivo inteiro, todas as tags:

dcmdump input.dcm

Apenas uma tag (por nome ou por grupo/elemento):

dcmdump --search PatientID input.dcm
dcmdump --search "0010,0010" input.dcm

A saída é uma linha por atributo:

(0010,0010) PN [DOE^JANE]                                #   8, 1 PatientName

Colunas: tag, VR, valor, comprimento, multiplicidade de valor, nome do atributo.

Para recursão em itens de sequência (por exemplo, lendo uma árvore de Relatório Estruturado) adicione +R. Para pular o despejo de dados de pixel brutos, adicione --max-read-length 4. A saída de dcmdump pode ser analisada de volta para DICOM pelo dump2dcm para edição round-trip.

7. Anonimizar / modificar tags

dcmodify modifica no local (cria um backup .bak a menos que -nb):

# Substituir PatientName em todas as ocorrências (conjunto principal + cada item de sequência)
dcmodify -nb -ma "(0010,0010)=ANON^PATIENT" input.dcm

# Inserir uma tag que não estava lá
dcmodify -nb -i "(0010,4000)=anonimizado 2026-05-25" input.dcm

# Excluir toda tag privada (grupo é ímpar)
dcmodify -nb -ep input.dcm

# Gerar novos UIDs para a hierarquia de estudo/série/instância
dcmodify -nb -gst -gse -gsi input.dcm

Flags de operação (mutualmente exclusivas por tag):

• -i inserir se ausente (erro se presente)
• -m modificar se presente (erro se ausente)
• -ma modificar-tudo (conjunto principal + cada item de sequência)
• -e apagar / -ea apagar-tudo / -ep apagar-privada
• -gst -gse -gsi regenerar UIDs de Study/Series/SOPInstance

Pegadinha: por padrão, dcmodify escreve um .bak de cada arquivo modificado. Em uma anonimização de 10 mil arquivos, isso dobra o uso de disco e é quase sempre indesejado — sempre passe -nb para trabalhos em lote.

8. Renderizar DICOM para PNG / JPEG / TIFF / BMP / PNM

dcm2img +on input.dcm out.png      # PNG (8 bits)
dcm2img +on2 input.dcm out.png     # PNG (16 bits — manter profundidade total de bits)
dcm2img +oj input.dcm out.jpg      # JPEG (8 bits lossy baseline)
dcm2img +ot input.dcm out.tiff     # TIFF
dcm2img +ob input.dcm out.bmp      # BMP
dcm2img +op input.dcm out.pgm      # PNM raw (PGM para tons de cinza, PPM para cor)

Convenção de letra da flag dcm2img: +o<letra> escolhe o formato de saída (n=PNG, j=JPEG, t=TIFF, b=BMP, p=PNM/PGM/PPM, l=JPEG-LS). +oa (--write-auto) escolhe baseado na extensão do nome do arquivo de saída.

dcm2img descomprime automaticamente entradas JPEG / JPEG-LS / RLE — nenhuma etapa separada de dcmdjpeg é necessária. Para dados de múltiplos quadros, +Fa escreve um arquivo de saída por quadro (os nomes de arquivo recebem um sufixo de número de quadro).

Se você precisar controlar a janela em vez de deixar dcm2img usar a VOI LUT do arquivo:

dcm2img +on +Wm input.dcm out.png         # usar min/máx dos pixels como janela
dcm2img +on +W 50 350 input.dcm out.png   # WindowCenter=50, WindowWidth=350

dcm2pnm, dcmj2pnm, dcml2pnm são apelidos obsoletos para dcm2img.

9. Empacotar um PDF como DICOM encapsulado

dcmencap input.pdf output.dcm

O PDF é armazenado como um Multiquadro de Documento Encapsulado. A tag de Instância espera (0042,0010) (Título do Documento) — você pode fornecê-la:

dcmencap --doc-title "Relatório de 2025-03-15" input.pdf output.dcm

Para extrair o PDF de volta:

dcmdecap input.dcm output.pdf

dcmencap e dcmdecap também funcionam com CDAs (Clinical Document Architecture, arquivos XML .cda) e, a partir do snapshot 2025.05 de desenvolvimento, com arquivos STL e OBJ (malha 3D encapsulada). Os apelidos legados pdf2dcm e dcm2pdf ainda existem, mas são proxies finos.

10. Relatórios Estruturados DICOM

Despejar a árvore de conteúdo BRUTA para texto:

dsrdump input.dcm

Renderizar para HTML:

dsr2html input.dcm output.html

Round-trip via XML (perde referências binárias = pixel data, ondas, templates aninhados):

dsr2xml input.dcm intermediate.xml
xml2dsr intermediate.xml output.dcm

11. Servidor PACS de teste

Use dcmqrscp + dcmqridx para um PACS de teste mínimo:

# 1. Inicializar o banco de dados de índice
dcmqridx --init-db /caminho/para/db/

# 2. Iniciar o servidor SCP (escutando em 11112)
dcmqrscp -v --db-dir /caminho/para/db/ --storage-dir /caminho/para/armazenamento/ 11112

# 3. Indexar estudos existentes no banco
dcmqridx --add-files -r /caminho/para/dicom/files/

12. Assinaturas Digitais

# Assinar com uma chave privada e certificado PEM
dcmsign -v -k privkey.pem -c cert.pem +g input.dcm

# Verificar todas as assinaturas em um arquivo
dcmsign -v -v input.dcm

# Remover assinaturas
dcmsign -r input.dcm

A flag +g adiciona a assinatura ao perfil de assinatura padrão 1.2.840.10008.1.1.1 (assinatura RSA com SHA-1). Para ECDSA ou DSA, passe a curva com +ec.

Referências

Cada módulo principal tem seu próprio documento de referência detalhando todas as ferramentas, flags e exemplos. Consulte os links acima.

• Opções comuns — logging, rede, TLS, formato de arquivo
• UIDs de sintaxe de transferência — tabela de UIDs com valores decimais e hexadecimais
• dcmdata — ferramentas base de arquivo
• dcmnet — ferramentas de rede
• image-codecs — compressão, descompressão, renderização
• img-pdf-import — encapsulamento de imagem/PDF/CDA/STL/OBJ
• dcmsr — Relatórios Estruturados
• dcmqrdb-wlm — servidores de banco de dados e worklist
• dcmsign-dcmrt — assinaturas e radioterapia