GDCMSCU(1)

📦
version 3.0.24 · 12 versions
, in opensuse-leap 16.0

🎀 GDCMSCU 🎀

okay so bestie, welcome to gdcmscu(1) — it lives in the DICOM Manipulation manual section and it's literally the tool you use to run a DICOM Query/Retrieve operation. pull up a chair 💅

✨ SYNOPSIS ✨

gdcmscu [OPTION]...[OPERATION]...HOSTNAME...[PORT]...

so you're executing a DICOM Q/R operation against HOSTNAME, on port PORT (104 when you don't specify one, cutie 🫶).

🌸 DESCRIPTION 🌸

gdcmscu is the command line program that runs your DICOM Query/Retrieve operation. it supports, and yes this is the whole slay list:

  • C-ECHO (SCU)
  • C-FIND (SCU)
  • C-STORE (SCU)
  • C-MOVE (SCU/SCP) — and heads up, C-MOVE operations get executed using two different ports (one for the SCU and one for the SCP). two ports, one vibe 💖

🦋 PARAMETERS 🦋

💜 OPTIONS 💜

specific options

  • -H, --hostname — %s Hostname.
  • -p, --port — %d Port number.
  • --aetitle — %s Set calling AE Title.
  • --call — %s Set called AE Title.

mode options

  • --echo — C-ECHO (the default when you pick none).
  • --store — C-STORE.
  • --find — C-FIND.
  • --move — C-MOVE.

C-STORE options

  • -i, --input — %s DICOM filename.
  • -r, --recursive — recursively process (sub-)directories.
  • --store-query — %s Store constructed query in file.

C-FIND/C-MOVE options

  • --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 it blank (i.e. --key 10,20="" or just --key 10,20) to retrieve values 👑

C-MOVE options

  • -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 🚫

general options

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

environment variable

  • GDCM_ROOT_UID — Root UID 🌈

💖 C-ECHO USAGE 💖

gdcmscu is genuinely such a great tool to test if a DICOM server is up — it's giving "are you there?" energy. for example, to send a C-ECHO to server dicom.example.com using port 104, use:

$ gdcmscu dicom.example.com

or if you prefer being explicit (main character behaviour):

$ gdcmscu --echo dicom.example.com 104

Using basic security, your DICOM server might require that you set the appropriate called AE-TITLE:

$ gdcmscu --echo dicom.example.com 11112 --call SERVSCP

If you want to specify your own AE-TITLE (the default is GDCMSCU, fyi), simply use:

$ gdcmscu --echo dicom.example.com 11112 --call SERVSCP --aetitle MYSCU

For example you could test on the DICOM server provided by DICOMObject team:

$ gdcmscu www.dicomserver.co.uk 11112

🍓 C-STORE USAGE 🍓

C-STORE is the operation that lets you send a DICOM file to a remote DICOM server. for instance, to send a file called myfile.dcm:

$ gdcmscu --store dicom.example.com 104 myfile.dcm

or if you prefer being explicit:

$ gdcmscu --store dicom.example.com 104 -i myfile.dcm

you can even send multiple files using the same association, no cap:

$ gdcmscu --store dicom.example.com 104 myfile1.dcm myfile2.dcm myfile3.dcm ...

🧚 C-FIND USAGE 🧚

gdcmscu also lets you query a DICOM server. that's the C-FIND operation. for example, to find all DICOM Instance where PatientsName matches a particular pattern, usage is simply:

$ gdcmscu --find --patient dicom.example.com 11112 --patientroot --key 10,10,"A*"

we also support a DCMTK compatible convention:

$ gdcmscu --find --patient dicom.example.com 11112 --patientroot --key 10,10="A*"

when an attribute is set without a value it will be part of the output result:

$ gdcmscu --find --patient dicom.example.com 11112 --call MI2B2 --patientroot -k 10,10="A*" -k 10,20

🔥 C-MOVE USAGE 🔥

C-MOVE is the operation to retrieve a DICOM instance from a remote DICOM server. most of the time it's a subsequent operation after a C-FIND query. to retrieve a DICOM instance where PatientID is ABCD1234, simply execute:

$ gdcmscu --move --patient --aetitle ACME1 --call ACME_STORE dicom.example.com 5678 --patientroot -k 10,20="ABCD1234" --port-scp 1234
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 to will be responsible for sending back incoming associations (the actual C-STORE SCP). Therefore you need to make sure that your mapping of (AE-TITLE, PortNumber) is properly set on the DICOM server side as well as the port for incoming association (--port-scp).

gdcmscu does not currently support external C-STORE association (C-STORE request sent to an external SCP application). nope, not a thing 🙈

👑 PATIENTROOT NOTES 👑

the flag --patientroot is just simply a wrapper around the syntax --key 8,52=PATIENT. for instance one would write using DCMTK syntax:

$ findscu --patient dicom.example.com 11112 --key 8,52=PATIENT --key 10,10="F*"

this would become, using GDCM syntax:

$ gdcmscu --find --patient dicom.example.com 11112 --patientroot --key 10,10="F*"

💀 DEBUGGING 💀

sometimes it is genuinely difficult to investigate why a connection to a remote DICOM server cannot be done. some recommendations follow:

  • 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.
  • Before trying a C-MOVE operation, make sure you can execute the C-FIND equivalent query first.
  • When doing a C-MOVE operation you really need to communicate with the PACS admin, because the C-MOVE operation is different from the other lower level operations such as HTTP/GET. When doing a C-MOVE, the server will communicate back using another channel (could be a different port) using its internal database to map an AE-TITLE back to the destination IP.
  • 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).

⭐ PORT WARNING ⭐

watch out 👀 — ports ranging [1-1024] are reserved for admin and are not easily accessible unless granted special privileges. therefore the default 104 DICOM port might not be accessible to all your users.

🌈 C-STORE WARNINGS 🌈

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 files (e.g. 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 this particular file to a non-compressed form:

$ gdcmconv --raw compressed.dcm non_compressed.dcm

💅 C-MOVE WARNINGS 💅

at the moment gdcmscu 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 makes gdcmscu --move equivalent to the DCMTK movescu syntax:

$ movescu -xi +xi ...

🦋 C-FIND IMAGE LEVEL (COMPOSITE OBJECT INSTANCE) 🦋

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:

$ gdcmscu --find --patientroot --image --key 8,18=1.2.3.4.5.6 dicom.example.com 11112

instead of the more explicit form:

$ 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

this would also be equivalent to:

$ 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

🎀 STORING THE QUERY 🎀

it is also possible to store the query:

gdcmscu --find --patient --patientroot dicom.example.com 11112 --key 10,20="*" --key 10,10 --store-query query.dcm

one can then check the DataSet values sent for the query:

$ 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

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. obsessed, honestly 💖

this means that the following command line will properly set up the Query with the appropriate Charset to be executed correctly:

$ gdcmscu --find --patient --patientroot dicom.example.com 11112 --key 10,10="*Jérôme*"

the query is always executed on the server side (SCP), and some implementations do not support string matching with a different Character Set. iykyk 😭

🌸 DICOM PUBLIC SERVERS 🌸

an up to date list of DICOM Public Servers can be found at:

http://www.dclunie.com/medical-image-faq/html/part8.html#DICOMPublicServers

💜 SEE ALSO 💜

gdcmconv(1) — go read it, bestie 🫶

🌟 AUTHOR 🌟

Mathieu Malaterre Main developer

Copyright © 2006, 2011 Mathieu Malaterre

okay that's the whole thing, you ate that 💅✨ this was GDCM 3.0.24, dated 12/25/2025 — mwah, go query something iconic 🎀🦋

📦 where this page comes from