API documentation

dicomweb_client package

dicomweb_client.api module

Application Programming Interface (API)

class dicomweb_client.api.DICOMClient(*args, **kwargs)

Bases: Protocol

Protocol for DICOM clients based on DICOMweb interface.

base_url: str

delete_instance(study_instance_uid, series_instance_uid, sop_instance_uid)

Delete specified instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID

Returns

HTTP response object returned.

Return type

requests.models.Response

Note

The Delete Instance resource is not part of the DICOM standard and may not be supported by all origin servers.

delete_series(study_instance_uid, series_instance_uid)

Delete all instances of a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID

Returns

HTTP response object returned.

Return type

requests.models.Response

Note

The Delete Series resource is not part of the DICOM standard and may not be supported by all origin servers.

delete_study(study_instance_uid)

Delete all instances of a study.

Parameters: study_instance_uid (str) – Study Instance UID
Returns: HTTP response object returned.
Return type: requests.models.Response

Note

The Delete Study resource is not part of the DICOM standard and may not be supported by all origin servers.

delete_url_prefix: Optional[str] = None

iter_bulkdata(url, media_types=None, byte_range=None)

Iterate over bulk data items at a given location.

Parameters

url (str) – Location of the bulk data
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes
byte_range (Union[Tuple[int, int], None], optional) – Start and end of byte range

Returns

Bulk data items

Return type

Iterator[bytes]

iter_instance_frames(study_instance_uid, series_instance_uid, sop_instance_uid, frame_numbers, media_types=None)

Iterate over frames of an image instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
frame_numbers (Sequence[int]) – One-based positional indices of the frames within the instance
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes

Returns

Pixel data for each frame

Return type

Iterator[bytes]

iter_series(study_instance_uid, series_instance_uid, media_types=None)

Iterate over all instances of a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the acceptable transfer syntaxes

Returns

Instances

Return type

Iterator[pydicom.dataset.Dataset]

Note

Instances are by default retrieved using Implicit VR Little Endian transfer syntax (Transfer Syntax UID "1.2.840.10008.1.2"). This means that Pixel Data of Image instances will be retrieved uncompressed. To retrieve instances in any available transfer syntax (typically the one in which instances were originally stored), specify acceptable transfer syntaxes using the wildcard ("application/dicom", "*").

iter_study(study_instance_uid, media_types=None)

Iterate over all instances of a study.

Parameters

study_instance_uid (str) – Study Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the acceptable transfer syntaxes

Returns

Instances

Return type

Iterator[pydicom.dataset.Dataset]

Note

Instances are by default retrieved using Implicit VR Little Endian transfer syntax (Transfer Syntax UID "1.2.840.10008.1.2"). This means that Pixel Data of Image instances will be retrieved uncompressed. To retrieve instances in any available transfer syntax (typically the one in which instances were originally stored), specify acceptable transfer syntaxes using the wildcard ("application/dicom", "*").

protocol: Optional[str]

qido_url_prefix: Optional[str] = None

retrieve_bulkdata(url, media_types=None, byte_range=None)

Retrieve bulk data at a given location.

Parameters

url (str) – Location of the bulk data
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes
byte_range (Union[Tuple[int, int], None], 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)

Retrieve an individual instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the acceptable transfer syntaxes

Returns

Instance

Return type

pydicom.dataset.Dataset

Note

Instances are by default retrieved using Implicit VR Little Endian transfer syntax (Transfer Syntax UID "1.2.840.10008.1.2"). This means that Pixel Data of Image instances will be retrieved uncompressed. To retrieve instances in any available transfer syntax (typically the one in which instances were originally stored), specify acceptable transfer syntaxes using the wildcard ("application/dicom", "*").

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

Retrieve one or more frames of an image instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
frame_numbers (Sequence[int]) – One-based positional indices of the frames within the instance
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], 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_numbers, media_types=None, params=None)

Retrieve one or more server-side rendered frames of an instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
frame_numbers (Sequence[int]) – One-based positional index of the frame within the instance
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media type (choices: "image/jpeg", "image/jp2", "image/gif", "image/png")
params (Union[Dict[str, Any], None], optional) – Additional parameters relevant for given media_type, e.g., {"quality": 95} for "image/jpeg" media type

Returns

Rendered representation of 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)

Retrieve metadata of an individual instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID

Returns

Metadata of instance 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)

Retrieve an individual, server-side rendered instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], 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 (Union[Dict[str, Any], None], optional) – Additional parameters relevant for given media_type, e.g., {"quality": 95} for "image/jpeg"

Returns

Rendered representation of instance

Return type

bytes

retrieve_series(study_instance_uid, series_instance_uid, media_types=None)

Retrieve all instances of a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the acceptable transfer syntaxes

Returns

Instances

Return type

List[pydicom.dataset.Dataset]

Note

Instances are by default retrieved using Implicit VR Little Endian transfer syntax (Transfer Syntax UID "1.2.840.10008.1.2"). This means that Pixel Data of Image instances will be retrieved uncompressed. To retrieve instances in any available transfer syntax (typically the one in which instances were originally stored), specify acceptable transfer syntaxes using the wildcard ("application/dicom", "*").

retrieve_series_metadata(study_instance_uid, series_instance_uid)

Retrieve metadata for all instances of a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID

Returns

Metadata of instances in DICOM JSON format

Return type

