dcmodify: Modificar arquivos DICOM

SINOPSE

dcmodify [options] dcmfile-in...

DESCRIÇÃO

dcmodify é uma ferramenta que permite modificar, inserir e excluir tags e itens em arquivos DICOM. Sequências e tags com multiplicidade de valor maior que 1 também são compatíveis. As informações do meta-cabeçalho e a VR da tag não podem ser modificadas diretamente pelo dcmodify neste momento. Além das modificações de tags, o dcmodify disponibiliza algumas opções de entrada - forçando o dcmodify a tratar seus arquivos de entrada conforme especificado pelo usuário - e opções de saída para controlar o formato de saída dos arquivos resultantes.

Caso seja necessário realizar múltiplas modificações, o dcmodify as executa na mesma ordem em que aparecem na linha de comando. Observe que o dcmodify não verifica se um determinado valor corresponde à sua representação de valor (VR). Geralmente uma mensagem de erro é exibida, mas de modo geral cabe ao usuário garantir o uso correto da VR.

Se o dcmodify não conhecer a tag a ser inserida, a VR da tag é definida como UN e o valor fornecido na linha de comando é interpretado como uma sequência de números hexadecimais (da mesma forma que são fornecidos para VR=OB). Insira essas tags no dicionário para evitar esse comportamento. Além disso, ao especificar a opção -iun, é possível forçar o dcmodify a deixar os valores UN intactos. Usando a opção -u, o dcmodify salva todos os atributos VR=UN como OB.

O dcmodify é capaz de trabalhar com os chamados caminhos de tags (tag paths) para acessar tags em sequências. A sintaxe (pseudoformalizada) é

{sequence[item-no].}*element

onde 'sequence' é uma tag de sequência como (0008,1111) ou um nome de dicionário para uma tag. 'item-no' descreve o número do item a ser acessado (contando a partir de zero). 'element' define a tag alvo a ser tratada. Uma tag pode ser especificada diretamente como (0010,0010) ou por meio do nome de dicionário correspondente "PatientName". O '' indica que você pode repetir instruções de sequência para acessar níveis mais profundos nos arquivos DICOM (veja a seção EXAMPLES). Para 'item-no', também é possível usar um caractere curinga '' para selecionar todos os itens da sequência envolvente (veja a seção WILDCARDS abaixo).

Ao inserir caminhos de tags compostos por múltiplos nós (ou seja, não um único elemento) usando a opção -i, quaisquer elementos de caminho ausentes (itens, sequências, elementos terminais) são inseridos automaticamente quando faltam. Isso não funciona para curingas de item: quando não existe nenhum item na sequência envolvente, o dcmodify obviamente não consegue decidir quantos itens devem ser gerados. Porém, se um número de item como '5' for especificado, todos os 6 itens (contados a partir de zero) podem ser (e são) gerados automaticamente no modo de inserção. Se já existissem 2 itens, os 4 restantes seriam inseridos.

O dcmodify não funciona em diretórios, ou seja, o parâmetro dcmfile-in... não deve incluir nomes de diretórios.

Observe que há alguns pontos de atenção relativos à modificação de tags privadas (veja a seção PRIVATE TAGS) e à alteração de UIDs (seção CHANGING UIDs).

PARÂMETROS

dcmfile-in  DICOM input filename(s) to be modified ("-" for stdin/stdout)

OPÇÕES

opções gerais

-h --help: exibe este texto de ajuda e sai
--version: exibe as informações de versão e sai
--arguments: exibe os argumentos de linha de comando expandidos
-q --quiet: modo silencioso, não exibe avisos nem erros
-v --verbose: modo detalhado, exibe os detalhes do processamento
-d --debug: modo de depuração, exibe informações de depuração
-ll --log-level [l]evel: string constant: (fatal, error, warn, info, debug, trace) usa o nível l para o logger
-lc --log-config [f]ilename: string: usa o arquivo de configuração f para o logger

