8.3.4.4 Response Pagination​

The following two parameters can be used to paginate a search response that might contain more matches than can readily be​ handled.​

offset = "offset" "=" uint

A single parameter specifies the number of matches the origin server shall skip before the first returned match. The "offset" parameter​ value is an unsigned integer (uint). If this Query Parameter is not present, its value defaults to 0.​

limit = "limit" "=" uint

Asingleparameterspecifiesthemaximumnumberofmatchestheoriginservershallreturninasingleresponse.The"limit"parameter​ value is an unsigned integer. If this parameter is not present, its value is determined by the origin server.​

8.3.4.4.1 Paging Behavior​

The search requests shall be idempotent, that is, two separate search requests with the same Target Resource, Query Parameters,​ and header fields shall return the same ordered list of matches, if the set of matches on the origin server has not changed.​

The results returned in the response are determined as follows:​

•​If (results <= 0) then there are no matches, and a 204 (No Content) response shall be returned with an empty payload.​

•​Otherwise, a 200 (OK) response shall be returned with a payload containing the results.​

•​If (remaining > 0) the response shall include a Warning header field (see [RFC7234] Section 5.5) containing the following:​

Warning: 299 <service>: There are <remaining> additional results that can be requested

The response may include a payload containing an appropriate Status Report.​

If the set of matching results has changed due to changes in the origin server contents, then the ordered list of results may be different​ for subsequent transactions with identical requests, and the results of using the "offset" and "limit" parameters may be inconsistent.​

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

- Standard -​

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​

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" )

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

- Standard -​

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.​Auseragentwantingmorecontroloverannotationscanretrieveanimage,omittingthe"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​

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 com-​ pressed. 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:​

- Standard -​

%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,maintainingtheaspectratioofthecroppedregion,untileithertherenderedcontentwidthorheightisthesameastheviewport​ 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"parametercontrolsthewindowingoftheimagesorvideoasdefinedinSectionC.8.11.3.1.5inPS3.3.Ithasthefollowing​ syntax:​

- Standard -​

Note​

ThesecorrespondtothedifferentlycapitalizedandpunctuatedvaluesofVOILUTFunction(0028,1056).SeeSectionC.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.​

IftheTargetResourceisaPresentationState,thisparametershallnotbeused.IfthisparameterispresentwhentheTargetResource​ 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" )

When this parameter is not present:​

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

•​thecolorcharacteristicsoftheimageintheresponsemayormaynotbeconsistentwithanyDICOMICCProfile(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,theICCprofileencodedinthesourceDICOMICCProfile(0028,2000)Attribute,ifany,appropriatetotheselectedframe,​

•​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"​

- Standard -​

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​ providesthenamesofwell-knowncolorspacesfortherenderedimageintheresponse.Itdoesnotprovideamechanism​ 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].​

8.3.5.2 Query Parameters For Thumbnails​

Table 8.3.5-2shows the Query Parameters that may be used when requesting a Thumbnail representation.​

Table 8.3.5-2. Thumbnail Query Parameters​

The Viewport parameter only has width and height values. If no viewport parameter is provided the origin server will determine the​ size of the thumbnail.​

8.4 Header Fields​

The following sections specify important header fields, some of which have stronger requirements than those specified in the HTTP​ Standard.​

8.4.1 Content Negotiation Header Fields​

HTTP uses the Accept and Content-Type header fields for content negotiation and data typing. The media types in the Accept​ header field of a request define the media types that the user agent would find acceptable in the response. The media type in the​ Content-Typeheaderfieldofamessage,orpayloadpart,describestheformatoftherepresentationcontainedinthemessagepayload​ or payload part.​

ContentNegotiationheaderfieldsinrequestsallowtheuseragenttospecifyacceptablerepresentationsfortheresponse.Table8.4.1-​ 1 lists the content negotiation header fields. The values in these fields apply to any content in the response, including representations​ of the Target Resource, representations of error or processing status, and potentially even the miscellaneous text strings that might​ appear within the HTTP protocol. See [RFC7231] Section 5.3.​

- Standard -​

8.4.1.1 Accept​

User agents use the Accept header field to specify Acceptable Media Types for the response payload. The Accept header field can​ be used to indicate that the response payload is specifically limited to a set of desired media types. It has the following syntax:​

MostrequestshaveanAcceptheaderfieldthatcontainsacomma-separatedlistofoneormoremediaranges.Amedia-rangeextends​ media-typewithwildcards(*/*ortype/*)andparametersthatarenotdefinedformedia-types.See[RFC7231]Section5.3.2fordetails.​

For example, if the user agent is willing to accept any media type in the response it should include */* as a value of the Accept header​ field.​

Many of the content negotiation header fields use a weight parameter, named "q" (case-insensitive), to assign a relative "weight" to​ the preference for that associated kind of content.​

The media types in the Accept header can be given a priority ordering by using weights.​

weight = OWS ";" OWS "q=" qvalue qvalue = ("0" ["." 0*3DIGIT])

/ ("1" ["." 0*3("0")])

This weight is often referred to as "quality value" or "qvalue". See [RFC7231] Section 5.3.1.​

All requests that might have a response containing a payload shall provide an Accept header field.​

See Section 8.7.5 for Acceptable Media Types.​

8.4.1.1.1 Charset Media Type Parameter​

Many media types, especially text/* types, define a "charset" parameter that specifies the character set for the representation. See​ [RFC7231] Section 3.1.1.2.​

DICOM Media Types define a "charset" parameter. See Section 8.7.3.5.3.​

For example,​

application/dicom; charset=ISO-8859-1

- Standard -​

See Section 8.8.1 for Acceptable Character Sets.​

8.4.2 Content Representation Header Fields​

The media type in the Content-Type header field of a message, or payload part, describes the format of the representation contained​ in the payload or part.​

When a message has a payload, the Content Representation Header Fields provide metadata describing how to interpret the repres-​ entation(s) contained in the payload. Table 8.4.2-1 describes the Content Representation Header Fields, and the usage requirements​ (Mandatory, Conditional, or Optional) for when they shall be present.​

Table 8.4.2-1. Content Representation Header Fields​

8.4.3 Payload Header Fields​

The Payload Header Fields contain metadata describing the payload, not the representation it contains. Table 8.4.3-1 describes the​ payload header fields, and the usage requirements (Mandatory, Conditional, or Optional) for when they shall be present.​

Table 8.4.3-1. Payload Header Fields​

IftheresponsemessagehasapayloadanddoesnothaveaContent-Encodingheader​ field, itshall have a Content-Length header field specifying the length in octets (bytes)​ of the payload.​

Shall not be present if the message has a Content-Encoding header field. Shall be​ present otherwise, even is the size of the payload is zero.​

- Standard -​

8.5 Status Codes​

Each response message contains a status-code.​

The most common HTTP status codes used are listed in Table 8.5-1 Most of these codes are described in detail in [RFC7231]. IANA​ maintains the HTTP Status Code Registry [IANA HTTP Status Code Registry], which contains a complete list of registered status​ codes.​

(Non-Authoritative Information)​ Section 5.7.2 and [RFC7230] [RFC7231] Section 6.3.4.​

- Standard -​

Note​

This status code was previously (erroneously) used to indicate that only​ some of a payload was stored.​

Redirection​The 3xx (Redirection) class of status code indicates that further action needs to be taken by the user agent to fulfill the​ request.​

Client Error​The 4xx (Client Error) class of status code indicates that the user agent has erred.​

For all these error codes,the origin server should return a payload containing an explanation of the error situation, and​ whether it is a temporary or permanent condition, except when responding to a HEAD request.​

- Standard -​