Dict[str, dict]

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

Retrieve rendered representation of a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], 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 (Union[Dict[str, Any], None], optional) – Additional parameters relevant for given media_type, e.g., {"quality": 95} for "image/jpeg"

Returns

Rendered representation of series

Return type

bytes

retrieve_study(study_instance_uid, media_types=None)

Retrieve all instances of a study.

Parameters

study_instance_uid (str) – Study Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the acceptable transfer syntaxes

Returns

Instances

Return type

List[pydicom.dataset.Dataset]

Note

Instances are by default retrieved using Implicit VR Little Endian transfer syntax (Transfer Syntax UID "1.2.840.10008.1.2"). This means that Pixel Data of Image instances will be retrieved uncompressed. To retrieve instances in any available transfer syntax (typically the one in which instances were originally stored), specify acceptable transfer syntaxes using the wildcard ("application/dicom", "*").

retrieve_study_metadata(study_instance_uid)

Retrieve metadata of all instances of a study.

Parameters: study_instance_uid (str) – Study Instance UID
Returns: Metadata of instances in DICOM JSON format
Return type: List[Dict[str, dict]]

scheme: str

search_for_instances(study_instance_uid=None, series_instance_uid=None, fuzzymatching=None, limit=None, offset=None, fields=None, search_filters=None, get_remaining=False)

Search for instances.

Parameters

study_instance_uid (Union[str, None], optional) – Study Instance UID
series_instance_uid (Union[str, None], optional) – Series Instance UID
fuzzymatching (Union[bool, None], optional) – Whether fuzzy semantic matching should be performed
limit (Union[int, None], optional) – Maximum number of results that should be returned
offset (Union[int, None], optional) – Number of results that should be skipped
fields (Union[Union[list, tuple, set], None], optional) – Names of fields (attributes) that should be included in results
search_filters (Union[Dict[str, Union[str, int, float]], None], 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
get_remaining (bool, optional) – Whether remaining results should be included (this may repeatedly query the server for remaining results)

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, get_remaining=False)

Search for series.

Parameters

study_instance_uid (Union[str, None], optional) – Study Instance UID
fuzzymatching (Union[bool, None], optional) – Whether fuzzy semantic matching should be performed
limit (Union[int, None], optional) – Maximum number of results that should be returned
offset (Union[int, None], optional) – Number of results that should be skipped
fields (Union[Union[list, tuple, set], None], optional) – Names of fields (attributes) that should be included in results
search_filters (Union[Dict[str, Union[str, int, float]], None], 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
get_remaining (bool, optional) – Whether remaining results should be included (this may repeatedly query the server for remaining results)

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, get_remaining=False)

Search for studies.

Parameters

fuzzymatching (Union[bool, None], optional) – Whether fuzzy semantic matching should be performed
limit (Union[int, None], optional) – Maximum number of results that should be returned
offset (Union[int, None], optional) – Number of results that should be skipped
fields (Union[Sequence[str], None], optional) – Names of fields (attributes) that should be included in results
search_filters (Union[dict, None], 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
get_remaining (bool, optional) – Whether remaining results should be included (this may repeatedly query the server for remaining results)

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)

Store instances.

Parameters

datasets (Sequence[pydicom.dataset.Dataset]) – Instances that should be stored
study_instance_uid (Union[str, None], optional) – Study Instance UID

Returns

Information about status of stored instances

Return type

pydicom.dataset.Dataset

stow_url_prefix: Optional[str] = None

url_prefix: str

wado_url_prefix: Optional[str] = None

class dicomweb_client.api.DICOMfileClient(url, update_db=False, recreate_db=False, in_memory=False, db_dir=None, readonly=False)

Bases: object

Client for managing DICOM Part10 files in a DICOMweb-like manner.

Facilitates serverless access to data stored locally on a file system as DICOM Part10 files.

Note

The class internally uses an in-memory database, which is persisted on disk to facilitate faster subsequent data access. However, the implementation details of the database and the structure of any database files stored on the file system may change at any time and should not be relied on.

Note

This is not an implementation of the DICOM File Service and does not depend on the presence of DICOMDIR files.

base_url

Unique resource locator of the DICOMweb service

Type: str

scheme

Name of the scheme (file)

Type: str

protocol

Name of the protocol (None)

Type: str

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, None]

wado_url_prefix

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

Type: Union[str, None]

stow_url_prefix

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

Type: Union[str, None]

delete_url_prefix

URL path prefix for DELETE (not part of base_url)

Type: Union[str, None]

Instantiate client.

Parameters

url (str) – Unique resource locator of directory where data is stored (must have file scheme)
update_db (bool, optional) – Whether the database should be updated (default: False). If True, the client will search base_dir recursively for new DICOM Part10 files and create database entries for each file. The client will further delete any database entries for files that no longer exist on the file system.
recreate_db (bool, optional) – Whether the database should be recreated (default: False). If True, the client will search base_dir recursively for DICOM Part10 files and create database entries for each file.
in_memory (bool, optional) – Whether the database should only be stored in memory (default: False).
db_dir (Union[pathlib.Path, str, None], optional) – Path to directory where database files should be stored (defaults to base_dir)
readonly (bool, optional) – Whether data should be considered read-only. Attempts to store or delete data will be denied.

delete_instance(study_instance_uid, series_instance_uid, sop_instance_uid)

Delete specified instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID

Return type

None

