DICOM PS3.18 2019e - Web Services

10.4 Retrieve Transaction

This Transaction uses the GET method to retrieve the Target Resource. The media type in the response payload will depend on the Target URI and the Query Parameters; for example, Instances as application/dicom, Metadata as application/dicom+json or rendered Instances as application/jpeg images.

The retrieve transaction supports DICOM, Rendered, and Thumbnail Resources.

10.4.1 Request

The request shall have the following syntax:

GET SP "/" {/resource} {?parameter*} SP versionCRLF
Accept: 1#media-type CRLF
*(header-fieldCRLF)
CRLF

Where parameter is one of the Query Parameters defined for the Target Resource in Section 10.4.1.2.

10.4.1.1 Target Resources

10.4.1.1.1 DICOM Resources

Table 10.4.1-1 defines the DICOM resources that may be retrieved.

Table 10.4.1-1. Retrieve Transaction DICOM Resources

Resource

URI Template

Study

/studies/{study}

Series

/studies/{study}/series/{series}

Instance

/studies/{study}/series/{series}/instances/{instance}

Frames

/studies/{study}/series/{series}/instances/{instance}/frames/{frames}

Bulkdata

/{/bulkdata}

10.4.1.1.2 Metadata Resources

Table 10.4.1-2 defines the resources used to retrieve the metadata contained in Instances.

Table 10.4.1-2. Retrieve Transaction Metadata Resources

Resource

URI Template

Study Metadata

/studies/{study}/metadata

Series Metadata

/studies/{study}/series/{series}/metadata

Instance Metadata

/studies/{study}/series/{series}/instances/{instance}/metadata

The Metadata Resources are used to retrieve the DICOM instances without retrieving Bulkdata. The Metadata returned for a study, series, or instance resource includes all Attributes in the resource. For Data Elements having a Value Representation (VR) of DS, FL, FD, IS, LT, OB, OD, OF, OL, OW, SL, SS, ST, UC, UL, UN, US, and UT, the origin server is permitted to replace the Value Field of the Data Element with a Bulkdata URI. The user agent can use the Bulkdata URI to retrieve the Bulkdata.

10.4.1.1.3 Rendered Resources

A Retrieve Transaction on a Rendered Resource will return a response that contains representations of a DICOM Resource rendered as appropriate images, videos, text documents, or other representations. Its primary use case is to provide user agents with a simple means to display medical images and related documents, without requiring deep knowledge of DICOM data structures and encodings.

A Rendered Resource contains one or more rendered representations, i.e., in a Rendered Media type, of its parent DICOM Resource. Table 10.4.1-3 shows the Rendered Resources supported by the Retrieve transaction along with their associated URI templates.

Table 10.4.1-3. Retrieve Transaction Rendered Resources

Resource

URI Template

Rendered Study

/studies/{study}/rendered

Rendered Series

/studies/{study}/series/{series}/rendered

Rendered Instance

/studies/{study}/series/{series}/instances/{instance}/rendered

Rendered Frames

/studies/{study}/series/{series}/instances/{instance}/frames/{frames}/rendered

The origin server shall be able to render all valid Instances of the Composite SOP classes for which conformance is claimed, e.g., origin server shall be able to render all Photometric Interpretations that are defined in the IOD for that SOP class.

The content type of the response payload shall be a Rendered Media Type. See Section 8.7.4.

10.4.1.1.4 Thumbnail Resources

A Retrieve Transaction on a Thumbnail resource will return a response that contains a rendered representation of its parent DICOM Resource.

Table 10.4.1-4 shows the Thumbnail resources supported by the Retrieve transaction along with their associated URI templates.

Table 10.4.1-4. Retrieve Transaction Thumbnail Resources

Resource

URI Template

Study Thumbnail

/studies/{study}/thumbnail

Series Thumbnail

/studies/{study}/series/{series}/thumbnail

Instance Thumbnail

/studies/{study}/series/{series}/instances/{instance}/thumbnail

Frame Thumbnail

/studies/{study}/series/{series}/instances/{instance}/frames/{frames}/thumbnail

The representation returned in the response to a Retrieve Thumbnail resource request shall be in a Rendered Media Type. The Thumbnail shall not contain any Patient Identifying Information. Only a single image shall be returned.

If the origin server supports any of the Thumbnail resources, it shall support all of them.

The origin server will determine what constitutes a meaningful representation.

The origin server may return a redirection response (HTTP status code 302) to a rendered resource instead of returning a rendered image.

There is no requirement that Thumbnail resources be related to any Icon Image Sequence (0088,0200) encoded in Instances or returned in query responses.

10.4.1.2 Query Parameters

The origin server shall support Query Parameters as required in Table 10.4.1-5.

The user agent shall supply in the request Query Parameters as required in Table 10.4.1-5.

Table 10.4.1-5. Query Parameters by Resource

Key

Resource Category

Usage

Section

User Agent

Origin Server

accept

All

O

M

Section 8.3.3.1

charset

Text

O

M

Section 8.3.3.2

annotation

Rendered

O

M

Section 8.3.5.1.1

quality

Rendered

O

M

Section 8.3.5.1.2

viewport

Rendered

O

M

Section 8.3.5.1.3

Thumbnail

O

O

window

Rendered

O

M

Section 8.3.5.1.4

iccprofile

Rendered

O

O

Section 8.3.5.1.5


10.4.1.3 Request Header Fields

The origin server shall support header fields as required in Table 10.4.1-6 in the request.

The user agent shall supply in the request header fields as required in Table 10.4.1-6.

Table 10.4.1-6. Request Header Fields

Name

Values

Usage

Description

User Agent

Origin Server

Accept

media-type

M

M

The Acceptable Media Types of the response payload

Accept-Charset

charset

O

M

The Acceptable Character Sets of the response payload


See also Section 8.4.

10.4.1.4 Request Payload

The request shall have no payload.

DICOM PS3.18 2019e - Web Services