DICOM PS3.18 2019a - Web Services

6.5.8 WADO-RS - Retrieve Rendered Transaction

This action retrieves DICOM instances rendered as: images, text-based documents, or other appropriate representations depending on the target resource. Its primary use case is to provide user agents with a simple interface for displaying medical images and related documents, without requiring deep knowledge of DICOM data structures and encodings. It is similar to the Retrieve DICOM service in that it uses the same method, resources, header fields and status codes. The primary differences are the resource component and the query parameters.

The origin server shall document the Composite SOP classes that it supports for this transaction in the Conformance Statement and in the response to the Retrieve Capabilities request, and shall be able to render all valid instances for which conformance is claimed, e.g., all photometric interpretations that are defined in the IOD for the SOP class.

6.5.8.1 Request

The Retrieve Rendered service has the following request message syntax:

    GET SP /{+resource}{?parameter*} SP version CRLF
    Accept: 1#rendered-media-type CRLF
    *(header-field CRLF)
    CRLF

Where

{+resource}

References a resource.

{?parameter*}

Zero or more query parameters as defined in Section 6.5.8.1.2.

version

HTTP version = "HTTP/1.1"

1#rendered-media-type

One or more Rendered Media Types See Section 6.1.1.3.

6.5.8.1.1 Target Resources

Table 6.5.8-1 shows the resources supported by the Retrieve Rendered transaction along with their associated URI templates.

Table 6.5.8-1. Resources, Templates and Description

Target Resource

Resource URI Template

Study

/studies/{study_uid}/rendered

Retrieves a study in acceptable Rendered Media Types.

Series

/studies/{study_uid}/series/{series_uid}/rendered

Retrieves a series in an acceptable Rendered Media Type.

Instance

/studies/{study_uid}/series/{series_uid}/instances/{instance_uid}/rendered

Retrieves an instance in an acceptable Rendered Media Type.

Frames

/studies/{study_uid}/series/{series_uid}/instances/{instance_uid}/frames/{frame_list}/rendered

Retrieves one or more frames in an acceptable Rendered Media Type.


6.5.8.1.2 Query Parameters

The query parameters defined in this section specify various rendering transformations to be applied to the images and video contained in the target resource.

The origin server shall support all of the Required query parameters defined in Table 6.5.8-2. An origin server may support Optional query parameters defined in Table 6.5.8-2. An origin server may define additional parameters. If additional parameters are defined, they shall be documented in the Conformance Statement and in the Retrieve Capabilities response. The origin server shall ignore any unknown parameters.

The following rules pertain to all parameters defined in this section:

  1. All parameters are optional for the user agent.

  2. All Required parameters are required to be supported by the origin server.

  3. These parameters only apply to resources that are images and video.

  4. Instances that are not images will be rendered in an Acceptable Media Type, if one exists; otherwise, they will not be rendered.

  5. The set of transformations specified by the parameters in this section shall be applied to the images as if they were a Presentation State, that is, in the order specified by the applicable image rendering pipeline specified in PS 3.4.

See Section 6.1.4.

Table 6.5.8-2. Retrieve Rendered Query Parameters

Key

Values

Target Resource

Section

Origin Server Support

annotation

"patient" and/or "technique"

All

6.5.8.1.2.1

Required

charset

token

All

6.1.2.2

Required

quality

integer

All

6.5.8.1.2.2

Required

viewport

vw, vh, [ sx, sy, sw, sh ]

Non-Presentation States

6.5.8.1.2.3

Required

viewport

vw, vh,

Presentation States

6.5.8.1.2.3

Required

window

center, width, shape

Non-Presentation States

6.5.8.1.2.4

Required

iccprofile

"yes", "no", "srgb", "adobergb", "rommrgb"

Images

6.5.8.1.2.5

Optional


6.5.8.1.2.1 Image Annotation

The annotation parameter specifies that the rendered images shall be annotated with patient and/or procedure information. Its value is a comma-separated list of one or more keywords. It has the following syntax:

    %s"annotation=" 1#( %s"patient" / %s"technique" )

Where

"patient"

indicates that the rendered images shall be annotated with patient information (e.g., patient name, birth date, etc.).

"technique"

indicates that the rendered images shall be annotated with information about the procedure that was performed (e.g., image number, study date, image position, etc.).

