dicomweb - A DICOMweb Client Adapter

DICOMweb is the DICOM Standard for web-based medical imaging and supported by many PACS servers. It is a set of RESTful services, enabling web developers to unlock the power of healthcare images using industry-standard toolsets. See https://www.dicomstandard.org/using/dicomweb

The DICOMweb_client python 3rd party library provides convenient access to DICOMweb servers. To make it even more convenient, this dicomweb.DicomWebClient wrapper class was created.

class dicomweb.DicomWebAdapter(dicomWebUrl: str, session: Session | None = None, username: str | None = None, password: str = '', **additionalClientParameters)[source]

Bases: object

This adapter class is supposed to provide a simple API for dealing with a DICOMWeb http(s) server, implemented by wrapping the dicomweb_client library.

It is currently not supposed to fully abstract from DICOMwebClient and make the implementation interchangeable, but if you only use public functionality, you won’t have to change any code if at some point we decide that it is.

Parameters:
setHttpRetryParameters(retry: bool = True, max_attempts: int = 5, wait_exponential_multiplier: int = 1000, retriable_error_codes: ~typing.Tuple[~http.HTTPStatus, ...] = (<HTTPStatus.TOO_MANY_REQUESTS: 429>, <HTTPStatus.REQUEST_TIMEOUT: 408>, <HTTPStatus.SERVICE_UNAVAILABLE: 503>, <HTTPStatus.GATEWAY_TIMEOUT: 504>))[source]

Sets parameters for HTTP retrying logic. These parameters are passed to retrying.retry which wraps the HTTP requests and retries all responses that return 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.

getStudyInstanceUIDForSeries(seriesInstanceUID: str) → [None, <class 'str'>][source]

Returns the study instance UID for the given series.

Parameters:

seriesInstanceUID – Instance UID of the series

Returns:

The study’s instance UID if the series could be found, otherwise None

Raises:

ConnectionError if there is a problem accessing the server

getSeriesInstanceUIDsForStudy(studyInstanceUID: str) → List[str][source]

Returns all series instance UIDs for the given study.

Parameters:

studyInstanceUID – Instance UID of the study

Returns:

A list of the series instance UIDs if the study could be found, otherwise an empty list.

Raises:

ConnectionError if there is a problem accessing the server

retrieveSeriesIntoFolder(studyInstanceUID: str, seriesInstanceUID: str, targetFolderRoot: str, useStudySubFolder: bool = True) → None[source]

Fetches the specified series and stores it as files in a newly created <seriesInstanceUID> subdirectory in the targetFolder (which must not previously exist). If useStudySubFolder is True, an intermediate study directory will be created Files are numbered with filenames starting with file000000.dcm.

Raises:

Different OSError versions if the targetFolderRoot was not found, is not writable, or if the series subfolder already exists.

Raises:

ConnectionError if there is a problem accessing the server

retrieveStudyIntoFolder(studyInstanceUID: str, targetFolderRoot: str) → None[source]

Fetches given study into targetFolder by calling retrieveSeriesIntoFolder() for each contained series.

Raises:

Different OSError versions if the targetFolderRoot was not found, is not writable, or if the study subfolder already exists.

Raises:

ConnectionError if there is a problem accessing the server

deleteStudy(studyInstanceUID: str) → None[source]

Deletes the study with the given UID from the PACS. WARNING: Apparently non-standard, may not be supported on your PACS-server. See tests for a REST-based workaround for ORTHANC servers (that allow deletion).

Parameters:

studyInstanceUID – Instance UID of the study to delete

deleteSeries(studyInstanceUID: str, seriesInstanceUID: str) → None[source]

Deletes the series with the given UID from the PACS. WARNING: Apparently non-standard, may not be supported on your PACS-server. See tests for a REST-based workaround for ORTHANC servers (that allow deletion).

Parameters:

  • studyInstanceUID – Instance UID of the study the series belongs to

  • seriesInstanceUID – Instance UID of the series to delete

storeDirectory(sourceDirectory: str, include_regex: str = None) → None[source]

Deletes the study with the given UID from the PACS.

WARNING: Has not been profiled, so the rerouting through pydicom may be similarly slow as DicomWebAdapter_Fallback._downloadSeries().

Parameters:

  • sourceDirectory – Directory to recursively traverse and look for files in

  • include_regex – Regular expression to restrict the files to be sent

class dicomweb.DicomWebAdapter_Fallback(dicomWebUrl: str, session: Session | None = None, username: str | None = None, password: str = '', **additionalClientParameters)[source]

Bases: DicomWebAdapter

This class uses only public functionality from DICOMwebClient and may thus be less fragile. However, last time we checked (SAT-1082), the download implementation in the base class was much faster.

_downloadSeries(studyInstanceUID: str, seriesInstanceUID: str, targetFolderForSeries: str) → None[source]

This method is how we would download a series with only the public interface of DICOMwebClient. Turns out it is substantially slower than the version in DicomWebAdapter, cf. SAT-1082.