findscu: SCU de consulta DICOM (C-FIND)

SINOPSE

findscu [options] peer port [dcmfile-in...]

DESCRIÇÃO

O aplicativo findscu implementa um SCU para a classe de serviço Query/Retrieve e para a classe de serviço Basic Worklist Management. O findscu oferece suporte apenas à funcionalidade de consulta usando a mensagem C-FIND. Ele envia chaves de consulta a um SCP e aguarda as respostas. O aplicativo pode ser usado para testar SCPs das classes de serviço Query/Retrieve e Basic Worklist Management.

PARÂMETROS

peer        hostname of DICOM peer

port        tcp/ip port number of peer

dcmfile-in  DICOM query file(s)

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 rede

-k --key [k]ey: gggg,eeee="str", path or dictionary name="str": substitui a chave de correspondência. modelo de informação da consulta:
-W --worklist: usa o modelo de informação Modality Worklist (padrão)
-P --patient: usa o modelo de informação patient root
-S --study: usa o modelo de informação study root
-O --psonly: usa o modelo de informação patient/study only. versão do protocolo IP:
-i4 --ipv4: usa apenas IPv4 (padrão)
-i6 --ipv6: usa apenas IPv6
-i0 --ip-auto: usa consulta DNS para determinar o protocolo IP. títulos de entidade de aplicação:
-aet --aetitle [a]etitle: string: define meu AE Title chamador (padrão: FINDSCU)
-aec --call [a]etitle: string: define o AE Title chamado do par (padrão: ANY-SCP). representações de valor posteriores a 1993:
+u --enable-new-vr: habilita o suporte a novos VRs (UN/UT) (padrão)
-u --disable-new-vr: desabilita o suporte a novas VRs, converte para OB. sintaxes de transferência propostas para transmissão:
-x= --propose-uncompr: propõe todas as TS não comprimidas, com o explicit VR e ordem de bytes local primeiro (padrão)
-xe --propose-little: propõe todas as TS não comprimidas, com o explicit VR little endian primeiro
-xb --propose-big: propõe todas as TS não comprimidas, com o explicit VR big endian primeiro
-xd --propose-deflated: propõe a TS deflated explicit VR little endian e todas as sintaxes de transferência não comprimidas
-xi --propose-implicit: propõe apenas a TS implicit VR little endian. nível de compressão deflate (somente com --propose-deflated):
+cl --compression-level [l]evel: integer (default: 6): 0=não comprimido, 1=mais rápido, 9=melhor compressão. outras opções de rede:
-to --timeout [s]econds: integer (default: unlimited): tempo limite para solicitações de conexão
-ts --socket-timeout [s]econds: integer (default: 60): tempo limite para o socket de rede (0 para nenhum)
-ta --acse-timeout [s]econds: integer (default: 30): tempo limite para mensagens ACSE
-td --dimse-timeout [s]econds: integer (default: unlimited): tempo limite para mensagens DIMSE
-pdu --max-pdu [n]umber of bytes: integer (4096..131072): define a pdu máxima recebida em n bytes (padrão: 16384)
--repeat [n]umber: integer: repete n vezes
--abort: interrompe a associação em vez de liberá-la
--cancel [n]umber: integer: cancela após n respostas (padrão: nunca)

opções de segurança da camada de transporte (TLS)

