dcm2xml: Converter arquivo DICOM e conjunto de dados para XML

SINOPSE

dcm2xml [options] dcmfile-in [xmlfile-out]

DESCRIÇÃO

O utilitário dcm2xml converte o conteúdo de um arquivo DICOM (formato de arquivo ou conjunto de dados bruto) para XML (Extensible Markup Language). Existem dois formatos de saída. O primeiro é específico do DCMTK, com sua DTD (Document Type Definition) descrita no arquivo dcm2xml.dtd. O segundo se refere ao "Native DICOM Model", especificado para o serviço DICOM Application Hosting definido na parte 19 do DICOM.

Se dcm2xml ler um conjunto de dados bruto (dados DICOM sem meta-cabeçalho de formato de arquivo), ele tentará adivinhar a sintaxe de transferência examinando os primeiros bytes do arquivo. Nem sempre é possível adivinhar corretamente a sintaxe de transferência, e é preferível converter um conjunto de dados para um formato de arquivo sempre que possível (usando o utilitário dcmconv). Também é possível usar as opções -f e -t[ieb] para forçar o dcm2xml a ler um conjunto de dados com uma sintaxe de transferência específica.

PARÂMETROS

dcmfile-in   DICOM input filename to be converted ("-" for stdin)

xmlfile-out  XML output filename (default: 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 meta do arquivo. 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 a TS implicit VR little endian valores de tag longos:
+M --load-all: carrega valores de tag muito longos (por exemplo, dados de pixel)
-M --load-short: não carrega valores muito longos (padrão)
+R --max-read-length [k]bytes: integer (4..4194302, default: 4): define o limite para valores longos em k kilobytes

opções de processamento

+Cr --charset-require: exige a declaração de conjunto de caracteres estendido (padrão)
+Ca --charset-assume [c]harset: string: assume o conjunto de caracteres c se nenhum conjunto de caracteres estendido for declarado
+Cc --charset-check-all: verifica todos os elementos de dados com valores do tipo string (padrão: somente PN, LO, LT, SH, ST, UC e UT) # esta opção é usada apenas para a verificação estendida quanto à necessidade de # presença do atributo Specific Character Set (0008,0005), mas não para a # conversão dos valores de elementos não afetados para UTF-8 (por exemplo, # valores de elementos com um VR de CS)
+U8 --convert-to-utf8: converte para UTF-8 todos os valores de elementos afetados pelo Specific Character Set (0008,0005) # requer suporte de uma # biblioteca de codificação de caracteres subjacente (veja a saída de --version para saber qual está disponível)

opções de saída

-dtk --dcmtk-format: gera saída no formato específico do DCMTK (padrão)
-nat --native-format: gera saída no formato Native DICOM Model (parte 19)
+Xn --use-xml-namespace: adiciona uma declaração de namespace XML ao elemento raiz formato específico do DCMTK (não usar com --native-format):
+Xd --add-dtd-reference: adiciona uma referência à document type definition (DTD)
+Xe --embed-dtd-content: incorpora a document type definition ao documento XML
+Xf --use-dtd-file [f]ilename: string: usa o arquivo DTD especificado (somente com +Xe) (padrão: /usr/local/share/dcmtk-/dcm2xml.dtd)
+Wn --write-element-name: grava o nome dos elementos de dados DICOM (padrão)
-Wn --no-element-name: não grava o nome dos elementos de dados DICOM
+Wb --write-binary-data: grava os dados binários dos elementos OB e OW (padrão: off, cuidado ao usar com --load-all) codificação dos dados binários:
+Eh --encode-hex: codifica os dados binários como números hexadecimais (padrão para o formato específico do DCMTK)
+Eu --encode-uuid: codifica os dados binários como uma referência UUID (padrão para Native DICOM Model)
+Eb --encode-base64: codifica os dados binários em Base64 (RFC 2045, MIME)

Formato DCMTK

A estrutura básica da saída XML específica do DCMTK, gerada a partir de um arquivo DICOM, é a seguinte:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE file-format SYSTEM "dcm2xml.dtd">
<file-format xmlns="http://dicom.offis.de/dcmtk">
  <meta-header xfer="1.2.840.10008.1.2.1" name="Little Endian Explicit">
    <element tag="0002,0000" vr="UL" vm="1" len="4"
             name="MetaElementGroupLength">
      166
    </element>
    ...
    <element tag="0002,0013" vr="SH" vm="1" len="16"
             name="ImplementationVersionName">
      OFFIS_DCMTK_353
    </element>
  </meta-header>
  <data-set xfer="1.2.840.10008.1.2" name="Little Endian Implicit">
    <element tag="0008,0005" vr="CS" vm="1" len="10"
             name="SpecificCharacterSet">
      ISO_IR 100
    </element>
    ...
    <sequence tag="0028,3010" vr="SQ" card="2" name="VOILUTSequence">
      <item card="3">
        <element tag="0028,3002" vr="xs" vm="3" len="6"
                 name="LUTDescriptor">
          256\0\8
        </element>
        ...
      </item>
      ...
    </sequence>
    ...
    <element tag="7fe0,0010" vr="OW" vm="1" len="262144"
             name="PixelData" loaded="no" binary="hidden">
    </element>
  </data-set>
</file-format>

As tags "file-format" e "meta-header" estão ausentes no caso de conjuntos de dados DICOM.

Codificação XML

Atributos com campos de valor muito grandes (por exemplo, dados de pixel) não são carregados por padrão. Eles podem ser identificados pelo atributo adicional "loaded" com o valor "no" (veja o exemplo acima). A opção de linha de comando –load-all força o carregamento de todos os campos de valor, incluindo os muito longos.

Além disso, os dados binários dos atributos OB e OW não são gravados no arquivo de saída XML por padrão. Esses elementos podem ser identificados pelo atributo adicional "binary" com o valor "hidden" (o padrão é "no"). A opção de linha de comando –write-binary-data também faz com que os campos de valor binários sejam impressos (o valor do atributo é "yes" ou "base64"). No entanto, tenha cuidado ao usar essa opção junto com –load-all, devido à grande quantidade de dados de pixel que pode ser impressa na saída. Observe que, nesse contexto, os valores de elementos com um VR de OD, OF, OL e OV não são considerados "dados binários".

Valores múltiplos (ou seja, quando a multiplicidade de valor DICOM é maior que 1) são separados por uma barra invertida "\" (exceto para dados codificados em Base64). O atributo "len" indica o número de bytes do respectivo campo de valor conforme armazenado no conjunto de dados DICOM, ou seja, pode divergir do comprimento do valor codificado em XML, por exemplo devido a um preenchimento não significativo que tenha sido removido. Se esse atributo estiver ausente nas tags de início "sequence" ou "item", o elemento DICOM correspondente foi armazenado com comprimento indefinido.

Formato Native DICOM Model

A descrição do formato Native DICOM Model pode ser encontrada no padrão DICOM, parte 19 ("Application Hosting").

Dados Volumosos

Dados binários, ou seja, valores de elementos DICOM com Representações de Valor (VR) de OB ou OW, bem como valores OD, OF, OL, OV e UN, não são gravados na saída XML por padrão devido ao seu tamanho. Em vez disso, para cada elemento, um novo Identificador Único Universal (UUID) é gerado e gravado como atributo de um elemento XML . Até o momento, não é possível gravar um arquivo adicional para armazenar os dados binários de cada bloco. Isso não é exigido pelo padrão; no entanto, pode ser útil para a implementação de uma interface Application Hosting, de modo que esse recurso pode vir a estar disponível em versões futuras do dcm2xml.

Além disso, o Supplement 163 (Store Over the Web by Representational State Transfer Services) introduz um novo elemento XML que permite codificar dados binários em Base64. Atualmente, a opção de linha de comando –encode-base64 habilita essa codificação para os seguintes VRs: OB, OD, OF, OL, OV, OW e UN.

Problemas conhecidos

Além do que foi descrito na seção "Dados Volumosos" acima, há outros problemas conhecidos na implementação atual do formato Native DICOM Model. Por exemplo, valores de elementos grandes com um VR diferente de OB, OD, OF, OL, OV, OW ou UN atualmente nunca são gravados como dados volumosos, embora isso pudesse ser útil, por exemplo, para elementos de texto muito longos (especialmente UT) ou campos numéricos muito longos (de diversos VRs).

NOTAS

Codificação de caracteres

A codificação de caracteres XML é determinada automaticamente a partir do atributo DICOM (0008,0005) "Specific Character Set", usando o seguinte mapeamento:

ASCII         (ISO_IR 6)    =>  "UTF-8"
UTF-8         "ISO_IR 192"  =>  "UTF-8"
ISO Latin 1   "ISO_IR 100"  =>  "ISO-8859-1"
ISO Latin 2   "ISO_IR 101"  =>  "ISO-8859-2"
ISO Latin 3   "ISO_IR 109"  =>  "ISO-8859-3"
ISO Latin 4   "ISO_IR 110"  =>  "ISO-8859-4"
ISO Latin 5   "ISO_IR 148"  =>  "ISO-8859-9"
ISO Latin 9   "ISO_IR 203"  =>  "ISO-8859-15"
Cyrillic      "ISO_IR 144"  =>  "ISO-8859-5"
Arabic        "ISO_IR 127"  =>  "ISO-8859-6"
Greek         "ISO_IR 126"  =>  "ISO-8859-7"
Hebrew        "ISO_IR 138"  =>  "ISO-8859-8"

Se esse atributo DICOM estiver ausente no arquivo de entrada, embora seja necessário, a opção –charset-assume pode ser usada para especificar manualmente um conjunto de caracteres apropriado (usando um dos termos definidos pelo DICOM). Por razões de compatibilidade com versões anteriores desta ferramenta, os seguintes termos também são aceitos e mapeados automaticamente para os termos DICOM correspondentes: latin-1, latin-2, latin-3, latin-4, latin-5, latin-9, cyrillic, arabic, greek, hebrew.

Conjuntos de caracteres múltiplos que usam técnicas de extensão de código não têm suporte. Se necessário, a opção –convert-to-utf8 pode ser usada para converter o arquivo ou conjunto de dados DICOM para a codificação UTF-8 antes da conversão para o formato XML. Isso também é útil para arquivos DICOMDIR, nos quais cada registro de diretório pode ter um conjunto de caracteres diferente.

Se nenhum mapeamento estiver definido e a opção –convert-to-utf8 não for usada, os caracteres não ASCII e aqueles abaixo de #32 são armazenados como "&#nnn;", em que "nnn" corresponde ao código numérico do caractere. Isso pode gerar referências de entidade de caractere inválidas (como "" para ESC) e fará com que a maioria dos analisadores XML rejeite o documento.

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 dcm2xml 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 embutido na aplicação (padrão no 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.

Dependendo das opções de linha de comando especificadas, o utilitário dcm2xml tentará carregar tabelas de mapeamento de conjunto de caracteres. Isso ocorre quando o DCMTK foi compilado com a biblioteca oficonv (que é o padrão) e as tabelas de mapeamento não estão embutidas na biblioteca (padrão quando o DCMTK usa bibliotecas compartilhadas).

Os arquivos de tabela de mapeamento são esperados em < datadir> do DCMTK. A variável de ambiente DCMICONVPATH pode ser usada para especificar um local diferente. Se um local diferente for especificado, essas tabelas de mapeamento também substituem quaisquer tabelas integradas.