delete_series(study_instance_uid, series_instance_uid)

Delete all instances of a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID

Return type

None

delete_study(study_instance_uid)

Delete all instances of a study.

Parameters: study_instance_uid (str) – Study Instance UID
Return type: None

iter_bulkdata(url, media_types=None, byte_range=None)

Iterate over bulk data items at a given location.

Parameters

url (str) – Location of the bulk data
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes
byte_range (Union[Tuple[int, int], None], optional) – Start and end of byte range

Returns

Bulk data items

Return type

Iterator[bytes]

Raises

IOError – When requested resource is not found at url

iter_instance_frames(study_instance_uid, series_instance_uid, sop_instance_uid, frame_numbers, media_types=None)

Iterate over frames of an image instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
frame_numbers (List[int]) – Frame numbers
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes

Returns

Frames

Return type

Iterator[bytes]

iter_series(study_instance_uid, series_instance_uid, media_types=None)

Iterate over all instances of a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes

Returns

Instances

Return type

Iterator[pydicom.dataset.Dataset]

iter_study(study_instance_uid, media_types=None)

Iterate over all instances of a study.

Parameters

study_instance_uid (str) – Study Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes

Returns

Instances

Return type

Iterator[pydicom.dataset.Dataset]

static lookup_keyword(tag)

Look up the keyword of a DICOM attribute.

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

static lookup_tag(keyword)

Look 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)

Retrieve bulk data at a given location.

Parameters

url (str) – Location of the bulk data
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes
byte_range (Union[Tuple[int, int], None], optional) – Start and end of byte range

Returns

Bulk data items

Return type

Iterator[bytes]

Raises

IOError – When requested resource is not found at url

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

Retrieve metadata of a single instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes

Returns

Instance

Return type

pydicom.dataset.Dataset

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

Retrieve one or more frames of an image instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
frame_numbers (List[int]) – Frame numbers
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes

Returns

Frames

Return type

List[bytes]

retrieve_instance_frames_rendered(study_instance_uid, series_instance_uid, sop_instance_uid, frame_numbers, media_types=None, params=None)

Retrieve server-side rendered frames of an image instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
frame_numbers (List[int]) – Frame numbers
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes
params (Union[Dict[str, str], None], optional) – Additional query parameters

Returns

Rendered representation of frames

Return type

bytes

retrieve_instance_metadata(study_instance_uid, series_instance_uid, sop_instance_uid)

Retrieve metadata of a single instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID

Returns

Metadata of instance

Return type

Dict[str, Any]

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

Retrieve an individual, server-side rendered instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], 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 (Union[Dict[str, Any], None], optional) – Additional parameters relevant for given media_type, e.g., {"quality": 95} for "image/jpeg"

Returns

Rendered representation of instance

Return type

bytes

Note

Only rendering of single-frame image instances is currently supported.

retrieve_series(study_instance_uid, series_instance_uid, media_types=None)

Retrieve all instances of a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes

Returns

Instances

Return type

Sequence[pydicom.dataset.Dataset]

retrieve_series_metadata(study_instance_uid, series_instance_uid)

Retrieve metadata of instances in a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID

Returns

Metadata of each instance in series

Return type

List[Dict[str, Any]]

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

Retrieve rendered representation of a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], 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 (Union[Dict[str, Any], None], optional) – Additional parameters relevant for given media_type, e.g., {"quality": 95} for "image/jpeg"

Returns

Rendered representation of series

Return type

bytes

retrieve_study(study_instance_uid, media_types=None)

Retrieve all instances of a study.

Parameters

study_instance_uid (str) – Study Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes

Returns

Instances

Return type

Sequence[pydicom.dataset.Dataset]

retrieve_study_metadata(study_instance_uid)

Retrieve metadata of instances in a study.

Parameters: study_instance_uid (str) – Study Instance UID
Returns: Metadata of each instance in study
Return type: List[Dict[str, Any]]

search_for_instances(study_instance_uid=None, series_instance_uid=None, fuzzymatching=None, limit=None, offset=None, fields=None, search_filters=None, get_remaining=False)

Search for instances.

Parameters

