dcm2json: converte um arquivo e um conjunto de dados DICOM para JSON

SINOPSE

dcm2json [options] dcmfile-in [jsonfile-out]

DESCRIÇÃO

O aplicativo dcm2json converte o conteúdo de um arquivo DICOM (formato de arquivo ou conjunto de dados bruto) para JSON (JavaScript Object Notation). A saída se refere ao "DICOM JSON Model", descrito em DICOM Part 18 Section F.

Quando o dcm2json lê um conjunto de dados bruto (dados DICOM sem meta-header de formato de arquivo), ele tenta 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 aplicativo dcmconv). Também é possível usar as opções -f e -t[ieb] para forçar o dcm2json 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)

jsonfile-out JSON 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

opções de processamento

-es --encode-strict: reporta um erro para 'inf' e 'nan' (padrão)
-ee --encode-extended: permite 'inf' e 'nan' nos números JSON. Codificação dos elementos IS e DS (cadeia de caracteres inteira/decimal):
-ia --is-ds-auto: codifica como número se válido, como cadeia de caracteres caso contrário (padrão)
-in --is-ds-num: sempre codifica como número, falha se inválido
-is --is-ds-string: sempre codifica como cadeia de caracteres. Opções das URIs de dados volumosos:
-b --bulk-disabled: grava tudo como binário embutido (padrão)
+b --bulk-enabled: grava atributos grandes como dados volumosos
+bz --bulk-size [s]ize: integer (default: 1): usa dados volumosos para atributos com tamanho igual ou superior a s kBytes
+bp --bulk-uri-prefix [u]ri prefix: string: usa o prefixo u ao gerar URIs de dados volumosos (padrão: URI de arquivo)
+bd --bulk-dir [d]irectory: string: grava os arquivos de dados volumosos em d (padrão: '.')
+bs --bulk-subdir: cria um subdiretório para cada instância SOP (padrão: sem subdiretório)

opções de saída

+fc --formatted-code: ativa a formatação com espaços em branco (padrão) # imprime espaços e quebras de linha adicionais para aumentar a legibilidade
-fc --compact-code: exibe somente os caracteres necessários
+m --write-meta: grava o conjunto de dados com as metainformações (aviso: não está em conformidade com o padrão DICOM)

Formato JSON

A estrutura básica da saída JSON gerada a partir de um arquivo DICOM tem a seguinte aparência (consulte DICOM Part 18 Section F para mais detalhes):

{
    "00080005": {
        "vr": "CS",
        "Value": [
            "ISO_IR 192"
        ]
    },
    "00080020": {
        "vr": "DT",
        "Value": [
            "20130409"
        ]
    },
    "00080030": {
        "vr": "TM",
        "Value": [
            "131600.0000"
        ]
    },
    "00080050": {
        "vr": "SH",
        "Value": [
            "11235813"
        ]
    },
    "00080056": {
        "vr": "CS",
        "Value": [
            "ONLINE"
        ]
    },
    "00080061": {
        "vr": "CS",
        "Value": [
            "CT",
            "PET"
        ]
    },
    "00080090": {
        "vr": "PN",
        "Value": [
          {
            "Alphabetic": "^Bob^^Dr."
          }
        ]
    },
    "00081190": {
        "vr": "UR",
        "Value": [
            "http://wado.nema.org/studies/
            1.2.392.200036.9116.2.2.2.1762893313.1029997326.945873"
        ]
    },
    "00090010": {
        "vr": "LO",
        "Value": [
            "Vendor A"
        ]
    },
    "00091002": {
        "vr": "UN",
        "InlineBinary": "z0x9c8v7"
    },
    "00100010": {
        "vr": "PN",
        "Value": [
          {
            "Alphabetic": "Wang^XiaoDong"
          }
        ]
    },
    "00100020": {
        "vr": "LO",
        "Value": [
            "12345"
        ]
    },
    "00100021": {
        "vr": "LO",
        "Value": [
            "Hospital A"
        ]
    },
    "00100030": {
        "vr": "DA",
        "Value": [
            "19670701"
        ]
    },
    "00100040": {
        "vr": "CS",
        "Value": [
            "M"
        ]
    },
    "00101002": {
        "vr": "SQ",
        "Value": [
            {
                "00100020": {
                    "vr": "LO",
                    "Value": [
                        "54321"
                    ]
                },
                "00100021": {
                    "vr": "LO",
                    "Value": [
                        "Hospital B"
                    ]
                }
            },
            {
                "00100020": {
                    "vr": "LO",
                    "Value": [
                        "24680"
                    ]
                },
                "00100021": {
                    "vr": "LO",
                    "Value": [
                        "Hospital C"
                    ]
                }
            }
        ]
    },
    "0020000D": {
        "vr": "UI",
        "Value": [
            "1.2.392.200036.9116.2.2.2.1762893313.1029997326.945873"
        ]
    },
    "00200010": {
        "vr": "SH",
        "Value": [
            "11235813"
        ]
    },
    "00201206": {
        "vr": "IS",
        "Value": [
            4
        ]
    },
    "00201208": {
        "vr": "IS",
        "Value": [
            942
        ]
    }
}

