img2dcm: converte formatos de imagem padrão para o formato DICOM

SINOPSE

img2dcm [options] imgfile-in... dcmfile-out

DESCRIÇÃO

A ferramenta img2dcm serve como uma ferramenta de conversão de um formato de imagem padrão como JPEG (incluindo JPEG-LS) ou BMP para DICOM. Diferentes SOP Classes de saída podem ser selecionadas. As informações adicionais (referentes a pacientes, séries etc.) armazenadas no arquivo DICOM de saída podem ser extraídas de outros arquivos DICOM que servem como "modelo" para o objeto DICOM resultante. O img2dcm também pode ser configurado para inventar os atributos DICOM type 1 e type 2 ausentes, para funcionar mesmo sem nenhum conjunto de dados modelo.

PARÂMETROS

imgfile-in   image input filename

dcmfile-out  DICOM output filename ("-" for 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

-i --input-format [i]nput file format: string: formatos aceitos: JPEG (padrão), BMP
-df --dataset-from [f]ilename: string: usa o conjunto de dados do arquivo DICOM f
-dx --dataset-from-xml [f]ilename: string: usa o conjunto de dados do arquivo XML f
-stf --study-from [f]ilename: string: lê paciente/estudo a partir do arquivo DICOM f
-sef --series-from [f]ilename: string: lê paciente/estudo/série a partir do arquivo DICOM f
-ii --instance-inc: aumenta o número de instância lido do arquivo DICOM JPEG format:
-dp --disable-progr: desativa o suporte a JPEG progressivo
-de --disable-ext: desativa o suporte a JPEG sequencial estendido
-jf --insist-on-jfif: exige a existência de um cabeçalho JFIF
-ka --keep-appn: mantém as seções APPn (exceto JFIF)
-rc --remove-com: remove o segmento COM XML validation:
+Vd --validate-document: valida o documento XML em relação à DTD
+Vn --check-namespace: verifica o namespace XML na raiz do documento

opções de processamento

--do-checks: ativa a verificação de validade dos atributos (padrão)
--no-checks: desativa a verificação de validade dos atributos
+i2 --insert-type2: insere os atributos type 2 ausentes (padrão) (only with --do-checks)
-i2 --no-type2-insert: não insere os atributos type 2 ausentes (only with --do-checks)
+i1 --invent-type1: inventa os atributos type 1 ausentes (padrão) (only with --do-checks)
-i1 --no-type1-invent: não inventa os atributos type 1 ausentes (only with --do-checks) character set conversion of study/series file:
-Ct --transliterate: tenta aproximar caracteres que não podem ser representados usando caracteres de aparência semelhante
-Cd --discard-illegal: descarta os caracteres que não podem ser representados no conjunto de caracteres de destino other processing options:
-k --key [k]ey: gggg,eeee="str", path or dictionary name="str": adiciona mais um atributo

opções de saída

-sc --sec-capture: grava a SOP class Secondary Capture (padrão)
-nsc --new-sc: grava as novas SOP classes Secondary Capture
-vlp --vl-photo: grava a SOP class Visible Light Photographic
-oph --oph-photo: grava as SOP classes Ophthalmic Photography output file format:
+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 group length encoding:
+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:
+e --length-explicit: grava com comprimentos explícitos (padrão)
-e --length-undefined: grava com comprimentos indefinidos preenchimento final do conjunto de dados (não com --write-dataset):
-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

NOTAS

Fontes de atributos

Para converter um formato de imagem geral para o formato DICOM, o aplicativo img2dcm pode receber algumas entradas adicionais para preencher os atributos obrigatórios (e opcionais) no novo arquivo DICOM, como informações de paciente, estudo e série. Essas informações podem ser coletadas usando diferentes abordagens, que podem ser combinadas e são aplicadas ao arquivo resultante na seguinte ordem:

Com a opção –dataset-from, o img2dcm é forçado a importar atributos de um arquivo DICOM existente. O arquivo DICOM indicado é totalmente importado e serve de base para todas as operações de exportação posteriores. Como exceção, o SOP Instance UID não é copiado por essa opção. Além disso, os dados relacionados à imagem, como Rows, Columns etc., são substituídos durante a conversão. Observe que o img2dcm não verifica a validade de nenhum outro valor de atributo, por exemplo, não examina o interior das sequências para adaptar atributos ao novo objeto (imagens referenciadas etc.). Por isso, recomenda-se usar os modelos do diretório data para os (antigos) objetos SC e VLP. Veja também a seção "Modelos de entrada". Como alternativa à opção –dataset-from, pode-se usar a opção mutuamente exclusiva –dataset-from-xml. Nesse caso, porém, o arquivo deve conter dados XML no formato produzido pelo dcm2xml.
As opções –study-from e –series-from podem ser usadas para importar informações de paciente, estudo e série de um arquivo DICOM existente. Se –series-from for especificada, o arquivo DICOM indicado é aberto pelo img2dcm e todas as informações obrigatórias até o nível de série são importadas. Observe que isso inclui informações de paciente, estudo e série. No caso de –study-from, as informações de série são excluídas. Usar –study-from e –series-from ao mesmo tempo faz sentido. Se as duas opções forem fornecidas na linha de comando, a que estiver mais à direita prevalece. Os seguintes atributos são adotados:
```
Patient Level:
        Patient's Name
        Patient ID
        Patient's Sex
        Patient's Birth Date
        Specific Character Set

      Study Level:
        Study Instance UID
        Study Date
        Study Time
        Referring Physician's Name
        Study ID
        Accession Number

      Series Level (only in case of option --series-from):
        Series Instance UID
        Series Number
        Manufacturer
```
Com as opções –insert-type2 e –invent-type1 (ambas ativadas por padrão), os atributos ausentes (atributos type 2) e/ou os valores de atributo ausentes (para atributos type 1) são adicionados e inventados automaticamente pelo img2dcm. Observe que essas opções só são avaliadas se a opção –do-checks estiver ativada (padrão). Se a opção –no-checks estiver ativada, nenhuma inserção automática de atributos ocorrerá.
A opção –key pode ser usada para adicionar mais atributos ao arquivo DICOM de saída. Também é possível especificar sequências, itens e atributos aninhados usando a opção –key. Nesses casos, deve-se usar uma notação de "caminho" especial. Os detalhes dessa notação de caminho podem ser encontrados na documentação do dcmodify. A opção –key pode estar presente mais de uma vez. A parte do valor (após o '=') pode estar ausente, fazendo com que o atributo seja definido com comprimento zero. Esteja ciente de que a opção –key é aplicada bem no final, pouco antes de salvar o arquivo DICOM, portanto não há nenhuma verificação de valor.

UIDs

Novos Study Instance UID e Series Instance UID são gerados se necessário após a aplicação das opções –study-from e –series-from. Se o Study Instance UID ou o Series Instance UID não estiverem presentes após essas etapas, eles são gerados novamente, de forma independente um do outro.

Um comportamento contrário é adotado para o SOP Instance UID, que se poderia esperar que fosse aproveitado ao usar a opção –dataset-from ou –dataset-from-xml. Não é o caso: o SOP Instance UID não é copiado para o novo objeto. Esse deve ser o comportamento desejável na maioria dos casos de uso. No entanto, se um determinado SOP Instance UID precisar ser inserido no novo objeto, deve-se usar a opção –key.

Modelos de entrada

Para apoiar a conversão para DICOM, o img2dcm vem com alguns modelos predefinidos que podem ser usados com a opção –dataset-from (veja os arquivos de exemplo SC.dump e VLP.dump). Esses modelos devem ser preenchidos com os valores desejados e então precisam ser convertidos (dump) em um arquivo DICOM antes de serem efetivamente usados com o img2dcm. Use o dump2dcm para converter o dump em DICOM. Exemplo:

  dump2dcm SC.dump SC.dcm

Para imagens Ophthalmic Photography, são fornecidos modelos XML (veja os arquivos de exemplo OP_template_utf_8.xml e OP_template_latin_1.xml).

É possível usar qualquer arquivo DICOM como modelo. Observe que o conjunto de dados DICOM completo é importado; portanto, deve-se garantir que estejam presentes apenas os atributos que devam fazer parte do objeto DICOM construído. O SOP Class UID e os atributos Pixel Data (incluindo atributos como Rows, Columns etc.) não são copiados, mas substituídos pelo img2dcm durante a conversão.

Imagens multiframe

É possível converter múltiplos arquivos de entrada em uma única imagem DICOM multiframe se a SOP class DICOM selecionada oferecer suporte a multiframe. Em particular, as Multi-frame Secondary Capture SOP Classes oferecem suporte a esse recurso. Elas são selecionadas por meio da opção de linha de comando –new-sc.

Conjuntos de caracteres

Quando um modelo de entrada é carregado usando –dataset-from ou –dataset-from-xml , o specific character set desse modelo é usado para o arquivo DICOM gerado. Se as opções –study-from ou –series-from também forem usadas, o img2dcm tentará converter o conjunto de caracteres desses atributos para o do modelo, e relatará um erro se isso não for possível.

Se as opções –study-from ou –series-from forem usadas sem um modelo, o specific character set dessa fonte é usado para o arquivo DICOM gerado. Todas as chaves especificadas na linha de comando com a opção –key são tratadas como bytes brutos e substituem quaisquer atributos que já possam estar presentes devido a um modelo ou a um arquivo study/series. Por isso, deve-se ter cuidado para não especificar um specific character set na linha de comando caso um possa ser carregado de outro arquivo. Também é responsabilidade do usuário garantir que os valores de atributo especificados na linha de comando usem a codificação correta, já que nenhuma conversão ocorrerá antes de os valores serem armazenados no arquivo DICOM.

Plugins de entrada

O aplicativo img2dcm atualmente oferece suporte aos formatos de imagem JPEG, JPEG-LS e BMP como entrada.

Plugin de entrada JPEG

No caso do JPEG, o fluxo JPEG original do arquivo de origem não é decodificado, mas extraído e ligeiramente transformado (por exemplo, o cabeçalho JFIF é removido), o que permite uma conversão rápida mesmo de arquivos JPEG grandes, sem a necessidade de decodificação e recodificação. O plugin JPEG escolhe automaticamente a transfer syntax de saída necessária, dependendo da codificação real dos dados dentro do arquivo JPEG. Por isso, as seguintes transfer syntaxes (e as respectivas codificações JPEG) são usadas pelo plugin JPEG:

JPEG Coding Process 1
Baseline, Lossy, Non-Hierarchical, Sequential, DCT, Huffman, 8 Bit
Transfer Syntax UID = 1.2.840.10008.1.2.4.50
JPEG Coding Process 2 (8-bit) and 4 (12-bit)
Extended, Lossy, Non-Hierarchical, Sequential, DCT, Huffman, 8/12 Bit
Transfer Syntax UID = 1.2.840.10008.1.2.4.51
JPEG Coding Process 10 (8-bit) and 12 (12-bit)
Full Progression, lossy, Non-Hierarch., Progressive, DCT, Huffman, 8/12 Bit
Transfer Syntax UID = 1.2.840.10008.1.2.4.55

Há suporte para imagens coloridas e em tons de cinza.

O suporte à Extended JPEG Transfer Syntax pode ser desativado (opção –disable-ext), assim como o suporte à (obsoleta) Progressive JPEG Transfer Syntax (opção –disable-progr).

A codificação JPEG sem perdas, bem como quaisquer modos de codificação JPEG aritmética ou hierárquica, não são compatíveis com o plugin.

As informações JFIF (JPEG File Interchange Format) utilizam marcadores APPn opcionais em um arquivo JPEG. Muitas câmeras digitais não integram essas informações JFIF na saída JPEG que geram. Por exemplo, o JFIF contém informações sobre a proporção de pixels (pixel aspect ratio) da imagem comprimida. Se você quiser que o aplicativo img2dcm exija um cabeçalho JFIF no fluxo JPEG, pode usar a opção –insist-on-jfif, que interromperá o processamento se nenhuma informação JFIF for encontrada. Por padrão, a ausência de informações JFIF é ignorada.

Para o DICOM, é uma espécie de "zona cinzenta" se a integração de dados JFIF (ou de qualquer outro APPn) no fluxo JPEG interno do objeto DICOM é permitida ou não. No entanto, a abordagem mais confiável é remover esses marcadores e suas informações do fluxo JPEG. Essa é também a abordagem adotada pelo aplicativo img2dcm. Por padrão, todos os marcadores APPn são removidos do fluxo JPEG original. No entanto, se você quiser manter outros marcadores APPn além do JFIF (por exemplo, informações EXIF) dentro do fluxo DICOM, a opção –keep-appn resolve. Ela também deve ser um pouco mais rápida do que remover as informações APPn, porque não é necessário varrer todo o fluxo JPEG em busca desses dados. Como dito antes, as informações JFIF são sempre removidas pelo img2dcm. No entanto, ao usar essa opção, o marcador APP2 é mantido, mas o img2dcm não cria um atributo ICC Profile (0028,2000) equivalente.

Plugin de entrada JPEG-LS

O plugin JPEG-LS foi integrado diretamente ao plugin JPEG principal. Não é necessário que o usuário informe previamente e de forma explícita se a entrada é JPEG ou JPEG-LS.

No caso do JPEG-LS, o fluxo JPEG-LS original do arquivo de origem não é decodificado, mas extraído e ligeiramente transformado (por exemplo, o marcador APP8 é removido), o que permite uma conversão rápida mesmo de arquivos JPEG-LS grandes, sem a necessidade de decodificação e recodificação.

O plugin JPEG-LS escolhe automaticamente a transfer syntax de saída necessária, dependendo da codificação real dos dados dentro do arquivo JPEG-LS. Por isso, as seguintes transfer syntaxes (e as respectivas codificações JPEG-LS) são usadas pelo plugin JPEG-LS:

JPEG-LS Lossless Image Compression
Transfer Syntax UID = 1.2.840.10008.1.2.4.80
JPEG-LS Lossy (Near-Lossless) Image Compression
Transfer Syntax UID = 1.2.840.10008.1.2.4.81

Há suporte para imagens coloridas e em tons de cinza. A CP-1843 determina que o valor de Planar Configuration (0028,0006) é irrelevante, já que a forma de codificação dos componentes é especificada no bitstream JPEG-LS como intercalação por componente, linha ou amostra; portanto, ele deve ser definido como 0. Como nenhuma transformação de cor específica para JPEG-LS está atualmente definida no DICOM, presume-se que o fluxo JPEG-LS esteja codificado no espaço de cores RGB.

Para o DICOM, é claro que o cabeçalho SPIFF não deve estar presente no fluxo JPEG-LS interno do objeto DICOM. O plugin simplesmente rejeita qualquer arquivo JPEG-LS de entrada que contenha um cabeçalho SPIFF no marcador APP8.

Por padrão, todos os marcadores APPn são removidos do fluxo JPEG-LS original. No entanto, se você quiser manter marcadores APPn (por exemplo, informações de transformação de cor APP8/HP, conhecidas como 'mrfx') dentro do fluxo DICOM, a opção –keep-appn resolve. Preste atenção que o plugin verifica a transformação de cor real especificada no marcador APP8/HP. Como o DICOM não permite que nenhuma transformação de cor seja especificada no marcador APP8, apenas o valor 0 (sem transformação de cor) é aceito.

Plugin de entrada BMP

O img2dcm oferece suporte a BMP como formato de entrada. No entanto, até o momento, há suporte apenas para as imagens BMP mais comuns. Em particular, imagens BMP que usam campos de bits ou codificação run length são rejeitadas. Essas imagens são incomuns. As imagens de entrada serão convertidas em uma imagem DICOM com modelo de cores RGB e profundidade de bits de 24, ou em uma imagem com modelo de cores MONOCHROME2 e 8 bits por pixel. Não há opções específicas para ajustar finamente a conversão do formato BMP.

Plugins de saída

A SOP Class de saída desejada pode ser selecionada na linha de comando. Atualmente, estão disponíveis plugins de exportação para a Secondary Capture Image SOP Class (padrão, opção -sc), as Multi-frame Secondary Capture Image SOP Classes (opção -nsc), a Visible Light Photographic Image SOP Class (opção -vl) e as Ophthalmic Photography Image SOP Classes (opção -oph). Observe que a primeira é obsoleta segundo o padrão DICOM, mas é selecionada como padrão por ser amplamente aceita. Versões futuras do img2dcm poderão oferecer outros plugins de saída para outras SOP Classes.

Para as novas Secondary Capture SOP Classes, não é possível especificar qual SOP Class exata deve ser usada na saída. Isso ocorre porque essas novas SOP classes se diferenciam entre si pela profundidade de cor (1/8/16) e pelo fato de a imagem ser preto e branco ou colorida. É por isso que o img2dcm decide, durante a conversão, qual SOP Class de saída é adequada para uma determinada imagem de origem.

EXEMPLOS

Aqui estão alguns exemplos que mostram como o aplicativo img2dcm pode ser usado.

img2dcm image.jpg out.dcm
Lê o arquivo JPEG "image.jpg", converte para a antiga Secondary Capture SOP Class e salva o resultado no arquivo DICOM "out.dcm". Essa é a maneira mais simples de usar o img2dcm. Todos os atributos type 1 e type 2 necessários para gravar objetos válidos dessa SOP Class são inseridos automaticamente.
img2dcm -i BMP image.bmp out.dcm
Igual ao anterior, mas instrui o img2dcm a ler um arquivo BMP em vez de JPEG.
img2dcm image.jpg out.dcm -vlp -k "PatientName=Bond^James"
Igual ao primeiro exemplo, mas grava um objeto Visible Light Photographic Image em "out.dcm" e define PatientName como "Bond^James", que de outra forma ficaria vazio.
img2dcm image.jpg out.dcm –series-from template.dcm -k "PatientName=Bond^James"
Igual a 1), mas importa informações de paciente/estudo/série do arquivo DICOM "template.dcm". Observe que o atributo PatientName conterá "Bond^James" no final; qualquer valor vindo de "template.dcm" será sobrescrito. Isso ocorre porque a opção -k é aplicada bem no final do pipeline de conversão (veja acima).
img2dcm image.jpg out.dcm –no-checks
Igual a 1), mas não realiza nenhuma verificação de atributos nem inserção de atributos type 1 e type 2! Portanto, nesse caso, seria gerado um objeto DICOM inválido. Isso pode ser útil se o arquivo de saída não se destina a ficar completo, mas passará por transformações adicionais, por exemplo, a adição de atributos usando o dcmodify. Use a opção –no-checks apenas se souber o que está fazendo!
img2dcm image.jpg out.dcm –no-type1-invent
Igual a 1), mas não insere os atributos type 1 ausentes e/ou seus valores. Os atributos type 2 serão inseridos. Observe que, nesse caso, deve-se garantir que todos os atributos type 1 sejam fornecidos por outros meios, ou seja, adicionando-os com a opção –key. Caso contrário, o img2dcm relatará um erro e interromperá a conversão.
img2dcm image.jpg out.dcm –keep-appn –insist-on-jfif
Igual a 1), mas transfere informações APPn, como EXIF, para o fluxo JPEG resultante do objeto DICOM. Além disso, –insist-on-jfif forçará o img2dcm a interromper o processamento se não houver informações JFIF no arquivo de origem.
img2dcm image1.jpg image2.jpg out.dcm –new-sc
Lê os arquivos JPEG "image1.jpg" e "image2.jpg", converte em uma imagem multiframe da Multi-frame Secondary Capture SOP Class apropriada e salva o resultado no arquivo DICOM "out.dcm".

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 img2dcm 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 no aplicativo (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.

ARQUIVOS

< datadir>/SC.dump - Arquivo dump de exemplo para imagens Secondary Capture
< datadir>/VLP.dump - Arquivo dump de exemplo para imagens Visible Light Photographic
< datadir>/OP_template.xml - Modelo XML de exemplo para imagens Ophthalmic Photography

VEJA TAMBÉM

dcm2pnm(1), dcmj2pnm(1), dump2dcm(1), dcmconv(1), dcmodify(1), dcm2xml(1)