When this parameter is not present, no annotations shall be applied.

The origin server shall apply the annotations after all other parameters have been applied.

The origin server may support additional keywords, which should be included in the Conformance Statement and the Retrieve Capabilities response.

The origin server shall ignore any unsupported parameter values.

Note

  1. The exact nature and presentation of the annotation is determined by the origin server. The annotation is burned into the rendered image pixels.

  2. A user agent wanting more control over annotations may retrieve an image, omitting the "annotation" parameter; and separately retrieve the metadata; and create customized annotations on the image.

6.5.8.1.2.2 Image Quality

The "quality" parameter specifies the requested quality of the rendered images. It has the following syntax:

    %s"quality=" integer

Where

integer

is an unsigned integer between 1 and 100 inclusive, with 100 being the best quality.

If the value of this parameter is less than 1 or greater than 100, the response shall be a 400 (Bad Request), and should include a payload containing an appropriate error message.

The "quality" parameter is only supported for media types that allow lossy compression.

Note

  1. Decompression and re-compression may degrade the image quality if the original image was already irreversibly compressed. If the image has been already lossy compressed using the same format as required (e.g., jpeg), it may be sent as it is without decompressing and re-compressing it.

  2. The specific interpretation of the meaning of this parameter is determined by the origin server.

6.5.8.1.2.3 Scaling Regions of Source Images to a Viewport

The "viewport" parameter specifies a rectangular region of the source image(s) to be cropped, and a rectangular region corresponding to the size of the user agent's viewport to which the cropped image should be scaled.

If the target resource is a Presentation State Instance, the syntax for this parameter is:

    %s"viewport=" vw "," vh

Otherwise it is:

    %s"viewport=" vw "," vh ["," [sx] "," [sy] "," [sw] "," [sh] ]

Where

vw and vh

are positive integers specifing the width and height, in pixels, of the rendered image.

sx and sy

are decimal numbers whose absolute values specify, in pixels, the top-left corner of the region of the source image(s) to be rendered; if either <sx> or <sy> is not specified it defaults to 0.

sw and sh

are decimal numbers whose absolute values specify, in pixels, the width and height of the region of the source image(s) to be rendered; if <sw> is not specified, the origin server shall render to the right edge of the source image; if <sh> is not specified, the origin server shall render to the bottom edge of the source image; if <sw> is a negative value, the image is flipped horizontally; if <sh> is a negative value, the image is flipped vertically.

The source image region parameters (sx, sy, sw, and sh) shall not be present when rendering a Presentation State Instance. If they are present the origin server shall return a 409 (Conflict).

The origin server shall first crop, if specified, then scale the source images, maintaining their original aspect ratio, until either the rendered image width is the same as the viewport width or the image height is the same as the viewport height, whichever avoids truncation. In other words, viewport scaling makes the image(s) as large as possible, within the viewport, without overflowing the viewport area and without distorting the image.

If any of the optional parameter values are not present the default value shall be used. Individual values may be elided, but the commas between the values shall be present. For example:

    viewport=512,512,,,512,512

The missing <sx> and <sy> parameter values shall default to 0.

If trailing values are elided, then the trailing commas shall be omitted. For example:

    viewport=1024,1024

The missing <sx>, <sy>, <sw>, <sh> will have their default values, which means the image(s) will not be cropped, and the full image will be rendered.

If the viewport parameter is not present, the rendered image(s) shall not be scaled, i.e., the rendered image(s) shall contain the same sized pixel matrix as the source DICOM image.

If this parameter specifies an ill-defined source region or viewport, the origin server shall return a 400 (Bad Request) response, and should include a payload containing an appropriate error message.

Note

The default values for <sx> and <sy> differ from the defaults in the Specified Displayed Area in Presentation States, which uses integer values with the top left corner being (1,1). See Section C.10.4 “Displayed Area Module” in PS3.3 .

6.5.8.1.2.4 Windowing

The "window" parameter controls the windowing of the images as defined in Section C.8.11.3.1.5 “VOI Attributes” in PS3.3 . It has the following syntax:

    %s"window=" center "," width "," function

center

is a decimal number containing the window-center value

width

is a decimal numbercontaining the window-width value

function

is one of the following keywords: "linear", "linear-exact", or "sigmoid".

Note