Dados Volumosos

Por padrão, os dados binários, ou seja, os valores de elementos DICOM com representação de valor (VR) OB, OD, OF, OL, OV, OW e UN, são gravados como "InlineBinary" (codificação base64) na saída JSON. A opção –bulk-enabled faz com que os dados binários, assim como DS, FD, FL, IS, SV e UV, sejam substituídos por valores "BulkDataURI" se o valor do elemento for maior que o limite de corte (padrão: 1 kByte). O limite de corte pode ser especificado com a opção –bulk-size. Os próprios valores dos elementos são gravados como arquivos no diretório indicado pela opção –bulk-dir (padrão: diretório atual). O nome do arquivo é baseado em uma soma de verificação SHA-256 do valor do elemento. Por padrão, são geradas URIs de arquivo que apontam para o diretório de dados volumosos. Para uso em produção, deve-se especificar, com a opção –bulk-uri-prefix, um prefixo de URI para um serviço WADO-RS por meio do qual os valores dos elementos possam ser recuperados. Isso pode ser implementado configurando um servidor web que tenha acesso de leitura ao diretório de dados volumosos do dcm2json. Por fim, a opção –bulk-subdir fará com que um subdiretório separado seja criado (e usado na URI de dados volumosos) para cada instância SOP distinta.

Observe que a sintaxe JSON para a representação de dados de pixel encapsulados na forma "InlineBinary" não é especificada no DICOM, assim como a representação JSON de dados de pixel encapsulados de múltiplos quadros. Esses arquivos DICOM não podem ser convertidos para JSON usando o dcm2json.

A extensão do nome de arquivo dos arquivos de dados volumosos gerados pode ser usada para determinar o tipo MIME que deve ser retornado pelo servidor WADO-RS:

  Extension     MIME Type

  .bin          application/octet-stream
  .jpeg         image/jpeg
  .dicom-rle    image/dicom-rle
  .jls          image/jls
  .jp2          image/jp2
  .jpx          image/jpx
  .jphc         image/jphc
  .jxl          image/jxl
  .mpeg         video/mpeg
  .mp4          video/mp4
  .H265         video/H265

Por fim, cabe observar que os dados volumosos serão gravados "como estão", ou seja, o dcm2json não tentará validar nem modificar o valor do elemento de forma alguma. Por exemplo, o dcm2json não adicionará um cabeçalho JFIF no caso de imagens comprimidas em JPEG baseline, que alguns visualizadores JPEG podem esperar.

NOTAS

Números como Cadeias de Caracteres

O padrão DICOM permite que certas representações de valor DICOM numéricas, DS, IS, SV e UV, sejam convertidas em um número JSON ou em uma cadeia de caracteres JSON. O dcm2json converte os valores DS e IS em números JSON se forem cadeias decimais ou cadeias inteiras válidas, e em cadeias de caracteres se contiverem algum caractere inválido. O dcm2json converte os valores SV e UV em números se não forem maiores que 9007199254740991ll nem menores que -9007199254740991ll, e em cadeias de caracteres caso contrário. Embora a especificação JSON permita números maiores, esses são os maiores inteiros que o JavaScript consegue tratar. Por isso, muitos analisadores JSON não conseguem processar números maiores.

Codificação de caracteres

Conforme exigido pela codificação JSON do DICOM, o dcm2json sempre gera a saída na codificação Unicode UTF-8 e converte os conjuntos de dados DICOM de acordo. Se isso não for possível, por exemplo porque o DCMTK foi compilado sem suporte à conversão de conjunto de caracteres, um erro é retornado.

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).

CÓDIGOS DE SAÍDA

O utilitário dcm2json usa os seguintes códigos de saída ao ser encerrado. Isso permite ao usuário verificar o motivo pelo qual o aplicativo foi encerrado.

geral

EXITCODE_NO_ERROR                         0
EXITCODE_COMMANDLINE_SYNTAX_ERROR         1

erros de arquivo de entrada

EXITCODE_CANNOT_READ_INPUT_FILE          20
EXITCODE_NO_INPUT_FILES                  21

erros de arquivo de saída

EXITCODE_CANNOT_WRITE_OUTPUT_FILE        40

erros de processamento

EXITCODE_CANNOT_CONVERT_TO_UNICODE       80
EXITCODE_CANNOT_WRITE_VALID_JSON         81

AMBIENTE

O aplicativo dcm2json tenta 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.

O aplicativo dcm2json tenta 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.