DICOM PS3.18 2020b - Web Services

8.3.5 Rendering Query Parameters (Current)
Prev | 8.3 Query Parameters | Next

### 8.3.5 Rendering Query Parameters

This section defines the Query Parameter syntax and behavior for Retrieve requests for Rendered Media Types.

All Retrieve transactions for Rendered Media Types shall support these parameters.

#### 8.3.5.1 Query Parameters For Rendered Resources

The Query Parameters defined in this section specify various rendering transformations to be applied to the DICOM images, video, and text contained in the parent DICOM Resource.

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

1. All parameters are optional for the user agent.

2. Not all parameters are required to be supported by the origin server.

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

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

Table 8.3.5-1 shows the Query Parameters that may be used when requesting a Rendered Representation.

Table 8.3.5-1. Retrieve Rendered Query Parameters

Key | Values | Target Resource Category | Section
--- | --- | --- | ---
    accept
    Rendered Media Type
| All Categories | Section 8.3.3.1
    annotation
    "patient" and/or "technique"
| Image (single or multi-frame) or Video | Section 8.3.5.1.1
    charset
    character set token
| All Categories | Section 8.3.3.2
    quality
    Integer
| Image (single or multi-frame) or Video | Section 8.3.5.1.2
    viewport
    vw, vh, [ sx, sy, sw, sh ]
| Non-Presentation States | Section 8.3.5.1.3
    viewport
    vw, vh,
| Presentation States | Section 8.3.5.1.3
    window
    center, width, shape
| Non-Presentation States | Section 8.3.5.1.4
    iccprofile
    "no", "yes", "srgb", "adobergb" or "rommrgb"
| Image (single or multi-frame) or Video | Section 8.3.5.1.5

##### 8.3.5.1.1 Image Annotation

This parameter specifies that the rendered images or video will have annotations. Its name is "annotation" and its value is a comma-separated list of one or more keywords. It has the following syntax:

    annotation = %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 image rendering pipelines specified in PS3.4 require that annotations be applied after all other parameters have been applied and the image or video has been rendered. The exact nature and presentation of the annotations is determined by the origin server and is "burned-in" to the rendered content.

The origin server may support additional keywords, which shall be documented in the Conformance Statement and, if the service supports it, the Retrieve Capabilities response.

If any of the parameter values are not keywords, or there are no parameter values, the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

The origin server shall ignore any unsupported parameter values. If unsupported values are present, the origin server shall include the following header field:

    Warning 299 <service>: The following annotation values are not supported: <values>

and may include a payload containing an appropriate warning message.

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

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

4. The Target Resource could already contain "burned-in" text that is beyond the control of this parameter.

##### 8.3.5.1.2 Image Quality

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

    quality = %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 missing or is not an integer between 1 and 100 inclusive, the response shall be a 400 (Bad Request) and may include a payload containing an appropriate error message.

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

The meaning of this parameter is determined by the origin server and shall be documented in the Conformance Statement and, if the Service supports it, Retrieve Capabilities response.

### 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 origin server could choose to disregard the quality parameter if the resultant image quality would be too low.

##### 8.3.5.1.3 Viewport Scaling

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

The syntax of this parameter for a Presentation State Instance or a Thumbnail is:

    %s"viewport=" vw "," vh

Otherwise it is:

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

Where

    vw and vh
| are positive integers specifying the width and height, in pixels, of the rendered image or video. Both values are required.
    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. A value of 0,0 specifies the top-left corner of the source image(s).
    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, it defaults to the right edge of the source image. If sh is not specified, it defaults 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 origin server shall crop the source images or video to the region specified by sx, sy, sw, and sh. It shall then scale the source content, maintaining the aspect ratio of the cropped region, until either the rendered content width or height is the same as the viewport width or 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 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, i.e., the image(s) shall not be cropped, i.e., the full image is rendered.

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

If any of the following are true:

- This parameter specifies viewport dimensions that are either ill-formed or not supported

- The Target Resource is a Presentation State or Thumbnail and anything other than vw and vh are specified

then the response shall be 400 (Bad Request) and may include a payload containing an appropriate Status Report.

### 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 in PS3.3 .

##### 8.3.5.1.4 Windowing

The "window" parameter controls the windowing of the images or video as defined in Section C.8.11.3.1.5 in PS3.3 . It has the following syntax:

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

Where

    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 in PS3.3 .

All three parameters shall be present with valid values.

If any of the parameter values are missing or ill-formed, the origin server shall return a 400 (Bad Request) response and may 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).

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

Prev | Up | Next
8.3.4.4 Response Pagination | Home | 8.3.5.2 Query Parameters For Thumbnails

DICOM PS3.18 2020b - Web Services