Source code

dicomweb_client package

dicomweb_client.api module

Application Programming Interface (API).

class dicomweb_client.api.DICOMwebClient(url, username=None, password=None, ca_bundle=None, cert=None, qido_url_prefix=None, wado_url_prefix=None, stow_url_prefix=None, proxies=None, headers=None, callback=None, auth=None, gcp_service_account_key_file=None)

Bases: object

Class for connecting to and interacting with a DICOMweb RESTful service.

base_url

unique resource locator of the DICOMweb service

Type:str
protocol

name of the protocol, e.g. "https"

Type:str
host

IP address or DNS name of the machine that hosts the server

Type:str
port

number of the port to which the server listens

Type:int
url_prefix

URL path prefix for DICOMweb services (part of base_url)

Type:str
qido_url_prefix

URL path prefix for QIDO-RS (not part of base_url)

Type:Union[str, NoneType]
wado_url_prefix

URL path prefix for WADO-RS (not part of base_url)

Type:Union[str, NoneType]
stow_url_prefix

URL path prefix for STOW-RS (not part of base_url)

Type:Union[str, NoneType]
static lookup_keyword(tag)

Looks up the keyword of a DICOM attribute.

Parameters:tag (Union[str, int, Tuple[str], pydicom.tag.Tag]) – attribute tag (e.g. "00080018")
Returns:attribute keyword (e.g. "SOPInstanceUID")
Return type:str
static lookup_tag(keyword)

Looks up the tag of a DICOM attribute.

Parameters:keyword (str) – attribute keyword (e.g. "SOPInstanceUID")
Returns:attribute tag as HEX string (e.g. "00080018")
Return type:str
retrieve_bulkdata(url, media_types=None, byte_range=None)

Retrieves bulk data from a given location.

Parameters:
  • url (str) – location of the bulk data
  • media_types (Tuple[Union[str, Tuple[str, str]]], optional) – acceptable media types and optionally the UIDs of the corresponding transfer syntaxes
  • byte_range (Tuple[int], optional) – start and end of byte range
Returns:

bulk data items

Return type:

List[bytes]

retrieve_instance(study_instance_uid, series_instance_uid, sop_instance_uid, media_types=None)

Retrieves an individual DICOM instance.

Parameters:
  • study_instance_uid (str) – unique study identifier
  • series_instance_uid (str) – unique series identifier
  • sop_instance_uid (str) – unique instance identifier
  • media_types (Tuple[Union[str, Tuple[str, str]]], optional) – acceptable media types and optionally the UIDs of the corresponding transfer syntaxes
Returns:

data set

Return type:

pydicom.dataset.Dataset

retrieve_instance_frames(study_instance_uid, series_instance_uid, sop_instance_uid, frame_numbers, media_types=None)

Retrieves one or more frames of an individual DICOM instance.

Parameters:
  • study_instance_uid (str) – unique study identifier
  • series_instance_uid (str) – unique series identifier
  • sop_instance_uid (str) – unique instance identifier
  • frame_numbers (List[int]) – one-based positional indices of the frames within the instance
  • media_types (Tuple[Union[str, Tuple[str, str]]], optional) – acceptable media types and optionally the UIDs of the corresponding transfer syntaxes
Returns:

pixel data for each frame

Return type:

List[bytes]

retrieve_instance_frames_rendered(study_instance_uid, series_instance_uid, sop_instance_uid, frame_number, media_types=None, params=None)

Retrieves one or more server-side rendered frames of an individual DICOM instance.

Parameters:
  • study_instance_uid (str) – unique study identifier
  • series_instance_uid (str) – unique series identifier
  • sop_instance_uid (str) – unique instance identifier
  • frame_number (int) – one-based positional index of the frame within the instance
  • media_types (Tuple[Union[str, Tuple[str]]], optional) – acceptable media type (choices: "image/jpeg", "image/jp2", "image/gif", "image/png")
  • params (Dict[str], optional) – additional parameters relevant for given media_type, e.g., {"quality": 95} for "image/jpeg" media type
Returns:

rendered frames

Return type:

bytes

Note

Not all media types are compatible with all SOP classes.

retrieve_instance_metadata(study_instance_uid, series_instance_uid, sop_instance_uid)