opções de entrada

+f --read-file: lê o formato de arquivo ou o conjunto de dados (padrão)
+fo --read-file-only: lê somente o formato de arquivo
-f --read-dataset: lê o conjunto de dados sem as informações de meta do arquivo
+fc --create-file: cria o formato de arquivo se o arquivo não existir. sintaxe de transferência de entrada:
-t= --read-xfer-auto: usa o reconhecimento de TS (padrão)
-td --read-xfer-detect: ignora a TS especificada no cabeçalho meta do arquivo
-te --read-xfer-little: lê com a TS explicit VR little endian
-tb --read-xfer-big: lê com a TS explicit VR big endian
-ti --read-xfer-implicit: lê com TS implicit VR little endian. análise de atributos de comprimento ímpar:
+ao --accept-odd-length: aceita atributos de comprimento ímpar (padrão)
+ae --assume-even-length: presume que o comprimento real é um byte maior. correção automática de dados:
+dc --enable-correction: habilita a correção automática de dados (padrão)
-dc --disable-correction: desabilita a correção automática de dados. formato de bitstream da entrada deflate:
+bd --bitstream-deflated: espera um bitstream deflate (padrão)
+bz --bitstream-zlib: espera um bitstream deflate no formato zlib

opções de processamento

--backup: faz backup dos arquivos antes de modificá-los (padrão)
-nb --no-backup: não faz backup dos arquivos (PERIGOSO). modo de inserção:
-i --insert "[t]ag-path=[v]alue": insere (ou substitui) o caminho na posição t com o valor v
-if --insert-from-file "[t]ag-path=[f]ilename": insere (ou substitui) o caminho na posição t com o valor do arquivo f
-nrc --no-reserv-check: não verifica reservas privadas. modo de modificação:
-m --modify "[t]ag-path=[v]alue": modifica a tag na posição t para o valor v
-mf --modify-from-file "[t]ag-path=[f]ilename": modifica a tag na posição t para o valor do arquivo f
-ma --modify-all "[t]ag=[v]alue": modifica TODAS as tags t correspondentes no arquivo para o valor v. modo de exclusão:
-e --erase "[t]ag-path": exclui a tag/item na posição t
-ea --erase-all "[t]ag": exclui TODAS as tags t correspondentes no arquivo
-ep --erase-private: exclui TODOS os dados privados do arquivo. identificador exclusivo:
-gst --gen-stud-uid: gera um novo Study Instance UID
-gse --gen-ser-uid: gera um novo Series Instance UID
-gin --gen-inst-uid: gera um novo SOP Instance UID
-nmu --no-meta-uid: não atualiza os UIDs do meta-cabeçalho se os UIDs relacionados no conjunto de dados forem modificados. tratamento de erros:
-ie --ignore-errors: continua com o arquivo, se ocorrer um erro de modificação
-imt --ignore-missing-tags: trata 'tag not found' como sucesso ao modificar ou excluir em arquivos
-iun --ignore-un-values: não tenta gravar nenhum valor em elementos cuja VR seja UN

opções de saída

+F --write-file: grava no formato de arquivo (padrão)
-F --write-dataset: grava o conjunto de dados sem as informações meta do arquivo. sintaxe de transferência de saída:
+t= --write-xfer-same: grava com a mesma TS da entrada (padrão)
+te --write-xfer-little: grava com a TS explicit VR little endian
+tb --write-xfer-big: grava com a TS explicit VR big endian
+ti --write-xfer-implicit: grava em implicit VR little endian TS representações de valor pós-1993:
+u --enable-new-vr: habilita o suporte a novos VRs (UN/UT) (padrão)
-u --disable-new-vr: desabilita o suporte a novos VRs, converte para OB. codificação do comprimento de grupo:
+g= --group-length-recalc: recalcula os comprimentos de grupo, se presentes (padrão)
+g --group-length-create: sempre grava com elementos de comprimento de grupo
-g --group-length-remove: sempre grava sem elementos de comprimento de grupo. codificação de comprimento em sequências e itens:
+le --length-explicit: grava com comprimentos explícitos (padrão)
-le --length-undefined: grava com comprimentos indefinidos preenchimento final do conjunto de dados (não com --write-dataset):
-p= --padding-retain: não altera o preenchimento (padrão se --write-dataset não for usado)
-p --padding-off: sem preenchimento (implícito com --write-dataset)
+p --padding-create [f]ile-pad [i]tem-pad: integer: alinha o arquivo em um múltiplo de f bytes e os itens em um múltiplo de i bytes

