DICOM PS3.18 2020e - Web Services

9.5 Retrieve Rendered Instance Transaction (Current)
Prev | 9 URI Service | Next

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

Prev | Up | Next
9.4.3.3 Response Payload | Home | 9.5.2 Behavior

DICOM PS3.18 2020e - Web Services