| DICOM PS3.18 2023e - Web Services |
|---|
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.
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:
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
accept |
Rendered Media Type |
||
annotation |
"patient" and/or "technique" |
||
charset |
character set token |
||
quality |
uint |
||
viewport |
vw, vh, [ sx, sy, sw, sh ] |
||
viewport |
vw, vh, |
||
window |
center, width, shape |
||
iccprofile |
"no", "yes", "srgb", "adobergb" or "rommrgb" |
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" )
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.
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.
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.
The Target Resource could already contain "burned-in" text that is beyond the control of this parameter.
The "quality" parameter specifies the requested quality of the rendered images or video. It has the following syntax:
quality = %s"quality=" uint
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.
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 origin server could choose to disregard the quality parameter if the resultant image quality would be too low.
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
%s"viewport=" vw "," vh ["," [sx] "," [sy] "," [sw] "," [sh] ]
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:
then the response shall be 400 (Bad Request) and may include a payload containing an appropriate Status Report.
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 .
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
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).
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" )
When this parameter is not present:
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:
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).
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.
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.
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].
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.
ICC profiles are embedded in rendered images of Media Type image/png in an iCCP chunk, as defined in [ISO 15948].
| DICOM PS3.18 2023e - Web Services |
|---|