study_instance_uid (Union[str, None], optional) – Study Instance UID
series_instance_uid (Union[str, None], optional) – Series Instance UID
fuzzymatching (Union[bool, None], optional) – Whether fuzzy semantic matching should be performed
limit (Union[int, None], optional) – Maximum number of results that should be returned
offset (Union[int, None], optional) – Number of results that should be skipped
fields (Union[Sequence[str], None], optional) – Names of fields (attributes) that should be included in results
search_filters (Union[dict, None], 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
get_remaining (bool, optional) – Whether remaining results should be included

Returns

Instances (see Instance Result Attributes)

Return type

List[Dict[str, dict]]

Note

No additional fields are currently supported.

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

Search for series.

Parameters

study_instance_uid (Union[str, None], optional) – Study Instance UID
fuzzymatching (Union[bool, None], optional) – Whether fuzzy semantic matching should be performed
limit (Union[int, None], optional) – Maximum number of results that should be returned
offset (Union[int, None], optional) – Number of results that should be skipped
fields (Union[Sequence[str], None], optional) – Names of fields (attributes) that should be included in results
search_filters (Union[dict, None], 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
get_remaining (bool, optional) – Whether remaining results should be included

Returns

Series (see Series Result Attributes)

Return type

List[Dict[str, dict]]

search_for_studies(fuzzymatching=None, limit=None, offset=None, fields=None, search_filters=None, get_remaining=False)

Search for studies.

Parameters

fuzzymatching (Union[bool, None], optional) – Whether fuzzy semantic matching should be performed
limit (Union[int, None], optional) – Maximum number of results that should be returned
offset (Union[int, None], optional) – Number of results that should be skipped
fields (Union[Sequence[str], None], optional) – Names of fields (attributes) that should be included in results
search_filters (Union[dict, None], 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
get_remaining (bool, optional) – Whether remaining results should be included

Returns

Studies (see Study Result Attributes)

Return type

List[Dict[str, dict]]

Note

No additional fields are currently supported.

store_instances(datasets, study_instance_uid=None)

Store instances.

Parameters

datasets (Sequence[pydicom.dataset.Dataset]) – Instances that should be stored
study_instance_uid (Union[str, None], optional) – Study Instance UID

Returns

Information about status of stored instances

Return type

pydicom.dataset.Dataset

class dicomweb_client.api.DICOMwebClient(url, session=None, qido_url_prefix=None, wado_url_prefix=None, stow_url_prefix=None, delete_url_prefix=None, proxies=None, headers=None, callback=None, chunk_size=1000000)

Bases: object

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

base_url

Unique resource locator of the DICOMweb service

Type: str

scheme

Name of the scheme, e.g. "https"

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, None]

wado_url_prefix

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

Type: Union[str, None]

stow_url_prefix

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

Type: Union[str, None]

delete_url_prefix

URL path prefix for DELETE (not part of base_url)

Type: Union[str, None]

Instatiate client.

Parameters

url (str) – Unique resource locator of the DICOMweb service consisting of protocol, hostname (IP address or DNS name) of the machine that hosts the service and optionally port number and path prefix
session (Union[requests.Session, None], optional) – Session required to make connections to the DICOMweb service (see dicomweb_client.session_utils module to create a valid session if necessary)
qido_url_prefix (Union[str, None], optional) – URL path prefix for QIDO RESTful services
wado_url_prefix (Union[str, None], optional) – URL path prefix for WADO RESTful services
stow_url_prefix (Union[str, None], optional) – URL path prefix for STOW RESTful services
delete_url_prefix (Union[str, None], optional) – URL path prefix for DELETE RESTful services
proxies (Union[Dict[str, str], None], optional) – Mapping of protocol or protocol + host to the URL of a proxy server
headers (Union[Dict[str, str], None], optional) – Custom headers that should be included in request messages, e.g., authentication tokens
callback (Union[Callable[[requests.Response, ...], requests.Response], None], optional) – Callback function to manipulate responses generated from requests (see requests event hooks)
chunk_size (int, optional) – Maximum number of bytes that should be transferred per data chunk when streaming data from the server using chunked transfer encoding (used by iter_*() methods as well as the store_instances() method); defaults to 10**6 bytes (1MB)

Warning

Modifies the passed session (in particular header fields), so be careful when reusing the session outside the scope of an instance.

Warning

Choose the value of chunk_size carefully. A small value may cause significant network communication and message parsing overhead.

delete_instance(study_instance_uid, series_instance_uid, sop_instance_uid)

Delete specified instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID

Note

The Delete Instance resource is not part of the DICOM standard and may not be supported by all origin servers.

Warning

This method performs a DELETE and should be used with caution.

Return type: None

delete_series(study_instance_uid, series_instance_uid)

Delete all instances of a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID

Note

The Delete Series resource is not part of the DICOM standard and may not be supported by all origin servers.

Warning

This method performs a DELETE and should be used with caution.

Return type: None

delete_study(study_instance_uid)

Delete all instances of a study.

Parameters: study_instance_uid (str) – Study Instance UID

Note

The Delete Study resource is not part of the DICOM standard and may not be supported by all origin servers.

Warning

This method performs a DELETE and should be used with caution.

Return type: None

iter_bulkdata(url, media_types=None, byte_range=None)

Iterate over bulk data items at a given location.

Parameters

url (str) – Location of the bulk data
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes
byte_range (Union[Tuple[int, int], None], optional) – Start and end of byte range

Returns

Bulk data items

Return type

Iterator[bytes]

Note

Data is streamed from the DICOMweb server.

iter_instance_frames(study_instance_uid, series_instance_uid, sop_instance_uid, frame_numbers, media_types=None)

Iterate over frames of an image instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
frame_numbers (Sequence[int]) – One-based positional indices of the frames within the instance
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes

Returns

Pixel data for each frame

Return type

Iterator[bytes]

Note

Data is streamed from the DICOMweb server.

iter_series(study_instance_uid, series_instance_uid, media_types=None)

Iterate over all instances of a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the acceptable transfer syntaxes

Returns

Instances

Return type

Iterator[pydicom.dataset.Dataset]

Note

Instances are by default retrieved using Implicit VR Little Endian transfer syntax (Transfer Syntax UID "1.2.840.10008.1.2"). This means that Pixel Data of Image instances will be retrieved uncompressed. To retrieve instances in any available transfer syntax (typically the one in which instances were originally stored), specify acceptable transfer syntaxes using the wildcard ("application/dicom", "*").

Note

Data is streamed from the DICOMweb server.

iter_study(study_instance_uid, media_types=None)

Iterate over all instances of a study.

Parameters

study_instance_uid (str) – Study Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the acceptable transfer syntaxes

Returns

Instances

Return type

Iterator[pydicom.dataset.Dataset]

Note

Instances are by default retrieved using Implicit VR Little Endian transfer syntax (Transfer Syntax UID "1.2.840.10008.1.2"). This means that Pixel Data of Image instances will be retrieved uncompressed. To retrieve instances in any available transfer syntax (typically the one in which instances were originally stored), specify acceptable transfer syntaxes using the wildcard ("application/dicom", "*").

Note

Data is streamed from the DICOMweb server.

static lookup_keyword(tag)

Look up the keyword of a DICOM attribute.

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

static lookup_tag(keyword)

Look 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)

Retrieve bulk data at a given location.

Parameters

url (str) – Location of the bulk data
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the corresponding transfer syntaxes
byte_range (Union[Tuple[int, int], None], optional) – Start and end of byte range

Returns

Bulk data items

Return type

Iterator[bytes]

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

Retrieve an individual instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the acceptable transfer syntaxes

Returns

Instance

Return type

pydicom.dataset.Dataset

Note

Instances are by default retrieved using Implicit VR Little Endian transfer syntax (Transfer Syntax UID "1.2.840.10008.1.2"). This means that Pixel Data of Image instances will be retrieved uncompressed. To retrieve instances in any available transfer syntax (typically the one in which instances were originally stored), specify acceptable transfer syntaxes using the wildcard ("application/dicom", "*").

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

Retrieve one or more frames of an image instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
frame_numbers (Sequence[int]) – One-based positional indices of the frames within the instance
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], 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_numbers, media_types=None, params=None)

