'\" t
.\"     Title: gdcmscu
.\"    Author: Mathieu Malaterre
.\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
.\"      Date: 04/08/2024
.\"    Manual: DICOM Manipulation.
.\"    Source: GDCM 3.0.22
.\"  Language: English
.\"
.TH "GDCMSCU" "1" "04/08/2024" "GDCM 3\&.0\&.22" "DICOM Manipulation\&."
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gdcmscu \- Tool to execute a DICOM Query/Retrieve operation
.SH "SYNOPSIS"
.PP
.if n \{\
.RS 4
.\}
.nf
gdcmscu [OPTION]\&.\&.\&.[OPERATION]\&.\&.\&.HOSTNAME\&.\&.\&.[PORT]\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
Execute a DICOM Q/R operation to HOSTNAME, using port PORT (104 when not specified)
.SH "DESCRIPTION"
.PP
The
\fBgdcmscu\fR
command line program is the tool to execute DICOM Query/Retrieve operation\&. It supports:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
C\-ECHO (SCU)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
C\-FIND (SCU)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
C\-STORE (SCU)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
C\-MOVE (SCU/SCP) C\-MOVE operation are executed using two different ports (one for the SCU and one for the SCP)\&.
.RE
.sp
.SH "PARAMETERS"
.SH "OPTIONS"
.SS "specific options"
.PP
.if n \{\
.RS 4
.\}
.nf
  \-H \-\-hostname    %s  Hostname\&.
  \-p \-\-port        %d  Port number\&.
     \-\-aetitle     %s  Set calling AE Title\&.
     \-\-call        %s  Set called AE Title\&.
.fi
.if n \{\
.RE
.\}
.SS "mode options"
.PP
.if n \{\
.RS 4
.\}
.nf
     \-\-echo           C\-ECHO (default when none)\&.
     \-\-store          C\-STORE\&.
     \-\-find           C\-FIND\&.
     \-\-move           C\-MOVE\&.
.fi
.if n \{\
.RE
.\}
.SS "C\-STORE options"
.PP
.if n \{\
.RS 4
.\}
.nf
  \-i \-\-input       %s   DICOM filename
  \-r \-\-recursive        recursively process (sub\-)directories
     \-\-store\-query %s   Store constructed query in file
.fi
.if n \{\
.RE
.\}
.SS "C\-FIND/C\-MOVE options"
.PP
.if n \{\
.RS 4
.\}
.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
.if n \{\
.RE
.\}
.SS "C\-MOVE options"
.PP
.if n \{\
.RS 4
.\}
.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
.if n \{\
.RE
.\}
.SS "general options"
.PP
.if n \{\
.RS 4
.\}
.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
.if n \{\
.RE
.\}
.SS "environment variable"
.PP
.if n \{\
.RS 4
.\}
.nf
  GDCM_ROOT_UID Root UID
