findscu

Added in version 1.5.

$ python -m pynetdicom findscu [options] addr port (-k keyword and/or -f file-in)

Description

The findscu application implements a Service Class User (SCU) for the Query/Retrieve and Basic Worklist Management service classes. It requests an association with a peer Application Entity and once established, sends a C-FIND query to be matched against the SCP’s managed SOP Instances. The SCP then responds with the matching query keys.

The source code for the application can be found here

Usage

The following example shows what happens when it is successfully run on an SCP at IP 127.0.0.1 and listen port 11112 that supports the Query/Retrieve (Find) service:

$ python -m pynetdicom findscu 127.0.0.1 11112 -k QueryRetrieveLevel=PATIENT -k PatientName=
I: Requesting Association
I: Association Accepted
I: Sending Find Request: MsgID 1
I:
I: # Request Identifier
I: (0008,0052) CS [PATIENT]                                # 1 QueryRetrieveLevel
I: (0010,0010) PN (no value available)                     # 0 PatientName
I:
I: Find SCP Response: 1 - 0xFF00 (Pending)
I:
I: # Response Identifier
I: (0008,0052) CS [PATIENT]                                # 1 QueryRetrieveLevel
I: (0008,0054) AE [QRSCP]                                  # 1 RetrieveAETitle
I: (0010,0010) PN [CompressedSamples^CT1]                  # 1 PatientName
I:
I: Find SCP Result: 0x0000 (Success)
I: Releasing Association

Parameters

addr

TCP/IP address or hostname of DICOM peer

port

TCP/IP port number of peer

Options

General Options

-q    --quiet

quiet mode, prints no warnings or errors

-v    --verbose

verbose mode, prints processing details

-d    --debug

debug mode, prints debugging information

-ll   --log-level [l]evel (str)

One of ['critical', 'error', 'warning', 'info', 'debug'], prints logging messages with corresponding level or higher

Network Options

-aet  --calling-aet [a]etitle (str)

set the local AE title (default: FINDSCU)

-aec  --called-aet [a]etitle (str)

set the called AE title for the peer AE (default: ANY-SCP)

-ta   --acse-timeout [s]econds (float)

timeout for ACSE messages (default: 30)

-td   --dimse-timeout [s]econds (float)

timeout for DIMSE messages (default: 30)

-tn   --network-timeout [s]econds (float)

timeout for the network (default: 30)

-pdu  --max-pdu [n]umber of bytes (int)

set maximum receive PDU bytes to n bytes (default: 16382)

Query Information Model Options

-P    --patient

use patient root information model (default)

-S    --study

use study root information model

-O    --psonly

use patient/study only information model

-W    --worklist

use modality worklist information model

-U    --ups

use unified procedure step pull information model

Query Options

-k [k]eyword: (gggg,eeee)=str, keyword=str

add or override a query element using either an element tag as (group,element) or the element’s keyword (such as PatientName). See the keyword pathing section for more information.

-f path to [f]ile (str)

use a DICOM file as the query dataset, if used with -k then the elements will be added to or overwrite those present in the file

Extended Negotiation Options

--relational-query

request the use of relational queries (not with -W)

--dt-matching

request the use of date-time matching (not with -W)

--fuzzy-names

request the use of fuzzy semantic matching of person names

--timezone-adj

request the use of timezone query adjustment

--enhanced-conversion

request the use of enhanced multi-frame image conversion (not with -W)

Output Options

-w    --write

write the responses to file as rsp000001.dcm, rsp000002.dcm, …

Keyword pathing

When using the -k keyword option it becomes possible to specify the query dataset (the Identifier) without needing to create a DICOM file. Multiple instances of -k can be used to build up the Identifier. For example, this will produce an Identifier with (0008,0052) Query Retrieve Level and (0010,0010) Patient Name elements:

-k QueryRetrieveLevel=PATIENT -k PatientName=

The value after the = is interpreted as the element’s value, so including any single or double quotation marks will result in an incorrect element value. PatientName=Citizen^Jan is correct, PatientName="Citizen^Jan" is not.

Alternatively the element tags can be used instead:

-k (0008,0052)=PATIENT -k (0010,0010)=

