.TH "gdcmscu" 1 "Mon Sep 5 2016" "Version 2.4.4" "GDCM" \" -*- nroff -*- .ad l .nh .SH NAME gdcmscu \- Tool to execute a DICOM Query/Retrieve operation .SH "SYNOPSIS" .PP .PP .nf gdcmscu [OPTION]...[OPERATION]...HOSTNAME...[PORT]... .fi .PP Execute a DICOM Q/R operation to HOSTNAME, using port PORT (104 when not specified) .SH "DESCRIPTION" .PP The \fBgdcmscu\fP command line program is the tool to execute DICOM Query/Retrieve operation\&. It supports: .PD 0 .IP "\(bu" 2 C-ECHO (SCU) .IP "\(bu" 2 C-FIND (SCU) .IP "\(bu" 2 C-STORE (SCU) .IP "\(bu" 2 C-MOVE (SCU/SCP) C-MOVE operation are executed using two different ports (one for the SCU and one for the SCP)\&. .PP .SH "PARAMETERS" .PP .SH "OPTIONS" .PP .SS "OPTIONS" .PP .nf -H --hostname %s Hostname. -p --port %d Port number. --aetitle %s Set calling AE Title. --call %s Set called AE Title. .fi .PP .SS "mode options" .PP .nf --echo C-ECHO (default when none). --store C-STORE. --find C-FIND. --move C-MOVE. .fi .PP .SS "C-STORE options" .PP .nf -i --input %s DICOM filename -r --recursive recursively process (sub-)directories --store-query %s Store constructed query in file .fi .PP .SS "C-FIND/C-MOVE options" .PP .nf --patientroot C-FIND Patient Root Model. --studyroot C-FIND Study Root Model. --patient C-FIND Query on Patient Info (cannot be used with --studyroot). --study C-FIND Query on Study Info. --series C-FIND Query on Series Info. --image C-FIND Query on Image Info. --key %d,%d[=%s] 0123,4567=VALUE for specifying search criteria (wildcard allowed) With --key, leave blank (ie, --key 10,20="" or --key 10,20) to retrieve values .fi .PP .SS "C-MOVE options" .PP .nf -o --output %s DICOM filename / directory --port-scp %d Port for incoming associations --key %d,%d[=%s 0123,4567=VALUE for specifying search criteria (wildcard not allowed) Note that C-MOVE supports the same queries as C-FIND, but no wildcards are allowed .fi .PP .SS "general options" .PP .nf -h --help print this help text and exit -v --version print version information and exit -V --verbose verbose mode (warning+error). -W --warning warning mode, print warning information -E --error error mode, print error information -D --debug debug mode, print debug information -L --log-file specify a filename where to write logs --queryhelp print query help .fi .PP .SS "environment variable" .PP .nf GDCM_ROOT_UID Root UID .fi .PP .SH "C-ECHO usage" .PP \fBgdcmscu\fP is a great tool to test if a DICOM server is up\&. For example to send a C-ECHO to server dicom\&.example\&.com using port 104, use: .PP .PP .nf $ gdcmscu dicom.example.com .fi .PP .PP or if you prefer being explicit: .PP .PP .nf $ gdcmscu --echo dicom.example.com 104 .fi .PP .PP Using basic security your DICOM server might require that you set the appropriate called AE-TITLE .PP .PP .nf $ gdcmscu --echo dicom.example.com 11112 --call SERVSCP .fi .PP .PP If you want to specifiy your own AE-TITLE (default is GDCMSCU), simply use: .PP .PP .nf $ gdcmscu --echo dicom.example.com 11112 --call SERVSCP --aetitle MYSCU .fi .PP .PP For example you could test on the DICOM server provided by DICOMObject team: .PP .PP .nf $ gdcmscu www.dicomserver.co.uk 11112 .fi .PP .SH "C-STORE usage" .PP C-STORE is the operation that allow sending a DICOM file to a remote DICOM server\&. For instance to send a file called myfile\&.dcm .PP .PP .nf $ gdcmscu --store dicom.example.com 104 myfile.dcm .fi .PP .PP or if you prefer being explicit: .PP .PP .nf $ gdcmscu --store dicom.example.com 104 -i myfile.dcm .fi .PP .PP You can even send multiple files using the same association: .PP .PP .nf $ gdcmscu --store dicom.example.com 104 myfile1.dcm myfile2.dcm myfile3.dcm ... .fi .PP .SH "C-FIND usage" .PP \fBgdcmscu\fP also allow querying a DICOM server\&. This is the C-FIND operation, for example to find all DICOM Instance where PatientsName match a particular pattern, usage is simply: .PP .PP .nf $ gdcmscu --find --patient dicom.example.com 11112 --patientroot --key 10,10,"A*" .fi .PP .PP We also support a DCMTK compatible convention: .PP .PP .nf $ gdcmscu --find --patient dicom.example.com 11112 --patientroot --key 10,10="A*" .fi .PP .PP When an attribute is set without a value it will be part of the output result: .PP .PP .nf $ gdcmscu --find --patient dicom.example.com 11112 --call MI2B2 --patientroot -k 10,10="A*" -k 10,20 .fi .PP .SH "C-MOVE usage" .PP C-MOVE is the operation to retrieve a DICOM instance from a remote DICOM server\&. Most of the time, it is a subsequent operation after a C-FIND query\&. To retrieve a DICOM instance where PatientID is ABCD1234, simply execute: .PP .PP .nf $ gdcmscu --move --patient --aetitle ACME1 --call ACME_STORE dicom.example.com 5678 --patientroot -k 10,20="ABCD1234" --port-scp 1234 .fi .PP .PP WARNING For this operation to work you need information from the DICOM server you are communicating with\&. Only the DICOM server you are sending a C-MOVE query will be responsible for sending back incoming associations (the actual C-STORE SCP)\&. Therefore you need to make sure that you mapping of (AE-TITLE,PortNumber) is properly set on the DICOM server side as well as the port for incoming association (--port-scp)\&. .PP \fBgdcmscu\fP does not currently support external C-STORE association (C-STORE request sent to an external SCP application)\&. .SH "patientroot notes" .PP The flag --patientroot is just simply a wrapper around the syntax --key 8,52=PATIENT For instance one would write using DCMTK syntax: .PP .PP .nf $ findscu --patient dicom.example.com 11112 --key 8,52=PATIENT --key 10,10="F*" .fi .PP .PP This would become using GDCM syntax: .PP .PP .nf $ gdcmscu --find --patient dicom.example.com 11112 --patientroot --key 10,10="F*" .fi .PP .SH "Debugging" .PP This is sometime difficult to investigate why a connection to a remote DICOM server cannot be done\&. Some recommendations follows: .PP Always try to do a simple C-ECHO at first\&. If you cannot get the C-ECHO to work none of the other operations will work .PP Before trying to a C-MOVE operation, make sure you can execute the C-FIND equivalent query first\&. .PP When doing a C-MOVE operation you really need to communicate with the PACS admin as the C-MOVE operation is different from the other lower level operation such as HTTP/GET\&. When doing a C-MOVE, the server will communicate back using another channel (could be different port) using it's internal database to map an AE-TITLE back to the destination IP\&. .PP Indeed the C-MOVE operation by design does not always use your incoming IP address to send back the resulting dataset\&. Instead it uses a mapping of AE-TITLE to IP address to send back any results\&. So pay particular attention to the spelling of your AE-TITLE and your incoming port (which may be different from the port to connect to the server)\&. .SH "Port Warning" .PP Watch out that port ranging [1-1024] are reserved for admin and not easily accessible unless granted special privileges\&. Therefore the default 104 DICOM port might not be accessible to all your users\&. .SH "C-STORE Warnings" .PP When constructing a C-STORE operation, gdcmscu will always use the Media Storage SOP Class UID as found in the file to be sent\&. For encapsulated DICOM file (eg\&. RLE Lossless) the receiving SCP server might not support this compression and will legitimately refuse the C-STORE operation\&. In this case users have to manually convert to a non-compressed form this particular file: .PP .PP .nf $ gdcmconv --raw compressed.dcm non_compressed.dcm .fi .PP .SH "C-MOVE Warnings" .PP At the moment \fBgdcmscu\fP only supports non-compressed transfer syntax\&. It will always request DataSet using Implicit VR Little Endian Transfer Syntax during a C-MOVE operation (both incoming and outgoing associations)\&. This make gdcmscu --move equivalent to DCMTK movescu syntax: .PP .PP .nf $ movescu -xi +xi ... .fi .PP .SH "C-FIND IMAGE level (Composite Object Instance)" .PP One should pay attention that gdcmscu --find and findscu are not completely equivalent\&. Using gdcmscu --find, all Unique Keys will be added automatically\&. One can therefore execute something like this: .PP .PP .nf $ gdcmscu --find --patientroot --image --key 8,18=1.2.3.4.5.6 dicom.example.com 11112 .fi .PP .PP instead of the more explicit form .PP .PP .nf $ gdcmscu --find --patientroot --image --key 8,18=1.2.3.4.5.6 dicom.example.com 11112 --key 10,20 --key 20,d --key 20,e .fi .PP .PP This would also be equivalent to: .PP .PP .nf $ findscu --patient --key 8,52=IMAGE --key 8,18=1.2.3.4.5.6 dicom.example.com 11112 --key 10,20 --key 20,d --key 20,e .fi .PP .SH "Storing the Query" .PP It is also possible to store the query: .PP .PP .nf gdcmscu --find --patient --patientroot dicom.example.com 11112 --key 10,20="*" --key 10,10 --store-query query.dcm .fi .PP .PP One can then check the DataSet values send for the query: .PP .PP .nf $ gdcmdump query.dcm # Dicom-File-Format # Dicom-Meta-Information-Header # Used TransferSyntax: # Dicom-Data-Set # Used TransferSyntax: 1.2.840.10008.1.2 (0008,0005) ?? (CS) [ISO_IR 192] # 10,1-n Specific Character Set (0008,0052) ?? (CS) [PATIENT ] # 8,1 Query/Retrieve Level (0010,0010) ?? (PN) (no value) # 0,1 Patient's Name (0010,0020) ?? (LO) [* ] # 2,1 Patient ID .fi .PP .PP The Specific Character Set was set to 'ISO_IR 192' as the locale encoding of the system was found automatically by gdcmscu to be UTF-8\&. .PP This means that the following command line will properly setup the Query with the appropriate Charset to be executed correctly: .PP .PP .nf $ gdcmscu --find --patient --patientroot dicom.example.com 11112 --key 10,10="*Jérôme*" .fi .PP .PP The query is always executed on the server side (SCP), some implementations does not support string matching with different Character Set\&. .SH "DICOM Public Servers" .PP An up to date list of DICOM Public Servers can be found at: .PP http://www.dclunie.com/medical-image-faq/html/part8.html#DICOMPublicServers .SH "SEE ALSO" .PP \fBgdcmconv\fP(1) .SH "COPYRIGHT" .PP Copyright Insight Software Consortium