-tls --disable-tls: usa uma conexão TCP/IP normal (padrão)
+tls --enable-tls [p]rivate key file, [c]ertificate file: string: usa uma conexão TLS segura autenticada
+tla --anonymous-tls: usa uma conexão TLS segura sem certificado. senha da chave privada (somente com --enable-tls):
+ps --std-passwd: solicita que o usuário digite a senha na entrada padrão (padrão)
+pw --use-passwd [p]assword: string: usa a senha especificada
-pw --null-passwd: usa uma string vazia como senha. formato do arquivo de chave e certificado:
-pem --pem-keys: lê chaves e certificados como arquivo PEM (padrão)
-der --der-keys: lê chaves e certificados como arquivo DER. autoridade de certificação:
+cf --add-cert-file [f]ilename: string: adiciona um arquivo de certificado à lista de certificados
+cd --add-cert-dir [d]irectory: string: adiciona os certificados de d à lista de certificados
+crl --add-crl-file [f]ilename: string: adiciona um arquivo de lista de revogação de certificados (implica --enable-crl-vfy)
+crv --enable-crl-vfy: ativa a verificação de CRL do certificado folha
+cra --enable-crl-all: habilita a verificação de CRL de toda a cadeia perfil de segurança:
+ph --list-profiles: lista os perfis TLS com suporte e sai
+pg --profile-8996: Perfil TLS BCP 195 RFC 8996 (padrão)
+pm --profile-8996-mod: Perfil TLS BCP 195 RFC 8996 modificado # only available if underlying TLS library supports # all TLS features required for this profile
+py --profile-bcp195-nd: Perfil TLS BCP 195 sem downgrade (obsoleto)
+px --profile-bcp195: Perfil TLS BCP 195 (obsoleto)
+pz --profile-bcp195-ex: Perfil TLS BCP 195 estendido (obsoleto)
+pb --profile-basic: perfil básico de conexão de transporte seguro TLS (obsoleto) # disponível apenas se a biblioteca TLS subjacente oferecer suporte a 3DES
+pa --profile-aes: AES TLS Secure Transport Connection Profile (obsoleto)
+pn --profile-null: Comunicação autenticada não criptografada (retirada, era usada no IHE ATNA) conjunto de cifras:
+cc --list-ciphers: lista os conjuntos de cifras TLS com suporte e sai
+cs --cipher [c]iphersuite name: string: adiciona a conjunto de cifras à lista de suítes negociadas indicação de nome de servidor:
--no-sni: não usa SNI (padrão)
--request-sni [s]erver name: string: solicita o nome de servidor s. gerador pseudoaleatório:
+rs --seed [f]ilename: string: inicializa o gerador aleatório com o conteúdo de f
+ws --write-seed: grava novamente a semente modificada (somente com --seed)
+wf --write-seed-file [f]ilename: string (only with --seed): grava a semente modificada no arquivo f. autenticação do par:
-rc --require-peer-cert: verifica o certificado do par, falha se ausente (padrão)
-ic --ignore-peer-cert: não verifica o certificado do par

opções de saída

-od --output-directory [d]irectory: string (default: "."): grava os arquivos de saída no diretório existente d. correção automática de dados:
+dc --enable-correction: habilita a correção automática de dados
-dc --disable-correction: desabilita a correção automática de dados (padrão). respostas C-FIND:
+sr --show-responses: sempre exibe as respostas no log
-sr --hide-responses: não exibe as respostas no log
-X --extract: extrai as respostas para um arquivo DICOM (rsp0001.dcm...)
-Xx --extract-xml: extrai as respostas para um arquivo XML (rsp0001.xml...)
-Xs --extract-xml-single [f]ilename: string: extrai todas as respostas para o arquivo XML f indicado
-Xlo --limit-output [n]umber: integer: limita a n o número de respostas extraídas para arquivo (padrão: ilimitado)

NOTAS

Cada arquivo informado na linha de comando é enviado ao SCP como parte de uma solicitação C-FIND. O arquivo de consulta deve ser um conjunto de dados DICOM válido contendo a parte de conjunto de dados de uma mensagem C-FIND-RQ. O arquivo de consulta pode, por exemplo, ser criado com o utilitário dump2dcm a partir de um script como o exemplo a seguir:

# query patient names and IDs
(0008,0052) CS [PATIENT]     # QueryRetrieveLevel
(0010,0010) PN []            # PatientName
(0010,0020) LO []            # PatientID

Os atributos individuais de cada arquivo enviado podem ser modificados ou complementados usando a opção -k. Por exemplo, o comando:

findscu -P -k "(0010,0010)=HEWETT*" caesar 5678 patqry.dcm

quando enviado ao SCP caesar na porta TCP/IP 5678, faz com que qualquer atributo PatientName em patqry.dcm passe a ter o valor "HEWETT*". Se esse atributo estiver presente, ele será substituído; se estiver ausente, será inserido. A opção -k pode ser informada mais de uma vez. A parte do valor (após o '=') pode estar ausente, fazendo com que o atributo seja enviado com comprimento zero.

Em versões anteriores do findscu , as chaves de tag eram especificadas sem parênteses ao redor do número de grupo e elemento, por exemplo, "0010,0010" em vez de "(0010,0010)". Recomenda-se migrar para a nova sintaxe; no entanto, a sintaxe antiga ainda funciona.