Retrieves metadata of an individual DICOM instance.

Parameters:
  • study_instance_uid (str) – unique study identifier
  • series_instance_uid (str) – unique series identifier
  • sop_instance_uid (str) – unique instance identifier
Returns:

metadata in DICOM JSON format

Return type:

Dict[str, dict]

retrieve_instance_rendered(study_instance_uid, series_instance_uid, sop_instance_uid, media_types=None, params=None)

Retrieves an individual, server-side rendered DICOM instance.

Parameters:
  • study_instance_uid (str) – unique study identifier
  • series_instance_uid (str) – unique series identifier
  • sop_instance_uid (str) – unique instance identifier
  • media_types (Tuple[union[str, Tuple[str]]], optional) – acceptable media types (choices: "image/jpeg", "image/jp2", "image/gif", "image/png", "video/gif", "video/mp4", "video/h265", "text/html", "text/plain", "text/xml", "text/rtf", "application/pdf")
  • params (Dict[str], optional) – additional parameters relevant for given media_type, e.g., {"quality": 95} for "image/jpeg"
Returns:

rendered instance

Return type:

bytes

retrieve_series(study_instance_uid, series_instance_uid, media_types=None)

Retrieves instances of a given DICOM series.

Parameters:
  • study_instance_uid (str) – unique study identifier
  • series_instance_uid (str) – unique series identifier
  • media_types (Tuple[Union[str, Tuple[str, str]]], optional) – acceptable media types and optionally the UIDs of the corresponding transfer syntaxes
Returns:

data sets

Return type:

List[pydicom.dataset.Dataset]

retrieve_series_metadata(study_instance_uid, series_instance_uid)

Retrieves metadata for instances of a given DICOM series.

Parameters:
  • study_instance_uid (str) – unique study identifier
  • series_instance_uid (str) – unique series identifier
Returns:

metadata in DICOM JSON format

Return type:

Dict[str, dict]

retrieve_series_rendered(study_instance_uid, series_instance_uid, media_types=None, params=None)

Retrieves an individual, server-side rendered DICOM series.

Parameters:
  • study_instance_uid (str) – unique study identifier
  • series_instance_uid (str) – unique series identifier
  • media_types (Tuple[Union[str, Tuple[str]]], optional) – acceptable media types (choices: "image/jpeg", "image/jp2", "image/gif", "image/png", "video/gif", "video/mp4", "video/h265", "text/html", "text/plain", "text/xml", "text/rtf", "application/pdf")
  • params (Dict[str], optional) – additional parameters relevant for given media_type, e.g., {"quality": 95} for "image/jpeg"
Returns:

rendered series

Return type:

bytes

retrieve_study(study_instance_uid, media_types=None)

Retrieves instances of a given DICOM study.

Parameters:
  • study_instance_uid (str) – unique study identifier
  • media_types (Tuple[Union[str, Tuple[str, str]]], optional) – acceptable media types and optionally the UIDs of the corresponding transfer syntaxes
Returns:

data sets

Return type:

List[pydicom.dataset.Dataset]

retrieve_study_metadata(study_instance_uid)

Retrieves metadata of instances of a given DICOM study.

Parameters:study_instance_uid (str) – unique study identifier
Returns:metadata in DICOM JSON format
Return type:Dict[str, dict]
search_for_instances(study_instance_uid=None, series_instance_uid=None, fuzzymatching=None, limit=None, offset=None, fields=None, search_filters=None)

Searches for DICOM instances.

Parameters:
  • study_instance_uid (str, optional) – unique study identifier
  • series_instance_uid (str, optional) – unique series identifier
  • fuzzymatching (bool, optional) – whether fuzzy semantic matching should be performed
  • limit (int, optional) – maximum number of results that should be returned
  • offset (int, optional) – number of results that should be skipped
  • fields (Union[list, tuple, set], optional) – names of fields (attributes) that should be included in results
  • search_filters (Dict[str, Union[str, int, float]], optional) – search filter criteria as key-value pairs, where key is a keyword or a tag of the attribute and value is the expected value that should match
Returns:

instance representations (see Instance Result Attributes)

Return type:

List[Dict[str, dict]]

Note

The server may only return a subset of search results. In this case, a warning will notify the client that there are remaining results. Remaining results can be requested via repeated calls using the offset parameter.

