6.5.8 WADO-RS - Retrieve Rendered Transaction

6.5.8 WADO-RS - Retrieve Rendered Transaction
Prev	6.5 WADO-RS Request/Response	Next

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 query parameters defined in this section. 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:

All parameters are optional for the user agent.
All parameters are required to be supported by the origin server.
These parameters only apply to resources that are images and video.
Instances that are not images will be rendered in an Acceptable Media Type, if one exists; otherwise, they will not be rendered.
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
annotation	"patient" and/or "technique"	All	6.5.8.1.2.1
charset	token	All	6.1.2.2
quality	integer	All	6.5.8.1.2.2
viewport	vw, vh, [ sx, sy, sw, sh ]	Non-Presentation States	6.5.8.1.2.3
viewport	vw, vh,	Presentation States	6.5.8.1.2.3
window	center, width, shape	Non-Presentation States	6.5.8.1.2.4

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

The exact nature and presentation of the annotation is determined by the origin server. The annotation is burned into the rendered image pixels.
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

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

Prev	Up	Next
6.5.7 Error Codes	Home	6.5.8.2 Behavior