| DICOM PS3.18 2024e - 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:
Not all parameters are required to be supported by the origin server.
These parameters only apply to Single Frame Image, Multi-Frame Image, Video and Text resources. See Section 8.7.2.
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. The origin server determines the presentation of other objects controlling the display of images, such as Structured Reports or Segmentation Objects.
Presentation State transformations are applied using the appropriate rendering pipeline specified in Section N.2 “Pixel Transformation Sequence” in PS3.4. Any Source Image Region parameters are applied after any Presentation State parameters. Any Viewport parameters are applied after any Source Image Region.
Even if the output of the image is defined in P-Values (grayscale values intended for display on a device calibrated to the DICOM Grayscale Standard Display Function PS3.14), or contains an ICC profile, the grayscale or color space for the rendered image is not defined by this Standard.
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].
If a Target Resource is a single Presentation State Instance, that Instance may contain references to one or more Series, each of which may contain one or more Instances, each of which may contain one or more Frames. The response shall return rendered versions of all supported Instances and Frames referenced by the Presentation State Instance.
For example, if the Presentation State Instance
If the Presentation State Instance contains a Blending Sequence, then the rendered images in the response shall correspond to the frames of the input that have a Blending Sequence Item with a Blending Position (0070,0405) value of UNDERLYING. See Section C.11.14.1.1 “Blending Sequence” in PS3.3 .
The origin server shall render all of the images referenced by the Presentation State in an Acceptable Media Type using the rendering pipeline specified in Section N.2 “Pixel Transformation Sequence” in PS3.4.
If there is more than one Frame in the response they shall be ordered according to the following criteria:
If the above does not fully specify the ordering of the frames, then the origin server shall resolve any remaining ambiguity in the ordering.
If the Target Resource is a Presentation State and If the Presentation Size Mode is SCALE TO FIT or TRUE SIZE, then the displayed area specified in the Presentation State shall be scaled, maintaining the aspect ratio, to fit the size specified by the rows and columns parameters if present, otherwise the displayed area selected in the presentation state will be returned without scaling.
The intent of the TRUE SIZE mode in the presentation state cannot be satisfied, since the physical size of the pixels displayed by the web browser is unlikely to be known. If the Presentation Size Mode in the presentation state is MAGNIFY, then the displayed area specified in the presentation shall be magnified (scaled) as specified in the presentation state. It will then be cropped to fit the size specified by the viewport parameters, if present.
Any Displayed Area relative annotations specified in the presentation state are rendered relative to the Specified Displayed Area within the presentation state, not the size of the returned image.
Though the output of the presentation state is defined in DICOM to be in P-Values (grayscale values intended for display on a device calibrated to the DICOM Grayscale Standard Display Function PS3.14), the grayscale or color space for the images returned by the request is not defined by this standard.
If the Presentation State contains the ICC Profile Module, the image(s) in the response shall include the ICC Profile as specified in Section 8.3.5.1.5.
The origin server shall reject the request if any of the following are true:
and the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.
| DICOM PS3.18 2024e - Web Services |
|---|