search_for_series(study_instance_uid=None, fuzzymatching=None, limit=None, offset=None, fields=None, search_filters=None)

Searches for DICOM series.

Parameters:
  • study_instance_uid (str, optional) – unique study identifier
  • fuzzymatching (bool, optional) – whether fuzzy semantic matching should be performed
  • limit (int, optional) – maximum number of results that should be returned
  • offset (int, optional) – number of results that should be skipped
  • fields (Union[list, tuple, set], optional) – names of fields (attributes) that should be included in results
  • search_filters (Dict[str, Union[str, int, float]], optional) – search filter criteria as key-value pairs, where key is a keyword or a tag of the attribute and value is the expected value that should match
Returns:

series representations (see Series Result Attributes)

Return type:

List[Dict[str, dict]]

Note

The server may only return a subset of search results. In this case, a warning will notify the client that there are remaining results. Remaining results can be requested via repeated calls using the offset parameter.

search_for_studies(fuzzymatching=None, limit=None, offset=None, fields=None, search_filters=None)

Searches for DICOM studies.

Parameters:
  • fuzzymatching (bool, optional) – whether fuzzy semantic matching should be performed
  • limit (int, optional) – maximum number of results that should be returned
  • offset (int, optional) – number of results that should be skipped
  • fields (List[str], optional) – names of fields (attributes) that should be included in results
  • search_filters (dict, optional) – search filter criteria as key-value pairs, where key is a keyword or a tag of the attribute and value is the expected value that should match
Returns:

study representations (see Study Result Attributes)

Return type:

List[Dict[str, dict]]

Note

The server may only return a subset of search results. In this case, a warning will notify the client that there are remaining results. Remaining results can be requested via repeated calls using the offset parameter.

store_instances(datasets, study_instance_uid=None)

Stores DICOM instances.

Parameters:
  • datasets (List[pydicom.dataset.Dataset]) – instances that should be stored
  • study_instance_uid (str, optional) – unique study identifier
dicomweb_client.api.load_json_dataset(dataset)

Loads DICOM Data Set in DICOM JSON format.

Parameters:dataset (Dict[str, dict]) – mapping where keys are DICOM Tags and values are mappings of DICOM VR and Value key-value pairs
Returns:
Return type:pydicom.dataset.Dataset

dicomweb_client.cli module

Command Line Interface (CLI)

dicomweb_client.cli.main()

Main entry point for the dicomweb_client command line program.

dicomweb_client

Client for DICOMweb RESTful services.

usage: dicomweb_client [-h] [-v] [-u NAME] [-p PASSWORD] [--ca CERT-FILE]
                       [--cert CERT-FILE] [--url URL]
                       {search,retrieve,store} ...
-h, --help

show this help message and exit

-v, --verbosity

logging verbosity that maps to a logging level (default: error, -v: warning, -vv: info, -vvv: debug, -vvvv: debug + traceback); all log messages are written to standard error

-u <name>, --user <name>

username for authentication with the DICOMweb service

-p <password>, --password <password>

password for authentication with the DICOMweb service

--ca <cert-file>

path to a CA bundle file

--cert <cert-file>

path to a client certificate file in PEM format

--url <url>

uniform resource locator of the DICOMweb service

dicomweb_client retrieve

WADO-RS: Web Access to DICOM Objects by RESTful Services.

usage: dicomweb_client retrieve [-h] INFORMATION ENTITIES ...
-h, --help

show this help message and exit

dicomweb_client retrieve bulkdata

Retrieve bulk data of a DICOM object from a known location.

usage: dicomweb_client retrieve bulkdata [-h]
                                         [--media-type MEDIATYPE [MEDIATYPE ...]]
                                         --uri URI
-h, --help

show this help message and exit

--media-type <mediatype>

acceptable media type and the optionally the UID of a corresponding tranfer syntax separted by a whitespace(e.g., “image/jpeg” or “image/jpeg 1.2.840.10008.1.2.4.50”)

--uri <uri>

unique resource identifier of bulk data element

dicomweb_client retrieve instances

Retrieve data for an individual DICOM instance.

usage: dicomweb_client retrieve instances [-h] --study UID --series UID
                                          --instance UID
                                          {metadata,full,frames} ...
