DICOM PS3.18 2021d - 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.

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 Instance Resources

Instance Resources (defined in Table 10.4.1-1 are used to retrieve Instances.

Retrieving a Series Instances resource retrieves all the individual Instances contained in the Series. Retrieving a Study Instances resource retrieves all the individual Instances contained in all the Series.

Table 10.4.1-1. Retrieve Transaction Instance Resources

Resource

URI Template

Study Instances

/studies/{study}

Series Instances

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

Instance

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

Note

Bulkdata and Frames were previously listed in this table. Bulkdata is addressed in Section 10.4.1.1.5 and Frames data is addressed in Section 10.4.1.1.6.

10.4.1.1.2 Metadata Resources

Metadata Resources (defined in Table 10.4.1-2 are used to retrieve the metadata of Instances without retrieving Bulkdata.

Retrieving a Series Metadata resource retrieves all the metadata for all individual Instances contained in the Series. Retrieving a Study Metadata resource retrieves all the metadata for all individual Instances contained in all the Series.

Note

An implementation interested in just study level or series level metadata, rather than instance level metadata for all instances, would be better served by using the Search Transaction on the All Studies or Study’s Series resources, matching against the Study Instance UID and using &includefield to specify the metadata of interest (see Section 10.6.1.2).

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

10.4.1.1.3 Rendered Resources

Rendered Resources (defined in Table 10.4.1-3) are used to retrieve 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 exposes one or more rendered representations, i.e., in a Rendered Media type, of its parent DICOM Resource.

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

10.4.1.1.4 Thumbnail Resources

Thumbnail resources (defined in Table 10.4.1-4 are used to retrieve a rendered representation appropriate to stand for its parent DICOM Resource.

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

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

10.4.1.1.5 Bulkdata Resources

Bulkdata resources (defined in Table 10.4.1.5-1 are used to retrieve data elements (typically containing large data, such as Pixel Data) extracted from DICOM Instances.

Table 10.4.1.5-1. Retrieve Transaction Bulkdata Resources

Resource

URI Template

Study Bulkdata

/studies/{study}/bulkdata

Series Bulkdata

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

Instance Bulkdata

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

Bulkdata

{bulkdataURI}

Note

  1. Bulkdata resources that contain pixel data can be retrieved equivalently as described in Section 10.4.1.1.6.

  2. Refer to Section Section 10.4.1.1.6 for URI templates for Bulkdata consisting of Frame Pixel Data.

10.4.1.1.6 Pixel Data Resources

Pixel Data resources (defined in Table 10.4.1.6-1 are used to retrieve data elements containing top-level pixel data from DICOM Instances.

Pixel data is a subset of bulkdata. The Pixel Data resources provide a convenient method to access that specific subset.

Table 10.4.1.6-1. Retrieve Transaction Pixel Data Resources

Resource

URI Template

Study Pixel Data

/studies/{study}/pixeldata

Series Pixel Data

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

Instance Pixel Data

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

Frame Pixel Data

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

Note

  1. Frame Pixel Data is inherently pixel data so a /pixeldata subresource is not needed in the URI Template.

  2. The Frame Pixel Data resource originally appeared in Table 10.4.1-1.

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

Resources

Usage

Section

User Agent

Origin Server

accept

All Resources

O

M

Section 8.3.3.1

charset

Metadata Resources

O

M

Section 8.3.3.2

annotation

Rendered Resources

O

M

Section 8.3.5.1.1

quality

Rendered Resources

O

M

Section 8.3.5.1.2

viewport

Rendered Resources

O

M

Section 8.3.5.1.3

Thumbnail Resources

O

O

window

Rendered Resources

O

M

Section 8.3.5.1.4

iccprofile

Rendered Resources

O

O

Section 8.3.5.1.5


10.4.1.3 Request Header Fields

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

The user agent shall supply 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

See Section 10.4.4 for media types corresponding to each set of target resources defined in Section 10.4.1.1.

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 2021d - Web Services