.fi
.if n \{\
.RE
.\}
.SH "C\-ECHO USAGE"
.PP
\fBgdcmscu\fR
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
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu dicom\&.example\&.com
.fi
.if n \{\
.RE
.\}
.PP
or if you prefer being explicit:
.PP
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu \-\-echo dicom\&.example\&.com 104
.fi
.if n \{\
.RE
.\}
.PP
Using basic security your DICOM server might require that you set the appropriate called AE\-TITLE
.PP
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu \-\-echo dicom\&.example\&.com 11112 \-\-call SERVSCP
.fi
.if n \{\
.RE
.\}
.PP
If you want to specify your own AE\-TITLE (default is GDCMSCU), simply use:
.PP
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu \-\-echo dicom\&.example\&.com 11112 \-\-call SERVSCP \-\-aetitle MYSCU
.fi
.if n \{\
.RE
.\}
.PP
For example you could test on the DICOM server provided by DICOMObject team:
.PP
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu www\&.dicomserver\&.co\&.uk 11112
.fi
.if n \{\
.RE
.\}
.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
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu \-\-store dicom\&.example\&.com 104 myfile\&.dcm
.fi
.if n \{\
.RE
.\}
.PP
or if you prefer being explicit:
.PP
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu \-\-store dicom\&.example\&.com 104 \-i myfile\&.dcm
.fi
.if n \{\
.RE
.\}
.PP
You can even send multiple files using the same association:
.PP
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu \-\-store dicom\&.example\&.com 104 myfile1\&.dcm myfile2\&.dcm myfile3\&.dcm \&.\&.\&.
.fi
.if n \{\
.RE
.\}
.SH "C\-FIND USAGE"
.PP
\fBgdcmscu\fR
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
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu \-\-find \-\-patient dicom\&.example\&.com 11112 \-\-patientroot \-\-key 10,10,"A*"
.fi
.if n \{\
.RE
.\}
.PP
We also support a DCMTK compatible convention:
.PP
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu \-\-find \-\-patient dicom\&.example\&.com 11112 \-\-patientroot \-\-key 10,10="A*"
.fi
.if n \{\
.RE
.\}
.PP
When an attribute is set without a value it will be part of the output result:
.PP
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu \-\-find \-\-patient dicom\&.example\&.com 11112 \-\-call MI2B2 \-\-patientroot \-k 10,10="A*" \-k 10,20
.fi
.if n \{\
.RE
.\}
.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
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu \-\-move \-\-patient \-\-aetitle ACME1 \-\-call ACME_STORE dicom\&.example\&.com 5678 \-\-patientroot \-k 10,20="ABCD1234" \-\-port\-scp 1234
.fi
.if n \{\
.RE
.\}
.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 (\(enport\-scp)\&.
.PP
\fBgdcmscu\fR
does not currently support external C\-STORE association (C\-STORE request sent to an external SCP application)\&.
.SH "PATIENTROOT NOTES"
.PP
The flag \(enpatientroot is just simply a wrapper around the syntax \(enkey 8,52=PATIENT For instance one would write using DCMTK syntax:
.PP
.if n \{\
.RS 4
.\}
.nf
$ findscu \-\-patient dicom\&.example\&.com 11112 \-\-key 8,52=PATIENT \-\-key 10,10="F*"
.fi
.if n \{\
.RE
.\}
.PP
This would become using GDCM syntax:
.PP
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu \-\-find \-\-patient dicom\&.example\&.com 11112 \-\-patientroot \-\-key 10,10="F*"
.fi
.if n \{\
.RE
.\}
.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\*(Aqs 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
.if n \{\
.RS 4
.\}
.nf
$ gdcmconv \-\-raw compressed\&.dcm non_compressed\&.dcm
.fi
.if n \{\
.RE
.\}
.SH "C\-MOVE WARNINGS"
.PP
At the moment
\fBgdcmscu\fR
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 \(enmove equivalent to DCMTK movescu syntax:
.PP
.if n \{\
.RS 4
.\}
.nf
$ movescu \-xi +xi \&.\&.\&.
.fi
.if n \{\
.RE
.\}
.SH "C\-FIND IMAGE LEVEL (COMPOSITE OBJECT INSTANCE)"
.PP
One should pay attention that gdcmscu \(enfind and findscu are not completely equivalent\&. Using gdcmscu \(enfind, all Unique Keys will be added automatically\&. One can therefore execute something like this:
.PP
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu \-\-find \-\-patientroot \-\-image \-\-key 8,18=1\&.2\&.3\&.4\&.5\&.6 dicom\&.example\&.com 11112
.fi
.if n \{\
.RE
.\}
.PP
instead of the more explicit form
.PP
.if n \{\
.RS 4
.\}
.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
.if n \{\
.RE
.\}
.PP
This would also be equivalent to:
.PP
.if n \{\
.RS 4
.\}
.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
.if n \{\
.RE
.\}
.SH "STORING THE QUERY"
.PP
It is also possible to store the query:
.PP
.if n \{\
.RS 4
.\}
.nf
gdcmscu \-\-find \-\-patient \-\-patientroot dicom\&.example\&.com 11112 \-\-key 10,20="*" \-\-key 10,10 \-\-store\-query query\&.dcm
.fi
.if n \{\
.RE
.\}
.PP
One can then check the DataSet values send for the query:
.PP
.if n \{\
.RS 4
.\}
.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\*(Aqs Name
(0010,0020) ?? (LO) [* ]                                          # 2,1 Patient ID
.fi
.if n \{\
.RE
.\}
.PP
The Specific Character Set was set to
\(lqISO_IR 192\(rq
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
.if n \{\
.RS 4
.\}
.nf
$ gdcmscu \-\-find \-\-patient \-\-patientroot dicom\&.example\&.com 11112 \-\-key 10,10="*Jérôme*"
.fi
.if n \{\
.RE
.\}
.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
\m[blue]\fBhttp://www\&.dclunie\&.com/medical\-image\-faq/html/part8\&.html#DICOMPublicServers\fR\m[]
.SH "SEE ALSO"
.PP
\fBgdcmconv\fR(1)
.SH "AUTHOR"
.PP
\fBMathieu Malaterre\fR
.RS 4
Main developer
.RE
.SH "COPYRIGHT"
.br
Copyright \(co 2006, 2011 Mathieu Malaterre
.br