Retrieve one or more server-side rendered frames of an instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
frame_numbers (Sequence[int]) – One-based positional index of the frame within the instance
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media type (choices: "image/jpeg", "image/jp2", "image/gif", "image/png")
params (Union[Dict[str, Any], None], optional) – Additional parameters relevant for given media_type, e.g., {"quality": 95} for "image/jpeg" media type

Returns

Rendered representation of 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)

Retrieve metadata of an individual instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID

Returns

Metadata of instance 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)

Retrieve an individual, server-side rendered instance.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
sop_instance_uid (str) – SOP Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], 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 (Union[Dict[str, Any], None], optional) – Additional parameters relevant for given media_type, e.g., {"quality": 95} for "image/jpeg"

Returns

Rendered representation of instance

Return type

bytes

retrieve_series(study_instance_uid, series_instance_uid, media_types=None)

Retrieve all instances of a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the acceptable transfer syntaxes

Returns

Instances

Return type

List[pydicom.dataset.Dataset]

Note

Instances are by default retrieved using Implicit VR Little Endian transfer syntax (Transfer Syntax UID "1.2.840.10008.1.2"). This means that Pixel Data of Image instances will be retrieved uncompressed. To retrieve instances in any available transfer syntax (typically the one in which instances were originally stored), specify acceptable transfer syntaxes using the wildcard ("application/dicom", "*").

retrieve_series_metadata(study_instance_uid, series_instance_uid)

Retrieve metadata for all instances of a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID

Returns

Metadata of instances in DICOM JSON format

Return type

Dict[str, dict]

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

Retrieve rendered representation of a series.

Parameters

study_instance_uid (str) – Study Instance UID
series_instance_uid (str) – Series Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], 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 (Union[Dict[str, Any], None], optional) – Additional parameters relevant for given media_type, e.g., {"quality": 95} for "image/jpeg"

Returns

Rendered representation of series

Return type

bytes

retrieve_study(study_instance_uid, media_types=None)

Retrieve all instances of a study.

Parameters

study_instance_uid (str) – Study Instance UID
media_types (Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional) – Acceptable media types and optionally the UIDs of the acceptable transfer syntaxes

Returns

Instances

Return type

List[pydicom.dataset.Dataset]

Note

Instances are by default retrieved using Implicit VR Little Endian transfer syntax (Transfer Syntax UID "1.2.840.10008.1.2"). This means that Pixel Data of Image instances will be retrieved uncompressed. To retrieve instances in any available transfer syntax (typically the one in which instances were originally stored), specify acceptable transfer syntaxes using the wildcard ("application/dicom", "*").

retrieve_study_metadata(study_instance_uid)

Retrieve metadata of all instances of a study.

Parameters: study_instance_uid (str) – Study Instance UID
Returns: Metadata of instances in DICOM JSON format
Return type: List[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, get_remaining=False)

Search for instances.

Parameters

study_instance_uid (Union[str, None], optional) – Study Instance UID
series_instance_uid (Union[str, None], optional) – Series Instance UID
fuzzymatching (Union[bool, None], optional) – Whether fuzzy semantic matching should be performed
limit (Union[int, None], optional) – Maximum number of results that should be returned
offset (Union[int, None], optional) – Number of results that should be skipped
fields (Union[Union[list, tuple, set], None], optional) – Names of fields (attributes) that should be included in results
search_filters (Union[Dict[str, Union[str, int, float]], None], 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
get_remaining (bool, optional) – Whether remaining results should be included (this may repeatedly query the server for remaining results)

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, get_remaining=False)

Search for series.

Parameters