These correspond to the differently capitalized and punctuated values of VOI LUT Function (0028,1056). See Section C.11.2.1.2 “Window Center and Window Width” in PS3.3 .

All three parameter shall be present with valid values.

If any of the parameter values are missing or invalid, the origin server shall return a 400 (Bad Request) response, and should include a payload containing an appropriate error message.

If the target resource is a Presentation State, this parameter shall not be used. If this parameter is present when the target resource is a Presentation state, the origin server shall return a 400 (Bad Request).

6.5.8.1.2.5 ICC Profile

The "iccprofile" parameter specifies the color characteristics of, and inclusion of an ICC Profile in, the rendered images. It has the following syntax:

    %s"iccprofile=" 1#( %s"no" / %s"yes" / %s"srgb" / %s"adobergb" / %s"rommrgb" )

Where

"no"

indicates that no ICC profile shall be present in the rendered image in the response.

"yes"

indicates that an ICC profile shall be present in the rendered image in the response, describing its color characteristics, if the Media Type supports embedded ICC Profiles.

"srgb"

indicates that an sRGB ICC profile shall be present in the image, if the Media Type supports embedded ICC Profiles, and that the pixels of the rendered image in the response shall be transformed from their original color space and be encoded in the sRGB color space [IEC 61966-2.1].

"adobergb"

indicates that an Adobe RGB ICC profile shall be present in the image, if the Media Type supports embedded ICC Profiles, and that the pixels of the rendered image in the response shall be transformed from their original color space and be encoded in the Adobe RGB color space [Adobe RGB].

"rommrgb"

indicates that a ROMM RGB ICC profile shall be present in the image, if the Media Type supports embedded ICC Profiles, and that the pixels of the rendered image in the response shall be transformed from their original color space and encoded in the ROMM RGB color space [ISO 22028-2].

When this parameter is not present:

  • an ICC profile may or may not be present in the image in the response;

  • the color characteristics of the image in the response may or may not be consistent with any DICOM ICC Profile (0028,2000) Attribute in the metadata.

The ICC Profile in the image in the response shall be:

  • the ICC profile of the color space specified explicitly by the parameter,

  • otherwise, the ICC profile encoded in the source DICOM ICC Profile (0028,2000) Attribute, if any, appropriate to the selected frame,

  • otherwise, the ICC profile, if any, embedded in the stored compressed representation of the selected frame,

  • otherwise, at the discretion of the origin server, the ICC profile of a well-known color space listed in Section C.11.15.1.2 “Color Space” in PS3.3 that is appropriate to the type and source of the image.

If the Media Type does not support embedded ICC Profiles:

  • a 400 Bad Request error shall be returned if the parameter value is other than "no"

Note

  1. This parameter allows ICC profile information to be present in the image in the response so that the user agent can make use of it for local color management (e.g., an ICC profile capable browser can apply the profile when displaying the rendered image in the response).

  2. This parameter provides a limited mechanism for requesting that the origin server perform some color management. It provides the names of well-known color spaces for the rendered image in the response. It does not provide a mechanism to supply an arbitrary ICC profile, such as the calibration profile of a display, so it does not absolve the user agent from the need to handle its own color calibration and color management.

  3. ICC profiles can theoretically be large relative to the compressed pixel data of a single frame, so the user agent may specify a parameter value of "no", retrieve the DICOM ICC Profile (0028,2000) Attribute value(s) that apply to multiple frames from the metadata, and combine these itself.

  4. ICC profiles are embedded in rendered images of Media Type image/jpeg as one or more chunks in APP2 marker segments with an identifier of "ICC_PROFILE", as defined in Annex B of [ISO 15076-1].

  5. ICC profiles are embedded in rendered images of Media Type image/jp2 either as JP2 Restricted or JPX Full profiles according to [ISO/IEC 15444-1] and [ISO/IEC 15444-2], respectively; rendered images in the response are not subject to the prohibition against inclusion of a JP2 box in JPEG 2000 compressed data streams in DICOM images.

  6. ICC profiles are embedded in rendered images of Media Type image/png in an iCCP chunk, as defined in [ISO 15948].

6.5.8.1.3 Header Fields

Required: Accept

The values of the Accept header field shall be one or more Rendered Media Types.

6.5.8.1.4 Payload

This request has no payload.

DICOM PS3.18 2019a - Web Services