Além disso, a opção -k aceita nomes de dicionário em vez de tags de elemento para especificar elementos DICOM. Por exemplo, a chamada do findscu acima passa a ser escrita assim:

findscu -P -k PatientName="HEWETT*" caesar 5678 patqry.dcm

Também é possível especificar sequências, itens e atributos aninhados usando a opção -k. Nesses casos, deve-se usar uma notação especial de "caminho", por exemplo:

findscu -W -k "(0040,0100)[0].Modality=CT" caesar 5678

Essa chamada consulta um servidor de lista de trabalho no host caesar em busca de procedimentos planejados para modalidades CT, especificando a tag (0040,0100) "Scheduled Procedure Step Sequence" e um atributo "Modality" no primeiro item dessa sequência com o valor "CT". Detalhes sobre essa notação de caminho podem ser encontrados na documentação do dcmodify.

Se nenhum arquivo for especificado na linha de comando, a consulta deve ser especificada completamente com uma ou mais opções -k. Se vários arquivos de consulta forem fornecidos, o findscu enviará várias solicitações C-FIND ao SCP.

Cada conjunto de identificadores de resposta recebido será exibido no log, a menos que a opção –hide-responses , qualquer uma das variantes –extract abaixo, –quiet ou uma configuração de log apropriada seja usada. Nesses casos, a exibição no log pode ser forçada com a opção –show-responses.

Além disso, os conjuntos de dados de resposta também podem ser extraídos como arquivos DICOM individuais (usando a opção –extract) ou arquivos XML (usando a opção –extract-xml). O formato de saída deste último é descrito pelo arquivo dcm2xml.dtd (começando pelo elemento de nível superior "data-set"). Para arquivos XML, o Specific Character Set é mapeado automaticamente para uma codificação XML apropriada. Quando isso não é possível, por exemplo no caso de conjuntos de caracteres ISO 2022, 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. Observe que isso pode gerar referências de entidade de caractere inválidas (como "" para ESC) e fazer com que a maioria dos analisadores XML rejeite o documento.

Alternativamente, todos os conjuntos de dados de resposta de uma associação podem ser extraídos para um único arquivo XML usando a opção –extract-xml-single. O elemento de nível superior do documento XML é "responses" (com um atributo "type" igual a "C-FIND"). Os conjuntos de dados individuais são armazenados conforme descrito acima. Se o suporte à conversão de conjunto de caracteres estiver habilitado, é usada a codificação UTF-8, ou seja, todos os conjuntos de dados são convertidos para a codificação UTF-8 (o que é fortemente recomendado para evitar problemas com caracteres não ASCII quando diferentes conjuntos de caracteres são usados).

Conformidade DICOM

O aplicativo findscu oferece suporte às seguintes classes SOP como SCU:

FINDPatientRootQueryRetrieveInformationModel       1.2.840.10008.5.1.4.1.2.1.1
FINDStudyRootQueryRetrieveInformationModel         1.2.840.10008.5.1.4.1.2.2.1
FINDPatientStudyOnlyQueryRetrieveInformationModel  1.2.840.10008.5.1.4.1.2.3.1
FINDModalityWorklistInformationModel               1.2.840.10008.5.1.4.31

O aplicativo findscu propõe contextos de apresentação para uma das classes SOP com suporte mencionadas acima, dependendo das opções de linha de comando (-P , -S , -O ou -W). Basicamente, há suporte para as seguintes sintaxes de transferência:

LittleEndianImplicitTransferSyntax                 1.2.840.10008.1.2
LittleEndianExplicitTransferSyntax                 1.2.840.10008.1.2.1
DeflatedExplicitVRLittleEndianTransferSyntax       1.2.840.10008.1.2.1.99 (*)
BigEndianExplicitTransferSyntax                    1.2.840.10008.1.2.2

(*) se compilado com suporte a zlib habilitado (veja a saída de –version)

É possível especificar quais sintaxes de transferência são efetivamente propostas, e em que ordem, com as opções –propose.

O aplicativo findscu não oferece suporte à negociação estendida.

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 findscu 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 é carregado, a menos que o dicionário esteja incorporado ao 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.

Dependendo das opções de linha de comando especificadas, o utilitário findscu tenta carregar tabelas de mapeamento de conjunto de caracteres. Isso ocorre quando o DCMTK foi compilado com a biblioteca oficonv (o que é o padrão) e as tabelas de mapeamento não estão incorporadas à 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.