DICOM PS3.18 2020e - Web Services

9.5 Retrieve Rendered Instance Transaction

This transaction returns a single Instance in a Rendered Media Type. See Section 8.7.4.

The Acceptable Media Type shall not be application/dicom. If it is, the response should be 406 (Not Acceptable) response.

9.5.1 Request

The request shall have the following syntax:

GET SP /?{requestType}&{study}&{series}&{instance}{&frameNumber}
         {&accept}
         {&charset}
         {&annotation}
         {&rows}
         {&columns}
         {&region}
         {&windowCenter}
         {&windowWidth}
         {&imageQuality}
         {&annotation}
         {&presentationSeriesUID}
         {&presentationUID}
SP HTTP/1.1 CRLF
Accept: 1#media-type CRLF
*(header-field CRLF)
CRLF

9.5.1.1 Target Resource

The Target Resource shall be an Instance of a Composite SOP Class as defined in PS3.3.

9.5.1.2 Query Parameters

The Query Parameters in this section shall only be included in a request if the DICOM Category of the Target Resource is Single Frame, Multi-Frame, or Video as defined in Section 8.7.2.

The origin server shall support Query Parameters as required in Table 9.5.1-1.

The user agent shall supply in the request Query Parameters as required in Table 9.5.1-1.

Table 9.5.1-1. Query Parameters

Key

Values

Usage

Section

User Agent

Origin Server

contentType

rendered-media-type

O

M

Section 9.1.2.2.1

charset

charset

O

M

Section 9.1.2.2.2

frameNumber

uint

O

O

Section 9.5.1.2.1

imageAnnotation

"patient" / "technique"

O

O

Section 9.5.1.2.2

imageQuality

uint

O

O

Section 9.5.1.2.3

rows

uint

O

O

Section 9.5.1.2.4.1

columns

uint

O

O

Section 9.5.1.2.4.2

region

4decimal

O

O

Section 9.5.1.2.5

windowCenter

decimal

O

O

Section 9.5.1.2.6.1

windowWidth

decimal

O

O

Section 9.5.1.2.6.2

presentationSeriesUID

uid

O

O

Section 9.5.1.2.7.1

presentationUID

uid

O

O

Section 9.5.1.2.7.2


9.5.1.2.1 Frame Number
frame-number = %s"frameNumber" "=" uint

This parameter specifies a single frame within a multi-frame image Instance, as defined in PS3.3 that shall be returned. Its name is "frameNumber" and its value shall be a positive integer (i.e., starts at 1 not 0).

9.5.1.2.2 Image Annotation

See Section 8.3.5.1.1.

9.5.1.2.3 Image Quality

See Section 8.3.5.1.2.

9.5.1.2.4 Viewport

The Viewport Query Parameters specify the dimensions of the user agent's viewport. The Viewport Rows and Columns parameters specify the height and width, in pixels, of the returned image. If either parameter is present, both shall be present.

The Viewport parameters syntax in this Section overrides that described in Section 8.3.5.1.3; however, the scaling behavior described in that section still applies.

9.5.1.2.4.1 Viewport Rows
rows = %s"rows" "=" uint

This parameter specifies the number of pixel rows in the returned image. It corresponds to the height in pixels of the user agent's viewport. Its name is "rows" and its value shall be a positive integer.

9.5.1.2.4.2 Viewport Columns
columns = %s"columns" "=" uint

This parameter specifies the number of pixel columns in the returned image. It corresponds to the width, in pixels, of the user agent's viewport. Its name is "columns" and its value shall be a positive integer.

9.5.1.2.5 Source Image Region
region = %s"region" "=" xmin "," ymin "," xmax "," ymax
xmin = decimal
ymin = decimal
xmax = decimal
ymax = decimal

This parameter specifies a rectangular region of the Target Resource. Its name is "region" and its values shall be a comma-separated list of four positive decimal numbers:

xmin

the left column of the region

ymin

the top row of the region

xmax

the right column of the region

ymax

the bottom row of the region

The region is specified using a normalized coordinate system relative to the size of the original image matrix, measured in rows and columns. Where

  • 0.0, 0.0 corresponds to the top row and left column of the image

  • 1.0, 1.0 corresponds to the bottom row and right column of the image

and

  • 0.0 <= xmin < xmax <= 1.0

  • 0.0 <= ymin < ymax <= 1.0

This parameter when used in conjunction with one of the viewport parameters, allows the user agent to map a selected area of the source image into its viewport.

9.5.1.2.6 Windowing

The Windowing parameters (Window Center and Window Width) are optional; however, if either is present, both shall be present. If only one is present the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

The URI Service does not support the "function" Query Parameter, which is described in Section 8.3.5.1.4.

The Windowing and Presentation State parameters shall not be present in the same request. If both are present the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

The Windowing parameters shall not be present if contentType is application/dicom; if either is present the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

9.5.1.2.6.1 Window Center
window-center = %s"windowCenter" "=" decimal

This parameter specifies the Window Center of the returned image as defined in PS3.3. Its name is "windowCenter" and its value shall be a decimal number.

9.5.1.2.6.2 Window Width
window-width = %s"windowWidth" "=" decimal

This parameter specifies the Window Width of the returned image as defined in PS3.3. Its name is "windowWidth" and its value shall be a decimal number.

9.5.1.2.7 Presentation State

The parameters below specify the Series and SOP Instance UIDs of a Presentation State. They are optional. However, if one is present, they shall both be present.

If the Presentation State parameters are present, then the only other optional parameters that may be present are Annotation, Image Quality, Region, and Viewport.

9.5.1.2.7.1 Presentation Series UID
presentation-series = %s"presentationSeriesUID" "=" uid

This parameter specifies the Series containing the Presentation State Instance to be used to render the image. Its name shall be "presentationSeriesUID" and its value shall be a Series Instance UID.

9.5.1.2.7.2 Presentation UID
presentation-instance = %s"presentationUID" "=" uid

This parameter identifies the Presentation State Instance, which is used to render the image. Its name is "presentationUID" and its value shall be a Presentation State Instance UID of a Presentation State Instance.

9.5.1.3 Request Header Fields

The origin server shall support header fields as required in Table 9.5.1-2.

The user agent shall supply in the request header fields as required in Table 9.5.1-2.

Table 9.5.1-2. Request Header Fields

Name

Values

Usage

Description

User Agent

Origin Server

Accept

media-type

M

M

The Acceptable Media Types for the response payload

Accept-Charset

charset

O

M

List of one or more character sets


The Acceptable Media Types shall contain only Rendered Media Types. See Section 8.7.4.

9.5.1.4 Request Payload

The request message has no payload.

DICOM PS3.18 2020e - Web Services