TAGS PRIVADAS

Há alguns pontos de atenção a considerar ao trabalhar com tags privadas. No entanto, a inserção ou modificação de uma tag de reserva (gggg,00xx) deve sempre funcionar.

Inserções

Se você deseja inserir uma tag privada (que não seja uma reserva com gggg,00xx), certifique-se de tê-la listado em seu dicionário (veja < docdir>/datadict.txt para detalhes). Se ela não estiver listada, o dcmodify a inserirá com VR=UN. Além disso, em alguns casos a inserção pode até falhar para determinados valores.

Se sua tag privada estiver no dicionário, o dcmodify procede da seguinte forma: quando encontra, no conjunto de dados que envolve a tag, uma reserva cujo criador privado corresponde, a inserção é feita com a VR encontrada no dicionário e o valor fornecido na linha de comando. Mas se o criador privado não corresponder ou nenhum estiver definido, o dcmodify retornará um erro. Se uma tag privada deve ser inserida independentemente da existência de uma reserva, a opção -nrc pode ser usada para forçar a inserção. Nesse caso, porém, a VR é definida como UN, pois a tag não pode ser encontrada no dicionário.

Veja a descrição acima sobre como é tratada a inserção de valores em elementos com VR desconhecida.

Modificações

Se você modificar o valor de uma tag privada, o dcmodify não verificará sua VR em relação ao dicionário. Portanto, tenha cuidado para inserir apenas valores que correspondam à VR da tag.

Se você deseja alterar o valor e a VR de uma tag privada, por exemplo porque acabou de adicionar essa tag ao seu dicionário, pode excluí-la com o dcmodify e reinseri-la. Assim o dcmodify usa a entrada do seu dicionário para determinar a VR correta (veja também a subseção inserções).

Veja também a descrição acima sobre como é tratada a inserção de valores em elementos com VR desconhecida.

Exclusões

Ao usar o dcmodify para excluir uma tag de reserva privada, observe que o dcmodify não tocará nas tags privadas que estão sob essa reserva. Cabe ao usuário cuidar da consistência entre as reservas e suas tags privadas associadas.

Para a exclusão de tags privadas que não sejam de reserva, não há pontos de atenção especiais.

ALTERAÇÃO DE UIDS

O dcmodify corrigirá automaticamente 'Media Storage SOP Class UID' e 'Media Storage SOP Instance UID' no meta-cabeçalho, se você fizer alterações nas tags relacionadas no conjunto de dados ('SOP Class UID' e 'SOP Instance UID') por meio das opções do modo de inserção ou modificação. Você pode desabilitar esse comportamento usando a opção -nmu.

Se você gerar novos UIDs com -gst , -gse ou -gin , isso afetará apenas o UID que você escolheu gerar. Assim, se você usar -gst para gerar um novo 'Study Instance UID', então 'Series Instance UID' e 'SOP Instance UID' não serão afetados! Isso lhe dá a possibilidade de gerar cada valor separadamente. Normalmente, você também modificaria os UIDs 'subjacentes'. Como desvantagem dessa flexibilidade, o usuário precisa garantir que, ao criar arquivos DICOM 'novos' com novos UIDs usando o dcmodify , os demais UIDs sejam atualizados pelo usuário conforme necessário.

