Introduction

Starting in v2.2, pydicom offers a useful command-line interface (CLI) for exploring DICOM files, and access to the codify option for creating pydicom Python code. Additional subcommands may be added over time.

Example at the command line in a terminal window:

$ pydicom show pydicom::rtplan.dcm
Dataset.file_meta -------------------------------
(0002, 0000) File Meta Information Group Length  UL: 156
(0002, 0001) File Meta Information Version       OB: b'\x00\x01'
(0002, 0002) Media Storage SOP Class UID         UI: RT Plan Storage
(0002, 0003) Media Storage SOP Instance UID      UI: 1.2.999.999.99.9.9999.9999.20030903150023
(0002, 0010) Transfer Syntax UID                 UI: Implicit VR Little Endian
(0002, 0012) Implementation Class UID            UI: 1.2.888.888.88.8.8.8
-------------------------------------------------
(0008, 0012) Instance Creation Date              DA: '20030903'
(0008, 0013) Instance Creation Time              TM: '150031'
(0008, 0016) SOP Class UID                       UI: RT Plan Storage
(0008, 0018) SOP Instance UID                    UI: 1.2.777.777.77.7.7777.7777.20030903150023
(0008, 0020) Study Date                          DA: '20030716'
...

Note that prefixing the file specification with pydicom:: will read the file from the pydicom test data files rather than from the normal file system. The following examples will use that so that you can replicate these examples exactly. In normal use, you would leave the pydicom:: prefix off when working with your files.

You can also show just parts of the DICOM file by specifying a data element using the usual pydicom keyword notation:

$ pydicom show pydicom::rtplan.dcm::FractionGroupSequence[0]
(300a, 0071) Fraction Group Number               IS: "1"
(300a, 0078) Number of Fractions Planned         IS: "30"
(300a, 0080) Number of Beams                     IS: "1"
(300a, 00a0) Number of Brachy Application Setups IS: "0"
(300c, 0004)  Referenced Beam Sequence  1 item(s) ----
(300a, 0082) Beam Dose Specification Point       DS: [239.531250000000, 239.531250000000, -751.87000000000]
(300a, 0084) Beam Dose                           DS: "1.0275401"
(300a, 0086) Beam Meterset                       DS: "116.0036697"
(300c, 0006) Referenced Beam Number              IS: "1"
---------

You can see the available subcommands by simply typing pydicom with no arguments, or with pydicom help:

$ pydicom help
Use pydicom help [subcommand] to show help for a subcommand
Available subcommands: codify, show

And, as noted in the block above, you get help for a particular subcommand by typing pydicom help [subcommand]. For example:

$ pydicom help show
usage: pydicom show [-h] [-x] [-t] [-q] filespec

Display all or part of a DICOM file

positional arguments:
filespec              File specification, in format [pydicom::]filename[::element]. If `pydicom::`
                        prefix is used, then show the pydicom test file with that name. If `element`
                        is given, use only that data element within the file. Examples:
                        path/to/your_file.dcm, your_file.dcm::StudyDate,
                        pydicom::rtplan.dcm::BeamSequence[0], yourplan.dcm::BeamSequence[0].BeamNumber

optional arguments:
-h, --help            show this help message and exit
-x, --exclude-private
                        Don't show private data elements
-t, --top             Only show top level
-q, --quiet           Only show basic information

Installing the pydicom CLI

The pydicom command should automatically be available after you pip install pydicom. It should not require any updates to the system path or environment variables.

If you are helping develop pydicom code, and are using git clones, you will have to pip install -e . or python setup.py develop from the pydicom repository root. This has to be repeated for any changes to setup.py (e.g. to add a new subcommand).

If you are developing subcommands within your own package, you will need to reinstall your package similar to the above as you add entry points.

Combining with other CLIs

CLIs are useful for general exploration while programming, but also can be combined with other command-line filters for additional functionality. The following is an example of piping the output of the pydicom ‘show’ subcommand into ‘grep’, filtering for lines with either “Dose” or “Sequence” in them:

$ pydicom show pydicom::rtplan.dcm | grep "Dose\|Sequence"
(300a, 0010)  Dose Reference Sequence  2 item(s) ----
(300a, 0012) Dose Reference Number               IS: "1"
(300a, 0014) Dose Reference Structure Type       CS: 'COORDINATES'
(300a, 0016) Dose Reference Description          LO: 'iso'
(300a, 0018) Dose Reference Point Coordinates    DS: [239.531250000000, 239.531250000000, -741.87000000000]
(300a, 0020) Dose Reference Type                 CS: 'ORGAN_AT_RISK'
(300a, 0023) Delivery Maximum Dose               DS: "75.0"
(300a, 002c) Organ at Risk Maximum Dose          DS: "75.0"
(300a, 0012) Dose Reference Number               IS: "2"
(300a, 0014) Dose Reference Structure Type       CS: 'COORDINATES'
(300a, 0016) Dose Reference Description          LO: 'PTV'
(300a, 0018) Dose Reference Point Coordinates    DS: [239.531250000000, 239.531250000000, -751.87000000000]
(300a, 0020) Dose Reference Type                 CS: 'TARGET'
(300a, 0026) Target Prescription Dose            DS: "30.826203"
(300a, 0070)  Fraction Group Sequence  1 item(s) ----
(300c, 0004)  Referenced Beam Sequence  1 item(s) ----
    (300a, 0082) Beam Dose Specification Point       DS: [239.531250000000, 239.531250000000, -751.87000000000]
    (300a, 0084) Beam Dose                           DS: "1.0275401"
(300a, 00b0)  Beam Sequence  1 item(s) ----
(300a, 00b6)  Beam Limiting Device Sequence  2 item(s) ----
(300a, 0111)  Control Point Sequence  2 item(s) ----
    (300a, 0115) Dose Rate Set                       DS: "650.0"
    (300a, 011a)  Beam Limiting Device Position Sequence  2 item(s) ----
    (300c, 0050)  Referenced Dose Reference Sequence  2 item(s) ----
        (300a, 010c) Cumulative Dose Reference Coefficie DS: "0.0"
        (300c, 0051) Referenced Dose Reference Number    IS: "1"
        (300a, 010c) Cumulative Dose Reference Coefficie DS: "0.0"
        (300c, 0051) Referenced Dose Reference Number    IS: "2"
    (300c, 0050)  Referenced Dose Reference Sequence  2 item(s) ----
        (300a, 010c) Cumulative Dose Reference Coefficie DS: "0.9990268"
        (300c, 0051) Referenced Dose Reference Number    IS: "1"
        (300a, 010c) Cumulative Dose Reference Coefficie DS: "1.0"
        (300c, 0051) Referenced Dose Reference Number    IS: "2"
(300a, 0180)  Patient Setup Sequence  1 item(s) ----
(300c, 0002)  Referenced RT Plan Sequence  1 item(s) ----
(300c, 0060)  Referenced Structure Set Sequence  1 item(s) ----

Using the “or Sequence” (`\|Sequence`) regular expression as above allows you to see any filtered results in relation to their parent Sequences.

See the pydicom show command section for more examples of the show command, its options, and the ability to show only data elements or sequences within the file.