study_instance_uid (Union[str, None], optional) – Study Instance UID
fuzzymatching (Union[bool, None], optional) – Whether fuzzy semantic matching should be performed
limit (Union[int, None], optional) – Maximum number of results that should be returned
offset (Union[int, None], optional) – Number of results that should be skipped
fields (Union[Union[list, tuple, set], None], optional) – Names of fields (attributes) that should be included in results
search_filters (Union[Dict[str, Union[str, int, float]], None], 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
get_remaining (bool, optional) – Whether remaining results should be included (this may repeatedly query the server for remaining results)

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, get_remaining=False)

Search for studies.

Parameters

fuzzymatching (Union[bool, None], optional) – Whether fuzzy semantic matching should be performed
limit (Union[int, None], optional) – Maximum number of results that should be returned
offset (Union[int, None], optional) – Number of results that should be skipped
fields (Union[Sequence[str], None], optional) – Names of fields (attributes) that should be included in results
search_filters (Union[dict, None], 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
get_remaining (bool, optional) – Whether remaining results should be included (this may repeatedly query the server for remaining results)

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.

set_chunk_size(chunk_size)

Set value of chunk_size attribute.

Parameters: chunk_size (int) – Maximum number of bytes that should be transferred per data chunk when streaming data from the server using chunked transfer encoding (used by iter_*() methods as well as the store_instances() method)
Return type: None

set_http_retry_params(retry=True, max_attempts=5, wait_exponential_multiplier=1000, retriable_error_codes=(<HTTPStatus.TOO_MANY_REQUESTS: 429>, <HTTPStatus.REQUEST_TIMEOUT: 408>, <HTTPStatus.SERVICE_UNAVAILABLE: 503>, <HTTPStatus.GATEWAY_TIMEOUT: 504>))

Set parameters for HTTP retrying logic.

These parameters determine whether and how individual HTTP requests will be retried in case the origin server responds with an error code defined in retriable_error_codes. The retrying method uses exponential back off using the multiplier wait_exponential_multiplier for a max attempts defined by max_attempts.

Parameters

retry (bool, optional) – Whether HTTP retrying should be performed, if it is set to False, the rest of the parameters are ignored.
max_attempts (int, optional) – The maximum number of request attempts.
wait_exponential_multiplier (float, optional) – Exponential multiplier applied to delay between attempts in ms.
retriable_error_codes (tuple, optional) – Tuple of HTTP error codes to retry if raised.

Return type

None

store_instances(datasets, study_instance_uid=None)

Store instances.

Parameters

datasets (Sequence[pydicom.dataset.Dataset]) – Instances that should be stored
study_instance_uid (Union[str, None], optional) – Study Instance UID

Returns

Information about status of stored instances

Return type

pydicom.dataset.Dataset

dicomweb_client.cli module

Command Line Interface (CLI)

dicomweb_client.cli.main(args): 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] [--bearer-token TOKEN] [--url URL]
                       [--chunk-size NUM]
                       {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

--bearer-token <token>: bearer token for authentication with the DICOMweb service

--url <url>: uniform resource locator of the DICOMweb service

--chunk-size <num>: maximum size of a network transfer chunk in bytes

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

QIDO-RS: Query based on ID for DICOM Objects by RESTful Serices.

usage: dicomweb_client search [-h] INFORMATION ENTITIES ...

-h, --help: show this help message and exit

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

-> no messages
-> CRITICAL, ERROR & WARN/WARNING messages
-> CRITICAL, ERROR, WARN/WARNING, & INFO messages
-> CRITICAL, ERROR, WARN/WARNING, INFO & DEBUG messages
-> all messages

Parameters: verbosity (int) – logging verbosity
Returns: package root logger
Return type: logging.Logger

dicomweb_client.session_utils module

dicomweb_client.session_utils.add_certs_to_session(session, ca_bundle=None, cert=None)

Adds CA bundle and certificate to an existing session.

Parameters

session (requests.Session) – input session
ca_bundle (str, optional) – path to CA bundle file
cert (str, optional) – path to client certificate file in Privacy Enhanced Mail (PEM) format

Returns

verified session

Return type

requests.Session

dicomweb_client.session_utils.create_session()

Creates an unauthorized session.

Returns: unauthorized session
Return type: requests.Session

dicomweb_client.session_utils.create_session_from_auth(auth)

Creates a session from a gicen AuthBase object.

Parameters: auth (requests.auth.AuthBase) – an implementation of requests.auth.AuthBase to be used for authentication with services
Returns: authorized session
Return type: requests.Session

dicomweb_client.session_utils.create_session_from_gcp_credentials(google_credentials=None)

Creates an authorized session for Google Cloud Platform.

Parameters: google_credentials (Any) – Google cloud credentials. (see https://cloud.google.com/docs/authentication/production for more information on Google cloud authentication). If not set, will be initialized to google.auth.default()
Returns: Google cloud authorized session
Return type: requests.Session

dicomweb_client.session_utils.create_session_from_user_pass(username, password)

Creates a session from a given username and password.

Parameters

username (str) – username for authentication with services
password (str) – password for authentication with services

Returns

authorized session

Return type

requests.Session

dicomweb_client.uri module

Utilities for DICOMweb URI manipulation.

class dicomweb_client.uri.URI(base_url, study_instance_uid=None, series_instance_uid=None, sop_instance_uid=None, frames=None, suffix=None, permissive=False)

Bases: object

Class to represent a fully qualified HTTP[S] URI to a DICOMweb resource.

http://dicom.nema.org/medical/dicom/current/output/html/part18.html

This is an immutable class. Use URI.update() to create copies of an instance with updated (new) values for its attributes.

Given an HTTP[S] base_url, a valid DICOMweb-compatible URI would be:

<base_url> (no DICOMweb suffix)
<base_url>/studies/<study_instance_uid>
<base_url>/studies/<study_instance_uid>/metadata
<base_url>/studies/<study_instance_uid>/rendered
<base_url>/studies/<study_instance_uid>/thumbnail
<base_url>/studies/<study_instance_uid>/series/<series_instance_uid>
<base_url>/studies/<study_instance_uid>/series/<series_instance_uid>/metadata
<base_url>/studies/<study_instance_uid>/series/<series_instance_uid>/rendered
<base_url>/studies/<study_instance_uid>/series/<series_instance_uid>/thumbnail
<base_url>/studies/<study_instance_uid>/series/<series_instance_uid>/instances/<sop_instance_uid>
<base_url>/studies/<study_instance_uid>/series/<series_instance_uid>/instances/<sop_instance_uid>/metadata
<base_url>/studies/<study_instance_uid>/series/<series_instance_uid>/instances/<sop_instance_uid>/rendered
<base_url>/studies/<study_instance_uid>/series/<series_instance_uid>/instances/<sop_instance_uid>/thumbnail
<base_url>/studies/<study_instance_uid>/series/<series_instance_uid>/instances/<sop_instance_uid>/frames/<frames>
<base_url>/studies/<study_instance_uid>/series/<series_instance_uid>/instances/<sop_instance_uid>/frames/<frames>/rendered
<base_url>/studies/<study_instance_uid>/series/<series_instance_uid>/instances/<sop_instance_uid>/frames/<frames>/thumbnail

Instantiates an object.

As per the DICOM Standard, the Study, Series, and Instance UIDs must be a series of numeric components (0-9) separated by the period . character, with a maximum length of 64 characters. If the permissive flag is set to True, any alpha-numeric or special characters (except for / and @) may be used.

Parameters

base_url (str) – DICOMweb service HTTP[S] URL. Trailing forward slashes are not permitted.
study_instance_uid (str, optional) – DICOM Study Instance UID.
series_instance_uid (str, optional) – DICOM Series Instance UID.
sop_instance_uid (str, optional) – DICOM SOP Instance UID.
frames (Sequence[int], optional) – A non-empty sequence of positive frame numbers in ascending order.
suffix (URISuffix, optional) – Suffix attached to the DICOM resource URI. This could refer to a metadata, rendered, or thumbnail resource.
permissive (bool) – If True, relaxes the DICOM Standard validation for UIDs (see main docstring for details). This option is made available since users may be occasionally forced to work with DICOMs or services that may be in violation of the standard. Unless required, use of this flag is not recommended, since non-conformant UIDs may lead to unexpected errors downstream, e.g., rejection by a DICOMweb server, etc.

Raises

ValueError – In the following cases: - base_url has a trailing slash. - base_url does not use the HTTP[S] addressing scheme. - base_url is incompatible with the DICOMweb standard. - series_instance_uid is supplied without study_instance_uid. - sop_instance_uid is supplied without study_instance_uid or series_instance_uid. - frames is supplied without study_instance_uid, series_instance_uid, or sop_instance_uid. - frames is empty. - A frame number in frames is not positive. - The frame numbers in frames are not in ascending order. - suffix is URISuffix.METADATA with frames or without study_instance_uid. - suffix is URISuffix.RENDERED without study_instance_uid. - suffix is URISuffix.THUMBNAIL without study_instance_uid. - Any one of study_instance_uid, series_instance_uid, or sop_instance_uid does not meet the DICOM Standard UID spec in the docstring.

base_uri()

Returns URI for the DICOM Service within this object.

Return type: dicomweb_client.uri.URI

property base_url: str

Returns the Base (DICOMweb Service) URL.

Return type: str

frame_uri()

Returns URI for the DICOM frames within this object.

Return type: dicomweb_client.uri.URI

property frames: Optional[Tuple[int, ...]]

Returns the sequence of frame numbers, if available.

Return type: typing.Optional[typing.Tuple[int, …]]

classmethod from_string(dicomweb_uri, uri_type=None, permissive=False)

Parses the string to return the URI.

Any valid DICOMweb compatible HTTP[S] URI is permitted, e.g., <SERVICE>/studies/<StudyInstanceUID>/series/<SeriesInstanceUID>.

Parameters

dicomweb_uri (str) – An HTTP[S] DICOMweb-compatible URI.
uri_type (URIType, optional) – The expected DICOM resource type referenced by the object. If set, it validates that the resource-scope of the dicomweb_uri matches the expected type.
permissive (bool) – Set if permissive handling of UIDs (if any) in dicomweb_uri is required. See the class initializer docstring for details.

Returns

The newly constructed URI object.

Return type

URI

Raises

ValueError – If the URI cannot be parsed or the actual URI type doesn’t match the specified expected uri_type.

instance_uri()

Returns URI for the DICOM Instances within this object.

Return type: dicomweb_client.uri.URI

property parent: URI

Returns a URI to the “parent” resource.

Depending on the type of the current URI, the URI of the parent resource is defined as:

Current	Suffixed	Parent
Service	N/A	Service
Study	No	Service
Study	Yes	Study
Series	No	Study
Series	Yes	Series
Instance	No	Series
Instance	Yes	Instance
Frame	No	Instance
Frame	Yes	Frame

Returns: An instance pointing to the parent resource.
Return type: URI

property permissive: bool

Returns the permissive parameter value in the initializer.

Return type: bool

property series_instance_uid: Optional[str]

Returns the Series UID, if available.

Return type: typing.Optional[str]

series_uri()

Returns URI for the DICOM Series within this object.

Return type: dicomweb_client.uri.URI

property sop_instance_uid: Optional[str]

Returns the Instance UID, if available.

Return type: typing.Optional[str]

property study_instance_uid: Optional[str]

Returns the Study UID, if available.

Return type: typing.Optional[str]

study_uri()

Returns URI for the DICOM Study within this object.

Return type: dicomweb_client.uri.URI

property suffix: Optional[URISuffix]

Returns the DICOM resource suffix, if available.

Return type: typing.Optional[dicomweb_client.uri.URISuffix]

property type: URIType

The URIType of DICOM resource referenced by the object.

Return type: dicomweb_client.uri.URIType

update(base_url=None, study_instance_uid=None, series_instance_uid=None, sop_instance_uid=None, frames=None, suffix=None, permissive=False)

Creates a new URI object based on the current one.

Replaces the specified URI components in the current URI to create the new one.

Parameters

base_url (str, optional) – DICOMweb service HTTP[S] URL to use in the new URI or None if the base_url from the current URI should be used.
study_instance_uid (str, optional) – Study Instance UID to use in the new URI or None if the study_instance_uid from the current URI should be used.
series_instance_uid (str, optional) – Series Instance UID to use in the new URI or None if the series_instance_uid from the current URI should be used.
sop_instance_uid (str, optional) – SOP Instance UID to use in the new URI or None if the sop_instance_uid from the current URI should be used.
frames (Sequence[int], optional) – Frame numbers to use in the new URI or None if the frames from the current URI should be used.
suffix (URISuffix, optional) – Suffix to use in the new URI or None if the suffix from the current URI should be used.
permissive (bool, optional) – Set if permissive handling of UIDs (if any) in the updated URI is required. See the class initializer docstring for details.

Returns

The newly constructed URI object.

Return type

URI

Raises

ValueError – If the new URI is invalid (e.g., if only the SOP Instance UID is specified, but the Series Instance UID is missing in the current URI).

class dicomweb_client.uri.URISuffix(value)

Bases: Enum

Optional suffixes for a DICOM resource.

METADATA = 'metadata'

RENDERED = 'rendered'

THUMBNAIL = 'thumbnail'

class dicomweb_client.uri.URIType(value)

Bases: Enum

Type of DICOM resource the URI points to.

FRAME = 'frame'

INSTANCE = 'instance'

SERIES = 'series'

SERVICE = 'service'

STUDY = 'study'

dicomweb_client.uri.build_query_string(params=None)

Build query string for a request message.

Parameters: params (Union[Dict[str, Any], None], optional) – Query parameters as mapping of key-value pairs; in case a key should be included more than once with different values, values need to be provided in form of an iterable (e.g., {"key": ["value1", "value2"]} will result in "?key=value1&key=value2")
Returns: Query string
Return type: str

dicomweb_client.uri.parse_query_parameters(fuzzymatching=None, limit=None, offset=None, fields=None, search_filters=None)

Parse query parameters for inclusion into a query string.

Parameters

fuzzymatching (Union[bool, None], optional) – Whether fuzzy semantic matching should be performed
limit (Union[int, None], optional) – Maximum number of results that should be returned
offset (Union[int, None], optional) – Number of results that should be skipped
fields (Union[Sequence[str], None], optional) – Names of fields (attributes) that should be included in results
search_filters (Union[Dict[str, Any], None], 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

Sanitized and sorted query parameters

Return type

collections.OrderedDict

dicomweb_client.ext.gcp.session_utils module

dicomweb_client.ext.gcp.uri module

Utilities for Google Cloud Healthcare DICOMweb API URI manipulation.

For details, visit: https://cloud.google.com/healthcare

class dicomweb_client.ext.gcp.uri.GoogleCloudHealthcareURL(project_id, location, dataset_id, dicom_store_id)

Bases: object

URL container for DICOM Stores under the Google Cloud Healthcare API.

This class facilitates the parsing and creation of URI.base_url corresponding to DICOMweb API Service URLs under the v1 API. The URLs are of the form: https://healthcare.googleapis.com/v1/projects/{project_id}/locations/{location}/datasets/{dataset_id}/dicomStores/{dicom_store_id}/dicomWeb

project_id

The ID of the GCP Project that contains the DICOM Store.

Type: str

location

The Region name of the geographic location configured for the Dataset that contains the DICOM Store.

Type: str

dataset_id

The ID of the Dataset that contains the DICOM Store.

Type: str

dicom_store_id

The ID of the DICOM Store.

Type: str

dataset_id: str

dicom_store_id: str

classmethod from_string(base_url)

Create an instance from base_url.

Parameters: base_url (str) – The URL for the DICOMweb API Service endpoint corresponding to a CHC API DICOM Store. See class docstring for supported formats.
Raises: ValueError – If base_url does not match the specifications in the class docstring.
Return type: dicomweb_client.ext.gcp.uri.GoogleCloudHealthcareURL

location: str

project_id: str