Ao escolher a opção -gin , a tag de meta-cabeçalho relacionada ('Media Storage SOP Instance UID') é atualizada automaticamente. Esse comportamento não pode ser desabilitado.

Ao trabalhar com múltiplos arquivos de entrada, o dcmodify processa cada arquivo de forma isolada, ou seja, gerará UIDs para cada arquivo individualmente. Por exemplo, ao usar a opção -gst , o dcmodify inserirá um Study Instance UID diferente em cada arquivo, em vez de gerar um único valor e gravá-lo em todos os arquivos processados.

CRIAÇÃO DE NOVOS ARQUIVOS

A opção –create-file permite que o dcmodify crie um arquivo caso ele ainda não exista no disco. Isso pode ser usado para criar arquivos do zero realizando inserções consecutivas com opções como –insert . Isso pode ser especialmente útil ao criar arquivos de consulta para ferramentas como findscu ou movescu . Caso nenhuma sintaxe de transferência de saída específica seja definida, o dcmodify escolhe Little Endian Explicit Uncompressed para a saída. Os arquivos recém-criados são sempre gravados no formato de arquivo DICOM, ou seja, a opção –write-dataset não é permitida junto com –create . Dessa forma, ao menos o meta-cabeçalho é gravado, e nenhum arquivo com zero bytes é criado caso nenhuma inserção seja realizada na chamada do dcmodify .

VALORES DE ELEMENTO A PARTIR DE ARQUIVO

Para ler o valor do elemento a partir de um arquivo em vez de especificá-lo na linha de comando, as opções -mf e -if podem ser usadas. Observe que, para elementos OW, espera-se que os dados estejam ordenados em little endian e serão trocados de ordem se necessário. O tamanho do arquivo deve sempre ser um número par de bytes, ou seja, nenhum preenchimento automático é realizado.

CURINGAS

O dcmodify também permite o uso de um caractere curinga "" para números de item em expressões de caminho, por exemplo, "ContentSequence[].CodeValue" seleciona todos os atributos "Code Value" em todos os itens de ContentSequence. O uso de um curinga é possível em todas as operações básicas, ou seja, nas opções de modificação -m , inserção -i e exclusão -e , o que faz dele, junto com a criação automática de nós de caminho intermediários, uma ferramenta poderosa para a construção e o processamento de conjuntos de dados complexos.

As opções -ma e -ea , para modificar ou excluir todas as ocorrências de um elemento DICOM com base em sua tag, não aceitam curingas e funcionam apenas em elementos únicos (ou seja, um único nome de dicionário ou chave de tag).

EXEMPLOS