-h, --help

show this help message and exit

--study <uid>

unique study identifier (StudyInstanceUID)

--series <uid>

unique series identifier (SeriesInstanceUID)

--instance <uid>

unique instance identifier (SOPInstanceUID)

dicomweb_client retrieve instances frames

Retrieve one or more frames of the pixel data element of an invidividual DICOM instance.

usage: dicomweb_client retrieve instances frames [-h] [--save]
                                                 [--output-dir PATH]
                                                 [--media-type MEDIATYPE [MEDIATYPE ...]]
                                                 [--numbers NUM [NUM ...]]
                                                 [--show]
-h, --help

show this help message and exit

--save

whether downloaded data should be saved

--output-dir <path>

path to directory where downloaded data should be saved

--media-type <mediatype>

acceptable media type and the optionally the UID of a corresponding tranfer syntax separted by a whitespace(e.g., “image/jpeg” or “image/jpeg 1.2.840.10008.1.2.4.50”)

--numbers <num>

frame numbers

--show

display retrieved images

dicomweb_client retrieve instances full

Retrieve a DICOM instance.

usage: dicomweb_client retrieve instances full [-h] [--save]
                                               [--output-dir PATH]
                                               [--media-type MEDIATYPE [MEDIATYPE ...]]
-h, --help

show this help message and exit

--save

whether downloaded data should be saved

--output-dir <path>

path to directory where downloaded data should be saved

--media-type <mediatype>

acceptable media type and the optionally the UID of a corresponding tranfer syntax separted by a whitespace(e.g., “image/jpeg” or “image/jpeg 1.2.840.10008.1.2.4.50”)

dicomweb_client retrieve instances metadata

Retrieve metadata of an invidividual DICOM instance.

usage: dicomweb_client retrieve instances metadata [-h]
                                                   [--prettify | --dicomize]
                                                   [--save]
                                                   [--output-dir PATH]
-h, --help

show this help message and exit

--prettify

pretty print JSON response message

--dicomize

convert JSON response message to DICOM data set

--save

whether downloaded data should be saved

--output-dir <path>

path to directory where downloaded data should be saved

dicomweb_client retrieve series

Retrieve data for all DICOM instances of a given DICOM series.

usage: dicomweb_client retrieve series [-h] --study UID --series UID
                                       {metadata,full} ...
-h, --help

show this help message and exit

--study <uid>

unique study identifier (StudyInstanceUID)

--series <uid>

unique series identifier (SeriesInstanceUID)

dicomweb_client retrieve series full

Retrieve DICOM instances of a given DICOM series.

usage: dicomweb_client retrieve series full [-h] [--save] [--output-dir PATH]
                                            [--media-type MEDIATYPE [MEDIATYPE ...]]
-h, --help

show this help message and exit

--save

whether downloaded data should be saved

--output-dir <path>

path to directory where downloaded data should be saved

--media-type <mediatype>

acceptable media type and the optionally the UID of a corresponding tranfer syntax separted by a whitespace(e.g., “image/jpeg” or “image/jpeg 1.2.840.10008.1.2.4.50”)

dicomweb_client retrieve series metadata

Retrieve metadata of DICOM instances of a given DICOM series.

usage: dicomweb_client retrieve series metadata [-h] [--prettify | --dicomize]
                                                [--save] [--output-dir PATH]
-h, --help

show this help message and exit

--prettify

pretty print JSON response message

--dicomize

convert JSON response message to DICOM data set

--save

whether downloaded data should be saved

--output-dir <path>

path to directory where downloaded data should be saved

dicomweb_client retrieve studies

Retrieve data for all DICOM instances of a given DICOM study.

usage: dicomweb_client retrieve studies [-h] --study UID {metadata,full} ...
-h, --help

show this help message and exit

--study <uid>

unique study identifier (StudyInstanceUID)

dicomweb_client retrieve studies full

Retrieve DICOM instances of a given DICOM study.

usage: dicomweb_client retrieve studies full [-h] [--save] [--output-dir PATH]
                                             [--media-type MEDIATYPE [MEDIATYPE ...]]
-h, --help

show this help message and exit

--save

whether downloaded data should be saved

--output-dir <path>

path to directory where downloaded data should be saved