Sequences can be specified using the same Python indexing syntax as used by pydicom:

-k OtherPatientIDsSequence[2].PatientID=12345678

When both the -f file and -k keyword options are used then the keywords will be used to update the elements in the file.

Examples

Empty (0010,0010) Patient Name element:

-k PatientName=
-k (0010,0010)=

(0010, 0010) Patient's Name                      PN: ''

Patient Name set to Citizen^Jan:

-k PatientName=Citizen^Jan
-k (0010,0010)=Citizen^Jan

(0010, 0010) Patient's Name                      PN: 'Citizen^Jan'

Numeric VRs like US and FL are converted to either int or float depending on the VR:

-k Columns=1024

(0028, 0011) Columns                             US: 1024

Byte VRs like OB and OW are converted to bytes:

-k PixelData=00FFEA08

(7fe0, 0010) Pixel Data                          OW: b'\x00\xff\xea\x08'

Elements with VM > 1 can be set by using \\ (where appropriate):

-k AcquisitionIndex=1\\2\\3\\4

(0020, 9518) Acquisition Index                   US: [1, 2, 3, 4]

Empty (300A,00B0) Beam Sequence:

-k BeamSequence=
-k (300a,00b0)=

(300a, 00b0)  Beam Sequence   0 item(s) ----

Beam Sequence with one empty item:

-k BeamSequence[0]=

(300a, 00b0)  Beam Sequence   1 item(s) ----

   ---------

Beam Sequence with four empty items:

-k BeamSequence[3]=

(300a, 00b0)  Beam Sequence   4 item(s) ----

   ---------

   ---------

   ---------

   ---------

Beam Sequence with one non-empty item:

-k BeamSequence[0].PatientName=CITIZEN^Jan

(300a, 00b0)  Beam Sequence   1 item(s) ----
   (0010, 0010) Patient's Name                      PN: 'Citizen^Jan'
   ---------

Nested sequence items:

-k BeamSequence[0].BeamLimitingDeviceSequence[0].NumberOfLeafJawPairs=1

(300a, 00b0)  Beam Sequence   1 item(s) ----
   (300a, 00b6)  Beam Limiting Device Sequence   1 item(s) ----
      (300a, 00bc) Number of Leaf/Jaw Pairs            IS: "1"
      ---------
   ---------

DICOM Conformance

The findscu application supports the Query/Retrieve and Basic Worklist Management services as an SCU. The following SOP classes are supported:

Query/Retrieve Service

SOP Classes

UID

Transfer Syntax

1.2.840.10008.5.1.4.1.2.1.1

Patient Root Query/Retrieve Information Model - FIND

1.2.840.10008.5.1.4.1.2.2.1

Study Root Query/Retrieve Information Model - FIND

1.2.840.10008.5.1.4.1.2.3.1

Patient Study Only Query/Retrieve Information - FIND

Transfer Syntaxes

UID

Transfer Syntax

1.2.840.10008.1.2

Implicit VR Little Endian

1.2.840.10008.1.2.1

Explicit VR Little Endian

1.2.840.10008.1.2.1.99

Deflated Explicit VR Little Endian

1.2.840.10008.1.2.2

Explicit VR Big Endian

Basic Worklist Management Service

SOP Classes

UID

Transfer Syntax

1.2.840.10008.5.1.4.31

Modality Worklist Information Model - FIND

Transfer Syntaxes

UID

Transfer Syntax

1.2.840.10008.1.2

Implicit VR Little Endian

1.2.840.10008.1.2.1

Explicit VR Little Endian

1.2.840.10008.1.2.1.99

Deflated Explicit VR Little Endian

1.2.840.10008.1.2.2

Explicit VR Big Endian

Unified Procedure Step Service

SOP Classes

UID

Transfer Syntax

1.2.840.10008.5.1.4.34.6.3

UPS Pull Information Model - FIND

Transfer Syntaxes

UID

Transfer Syntax

1.2.840.10008.1.2

Implicit VR Little Endian

1.2.840.10008.1.2.1

Explicit VR Little Endian

1.2.840.10008.1.2.1.99

Deflated Explicit VR Little Endian

1.2.840.10008.1.2.2

Explicit VR Big Endian