-i --insert:: dcmodify -i "(0010,0010)=A Name" file.dcm Insere a tag PatientName em 'file.dcm' no 1º nível. Se a tag já existir, -i a substituirá! Se você quiser inserir um elemento com multiplicidade de valor maior que 1 (por exemplo, 4), pode fazer isso com: dcmodify -i "(0018,1310)=1\\2\\3\\4" dcmodify -i "(0008,1111)[0].PatientName=Another Name" .dcm Insere a tag PatientName no primeiro item da sequência (0008,1111). Observe que é possível usar curingas para os arquivos. Você também pode especificar caminhos de tags mais longos (por exemplo, "(0008,1111)[0].(0008,1111)[1].(0010,0010)=A Third One"). Se alguma parte do caminho, por exemplo a sequência ou o item "0", não existir, ela é inserida automaticamente pelo dcmodify. dcmodify -i "(0008,1111)[].PatientName=Another Name" .dcm Insere a tag PatientName em todos os itens da sequência (0008,1111). Observe que é possível usar curingas para os arquivos. Você também pode especificar caminhos de tags mais longos (por exemplo, "(0008,1111)[].(0008,1111)[*].(0010,0010)=A Third One").
-if --insert-from-file:: dcmodify -if "PixelData=pixel.raw" file.dcm Insere o conteúdo do arquivo 'pixel.raw' no elemento PixelData de 'file.dcm'. O conteúdo do arquivo será lido como está. Espera-se que os dados OW estejam ordenados em little endian e serão trocados de ordem se necessário. Nenhuma verificação é feita para garantir que a quantidade de dados seja razoável em relação a outros atributos, como Rows ou Columns.
-m --modify:: dcmodify -m "(0010,0010)=A Name" file.dcm Altera a tag (0010,0010) no 1º nível para "A Name". Essa opção também permite caminhos de tags mais longos, como demonstrado acima para -i. Se o elemento terminal ou qualquer parte intermediária do caminho não existir, ele não é inserido como seria com a opção '-i'. dcmodify -m "(0010,0010)=A Name" -imt file.dcm Altera a tag (0010,0010) no 1º nível para "A Name". Devido à opção '-imt' fornecida, é retornado sucesso em vez de "tag not found", caso o elemento/item (ou qualquer nó intermediário em um caminho mais longo) não exista. Observe que, na opção '-m', o último nó do caminho deve ser um elemento terminal, ou seja, não uma sequência ou um item.
-mf --modify-from-file:: dcmodify -mf "PixelData=pixel.raw" file.dcm Faz o mesmo que -if, caso já existisse um elemento PixelData em 'file.dcm'. Caso contrário, nada é alterado.
-ma --modify-all:: dcmodify -ma "(0010,0010)=New Name" file.dcm Faz o mesmo que -m, mas atua sobre todas as tags correspondentes encontradas em 'file.dcm'. Assim, ele pesquisa todo o conjunto de dados, incluindo sequências, em busca da tag (0010,0010) e as altera para "New Name"
-e --erase:: dcmodify -e "(0010,0010)" .dcm Exclui a tag (0010,0010) em todos os arquivos .dcm no 1º nível. Essa opção também permite caminhos de tags mais longos, como demonstrado acima para -i. dcmodify -e "(0010,0010)" -imt .dcm Exclui a tag (0010,0010) em todos os arquivos .dcm no 1º nível. Devido à opção '-imt' fornecida, é retornado sucesso em vez de "tag not found", caso o elemento/item (ou qualquer nó intermediário em um caminho mais longo) não exista.
-ea --erase-all:: dcmodify -ea "(0010,0010)" *.dcm O mesmo que -e, mas também pesquisa em sequências e itens.
-ep --erase-private:: dcmodify -ep .dcm Exclui todas as tags privadas (ou seja, tags com número de grupo ímpar) de todos os arquivos correspondentes a .dcm no diretório atual.
-gst --gen-stud-uid:: dcmodify -gst file.dcm Isso gera um novo valor para o StudyInstanceUID (0020,000d). Outros UIDs não são modificados!
-gse --gen-ser-uid:: dcmodify -gse file.dcm Isso gera um novo valor para o SeriesInstanceUID (0020,000e). Outros UIDs não são modificados!
-gin --gen-inst-uid:: dcmodify -gin file.dcm Esse comando gera um novo valor para o SOPInstanceUID (0008,0018). O MediaStorageSOPInstanceUID (0002,0003) correspondente é ajustado automaticamente para o novo valor. Observe que não é possível evitar essa atualização do meta-cabeçalho por meio da opção -nmu.
-nmu --no-meta-uid:: dcmodify -m "SOPInstanceUID=[UID]" -nmu *.dcm Isso modificará o SOPInstanceUID para o [UID] fornecido, mas -nmu evita que o dcmodify também ajuste o MediaStorageSOPInstanceUID no meta-cabeçalho.

TRATAMENTO DE ERROS

O dcmodify tenta executar cada operação de modificação fornecida na linha de comando: se uma delas retornar um erro, as demais são executadas mesmo assim. No entanto, em caso de qualquer erro, o arquivo modificado não é salvo, a menos que a opção –ignore-errors seja especificada. Se essa opção for selecionada, o dcmodify também continua modificando os demais arquivos especificados na linha de comando; caso contrário, o dcmodify encerra após o primeiro arquivo que apresentou erros de modificação.

