1GDCMSCU(1)                    DICOM Manipulation.                   GDCMSCU(1)
2
3
4

NAME

6       gdcmscu - Tool to execute a DICOM Query/Retrieve operation
7

SYNOPSIS

9           gdcmscu [OPTION]...[OPERATION]...HOSTNAME...[PORT]...
10
11       Execute a DICOM Q/R operation to HOSTNAME, using port PORT (104 when
12       not specified)
13

DESCRIPTION

15       The gdcmscu command line program is the tool to execute DICOM
16       Query/Retrieve operation. It supports:
17
18       •   C-ECHO (SCU)
19
20       •   C-FIND (SCU)
21
22       •   C-STORE (SCU)
23
24       •   C-MOVE (SCU/SCP) C-MOVE operation are executed using two different
25           ports (one for the SCU and one for the SCP).
26
27

PARAMETERS

OPTIONS

30   specific options
31             -H --hostname    %s  Hostname.
32             -p --port        %d  Port number.
33                --aetitle     %s  Set calling AE Title.
34                --call        %s  Set called AE Title.
35
36   mode options
37                --echo           C-ECHO (default when none).
38                --store          C-STORE.
39                --find           C-FIND.
40                --move           C-MOVE.
41
42   C-STORE options
43             -i --input       %s   DICOM filename
44             -r --recursive        recursively process (sub-)directories
45                --store-query %s   Store constructed query in file
46
47   C-FIND/C-MOVE options
48                --patientroot       C-FIND Patient Root Model.
49                --studyroot         C-FIND Study Root Model.
50
51                --patient           C-FIND Query on Patient Info (cannot be used with --studyroot).
52                --study             C-FIND Query on Study Info.
53                --series            C-FIND Query on Series Info.
54                --image             C-FIND Query on Image Info.
55                --key   %d,%d[=%s]  0123,4567=VALUE for specifying search criteria (wildcard allowed)
56                                    With --key, leave blank (ie, --key 10,20="" or --key 10,20) to retrieve values
57
58   C-MOVE options
59             -o --output    %s      DICOM filename / directory
60                --port-scp  %d      Port for incoming associations
61                --key   %d,%d[=%s   0123,4567=VALUE for specifying search criteria (wildcard not allowed)
62                                    Note that C-MOVE supports the same queries as C-FIND, but no wildcards are allowed
63
64   general options
65             -h   --help
66                    print this help text and exit
67
68             -v   --version
69                    print version information and exit
70
71             -V   --verbose
72                    verbose mode (warning+error).
73
74             -W   --warning
75                    warning mode, print warning information
76
77             -E   --error
78                    error mode, print error information
79
80             -D   --debug
81                    debug mode, print debug information
82
83             -L   --log-file
84                    specify a filename where to write logs
85
86             --queryhelp
87                    print query help
88
89   environment variable
90             GDCM_ROOT_UID Root UID
91

C-ECHO USAGE

93       gdcmscu is a great tool to test if a DICOM server is up. For example to
94       send a C-ECHO to server dicom.example.com using port 104, use:
95
96           $ gdcmscu dicom.example.com
97
98       or if you prefer being explicit:
99
100           $ gdcmscu --echo dicom.example.com 104
101
102       Using basic security your DICOM server might require that you set the
103       appropriate called AE-TITLE
104
105           $ gdcmscu --echo dicom.example.com 11112 --call SERVSCP
106
107       If you want to specify your own AE-TITLE (default is GDCMSCU), simply
108       use:
109
110           $ gdcmscu --echo dicom.example.com 11112 --call SERVSCP --aetitle MYSCU
111
112       For example you could test on the DICOM server provided by DICOMObject
113       team:
114
115           $ gdcmscu www.dicomserver.co.uk 11112
116

C-STORE USAGE

118       C-STORE is the operation that allow sending a DICOM file to a remote
119       DICOM server. For instance to send a file called myfile.dcm
120
121           $ gdcmscu --store dicom.example.com 104 myfile.dcm
122
123       or if you prefer being explicit:
124
125           $ gdcmscu --store dicom.example.com 104 -i myfile.dcm
126
127       You can even send multiple files using the same association:
128
129           $ gdcmscu --store dicom.example.com 104 myfile1.dcm myfile2.dcm myfile3.dcm ...
130

C-FIND USAGE

132       gdcmscu also allow querying a DICOM server. This is the C-FIND
133       operation, for example to find all DICOM Instance where PatientsName
134       match a particular pattern, usage is simply:
135
136           $ gdcmscu --find --patient dicom.example.com 11112 --patientroot --key 10,10,"A*"
137
138       We also support a DCMTK compatible convention:
139
140           $ gdcmscu --find --patient dicom.example.com 11112 --patientroot --key 10,10="A*"
141
142       When an attribute is set without a value it will be part of the output
143       result:
144
145           $ gdcmscu --find --patient dicom.example.com 11112 --call MI2B2 --patientroot -k 10,10="A*" -k 10,20
146

C-MOVE USAGE

148       C-MOVE is the operation to retrieve a DICOM instance from a remote
149       DICOM server. Most of the time, it is a subsequent operation after a
150       C-FIND query. To retrieve a DICOM instance where PatientID is ABCD1234,
151       simply execute:
152
153           $ gdcmscu --move --patient --aetitle ACME1 --call ACME_STORE dicom.example.com 5678 --patientroot -k 10,20="ABCD1234" --port-scp 1234
154
155       WARNING For this operation to work you need information from the DICOM
156       server you are communicating with. Only the DICOM server you are
157       sending a C-MOVE query will be responsible for sending back incoming
158       associations (the actual C-STORE SCP). Therefore you need to make sure
159       that you mapping of (AE-TITLE,PortNumber) is properly set on the DICOM
160       server side as well as the port for incoming association (–port-scp).
161
162       gdcmscu does not currently support external C-STORE association
163       (C-STORE request sent to an external SCP application).
164

PATIENTROOT NOTES

166       The flag –patientroot is just simply a wrapper around the syntax –key
167       8,52=PATIENT For instance one would write using DCMTK syntax:
168
169           $ findscu --patient dicom.example.com 11112 --key 8,52=PATIENT --key 10,10="F*"
170
171       This would become using GDCM syntax:
172
173           $ gdcmscu --find --patient dicom.example.com 11112 --patientroot --key 10,10="F*"
174

DEBUGGING

176       This is sometime difficult to investigate why a connection to a remote
177       DICOM server cannot be done. Some recommendations follows:
178
179       Always try to do a simple C-ECHO at first. If you cannot get the C-ECHO
180       to work none of the other operations will work
181
182       Before trying to a C-MOVE operation, make sure you can execute the
183       C-FIND equivalent query first.
184
185       When doing a C-MOVE operation you really need to communicate with the
186       PACS admin as the C-MOVE operation is different from the other lower
187       level operation such as HTTP/GET. When doing a C-MOVE, the server will
188       communicate back using another channel (could be different port) using
189       it's internal database to map an AE-TITLE back to the destination IP.
190
191       Indeed the C-MOVE operation by design does not always use your incoming
192       IP address to send back the resulting dataset. Instead it uses a
193       mapping of AE-TITLE to IP address to send back any results. So pay
194       particular attention to the spelling of your AE-TITLE and your incoming
195       port (which may be different from the port to connect to the server).
196

PORT WARNING

198       Watch out that port ranging [1-1024] are reserved for admin and not
199       easily accessible unless granted special privileges. Therefore the
200       default 104 DICOM port might not be accessible to all your users.
201

C-STORE WARNINGS

203       When constructing a C-STORE operation, gdcmscu will always use the
204       Media Storage SOP Class UID as found in the file to be sent. For
205       encapsulated DICOM file (eg. RLE Lossless) the receiving SCP server
206       might not support this compression and will legitimately refuse the
207       C-STORE operation. In this case users have to manually convert to a
208       non-compressed form this particular file:
209
210           $ gdcmconv --raw compressed.dcm non_compressed.dcm
211

C-MOVE WARNINGS

213       At the moment gdcmscu only supports non-compressed transfer syntax. It
214       will always request DataSet using Implicit VR Little Endian Transfer
215       Syntax during a C-MOVE operation (both incoming and outgoing
216       associations). This make gdcmscu –move equivalent to DCMTK movescu
217       syntax:
218
219           $ movescu -xi +xi ...
220

C-FIND IMAGE LEVEL (COMPOSITE OBJECT INSTANCE)

222       One should pay attention that gdcmscu –find and findscu are not
223       completely equivalent. Using gdcmscu –find, all Unique Keys will be
224       added automatically. One can therefore execute something like this:
225
226           $ gdcmscu --find --patientroot --image --key 8,18=1.2.3.4.5.6 dicom.example.com 11112
227
228       instead of the more explicit form
229
230           $ 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
231
232       This would also be equivalent to:
233
234           $ 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
235

STORING THE QUERY

237       It is also possible to store the query:
238
239           gdcmscu --find --patient --patientroot dicom.example.com 11112 --key 10,20="*" --key 10,10 --store-query query.dcm
240
241       One can then check the DataSet values send for the query:
242
243           $ gdcmdump query.dcm
244           # Dicom-File-Format
245
246           # Dicom-Meta-Information-Header
247           # Used TransferSyntax:
248
249           # Dicom-Data-Set
250           # Used TransferSyntax: 1.2.840.10008.1.2
251           (0008,0005) ?? (CS) [ISO_IR 192]                                  # 10,1-n Specific Character Set
252           (0008,0052) ?? (CS) [PATIENT ]                                    # 8,1 Query/Retrieve Level
253           (0010,0010) ?? (PN) (no value)                                    # 0,1 Patient's Name
254           (0010,0020) ?? (LO) [* ]                                          # 2,1 Patient ID
255
256       The Specific Character Set was set to “ISO_IR 192” as the locale
257       encoding of the system was found automatically by gdcmscu to be UTF-8.
258
259       This means that the following command line will properly setup the
260       Query with the appropriate Charset to be executed correctly:
261
262           $ gdcmscu --find --patient --patientroot dicom.example.com 11112 --key 10,10="*Jérôme*"
263
264       The query is always executed on the server side (SCP), some
265       implementations does not support string matching with different
266       Character Set.
267

DICOM PUBLIC SERVERS

269       An up to date list of DICOM Public Servers can be found at:
270
271       http://www.dclunie.com/medical-image-faq/html/part8.html#DICOMPublicServers
272

SEE ALSO

274       gdcmconv(1)
275

AUTHOR

277       Mathieu Malaterre
278           Main developer
279

COPYRIGHT

281       Copyright © 2006, 2011 Mathieu Malaterre
282
283
284
285GDCM 3.0.21                       02/06/2023                        GDCMSCU(1)