--media-type <mediatype>

acceptable media type and the optionally the UID of a corresponding tranfer syntax separted by a whitespace(e.g., “image/jpeg” or “image/jpeg 1.2.840.10008.1.2.4.50”)

dicomweb_client retrieve studies metadata

Retrieve metadata of DICOM instances of a given DICOM study.

usage: dicomweb_client retrieve studies metadata [-h]
                                                 [--prettify | --dicomize]
                                                 [--save] [--output-dir PATH]
-h, --help

show this help message and exit

--prettify

pretty print JSON response message

--dicomize

convert JSON response message to DICOM data set

--save

whether downloaded data should be saved

--output-dir <path>

path to directory where downloaded data should be saved

dicomweb_client search instances

Search for DICOM instances.

usage: dicomweb_client search instances [-h] [--prettify | --dicomize]
                                        [--filter KEY=VALUE] [--field NAME]
                                        [--limit NUM] [--offset NUM] [--fuzzy]
                                        [--study UID] [--series UID]
-h, --help

show this help message and exit

--prettify

pretty print JSON response message

--dicomize

convert JSON response message to DICOM data set

--filter <key=value>

query filter criterion

--field <name>

field that should be included in response

--limit <num>

number of items that should be maximally retrieved

--offset <num>

number of items that should be skipped

--fuzzy

perform fuzzy matching

--study <uid>

unique study identifer (StudyInstanceUID)

--series <uid>

unique series identifier (SeriesInstanceUID)

dicomweb_client search series

Search for DICOM series.

usage: dicomweb_client search series [-h] [--filter KEY=VALUE] [--field NAME]
                                     [--limit NUM] [--offset NUM] [--fuzzy]
                                     [--prettify | --dicomize] [--study UID]
-h, --help

show this help message and exit

--filter <key=value>

query filter criterion

--field <name>

field that should be included in response

--limit <num>

number of items that should be maximally retrieved

--offset <num>

number of items that should be skipped

--fuzzy

perform fuzzy matching

--prettify

pretty print JSON response message

--dicomize

convert JSON response message to DICOM data set

--study <uid>

unique study identifer (StudyInstanceUID)

dicomweb_client search studies

Search for DICOM studies.

usage: dicomweb_client search studies [-h] [--filter KEY=VALUE] [--field NAME]
                                      [--limit NUM] [--offset NUM] [--fuzzy]
                                      [--prettify | --dicomize]
-h, --help

show this help message and exit

--filter <key=value>

query filter criterion

--field <name>

field that should be included in response

--limit <num>

number of items that should be maximally retrieved

--offset <num>

number of items that should be skipped

--fuzzy

perform fuzzy matching

--prettify

pretty print JSON response message

--dicomize

convert JSON response message to DICOM data set

dicomweb_client store

STOW-RS: Store Over the Web by RESTful Services.

usage: dicomweb_client store [-h] INFORMATION ENTITIES ...
-h, --help

show this help message and exit

dicomweb_client store instances

Store DICOM instances.

usage: dicomweb_client store instances [-h] [--study UID] PATH [PATH ...]
path

paths to DICOM files that should be loaded

-h, --help

show this help message and exit

--study <uid>

unique study identifer (StudyInstanceUID)

dicomweb_client.error module

Custom error classes

exception dicomweb_client.error.DICOMJSONError

Bases: ValueError

Exception class for malformatted DICOM JSON.

exception dicomweb_client.error.HTTPError(*args, **kwargs)

Bases: requests.exceptions.HTTPError

Exception class for HTTP requests with failure status codes.

dicomweb_client.log module

Utility functions for logging configuration

dicomweb_client.log.configure_logging(verbosity)

Configures the root logger with a “stderr” stream handler that directs logging messages to standard error (to allow capturing program standard output, e.g. in order to redirect it to a file).

Logging verbosity maps to levels as follows:

0 -> no messages
1 -> CRITICAL, ERROR & WARN/WARNING messages
2 -> CRITICAL, ERROR, WARN/WARNING, & INFO messages
3 -> CRITICAL, ERROR, WARN/WARNING, INFO & DEBUG messages
4 -> all messages
Parameters:verbosity (int) – logging verbosity
Returns:package root logger
Return type:logging.Logger