Se a opção –ignore-missing-tags estiver habilitada, qualquer operação de modificação ou exclusão (ou seja, exceto –insert ) que falhe devido a uma tag inexistente é tratada como bem-sucedida. Isso faz sentido se alguém quiser ter certeza de que tags específicas não estão presentes no arquivo ou de que - se existirem - estão definidas com um valor específico.

REGISTRO DE LOG

O nível de detalhamento do log das diversas ferramentas de linha de comando e das bibliotecas subjacentes pode ser especificado pelo usuário. Por padrão, apenas erros e avisos são gravados no fluxo de erro padrão. Ao usar a opção –verbose, mensagens informativas, como detalhes do processamento, também são relatadas. A opção –debug pode ser usada para obter mais detalhes sobre a atividade interna, por exemplo, para fins de depuração. Outros níveis de log podem ser selecionados com a opção –log-level. No modo –quiet, apenas erros fatais são relatados. Nesses casos de erro muito graves, o aplicativo normalmente é encerrado. Para mais detalhes sobre os diferentes níveis de log, consulte a documentação do módulo "oflog".

Caso a saída do log deva ser gravada em arquivo (opcionalmente com rotação de arquivo de log), no syslog (Unix) ou no log de eventos (Windows), pode-se usar a opção –log-config. Esse arquivo de configuração também permite direcionar apenas determinadas mensagens para um fluxo de saída específico e filtrar certas mensagens com base no módulo ou aplicativo em que são geradas. Um arquivo de configuração de exemplo é fornecido em < etcdir>/logger.cfg.

LINHA DE COMANDO

Todas as ferramentas de linha de comando usam a seguinte notação para os parâmetros: colchetes delimitam valores opcionais (0-1), reticências no final indicam que múltiplos valores são permitidos (1-n), e a combinação dos dois significa de 0 a n valores.

As opções de linha de comando se distinguem dos parâmetros por um sinal '+' ou '-' à frente. Normalmente, a ordem e a posição das opções de linha de comando são arbitrárias (ou seja, podem aparecer em qualquer lugar). No entanto, se as opções forem mutuamente exclusivas, é usada a ocorrência mais à direita. Esse comportamento está em conformidade com as regras de avaliação padrão dos shells Unix comuns.

Além disso, um ou mais arquivos de comando podem ser especificados usando um sinal '@' como prefixo do nome do arquivo (por exemplo, @command.txt). Esse argumento de comando é substituído pelo conteúdo do arquivo de texto correspondente (múltiplos espaços em branco são tratados como um único separador, a menos que apareçam entre duas aspas) antes de qualquer avaliação posterior. Observe que um arquivo de comando não pode conter outro arquivo de comando. Essa abordagem simples, mas eficaz, permite agrupar combinações comuns de opções/parâmetros e evita linhas de comando longas e confusas (um exemplo é fornecido no arquivo < datadir>/dumppat.txt).

AMBIENTE

O utilitário dcmodify tentará carregar os dicionários de dados DICOM especificados na variável de ambiente DCMDICTPATH. Por padrão, ou seja, se a variável de ambiente DCMDICTPATH não estiver definida, o arquivo < datadir>/dicom.dic será carregado, a menos que o dicionário esteja incorporado ao aplicativo (padrão para o Windows).

É preferível manter o comportamento padrão e usar a variável de ambiente DCMDICTPATH apenas quando dicionários de dados alternativos forem necessários. A variável de ambiente DCMDICTPATH tem o mesmo formato da variável PATH dos shells Unix, em que dois-pontos (":") separam as entradas. Em sistemas Windows, um ponto e vírgula (";") é usado como separador. O código do dicionário de dados tenta carregar cada arquivo especificado na variável de ambiente DCMDICTPATH. Ocorre um erro se nenhum dicionário de dados puder ser carregado.