Table of Contents
List of Figures
List of Tables
The information in this publication was considered technically sound by the consensus of persons engaged in the development and approval of the document at the time it was developed. Consensus does not necessarily mean that there is unanimous agreement among every person participating in the development of this document.
NEMA standards and guideline publications, of which the document contained herein is one, are developed through a voluntary consensus standards development process. This process brings together volunteers and/or seeks out the views of persons who have an interest in the topic covered by this publication. While NEMA administers the process and establishes rules to promote fairness in the development of consensus, it does not write the document and it does not independently test, evaluate, or verify the accuracy or completeness of any information or the soundness of any judgments contained in its standards and guideline publications.
NEMA disclaims liability for any personal injury, property, or other damages of any nature whatsoever, whether special, indirect, consequential, or compensatory, directly or indirectly resulting from the publication, use of, application, or reliance on this document. NEMA disclaims and makes no guaranty or warranty, expressed or implied, as to the accuracy or completeness of any information published herein, and disclaims and makes no warranty that the information in this document will fulfill any of your particular purposes or needs. NEMA does not undertake to guarantee the performance of any individual manufacturer or seller's products or services by virtue of this standard or guide.
In publishing and making this document available, NEMA is not undertaking to render professional or other services for or on behalf of any person or entity, nor is NEMA undertaking to perform any duty owed by any person or entity to someone else. Anyone using this document should rely on his or her own independent judgment or, as appropriate, seek the advice of a competent professional in determining the exercise of reasonable care in any given circumstances. Information and other standards on the topic covered by this publication may be available from other sources, which the user may wish to consult for additional views or information not covered by this publication.
NEMA has no power, nor does it undertake to police or enforce compliance with the contents of this document. NEMA does not certify, test, or inspect products, designs, or installations for safety or health purposes. Any certification or other statement of compliance with any health or safety-related information in this document shall not be attributable to NEMA and is solely the responsibility of the certifier or maker of the statement.
This DICOM Standard was developed according to the procedures of the DICOM Standards Committee.
The DICOM Standard is structured as a multi-part document using the guidelines established in [ISO/IEC Directives, Part 2].
PS3.1 should be used as the base reference for the current parts of this standard.
DICOM® is the registered trademark of the National Electrical Manufacturers Association for its standards publications relating to digital communications of medical information, all rights reserved.
HL7® and CDA® are the registered trademarks of Health Level Seven International, all rights reserved.
SNOMED®, SNOMED Clinical Terms®, SNOMED CT® are the registered trademarks of the International Health Terminology Standards Development Organisation (IHTSDO), all rights reserved.
LOINC® is the registered trademark of Regenstrief Institute, Inc, all rights reserved.
This standard specifies a web-based service for accessing and presenting DICOM (Digital Imaging and Communications in Medicine) objects (e.g., images, medical imaging reports). This is intended for distribution of results and images to healthcare professionals. It provides a simple mechanism for accessing a DICOM object, through HTTP/HTTPS protocol, using DICOM UIDs (Unique Identifiers). Data may be retrieved either in a presentation-ready form as specified by the requester (e.g., JPEG or GIF) or in a native DICOM format. It does not support facilities for web searching of DICOM images. This standard relates only to DICOM Objects (not to non-DICOM objects). Access control beyond the security mechanisms generally available to web applications is outside the scope of this standard.
Systems claiming conformance to this standard shall function in accordance with all its mandatory sections.
The following normative documents contain provisions that, through reference in this text, constitute provisions of this part of DICOM. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. However, parties to agreements based on this part of DICOM are encouraged to investigate the possibility of applying the most recent editions of the normative documents indicated below. For undated references, the latest edition of the normative document referred to applies. Members of ISO and IEC maintain registers of currently valid International Standards.
[ISO/IEC Directives, Part 2] 2016/05. 7.0. Rules for the structure and drafting of International Standards. http://www.iec.ch/members_experts/refdocs/iec/isoiecdir-2%7Bed7.0%7Den.pdf .
[ISO/IEC 10918-1] 1994. JPEG Standard for digital compression and encoding of continuous-tone still images. Part 1 - Requirements and implementation guidelines.
[ISO/IEC 10646] 2003. Information Technology - Universal Multiple-Octet Coded Character Set (UCS). ISO/IEC 10646-2003 is the same as Unicode Version 4.0, available at http://unicode.org .
[RFC822] August 1982. Standard for ARPA Internet Text Messages. http://tools.ietf.org/html/rfc822 .
[RFC1945] May 1996. Hypertext Transfer Protocol Version 1.0 (HTTP/1.0) . http://tools.ietf.org/html/rfc1945 .
[RFC2045] November 1996. Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. http://tools.ietf.org/html/rfc2045 .
[RFC2046] November 1996. Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. http://tools.ietf.org/html/rfc2046 .
[RFC2387] August 1998. The MIME Multipart/Related Content-type. http://tools.ietf.org/html/rfc2387 .
[RFC2818] May 2000. HTTP Over TLS. http://tools.ietf.org/html/rfc2818 .
[RFC2978] October 2000. IANA Charset Registration Procedures. http://tools.ietf.org/html/rfc2978 .
[RFC3240] February 2002. Digital Imaging and Communications in Medicine (DICOM) - Application/dicom MIME Sub-type Registration. http://tools.ietf.org/html/rfc3240 .
[RFC3986] Uniform Resource Identifiers (URI): Generic Syntax. http://tools.ietf.org/html/rfc3986 .
[RFC4627] July 2006. The application/json Media Type for JavaScript Object Notation (JSON). http://tools.ietf.org/html/rfc4627 .
[RFC5234] January 2008. Augmented BNF for Syntax Specifications: ABNF. http://tools.ietf.org/html/rfc5234 .
[RFC6365] September 2011. Terminology Used in Internationalization in the IETF. http://tools.ietf.org/html/rfc6365 .
[RFC6455] December 2011. The WebSocket Protocol. http://tools.ietf.org/html/rfc6455 .
[RFC6570] March 2012. URI Template. http://tools.ietf.org/html/rfc6570 .
[RFC6838] January 2013. Media Type Specifications and Registration Procedures. http://tools.ietf.org/html/rfc6838 .
[RFC7230] June 2014. Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. http://tools.ietf.org/html/rfc7230 .
[RFC7231] June 2014. Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. http://tools.ietf.org/html/rfc7231 .
[RFC7232] June 2014. Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests. http://tools.ietf.org/html/rfc7232 .
[RFC7233] June 2014. Hypertext Transfer Protocol (HTTP/1.1): Range Requests. http://tools.ietf.org/html/rfc7233 .
[RFC7234] June 2014. Hypertext Transfer Protocol (HTTP/1.1): Caching. http://tools.ietf.org/html/rfc7234 .
[RFC7235] June 2014. Hypertext Transfer Protocol (HTTP/1.1): Authentication. http://tools.ietf.org/html/rfc7235 .
[RFC7236] June 2014. Initial Hypertext Transfer Protocol (HTTP) Authentication Scheme Registrations. http://tools.ietf.org/html/rfc7236 .
[RFC7237] June 2014. Initial Hypertext Transfer Protocol (HTTP) Method Registrations. http://tools.ietf.org/html/rfc7237 .
[RFC7405] December 2014. Case-Sensitive String Support in ABNF. http://tools.ietf.org/html/rfc7405 .
[RFC7540] May 2015. Hypertext Transfer Protocol Version 2 (HTTP/2). http://tools.ietf.org/html/rfc7540 .
[HL7 CDA R2] 2005. HL7 Version 3 Standard: Clinical Document Architecture Framework, Release 2. http://www.hl7.org/documentcenter/private/standards/cda/r2/cda_r2_normativewebedition2010.zip .
[IHE ITI TF-2x Appendix V] . . IT Infrastructure Technical Framework - Web Services for IHE Transactions. http://www.ihe.net/uploadedFiles/Documents/ITI/IHE_ITI_TF_Vol2x.pdf .
[WADL] 31 August 2009. . Member Submission - Web Application Description Language. http://www.w3.org/Submission/wadl/ .
For the purposes of this part of DICOM, the following terms and definitions apply.
A query parameter that specifies one or more media types acceptable for the representation(s) contained in the response. See Section 6.1.1.5.
One or more character sets acceptable to the user agent in the response. See Section 6.1.2.1.
One or more media type acceptable to the user agent in the response. See Section 6.1.1.4.
A Uniform Resource Identifier in accordance with [RFC3986] that identifies an octet-stream representing the value of a DICOM attribute.
A media type in which bulk data (such as Pixel Data) extracted from DICOM instances is encoded. See Section 6.1.1.8.
A media type in which DICOM instances are encoded. See Section 6.1.1.8.
A query parameter that specifies one or more character sets for the representation(s) contained in the response. See Section 6.1.2.2.
An instance of a data object as defined by PS3.3 that has been allocated an unique identifier in the format specified for SOP Instance UID in PS3.3 and has been chosen as an object to be saved securely for some period of time. Within the DICOM Standard, a DICOM Object is referred to as a Composite Service Object Pair (SOP) Instance.
A set of categories for the content of DICOM SOP Instances. Examples include images, video, and text. See Section 6.1.1.2.
The term HTTP as used in this Standard means the Hypertext Transport Protocol versions 1.0, 1.1 or 2. See [RFC1945], [RFC7230] and [RFC7540].
The term HTTPS as used in this Standard means the Hypertext Transport Protocol Secure versions 1.0, 1.1 or 2. See [RFC2818] and [RFC7230].
A non-DICOM media type into which DICOM instances may be transformed in order to display them using commonly available non-DICOM software, for example browsers. See Section 6.1.1.3.
The character sets selected by the origin server for the response payload. See Section 6.1.2.4.
The media type selected by the origin server for the response payload. See Section 6.1.1.7.
A service enabling the user agent to retrieve DICOM Objects managed by an origin serven, through HTTP/HTTPS protocol.
A RESTful Web service is a Web service implemented using REST architecture and HTTP (see http://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf)
A standard RGB color space defined in [IEC 61966-2.1].
Unicode UTF-8 character set defined in [ISO/IEC 10646].
DICOM Web Services use the HTTP and HTTPS protocols as its transport medium. Web Services supports versions 1.0, 1.1 and 2 of the protocol. If an origin server supports version 2, it shall also support version 1.1. If an origin server supports version 1.1, it shall also support version 1.0.
It is recommended that user agents that want to use HTTP/2 first initiate an HTTP/1.1 connection to the origin server and then upgrade to HTTP/2. If the upgrade fails then the user agent can still use the HTTP/1.1 connection. [RFC7540] Section 3 explains how to initiate HTTP/2 connections.
The interaction shall be as shown in Figure 6-1.
Multiple communications modes are possible:
Media types are identifiers used to define the data format of a representation. HTTP uses media types in the Content-Type and Accept header fields in order to provide open and extensible data typing and type negotiation. The syntax of media types is:
media-type = type "/" subtype *(OWS ";" OWS parameter)
type = token subtype = token parameter = token "=" (token / quoted-string) )
The <type>/<subtype> may be followed by parameters in the form of name=value pairs.
The type, subtype, and parameter name tokens are case-insensitive, but the case sensitivity of parameter values depends on the semantics of the parameter name. The presence or absence of a parameter might be significant to the processing of a media-type, depending on its definition within the media type registry.
A parameter value can be transmitted either as a token or quoted-string. The quoted and unquoted values are equivalent.
Media types are defined in [RFC7231] Section 3.1.1.1.
IANA maintains a registry of media types at http://www.iana.org/assignments/media-types/media-types.xhtml.
Some of the services defined in this Standard support the multipart media types [RFC2387]. The syntax is:
multipart-media-type = "multipart" "/" subtype *( OWS ";" OWS parameter )
The "application/multipart-related" media type is used by the RS services. Its syntax is:
multipart-related = "multipart/related" OWS ";" OWS "type" "=" DQUOTE media-type DQUOTE OWS ";" OWS "boundary" "=" boundary [related-parameters]
boundary = 0*69bchar bchar-nospace bchar = bchar-nospace / SP bchar-nospace = DIGIT / ALPHA / "'" / "(" / ") " / "+" / "_" / "," / "-" / "." / "/" / ":" / "=" / "?" "/" / ":" / "=" / "?" related-parameters = [";" "start" "=" cid] [";" "start-info" "=" cid-list] cid-list = cid cid-list cid = token / quoted-string
The "type" parameter is required. It contains the media type of the "root" body part. It always contains the special character "/" and thus requires quote marks.
The <cid> is a content identifier. It should be unique for each part of the multipart message.
Typically, the "start" and "start-info" parameters are not specified, and the "root" is the first body part.
Table 6.1.1-1 defines Resource Categories that correspond to different SOP Classes. The following sections map each Resource Category to appropriate DICOM and Rendered media types.
Table 6.1.1-1. Resource Categories
This category includes all resources that are instances of a multi-frame SOP Class, that are not video and that contain more than one frame. |
|
This category includes all resources that contain more than one frame and: |
|
This category includes all resources that:
|
|
This category includes all resources that are not included above. |
DICOM instances may be converted by a rendering process into non-DICOM media types in order to display them using commonly available non-DICOM software, such as browsers.
A DICOM SOP Instance containing an image could be rendered into the image/jpeg or image/png Rendered Media Types.
A DICOM SOP Instance containing a multi-frame image in a lossless transfer syntax could be rendered into a video/mpeg or video/mp4 Rendered Media Type.
A DICOM SOP Instance containing a Structured Report could be rendered into a text/html, text/plain, or application/pdf Rendered Media Type.
Rendered Media Types are usually consumer format media types. Some of the same non-DICOM media types are also used as Bulk Data Media Types, that is, for encoding bulk data extracted from Encapsulated Pixel Data (used with compressed Transfer Syntaxes), without applying a rendering process; see Section 6.1.1.8.
Table 6.1.1-2 specifies the meaning of media type requirement terms used in Table 6.1.1-3 and the tables in Section 6.1.1.8.
Table 6.1.1-2. Definition of Media Type Requirement Terms
The origin server shall return this media type when none of the Acceptable Media Types (see Section 6.1.1.4) are supported. The origin server shall support this media type. |
|
Origin servers that support Web Services shall support rendering instances of different Resource Categories into Rendered Media Types as specified in Table 6.1.1-3.
When an image/jpeg media type is returned, the image shall be encoded using the JPEG baseline lossy 8 bit Huffman encoded non-hierarchical non-sequential process defined in ISO/IEC 10918-1.
The origin server may support additional rendered media types.
A transfer syntax media type parameter is not permitted for Rendered Media Types.
The term Acceptable Media Types denotes the media types that are acceptable to the user agent in the response. The Acceptable Media Types are those specified in:
All requests that expect a response with a payload, shall include the Accept header field. The response to a request without an Accept header field shall be 406 (Not Acceptable). Even if specific media types are provided in the <accept> query parameter, an Accept header field with one or more values shall be present, at a minimum */*.
The Acceptable Media Types shall be either DICOM media-types or Rendered media types, but not both. If the Acceptable Media Types contains both DICOM and Rendered Media Types, the origin server shall return 409 (Conflict).
The user agent may specify the relative degree of preference for media types, whether in the <accept> query parameter or the Accept header field, using the <weight> parameter. See [RFC7231] Section 5.3.1.
weight = OWS ";" OWS "q=" qvalue qvalue = ("0" ["." 0*3DIGIT]) / ("1" ["." 0*3("0") ])
The <accept> query parameter is primarily designed for use in hyperlinks (URLs) embedded in documents, where the Accept header field is not accessible. It is similar to the Accept header field, except that it shall not have wildcards (<type>/* or */*).
The <accept> query parameter has the following syntax:
accept = accept-name "=" 1#(media-type [weight]) accept-name = "%s" quoted-string
The "%s" that prefixes the <accept-name> specifies that it is a case sensitive token. See [RFC7405].
Its value is a comma-separated list of one or more <media-type>s, possibly including parameters. It shall be supported by the origin server. It is optional for the user agent.
The <accept-name> of the <accept> query parameter is defined by the Service. It is case-sensitive. Table 6.1.1-4 contains the <accept-name> of the <accept> query parameter for some services.
The <accept> query parameter should not be used when the user agent can specify the values in the Accept header field.
All media types present in an <accept> query parameter shall be compatible with a media range in the Accept header field, either explicitly or implicitly through wildcards.
For example, the presence of image/jpeg in the <accept> query parameter will require the Accept header field to include one of the following values: image/jpeg, image/*, or */*.
See Section 6.1.4.
The Accept header field is used to specify media ranges acceptable to the user agent. It has the following syntax:
Accept = 1#(media-range [weight])
media-range = media-type / type "/" "*" parameters / "*/*" parameters parameters ; See Section 6.1.1
The Accept header field shall be present. Its value shall be a comma-separated list of one or more media ranges acceptable in the response. See [RFC7231] Section 5.3.2.
A media range is either a media-type or a wildcard. Wildcards use the asterisk ("*") to group media types into ranges, with <type>/* indicating all subtypes of that type, and */* indicating all media types from the target's Resource's Category.
For example, the media range "image/*" matches "image/jpeg", which is the default media type for the Single Frame Image Resource Category, and "text/*" matches "text/html", which is the default media type for the Text Resource Category. The "*/*" media range matches the default media type for the target's Resource Category.
If the origin server receives a request without an Accept header field, but that might have a response payload, it shall return a 406 (Not Acceptable).
Any Accept header field values that are not valid or not supported shall be ignored.
The Selected Media Type is the media type selected by the origin server for the response payload. The media types in the <accept> query parameter and the media ranges in the Accept header field shall each be separately prioritized according to the rules defined in [RFC7231] Section 5.3.1.
For multipart payloads the Selected Media Type is determined independently for each message part in the response.
The Selected Media Type of each message part depends on the Resource Category of the Instance and the Acceptable Media Types for that Resource Category.
The Selected Media Type is chosen as follows:
Select the representation with the highest priority supported media type for that category in the <accept> query parameter, which is compatible with the Accept header field.
If no media type in the <accept> query parameter is supported, select the highest priority supported media type for that category in the Accept header field, if any.
Otherwise, select the default media type for the category if the Accept header field contains a wildcard media range matching the category, if any.
For a set of media types in the <accept> query parameter (step 2 above), or for a set of media ranges in the Accept header field (step 3 above), the highest priority supported media type is determined as follows:
Assign a <qvalue> of 1 to any member of the set that does not have a one.
Assign each representation supported by the origin server the <qvalue> of the most specific media type that it matches.
Select the representation with the highest <qvalue>. If there is a tie, the origin server shall determine which is returned.
For example, consider an origin server that receives a request with the following Accept header field:
Accept: text/*; q=0.5, text/html; q=0.4, text/html; level=1, text/html; level=2; q=0.7, image/png, */*; q=0.4
Suppose that for the resource indicated in the request, the origin server supports representations for the following media types:
text/html(regular, level 1 and level 2) text/rtf text/plain text/x-latex
These media types are assigned the following <qvalue>s, based on the media ranges above:
Although "image/png" has been assigned a default <qvalue> of 1.0, it is not among the supported media types for this resource, and thus is not listed.
The selected media type is "text/html; level=1" since it is the supported media type in the Text Category with the highest qvalue.
This section defines the media types used to represent DICOM Instances and bulk data. It describes:
The media type and transfer syntax parameter for DICOM PS3.10 Files
The media types that can be used for the bulk data of single and multi-frame images and video extracted from Instances.
The syntax of DICOM Media Types including their transfer syntax and character set parameters.
The meaning of Acceptable Transfer Syntaxes and Selected Transfer Syntax.
The media types defined in this section are distinct from those into which DICOM Instances may be rendered (which are defined in Section 6.1.1.3); some of the same media types are used for both rendered content and bulk data.
Depending on the service, the media types may be single part or multipart, and may have required or optional transfer syntax and/or character set parameters.
Table 6.1.1.8-1a, Table 6.1.1.8-1b, Table 6.1.1.8-1c and Table 6.1.1.8-1d specify the media types used to encode different representations of DICOM Instances for the Web Services. These media types apply to all Resource Categories and have default encodings for images and video data elements contained in the Instances.
The definitions of media type requirements are provided in Table 6.1.1-2.
Table 6.1.1.8-1a. Media Types for DICOM PS3.10 Files
Encodes Composite SOP Instances in the DICOM File Format defined in PS3.10 Section 7 “DICOM File Format”. |
See Table 6.1.1.8-2 |
See Table 6.1.1.8-2 |
Table 6.1.1.8-1c. Media Types for DICOM Uncompressed Bulk Data
Encodes a Bulkdata object as a stream of uncompressed bytes, in little endian byte order. NoteThis is the same encoding defined in PS3.19 for the returned value of the getData() call for uncompressed Bulk Data. |
See Table 6.1.1.8-3a |
Table 6.1.1.8-1d. Media Types for DICOM Compressed Bulk Data
Encodes Bulkdata values, which in the case of compressed Pixel Data for WADO-RS services, will have each frame encoded as a separate part of a multipart response and identified by an appropriate Content-Type header. |
See Table 6.1.1.8-3b |
Table 6.1.1.8-2 specifies, by Resource Category (see Table 6.1.1-1) , the application/dicom media type for PS3.10 Files, along with the default and allowed Transfer Syntax UID combinations for each resource category for the Web Services. The default media type for the Resource Category shall be returned when the origin server supports none of the Acceptable Media Types.
If no transfer-syntax parameter is specified for the media type for PS3.10 Files (application/dicom) then the Explicit VR Little Endian Transfer Syntax "1.2.840.10008.1.2.1" shall be used.
This is different from the Default Transfer Syntax defined in Section 10.1 “DICOM Default Transfer Syntax” in PS3.5 , which is Implicit VR Little Endian.
Table 6.1.1.8-2. Transfer Syntax UIDs for 'application/dicom' Media Type Instances in the Image or Video Resource Categories
Table 6.1.1.8-3a and Table 6.1.1.8-3b specify, by Resource Category (see Table 6.1.1-1) , the various media types for bulk data, along with the default and allowed media types and Transfer Syntax UID combinations for each resource category for the RS service.
No entries are specified for the WADO-URI service, because it does not support separate retrieval of bulk data.
These media types can be used to retrieve image or video bulk data encoded in a specific Transfer Syntax.
Table 6.1.1.8-3a. Media Types and Transfer Syntax UIDs for Uncompressed Pixel Data in Bulk Data Values
Table 6.1.1.8-3b. Media Types and Transfer Syntax UIDsfor Compressed Pixel Data in Bulk Data Values
The Implicit VR Little Endian (1.2.840.10008.1.2) ,and Explicit VR Big Endian (1.2.840.10008.1.2.2) transfer syntaxes shall not be used with Web Services.
If a transfer syntax parameter for a DICOM Media Type is not specified in a request or response, the Transfer Syntax in the response shall be the Transfer Syntax specified as the default for the Resource Category and media type combination in Table 6.1.1.8-3a or Table 6.1.1.8-3b.
The origin server may support additional Transfer Syntaxes.
The compressed bulk data of each part of a multipart payload contains only the compressed bit stream and not the DICOM PS3.5 Encapsulated Sequence or Delimiter Items.
For the media type image/dicom+jpeg Transfer Syntaxes, the image may or may not include the JFIF marker segment. See Section 8.2.1 “JPEG Image Compression” in PS3.5 .
For the media type image/dicom+jp2 and image/dicom+jpx Transfer Syntaxes, the image does not include the jp2 marker segment. See Section 8.2.4 “JPEG 2000 Image Compression” in PS3.5 and Section A.4.4 “JPEG 2000 Image Compression” in PS3.5 .
The resource on the origin server may have been encoded in the Deflated Explicit VR Little Endian (1.2.840.10008.1.2.1.99) transfer syntax. If so, the origin server may inflate it, and then convert it into an Acceptable Transfer Syntax. Alternatively, if the user-agent allowed a Content-Encoding header field of 'deflate', then the deflated bytes may be transferred unaltered, but the transfer syntax parameter in the response should be the Explicit VR Little Endian transfer syntax.
Compressed multi-frame image bulk data is encoded as one frame per part. E.g., each frame of a JPEG 2000 multi-frame image will be encoded as a separate part with an image/jp2 media type, rather than as a single part with a video/mj2 (RFC 3745) or uncompressed application/octet-stream media type.
Video bulk data is encoded as a single part containing all frames. E.g., all frames of an MPEG-4 video will be encoded as a single part with a video/mp4 (RFC 4337) media type.
Many of the media types used for compressed Pixel Data transferred as bulk data values are also used for consumer format media types. The browser may not be able to display the encoded data directly, even though some of the same media types are also used for encoding rendered Pixel Data; see Section 6.1.1.3.
E.g., the media type for bulk data values of lossless 16-bit JPEG 10918-1 encoded Pixel Data is "image/jpeg", the same as might be used for 8-bit JPEG 10918-1 encoded Pixel Data, whether extracted as bulk data, or rendered. The transfer syntax parameter of the Content-Type header field is useful to signal the difference.
The syntax of DICOM Media Types is:
dicom-media-type = (dcm-singlepart / dcm-multipart) [dcm-parameters]
dcm-singlepart = dcm-mt-name dcm-multipart ; see Section 6.1.1.8.1.1. dcm-parameters = transfer-syntax-mtp ; see Section 6.1.1.8.1.2. / charset-mtp ; see Section 6.1.1.8.1.3. dcm-mt-name = dicom / dicom-xml / dicom-json ; DICOM Media Type name dicom = "application/dicom" dicom-xml = "application/dicom+xml dicom-json = "application/dicom+json" octet-stream = "application/octet-stream"
All DICOM Media Types may have a transfer syntax parameter, but its usage may be constrained by the service for which they are used.
Note. The application/dicom+xml and application/dicom+json Media Types may have a transfer syntax parameter in order to specify the encoding of inline binary data.
All DICOM Media Types may have a character set parameter, but its usage may be constrained by the service for which they are used.
The syntax of multipart media types is:
dcm-multipart = "multipart/related" OWS ";" OWS "type" "=" dcm-mp-mt-name OWS ";" OWS "boundary=" boundary [dcm-parameters] [related-parameters]
dcm-mp-mt-name = dicom / dicom-xml / dicom-json / octet-stream
See Section 6.1.1.1 for the definition of boundary and related-parameters.
Each multipart media type shall include a "type" parameter that defines the media type of the parts, and shall also include a "boundary" parameter that specifies the boundary string that is used to separate the parts.
All DICOM Media Types may have a single transfer syntax parameter, but its usage may be constrained by the service for which they are used.
RS origin servers shall support the transfer syntax parameter.
Transfer syntax parameters are forbidden in URI requests and responses.
transfer-syntax-mtp = OWS ";" OWS $s"transfer-syntax=" ts-value ts-value = transfer-syntax-uid / "*" transfer-syntax-uid ; a UID from PS3.6 Table A-1 with a UID Type of Transfer Syntax
The value of the transfer syntax parameter may be either a Transfer Syntax UID or the token "*".
For example, to specify that 1.2.840.10008.1.2.4.50 is the acceptable Transfer Syntaxes, an Accept header field could be:
Accept: application/dicom; transfer-syntax=1.2.840.10008.1.2.4.50
A DICOM Media Type may only have one transfer syntax parameter and it shall have only one value.
Per RFC 6838 Media Type Specifications and Registration Procedures, it is an error for a specific parameter to be specified more than once. If a choice of Transfer Syntaxes is acceptable. more than one media type may be provided in the Accept header with different q parameter values to indicate preference. E.g., to specify that 1.2.840.10008.1.2.4.50 and to specify that 1.2.840.10008.1.2.4.57 are acceptable but 1.2.840.10008.1.2.4.50 is preferred, an Accept header field could be:
Accept: multipart/related; application/dicom;transfer-syntax=1.2.840.10008.1.2.4.50, application/dicom;transfer-syntax=1.2.840.10008.1.2.4.57;q=0.5
The wildcard value "*" indicates that the user agent will accept any Transfer Syntax. This allows, for example, the origin server to respond without needing to transcode an existing representation to a new Transfer Syntax, or to respond with the Explicit VR Little Endian Transfer Syntax regardless of the Transfer Syntax stored.
If an Origin server supports the transfer syntax parameter, it shall support the wildcard value.
Origin servers that support the transfer syntax parameter shall specify in their conformance statement those values of transfer syntax parameter that are supported in the response.
User agents that support the transfer syntax parameter shall specify in their conformance statement those transfer syntax parameter values that may be supplied in the request.
The DICOM Media Type character set parameter is used to specify Acceptable Character Sets for the response. A DICOM Media Type may have a single character set parameter, which shall have only a single value.
charset-mtp = OWS ";" OWS %s"charset" "=" charset
All DICOM Media Types shall have a Default Character Set of UTF-8.
See Section 6.1.2 for character set details.
The transfer syntax query parameter specifies a comma-separated list of one or more Transfer Syntax UIDs, as defined in PS3.6. It is optional.
transfer-syntax-qp = ts-parameter-name "=" (1#transfer-syntax-uid / "*") ts-parameter-name = %s quoted-string
The URI service defines the ts-parameter-name to be "transferSyntax", which is case-sensitive.
The RS service uses the transfer syntax parameter in the "accept" query parameter (see Section 6.1.1.5) and the transfer syntax query parameter is not supported.
Each media type in the Acceptable Media Types has an associated set of Acceptable Transfer Syntaxes.
The Acceptable Transfer Syntaxes for a media type can be specified in any of the following ways, depending on the service:
The transfer syntax media type parameter contained in the accept query parameter (see Section 6.1.1.5)
The value(s) contained in the transfer syntax query parameter (see Section 6.1.1.8.4)
The transfer syntax media type parameter contained in the Accept header field.
The Selected Transfer Syntax is the transfer syntax selected by the origin server to encode a single message part in the response.
The origin server shall first determine the Selected Media Type as defined in Section 6.1.1.7 and then determine the Selected Transfer Syntax.
If the Selected Media Type was contained in the accept query parameter, then the Selected Transfer Syntax is determined as follows:
If the Selected Media Type was contained in the Accept header field, then the Selected Transfer Syntax is determined as follows:
The URI and RS APIs support the following DICOM Media Types:
uri-media-type = dicom rs-media-types = (dcm-multipart / dicom-json) [dcm-parameters]
Support for the transfer syntax and charset media type parameters is required for RS services.
Support for the "transfer-syntax" and "charset" parameters is forbidden for URI Services (i.e., they may not present in the request or the response).
HTTP uses charset names to indicate or negotiate the character encoding of textual content in representations [RFC6365] Section 3.3.
Character sets may be identified using the value in the IANA Preferred MIME Name column in the IANA Character Set Registry http://www.iana.org/assignments/character-sets/character-sets.xhtml.
Character sets may be identified by using the DICOM Defined Terms for the character set. See Section C.12.1.1.2 “Specific Character Set” in PS3.3 , and Section 6.1.2.3 “Encoding of Character Repertoires” in PS3.5 .
The origin server shall support the "UTF-8" charset name for RS Retrieve Rendered, but is not required to support the DICOM Defined Term "ISO_IR 192".
charset = token / defined-term / DQUOTE defined-term DQUOTE
Some DICOM Defined Terms for character sets contain space characters; and shall be enclosed in double quotes in HTTP header fields and percent encoded in URLs.
The Conformance Statement shall document all supported character sets. The Retrieve Capabilities response for all RS Services shall also document all supported character sets.
A request without any <charset> query parameter or Accept-Charset header field implies that the user agent will accept any charset in the response.
Annex D contains a mapping of some Specific Character Set (0008,0005) Defined Terms to IANA charset tokens.
The term Acceptable Character Sets denotes the character sets that are acceptable to the user agent in the response. The Acceptable Character Sets are those specified in:
When the Acceptable Character Sets contains a list of one or more Defined Terms they should be ordered as specified in Section C.12.1.1.2 “Specific Character Set” in PS3.3 and Section 6.1.2.3 “Encoding of Character Repertoires” in PS3.5 . This is especially important for ISO 2022 character sets.
Any Accept-Charset header field values that are not defined in Annex D or not supported shall be ignored.
The character set query parameter is primarily designed for use in hyperlinks (URLs) embedded in documents, where the Accept-Charset header field is not accessible.
The character set query parameter has the following syntax:
charset-qp = name "=" 1#(charset [weight])
The character set query parameter value is a comma-separated list of one or more charsets. It is similar to the Accept-Charset header field, except that it shall not have wildcards. It shall be supported by the origin server. It is optional for the user agent.
All charsets present in the character set query parameter may have a corresponding character set in the Accept-Charset header field, either explicitly or implicitly through wildcards.
The name of the character set query parameter is defined by the Service. Table 6.1.2-1 contains the names of the character set query parameter for some services.
If this parameter has a value that is not supported it shall be ignored.
See Section 6.1.4.
The Accept-Charset header field has the following syntax:
Accept-Charset = 1#(charset [weight]) / ("*" [weight])
The user agent may provide a list of Acceptable Character Sets in the Accept-Charset header field of the request. Its value is a comma-separated list of one or more <charset>s and/or the wildcard value ("*"). It shall be supported by the origin server. It is optional for the user agent.
The values of the Accept-Charset header field values are prioritized by their <weight> parameter.
If no wildcard ("*") is present, then any character sets not explicitly mentioned in the header field are considered "not acceptable" to the client.
A request without an Accept-Charset header field implies that the user agent will accept any charset in response.
If the media type defines a "charset" parameter, it should be included with the media type in the Accept header field, rather than in the Accept-Charset header field.
Any Accept-Charset header field values that are not supported shall be ignored.
The origin server shall determine the Selected Character Set(s) as follows:
Select the first supported character set in the "charset" parameter(s) of the Selected Media Type.
Otherwise, select the highest priority supported <charset> in the <character-set> query parameter.
Otherwise, select the highest priority supported <charset> in the Accept-Charset header field.
Otherwise, if the Selected Media Type has a default character set that is supported, select it.
Rendered representations returned in the response shall have all contained strings returned in the Selected Character Sets.
If the character set in which the target resource is encoded is not the Selected CharacterSet:
This means that some SOP Instances may be convertible and others will not be, even though they have the same Specific Character Set (0008,0005).
All origin servers shall support conversion to the UTF-8 character set for RS Rendered Retrieve.
If the user agent chooses to perform its own conversion rather than have it done by the origin server:
The user agent may omit the Accept-Charset header field or send the "*" wildcard
The user agent may transcode the character set replacing all unknown characters with a suitable replacement. For example:
A question mark ("?"), or other similar character indicating an unknown character.
The corresponding Unicode Code Point for the character, represented as "U+xxxx".
The four characters "\nnn", where "nnn" is the 3 digit octal representation of each byte (see Section 6.1.2.3 “Encoding of Character Repertoires” in PS3.5 ).
The Content-Type header field specifies the media type of the payload. It should only be present when a payload is present, and any media type parameters shall specify the encoding of the corresponding message part.
In particular, a DICOM Media Type used as the value of a Content-Type header field shall have zero or one transfer syntax parameter (see Section 6.1.1.8.1.2), and zero or one charset parameter (see Section 6.1.1.8.1.3), which corresponds to the character encoding of the corresponding message part.
Content-Type: dicom-media-type +transfer-syntax-mtp +charset-mtp
If there is a conflict between the Transfer Syntax specified in the media type and the one specified in the File Meta Information Transfer Syntax UID (0002,0010) attribute, the latter has precedence.
[RFC3986] does not permit an empty query component, i.e., if the "?" appears in the Target URI, then there shall be at least one Query Parameter in the URI.
The origin server may define and support additional Query Parameters, or additional Query Parameter values for an existing Query Parameter. If an origin server defines new or extends existing Query Parameters, they shall be included in the Conformance Statement and, if the service supports it, the Retrieve Capabilities response.
The origin server shall ignore any unsupported Query Parameters. The origin server shall process the request as if the unsupported parameters were not present, and should include a payload containing an appropriate warning or error message.
If a supported Query Parameter has an invalid value, the origin server shall return a 400 (Bad Request) error response, and should include should include a payload containing an appropriate warning or error message.
The HTTP Request used shall use the GET method as defined in [RFC7230].
The parameters of the <query> component of the Request-URI to be sent to the web Server through the HTTP GET method request shall be represented as defined in [RFC3986].
See Section 6.1.4.
Specifies the Acceptable Media Types for the response payload. See Section 6.1.1.4. The name of the parameter is "contentType", which is case-sensitive. Its syntax is:
accept = %s"contentType" "=" 1#rendered-media-type / 1#uri-media-type
The WADO-URI service supports Rendered Media Types (see Section 6.1.1.3) or the uri-media-type (see Section 6.1.1.8.5).
The transfer-syntax and charset media type parameters are forbidden in the request.
WADO-URI origin servers support transfer syntax and charset query parameters, which have been used instead of transfer-syntax and charset media type parameters since the inception of the service, even though this is different from the approach used by the later introduced WADO-RS service, which uses transfer-syntax and charset media type parameters instead of query parameters.
Only one transferSyntax query parameter is permitted and it may have only one UID value. See Section 8.2.11.
Specifies the Acceptable Character Sets for the response payload. See Section 6.1.2.1. The name of the parameter is "charset", which is case-sensitive. Its syntax is:
charset-qp = %s"charset" "=" 1#(charset [weight])
The Accept header field specifies the media type(s) acceptable to the user agent in the response. It shall be present. See Section 6.1.1.6 for details.
The Accept-Charset header field specifies the character set(s) acceptable to the user agent in the response. It is optional. See Section 6.1.2.3 for details.
The response shall be an HTTP Response Message as specified in [RFC7230].
The media type shall be 'application/dicom', as specified in [RFC3240].
The body content shall be a DICOM File that includes File Meta Information as defined in PS3.10.
Since the Selected Media Type is a DICOM Media Type, the representations in the response shall be encoded using the Selected Transfer Syntax. See Section 6.1.1.8.4.
The WADO-URI service supports Rendered Media Types (see Section 6.1.1.3) or the uri-media-type (see Section 6.1.1.8.5).
The transfer-syntax and charset media type parameters are forbidden in the request.
WADO-URI user agents may not depend on the presence of transfer syntax and charset media type parameters, since these have been absent since the inception of the service and are forbidden, even though this is different from the approach used by the later introduced WADO-RS service, which returns transfer-syntax and charset media type parameters in the response. The Transfer Syntax used can be determined from the PS3.10 File Meta Information.
The media type shall be one on the media types defined in the contentType parameter, preferably the most desired by the user agent, and shall be in any case compatible with the Accept header field of the GET method.
The content shall be a single MIME part containing the object to be retrieved.
Multiple objects in a response are not supported by this standard. The parameters select only a single object to retrieve. Most current user agents are able to retrieve single objects, within a "non multipart" MIME body, and are not able to support multipart/related or multipart/mixed responses.
The DICOM RESTful Service defines several action types. An implementation shall support all the following six action types:
This action retrieves the set of DICOM instances associated with a given study unique identifier (UID). The response can be DICOM or bulk data depending on the "Accept" type, and is encapsulated in a multipart MIME response.
This action retrieves the set of DICOM instances associated with a given study and series UID. The response can be DICOM or bulk data depending on the "Accept" type, and is encapsulated in a multipart MIME response.
This action retrieves the DICOM instance associated with the given study, series, and SOP Instance UID. The response can be DICOM or bulk data depending on the "Accept" type, and is encapsulated in a multipart MIME response.
This action retrieves the DICOM frames for a given study, series, SOP Instance UID, and frame numbers. The response is pixel data, and encapsulated in a multipart MIME response.
This action retrieves the bulk data for a given BulkDataURI.
This action retrieves the DICOM instances presented as the study, series, or instance metadata with the bulk data removed.
WADO-RS requests may contain the following query parameters:
"accept" The <accept> query parameter is specified in Section 6.1.1.5. The syntax is:
accept = "accept=" 1#media-type
"charset" The <character-set> query parameter is specified in Section 6.1.2.2. The syntax is:
character-set = "charset" = 1#charset
WADO-RS requests shall include an "Accept" header field (see Section 6.1.1.6) specifying the Acceptable Media Types.
WADO-RS requests may optionally support the "Accept-Charset" header field. See Section 6.1.2.3.
See Section 6.1.4.
Responses shall be encoded in the following manner: (see Figure 6.5-1).
DICOM Files as defined in PS3.10, encoded in a requested Transfer Syntax (Explicit VR Little Endian by default) with one message part per DICOM Instance.
XML as described in the Native DICOM Model defined in PS3.19 with one message part per XML object.
JSON as a DICOM JSON Model Object as defined in Annex F.
Uncompressed bulk and pixel data in a Little Endian format using the application/octet-stream media type with one message part per bulk data item.
The compressed pixel data consists of the compressed bit stream only, and shall not include any Sequence Items and Delimiters from the PS3.5 Encapsulated Pixel Data format.
Compressed pixel data shall be encoded using the application/dicom media type and transfer syntaxes specified in Table 6.1.1.8-2.
The request header field Content-Type is used to indicate the media type of the payload.
If the origin server returns XML or JSON responses that contain bulk data references, the origin server is required to support uncompressed bulk data (application/octet-stream) and must be able to deliver all bulk data in that form (i.e., decompress it from its original form if necessary) unless it is available only in a lossy-compressed format.
The DICOM Media Types supported are defined in Section 6.1.1.8.5.
The Bulk Data Media Types supported are defined in Table 6.1.1.8-1c and Table 6.1.1.8-1d.
The origin server shall support the transfer-syntax and charset media type parameters.
This action retrieves the set of DICOM instances associated with a given study unique identifier (UID). The response can be DICOM or bulk data depending on the "Accept" type, and is encapsulated in a multipart MIME response.
The specific Services resource to be used for the RetrieveStudy action shall be as follows:
Accept - A comma-separated list of representation schemes, in preference order, which will be accepted by the service in the response to this request. The types allowed for this request header are as follows:
multipart/related; type="application/dicom" [dcm-parameters]
Specifies that the response can be DICOM Instances encoded in PS3.10 format. If transfer-syntax is not specified in the dcm-parameters the origin server shall use the Explicit VR Little Endian Transfer Syntax "1.2.840.10008.1.2.1" for each Instance (see Section 6.1.1.8).
multipart/related; type="application/octet-stream" [dcm-parameters]
Specifies that the response can be Little Endian uncompressed bulk data. See Section 6.1.3.
multipart/related; type="{media-type}" [dcm-parameters]
Specifies that the response can be compressed pixel data encoded using the media types and transfer syntaxes specified in Table 6.1.1.8-3b. See Section 6.1.3.
The Server shall provide the document(s) indicated in the request. In order to parse the bulk data items it is necessary to also retrieve the metadata for the Study.
The Server shall return the document(s), or an error code when the document(s) cannot be returned. If the server cannot convert all of the data to any of the requested media types/Transfer Syntaxes, then an error code shall be returned, either a "Not Acceptable" response if no data is returned or a "Partial Content" response if only some data is returned.
The client can compare the SOP Instance UIDs or BulkDataURIs in the metadata and the message response to determine which bulk data elements have been returned.
All response formats have a media type of multipart/related with a message boundary separator. The response format depends on the Accept header specified in the request.
See Section 6.1.3.
See Section 6.1.3.
The entire multipart response contains all bulk data for the specified Study that can be converted to one of the requested media types.
Each item in the response is one of:
an uncompressed bulk data element encoded in Little Endian binary format with the following headers:
an Encapsulated Document (0042,0011) bulk data element from a SOP Instance in the Study encoded in the media type specified in MIME Type of Encapsulated Document (0042,0012) in the Instance with the following header fields:
a compressed bulk data element from a SOP Instance in the Study encoded in a single-frame compression {MediaType} with the following headers:
a compressed frame from a multi-frame SOP Instance in the Study encoded in a single-frame media type with the following headers:
all of the compressed frames from a SOP Instance in the Study encoded in a video media type with the following headers:
This action retrieves the set of DICOM instances associated with a given study and series UID. The response can be DICOM or bulk data depending on the "Accept" type, and is encapsulated in a multipart MIME response.
The specific resource to be used for the RetrieveSeries action shall be as follows:
Accept - A comma-separated list of representation schemes, in preference order, which will be accepted by the service in the response to this request. The types allowed for this request header are as follows:
multipart/related; type="application/dicom" [dcm-parameters]
Specifies that the response can be DICOM Instances encoded in PS3.10 format. If transfer-syntax is not specified in the dcm-parameters the origin server shall use the Explicit VR Little Endian Transfer Syntax "1.2.840.10008.1.2.1" for each Instance (see Section 6.1.1.8).
multipart/related; type="application/octet-stream" [dcm-parameters]
Specifies that the response can be Little Endian uncompressed bulk data. See Section 6.1.3.
multipart/related; type="{media-type}" [dcm-parameters]
Specifies that the response can be compressed pixel data encoded using the media types and transfer syntaxes specified in Table 6.1.1.8-3b. See Section 6.1.3.
The Server shall provide the document(s) indicated in the request. In order to parse the bulk data items it is necessary to also retrieve the corresponding metadata for the specified Study, Series, or Instance.
The Server shall return the document(s), or an error code when the document(s) cannot be returned. If the server cannot convert all of the data to any of the requested media types/Transfer Syntaxes, then an error code shall be returned, either a "Not Acceptable" response if no data is returned or a "Partial Content" response if only some data is returned.
The client can compare the SOP Instance UIDs or BulkDataURIs in the metadata and the message response to determine which bulk data elements have been returned.
All response formats have a media type of multipart/related with a message boundary separator. The response format depends on the Accept header specified in the request.
See Section 6.1.3.
See Section 6.1.3.
The entire multipart response contains all bulk data for the specified Series that can be converted to one of the requested media types.
Each item in the response is one of:
an uncompressed bulk data element encoded in Little Endian binary format with the following headers:
an Encapsulated Document (0042,0011) bulk data element from a SOP Instance in the Series encoded in the media type specified in MIME Type of Encapsulated Document (0042,0012) in the Instance with the following header fields:
a compressed bulk data element from a SOP Instance in the Series encoded in a single-frame media type with the following headers:
a compressed frame from a multi-frame SOP Instance in the Series encoded in a single-frame media type with the following headers:
all of the compressed frames from a multi-frame SOP Instance in the Series encoded in a video media type with the following headers:
This action retrieves the DICOM instance associated with the given study, series, and SOP Instance UID. The response can be DICOM or bulk data depending on the "Accept" type, and is encapsulated in a multipart MIME response.
The specific resource to be used for the RetrieveInstance action shall be as follows:
{SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances/{SOPInstanceUID}, where
{SERVICE} is the base URL for the service. This may be a combination of protocol (either http or https), host, port, and application.
{StudyInstanceUID} is the study instance UID for a single study.
{SeriesInstanceUID} is the series instance UID for a single series.
{SOPInstanceUID} is the SOP Instance UID for a single SOP Instance.
Accept - A comma-separated list of representation schemes, in preference order, which will be accepted by the service in the response to this request. The types allowed for this request header are as follows:
multipart/related; type="application/dicom" [dcm-parameters]
Specifies that the response can be DICOM Instances encoded in PS3.10 format. If transfer-syntax is not specified in the dcm-parameters the origin server shall use the Explicit VR Little Endian Transfer Syntax "1.2.840.10008.1.2.1" for each Instance (see Section 6.1.1.8).
multipart/related; type="application/octet-stream" [dcm-parameters]
Specifies that the response can be Little Endian uncompressed bulk data. See Section 6.1.3.
multipart/related; type="{media-type}" [dcm-parameters]
Specifies that the response can be compressed pixel data encoded using the media types and transfer syntaxes specified in Table 6.1.1.8-3b. See Section 6.1.3.
The Server shall provide either a single DICOM PS3.10 object for the SOP Instance or one or more bulk data items. In order to parse the bulk data items it is necessary to also retrieve the corresponding metadata for the specified Study, Series, or Instance.
The Server shall return the document(s), or an error code when the document(s) cannot be returned. If the server cannot convert all of the bulk data to any of the requested media types, then an error code shall be returned, either a "Not Acceptable" response if no data is returned or a "Partial Content" response if only some data is returned.
The client can compare the BulkDataURIs in the metadata and the message response to determine which bulk data elements have been returned.
All response formats have a media type of multipart/related with a message boundary separator. The response format depends on the Accept header specified in the request.
See Section 6.1.3.
See Section 6.1.3.
The entire multipart response contains all bulk data for the specified Instance that can be converted to one of the requested media types.
Each item in the response is one of:
an uncompressed bulk data element encoded in Little Endian binary format with the following headers:
an Encapsulated Document (0042,0011) bulk data element encoded in the media type specified in MIME Type of Encapsulated Document (0042,0012) in the Instance with the following header fields:
a compressed bulk data element from a SOP Instance encoded in a single-frame media type with the following headers:
a compressed frame from a multi-frame SOP Instance encoded in a single-frame media type with the following headers:
all of the compressed frames from a multi-frame SOP Instance encoded in a video media type with the following headers:
This action retrieves the DICOM frames for a given study, series, SOP Instance UID, and frame numbers. The response is pixel data, and is encapsulated in a multipart MIME response.
The specific Services resources to be used for the RetrieveFrames action shall be as follows:
{SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances/{SOPInstanceUID}/frames/{FrameList}, where
{SERVICE} is the base URL for the service. This may be a combination of protocol (either http or https), host, port, and application.
{StudyInstanceUID} is the study instance UID for a single study.
{SeriesInstanceUID} is the series instance UID for a single series.
{SOPInstanceUID} is the SOP Instance UID for a single SOP Instance.
{FrameList} is a comma or %2C separated list of one or more non duplicate frame numbers. These may be in any order (e.g., ../frames/1,2,4,3).
multipart/related; type="application/octet-stream" [dcm-parameters]
Specifies that the response can be Little Endian uncompressed pixel data
multipart/related; type="{media-type}" [dcm-parameters]
Specifies that the response can be compressed pixel data encoded using the media types and transfer syntaxes specified in Table 6.1.1.8-3b. See Section 6.1.3.
The Server shall provide the document(s) indicated in the request. In order to parse the bulk data items it is necessary to also retrieve the corresponding metadata for the specified Study, Series, or Instance.
The Server shall return the document(s) or an error code when the document(s) cannot be returned. If the server cannot encode the pixel data using any of the requested media types, then an error status shall be returned.
All response formats has a media type of multipart/related with a message boundary separator.
The entire multipart response contains all requested Frames for the specified Instance.
Each item in the response is one of:
an uncompressed frame encoded in Little Endian binary format (as specified in Table 6.1.1.8-3a) with the following headers:
a compressed frame encoded in a single-frame media type (as specified in Table 6.1.1.8-3b) with the following headers:
all of the compressed frames encoded in a video media type (as specified in Table 6.1.1.8-3b) with the following headers:
The frames will be returned in the order specified by the Frame List.
This action retrieves the bulk data for a given BulkDataURI.
The specific Services resource to be used for the RetrieveBulkdata action shall be as follows:
multipart/related; type="application/octet-stream" [dcm-parameters]
Specifies that the response can be Little Endian uncompressed bulk data. See Section 6.1.3.
multipart/related; type="{media-type}" [dcm-parameters]
Specifies that the response can be compressed pixel data encoded using the media types and transfer syntaxes specified in Table 6.1.1.8-3b. See Section 6.1.3.
See [RFC7233] Section 3.1. If omitted in the request the server shall return the entire bulk data object.
The Server shall provide the document(s) indicated in the request.
The server shall always return the same bulk data for a specified BulkData URL if the data is available.
If the resource specified by the BulkData URL is not available, the server shall return:
The server determines the period of time a BulkData URL resource is available.
The Server shall return the document(s) or an error code when the document(s) cannot be returned. If the server cannot encode the pixel data using any of the requested media types, then an error status shall be returned.
All response formats have a media type of multipart/related with a message boundary separator. The response format depends on the Accept header specified in the request.
multipart/related; type="application/octet-stream"; boundary={MessageBoundary} [dcm-parameters]
multipart/related; type="{media-type}"; boundary={MessageBoundary} [dcm-parameters]
where {media-type} is of compressed pixel data encoded as specified in Table 6.1.1.8-3b.
See Section 6.1.3.
The entire multipart response contains all bulk data that can be converted to one of the requested media types.
Each part in the response is one of:
an uncompressed bulk data element encoded in Little Endian binary format with the following headers:
an Encapsulated Document (0042,0011) bulk data element from a SOP Instance in the Study encoded in the media type specified in MIME Type of Encapsulated Document (0042,0012) in the Instance with the following header fields:
a compressed bulk data element from a SOP Instance encoded in a single-frame media type with the following headers:
Content-Type: {media-type} [dcm-parameters]
where {media-type} is of compressed pixel data encoded as specified in Table 6.1.1.8-3b.
a compressed frame from a multi-frame SOP Instance encoded in a single-frame media type with the following headers:
Content-Type: {media-type} [dcm-parameters]
where {media-type} is of compressed pixel data encoded as specified in Table 6.1.1.8-3b.
all of the compressed frames from a SOP Instance encoded in a video media type with the following headers:
Content-Type: {media-type} [dcm-parameters]
where {media-type} is of compressed pixel data encoded as specified in Table 6.1.1.8-3b.
If the Range header is specified in the request, the server shall return only the specified bytes of the bulk data object. See [RFC7233] Section 4.
This action retrieves the DICOM instances presented as the study, series, or instance metadata with the bulk data removed. The response is metadata for the DICOM attributes.
The study, series, or instance metadata includes all attributes; however, a RESTful Service is permitted to replace the Value Field of an attribute with a BulkDataURI for attributes with Value Representations (VR) of DS, FL, FD, IS, LT, OB, OD, OF, OL, OW, SL, SS, ST, UC, UL, UN, US, and UT. The client can use the BulkDataURI with the RetrieveBulkData action to retrieve the original Value Field of that attribute.
The server is not required to replace any attribute with a BulkDataURI; this is intended to allow the server to provide clients with metadata of a reasonably small size by leaving out large data Value Fields.
OB, OD, OF, OL, OW and UN Attributes not replaced with a BulkDataURL are encoded as XML Base64 binary values.
Some DICOM instances, such as SR documents, may be entirely described in the metadata.
The specific Services resources to be used for the RetrieveMetadata action shall be as follows:
{SERVICE} is the base URL for the service. This may be a combination of protocol (either http or https), host, port, and application.
{StudyInstanceUID} is the study instance UID for a single study.
{SeriesInstanceUID} is the series instance UID for a single series.
{SOPInstanceUID} is the SOP Instance UID for a single SOP Instance.
multipart/related; type="application/dicom+xml"
Specifies that the response should be PS3.19 XML. WADO-RS origin servers shall support this Media Type. See Table 6.1.1.8-1b.
Specifies that the response should be DICOM JSON (see Annex F). WADO-RS origin servers shall support this Media Type. See Table 6.1.1.8-1b.
The Server shall provide the document(s) indicated in the request. The Server shall return the document(s) or an error code when the document(s) could not be returned.
The response has a media type of either:
The response must include the URL attribute for each BulkData element.
The metadata is consistent with the characteristics of the bulk data on the server. If bulk data is requested using specified Transfer Syntaxes or media types, it is possible that the bulk data retrieved may be inconsistent with the metadata. For example, for a Study whose DICOM Tag (0028,2110) "LossyImageCompression" is set to "00", indicating no lossy compression, calling RetrieveStudy and requesting a lossy compression media type will provide pixel data that is inconsistent with the metadata. It is the responsibility of the client to deal with these inconsistencies appropriately.
The response is a JSON array that contains all metadata for the specified Study.
Each element in the array is the DICOM JSON encoded metadata for an Instance (see Annex F).
The following error codes are defined and shall be used to report any of the associated error and warning situations. Other error codes may be present for other error and warning situations.
Table 6.5-2. Error Codes
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.
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
Zero or more query parameters as defined in Section 6.5.8.1.2. |
|
One or more Rendered Media Types See Section 6.1.1.3. |
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
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 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.
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" )
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.
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.
The "quality" parameter specifies the requested quality of the rendered images. It has the following syntax:
%s"quality=" integer
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.
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.
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
%s"viewport=" vw "," vh ["," [sx] "," [sy] "," [sw] "," [sh] ]
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.
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 .
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
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).
The target resource(s) are rendered according to the query parameters, by applying the transformations according to the appropriate rendering pipeline specified in Section N.2 “Pixel Transformation Sequence” in PS3.4 .
It the target resource is not a single instance, Presentation State Instances contained in the target resource shall not be rendered.
Rendered images shall contain no more than 8 bits per channel.
If the target resource is a 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 references a multi-frame image, then the response will contain all frames specified by the target resource, or if the Presentation State instance references a series, then the response will contain all instances contained in that series.
If the target resource is a Presentation State Instance, then only the Charset, Annotation, Quality, and Viewport parameters may also be present. If any other Retrieve Rendered Transaction Query Parameters are present the response shall be 400 (Bad Request), and should include a payload containing an appropriate error message.
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 PS3.4.
If there is more than one image in the response they shall be ordered according to the:
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 Presentation Size Mode is TRUE SIZE it shall be treated as SCALE TO FIT.
If the Presentation Size Mode is SCALE TO FIT, the origin server shall scale the Specified Displayed Area in the Presentation State, maintaining its original aspect ratio, until either the rendered image width is the same as the viewport width or the rendered image height is the same as the viewport height, whichever comes first. In other words, viewport scaling makes the displayed area selection as large as possible, within the viewport, without overflowing the viewport area and without distorting the image. If the viewport parameter is not present, the returned images shall have the dimensions of the Specified Displayed Area.
If the Presentation Size Mode is MAGNIFY, then the referenced images shall be scaled to the Specified Displayed Area in the Presentation State, and then they shall be cropped to the size specified by the "viewport" parameter. If the request does not contain a "viewport" parameter, then the referenced images shall not be cropped.
Any Specified Displayed Area relative annotations in the Presentation State shall be rendered relative to the Specified Displayed Area within the Presentation State, not the size of the viewport.
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 rendered images is not defined by this standard.
The Retrieve Rendered service has the following response message syntax:
version SP status-code SP reason-phrase CRLF Content-Type: rendered-media-type CRLF *(header-field CRLF) CRLF payload
is a Rendered Media Type; see Section 6.1.1.3. |
|
The response shall include a status code from Table 6.5.8-3, if applicable; otherwise, an appropriate status code shall be used.
Table 6.5.8-3. Common Status Codes
The origin server shall be capable of returning representations in Rendered Media Types identified as default and required in Section 6.1.1.3.
The STOW-RS Service defines one action type. An implementation shall support the following action type:
All request messages are HTTP multipart messages. The organization of SOP Instances into message parts depends on whether the SOP Instances are structured as PS3.10 binary instances, or metadata and bulk data.
PS3.10 binary instances shall be encoded with one message part per DICOM Instance.
When the request message contains compressed bulk data with a Content Type that is one of the media types specified in Table 6.6-1, the request may omit the Image Pixel Description Macro attributes and the origin server will derive them from the compressed bit stream. Some media types do not directly correspond to a DICOM Transfer Syntax and the origin server will transform the received bit stream into an uncompressed or lossless (reversibly) compressed Transfer Syntax.
This allows a user agent to use consumer media types to encode the pixel data even though it may not have:
If the supplied compressed bit stream is in a lossless (reversible) format, the intent is to allow full fidelity retrieval of the decompressed pixels, not the format in which it happened to be submitted.
If the supplied compressed bit stream is in a lossy (irreversible) format, there will be a corresponding DICOM Transfer Syntax, and the origin server is not expected to recompress it causing further loss.
Metadata and bulk data requests will be encoded in the following manner:(see Figure 6.5-1 Mapping between IOD and HTTP message parts):
All XML request messages shall be encoded as described in the Native DICOM Model defined in PS3.19 with one message part per XML object; the attributes of the Image Pixel Description Macro may be omitted for the media types specified in Table 6.6-1.
All JSON request messages shall be encoded as an array of DICOM JSON Model Objects defined in Annex F in a single message part; the attributes of the Image Pixel Description Macro may be omitted for the media types specified in Table 6.6-1.
Bulk data (with the exception of encapsulated document element) and uncompressed pixel data shall be encoded in a Little Endian format using the application/octet-stream media type with one message part per bulk data item.
An Encapsulated Document (0042,0011) bulk data element shall be encoded using the media-type from the MIME Type of Encapsulated Document (0042,0012) attribute with one message part per bulk data item.
Compressed pixel data shall be encoded using the media types and transfer syntaxes specified in Table 6.1.1.8-3b. Media types corresponding to several DICOM Transfer Syntax UIDs may require a transfer-syntax parameter to convey the Transfer Syntax the compressed pixel data is encoded in.
The request header field Content-Type is used to indicate the media type of the payload.
The Service shall support uncompressed bulk data (multipart/related; type="application/octet-stream").
Table 6.6-1 contains a list of media types containing compressed pixel data from which an origin server shall be able to derive the Image Pixel Data Description Macro Attribute values.
Requirements are specified in Table 6.6-1 as follows:
Transform - No DICOM Transfer Syntax exists; shall be transformed by the origin server into an uncompressed or lossless compressed Transfer Syntax (the choice of which is at the discretion of the origin server).
Unchanged - Shall be encapsulated in the corresponding DICOM Transfer Syntax without further lossy compression
In the case of pixel data supplied as image/gif or image/png, the origin server may transform the color representation from indexed color to true color (RGB) as necessary to conform to any Photometric Interpretation constraints specified by the IOD (i.e., if PALETTE COLOR is not permitted); such a transformation is considered lossless.
If the number of bits per channel of an image/png file is not supported by the IOD, a lossless transformation cannot be performed.
An animated image/gif will be converted into a multi-frame image; image/png does not support animation, and MNG is not included in Table 6.6-1.
Any transparency information present in an image/gif or image/png file will be discarded, since DICOM does not support the concept of transparency.
If an alpha channel is supplied in an image/png file, and the IOD does not support the RGBA Photometric Interpretation, the alpha channel will be discarded (i.e., considered to consist of all opaque values, consistent with the policy of discarding any transparency information).
This action stores one or more DICOM instances associated with one or more study instance unique identifiers (SUID). The request message can be DICOM or metadata and bulk data depending on the "Content-Type", and is encapsulated in a multipart request body.
The specific Service resource to be used for the Store Instances action shall be as follows:
{SERVICE}/studies[/{StudyInstanceUID}], where
{SERVICE} is the base URL for the service. This may be a combination of scheme (either HTTP or HTTPS), host, port, and application.
{StudyInstanceUID} (optional) is the study instance UID for a single study. If not specified, instances can be from multiple studies. If specified, all instances shall be from that study; instances not matching the StudyInstanceUID shall be rejected.
It is not necessary that the study referenced by the StudyInstanceUID in the resource (and in the provided instances) exists on the server, however it is necessary that it be a valid UID. The client may have obtained an appropriate UID from elsewhere or generated it as described in Chapter 9 “Unique Identifiers (UIDs)” in PS3.5 and Annex B “Creating a Privately Defined Unique Identifier (Informative)” in PS3.5.
Content-Type - The representation scheme being posted to the RESTful service. The types allowed for this request header are as follows:
multipart/related; type="application/dicom"; boundary={messageBoundary}
Specifies that the post is PS3.10 binary instances. All STOW-RS providers shall accept this Content-Type.
multipart/related; type="application/dicom+xml"; boundary={messageBoundary}
Specifies that the post is PS3.19 XML metadata and bulk data. All STOW-RS providers shall accept this Content-Type.
multipart/related; type="application/dicom+json"; boundary={messageBoundary}
Specifies that the post is DICOM JSON metadata and bulk data. All STOW-RS providers shall accept this Content-Type.
The XML Metadata and Bulk Data Request Message has a multipart body.
The multipart request body contains all the metadata and bulk data to be stored. If the number of bulk data parts does not correspond to the number of unique BulkDataURIs in the metadata then the entire message is invalid and will generate an error status line.
Each body part is either DICOM PS3.19 XML metadata or a bulk data item from a SOP Instance sent as part of the Store operation. The first part of the multipart message shall be XML metadata.
Each bulk data item shall be preceded by all metadata items that contain a reference to it.
The first part in the multipart request will contain the following HTTP headers:
Subsequent items will contain the following HTTP headers (order is not guaranteed):
Metadata and its associated bulk data shall always be sent in the same POST request.
The JSON Metadata and Bulk Data Request Message has a multipart body.
The multipart request body contains all the metadata and bulk data to be stored. If the number of bulk data parts does not correspond to the number of unique BulkDataURIs in the metadata then the entire message is invalid and will generate an error status line.
The first part in the multipart request will contain a JSON array of DICOM JSON Model Objects (defined in Annex F). Each array element is the metadata from a SOP Instance sent as part of the Store operation. This message part will have the following headers:
Subsequent items will be one of the following:
JSON Metadata and its associated bulk data shall always be sent in the same POST request.
The origin server may coerce or replace values of attributes such as Patient Name, ID, Accession Number, for example, during import of media from an external institution, reconciliation against a master patient index, or reconciliation against an imaging procedure order. The Service may correct, or replace incorrect values, such as Patient Name or ID, for example, when incorrect worklist item was chosen or operator input error occurs.
If any element is coerced or corrected, the Original Attribute Sequence (0400,0561) shall be included in the DICOM Object that is stored and may be included in the PS3.18 XML Store Instances Response Module in the response.
For more information on populating the Original Attribute Sequence, see Section C.12.1 “SOP Common Module” in PS3.3 .
The origin server shall encapsulate or convert any compressed pixel data received as bulk data into an appropriate DICOM Transfer Syntax, as defined in Table 6.6-1.
The origin server shall populate the attributes of the Image Pixel Description Macro, if absent from the Metadata, by deriving them from the compressed pixel data received as bulk data.
The stored Instance(s) shall fully conform to the IOD and encoding requirements of PS3.3 and PS3.5, respectively.
The origin server shall return a status of 415 (Unsupported Media Type) if it cannot convert the bulk data or populate the Image Pixel Description Macro Attribute values.
The RESTful Service shall return an HTTP status line, including a status code and associated textual phrase for the entire set of stored SOP Instances, followed by a message body containing the Store Instances Response Module as defined in Table 6.6.1-2. The message body shall be encoded as either:
If the status for all instances included in the POST request is Success, the RESTful Service shall return an "HTTP 200 - Success" response code.
If the status for all instances included in the POST request is Failure, the RESTful Service shall return an appropriate failure status line with a response code from Table 6.6.1-1. If there are instance specific errors, the response code shall be a 409 and the response payload shall contain the Store Instances Response Module, which contains additional information regarding instance errors.
In all other conditions, the RESTful Service shall return an "HTTP 202 - Accepted" response code. The response payload may contain a Store Instances Response Module, which specifies additional information regarding instance warnings or failures.
Table 6.6.1-1. HTTP Standard Response Code
HTTP Status Codes for Failures and Warnings are returned in HTTP response headers. It is recommended that the text returned in the HTTP Response Warning contain a DICOM Status Code and descriptive reason as defined in Section 6.6.1.3.2.1. For example,
The message body shall provide appropriate status codes for individual SOP Instances indicating success, warning, or failure as defined below.
The message body may also include details about the processing of attributes by the service.
The message body shall also include details of failures that are not associated with a specific SOP Instance.
Table 6.6.1-2 defines the Attributes for referencing SOP Instances that are contained in a Store Instances Response Module in the response message body.
Table 6.6.1-2. Store Instances Response Module Attributes
The URL where the Study is available for retrieval via a WADO-RS Retrieve Study service. |
|||
A sequence of Items where each Item references a single SOP Instance for which storage could not be provided. |
|||
>Table 10-11 “SOP Instance Reference Macro Attributes” in PS3.3 |
|||
The reason that storage could not be provided for this SOP Instance. |
|||
A sequence of Items where each Item references a single SOP Instance that was successfully stored. Required if one or more SOP Instances were successfully stored. |
|||
>Table 10-11 “SOP Instance Reference Macro Attributes” in PS3.3 |
|||
The URL where the SOP Instance is available for retrieval via a WADO-RS service. |
|||
The reason that this SOP Instance was accepted with warnings. |
|||
Sequence of Items containing all attributes that were removed or replaced by other values. |
|||
Identification of the system that removed and/or replaced the attributes. |
|||
Reason for the attribute modification. Defined terms are: COERCE = Replace values of attributes such as Patient Name, ID, Accession Number, for example, during import of media from an external institution, or reconciliation against a master patient index. CORRECT = Replace incorrect values, such as Patient Name or ID, for example, when incorrect worklist item was chosen or operator input error. |
|||
Sequence that contains all the Attributes, with their previous values, that were modified or removed from the main data set. |
|||
>>Any Attribute from the main data set that was modified or removed; may include Sequence Attributes and their Items. |
|||
Reasons not associated with a specific SOP Instance that storage could not be provided. Each Item references a single storage failure. Required if there are one or more failures not associated with a specific SOP Instance. |
|||
The reason that storage could not be provided for this message item. |
Table 6.6.1-3 defines the semantics for which the associated value shall be used for the Warning Reason (0008,1196):
Table 6.6.1-3. Store Instances Response Warning Reason Values
The STOW-RS Service modified one or more data elements during storage of the instance. See Section 6.6.1.3. |
|||
The STOW-RS Service discarded some data elements during storage of the instance. See Section 6.6.1.3. |
|||
The STOW-RS Service observed that the Data Set did not match the constraints of the SOP Class during storage of the instance. |
Additional codes may be used for the Warning Reason (0008,1196) to address the semantics of other issues.
In the event that multiple codes may apply, the single most appropriate code shall be used.
Table 6.6.1-4 defines the semantics for which the associated value shall be used for the Failure Reason (0008,1197). Implementation specific warning and error codes shall be defined in the conformance statement:
Table 6.6.1-4. Store Instances Response Failure Reason Values
Additional codes may be used for the Failure Reason (0008,1197) to address the semantics of other issues.
In the event that multiple codes may apply, the single most appropriate code shall be used.
The following is an example of a PS3.18 XML Store Instances Response Module in the response message body containing 2 failed SOP Instances, 1 successful SOP Instance, and 1 accepted SOP Instance with a warning:
<?xml version="1.0" encoding="utf-8" xml:space="preserve"?> <NativeDicomModel xmlns="http://dicom.nema.org/PS3.19/models/NativeDICOM" xsi:schemaLocation="http://dicom.nema.org/PS3.19/models/NativeDICOM" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <DicomAttribute tag="00081198" vr="SQ" keyword="FailedSOPSequence"> <Item number="1"> <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID"> <Value number="1">1.2.840.10008.3.1.2.3.1</Value> </DicomAttribute> <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID"> <Value number="1"> 2.16.124.113543.6003.1011758472.49886.19426.2085542308</Value> </DicomAttribute> <DicomAttribute tag="00081197" vr="US" keyword="FailureReason"> <Value number="1">290</Value> </DicomAttribute> </Item> <Item number="2"> <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID"> <Value number="1">1.2.840.10008.3.1.2.3.1</Value> </DicomAttribute> <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID"> <Value number="1"> 2.16.124.113543.6003.1011758472.49886.19426.2085542309</Value> </DicomAttribute> <DicomAttribute tag="00081197" vr="US" keyword="FailureReason"> <Value number="1">290</Value> </DicomAttribute> </Item> </DicomAttribute> <DicomAttribute tag="00081199" vr="SQ" keyword="ReferencedSOPSequence"> <Item number="1"> <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID"> <Value number="1">1.2.840.10008.5.1.4.1.1.2</Value> </DicomAttribute> <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID"> <Value number="1"> 2.16.124.113543.6003.189642796.63084.16748.2599092903</Value> </DicomAttribute> <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL"> <Value number="1"> https://wadors.hospital.com/studies/2.16.124.113543.6003.1154777499.30246.19789.3503430045/ series/2.16.124.113543.6003.2588828330.45298.17418.2723805630/ instances/2.16.124.113543.6003.189642796.63084.16748.2599092903</Value> </DicomAttribute> </Item> <Item number="2"> <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID"> <Value number="1">1.2.840.10008.5.1.4.1.1.2</Value> </DicomAttribute> <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID"> <Value number="1"> 2.16.124.113543.6003.189642796.63084.16748.2599092905</Value> </DicomAttribute> <DicomAttribute tag="00081196" vr="US" keyword="WarningReason"> <Value number="1">45056</Value> </DicomAttribute> <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL"> <Value number="1"> https://wadors.hospital.com/studies/2.16.124.113543.6003.1154777499.30246.19789.3503430045/ series/2.16.124.113543.6003.2588828330.45298.17418.2723805630/ instances/2.16.124.113543.6003.189642796.63084.16748.2599092905</Value> </DicomAttribute> </Item> </DicomAttribute> <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL"> <Value number="1"> https://wadors.hospital.com/studies/2.16.124.113543.6003.1154777499.30246.19789.3503430045</Value> </DicomAttribute> </NativeDicomModel>
DICOM QIDO-RS defines several action types. An implementation shall support the following action types:
This action searches for DICOM Studies that match specified search parameters and returns a list of matching studies and the requested attributes for each study.
This action searches for DICOM Series that match specified search parameters and returns a list of matching series and the requested attributes for each series.
This action searches for DICOM Instances that match specified search parameters and returns a list of matching instances and the requested attributes for each instance.
The specific resources to be used for the search actions shall be as follows:
Each {attributeID} must refer to one of:
Series IE attributes (SearchForSeries or SearchForInstances requests only)
Composite Instance IE attributes (SearchForInstances requests only)
Additional Query/Retrieve Attributes (Section C.3.4 in PS3.4 )
See Section 6.7.1.1.1 for {attributeID} and {value} encoding rules
The “limit” parameter value is an unsigned integer, which specifies the maximum number of results the origin server shall return. If the “limit” parameter is not present the origin server shall return the maximum number of results in a single response that it supports.
The “offset” parameter value is an unsigned integer, which specifies the number of results the origin server shall skip before the first returned result. If the “offset” query parameter is not present, its value is 0.
See Section 6.1.4.
Each {attributeID} query key shall be unique unless the associated DICOM Attribute allows UID List matching (see Section C.2.2.2.2 in PS3.4 ), in which case each {value} will be interpreted to be an element of the UID List.
The acceptable values for {value} are determined by the types of matching allowed by C-FIND for its associated {attributeID} (see Section C.2.2.2 in PS3.4 ). All characters in {value} that are disallowed for URIs shall be percent-encoded. See [RFC3986] for details.
If an {attributeID} is passed as the value of an "includefield" query key this is equivalent to C-FIND Universal matching for the specified attribute (see Section C.2.2.2.3 in PS3.4 ).
{attributeID} can be one of the following:
{dicomTag} is the eight character hexadecimal string corresponding to the Tag of a DICOM Attribute (see Chapter 6 in PS3.6 ).
{dicomKeyword} is the Keyword of a DICOM Attribute (see Chapter 6 in PS3.6 ).
Examples of valid QIDO-RS URLs:
http://dicomrs/studies?PatientID=11235813&StudyDate=20130509
http://dicomrs/studies?00100010=SMITH*&00101002.00100020=11235813&limit=25
http://dicomrs/studies?00100010=SMITH*&OtherPatientIDsSequence.00100020=11235813
http://dicomrs/studies?PatientID=11235813&includefield=00081048&includefield=00081049&includefield=00081060
http://dicomrs/studies?PatientID=11235813&StudyDate=20130509-20130510
http://dicomrs/studies?StudyInstanceUID=1.2.392.200036.9116.2.2.2.2162893313.1029997326.94587%2c1.2.392.200036.9116.2.2.2.2162893313.1029997326.94583
The origin server shall perform the query indicated in the request.
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 results, if the set of matching results on the origin server has not changed.
The results returned in the response are determined as follows:
is the maximum number of results the origin server allows in a single response.
is the value of the "offset" query parameter. It is the index of the first element in results.
is the length of the returned results. It is equal to the minimum of:
is the number of remaining matches. It is equal to: M-(offset+R).
The response is determined as follows:
If (R<=0) then there were 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 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
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 "limit" and "offset" parameters may be inconsistent
The response will be in an Acceptable Media Type.
The matching semantics for each attribute are determined by the types of matching allowed by C-FIND (see Section C.2.2.2 in PS3.4 ).
Matching results shall be generated according to the Hierarchical Search Method described in Section C.4.1.3.1.1 in PS3.4 .
Combined Datetime matching shall be performed (see Section C.2.2.2.5 in PS3.4 ).
If a QIDO-RS provider is acting as a proxy for a C-FIND SCP that does not support combined Datetime matching the QIDO-RS provider will need to perform a C-FIND request using Date only and filter results outside the time range before returning a QIDO-RS response
If the TimezoneOffsetFromUTC / 00080201 query key is included in the request, dates and times in the request are to be interpreted in the specified time zone.
If the "fuzzymatching=true" query key/value is included in the request and it is supported then additional fuzzy semantic matching of person names shall be performed in the manner specified in the DICOM Conformance Statement for the service provider.
If the "fuzzymatching=true" query key/value is included in the request and it is not supported, the response shall include the following HTTP Warning header (see [RFC7234] Section 5.5):
Warning: 299 {SERVICE}: "The fuzzymatching parameter is not supported. Only literal matching has been performed."
where {SERVICE} is the base URL for the QIDO-RS provider. This may be a combination of scheme (http or https), host, port, and application.
The Warning header is separate from the Status Line and does not affect the returned Status Code.
Providers of the SearchForStudies service shall support the search query keys described in Table 6.7.1-1:
Providers of the SearchForSeries service shall support the search query keys described in Table 6.7.1-1a:
If {StudyInstanceUID} is not specified in the URL and this form of Relational Query is supported, all Study-level attributes specified in Table 6.7.1-1 shall also be supported.
Providers of the SearchForInstances service shall support the search query keys described in Table 6.7.1-1b:
If {StudyInstanceUID} is not specified in the URL and this form of Relational Query is supported, all Study-level attributes specified in Table 6.7.1-1 shall also be supported.
If {SeriesInstanceUID} is not specified in the URL and this form of Relational Query is supported, all Series-level attributes specified in Table 6.7.1-1a shall also be supported.
For each matching Study, the QIDO-RS provider shall return all attributes in accordance with Table 6.7.1-2:
Table 6.7.1-2. QIDO-RS STUDY Returned Attributes
Series Level and Instance Level attributes passed as "includefield" query values shall not be returned.
The above list is consistent with those required for IHE RAD-14 (see http://www.ihe.net/Technical_Framework/upload/IHE_RAD_TF_Vol2.pdf Table 4.14-1).
For each matching Series, the QIDO-RS provider shall return all attributes listed in Table 6.7.1-2a:
Table 6.7.1-2a. QIDO-RS SERIES Returned Attributes
Shall be empty if the resource cannot be retrieved via WADO-RS |
||
All other Series Level DICOM Attributes passed as {attributeID} query keys that are supported by the service provider as matching or return attributes |
||
All other Study or Series Level DICOM Attributes passed as "includefield" query values that are supported by the service provider as return attributes |
||
All available Instance Level DICOM Attributes if the "includefield" query key is included with a value of "all" |
||
If {StudyInstanceUID} is not specified, all Study-level attributes specified in Table 6.7.1-2 |
Instance Level attributes passed as "includefield" query values shall not be returned.
The above list is consistent with the attributes required for IHE RAD-14 (see http://www.ihe.net/Technical_Framework/upload/IHE_RAD_TF_Vol2.pdf Table 4.14-1).
For each matching instance, the QIDO-RS provider shall return all attributes listed in Table 6.7.1-2b:
Table 6.7.1-2b. QIDO-RS Instance Returned Attributes
Shall be empty if the resource cannot be retrieved via WADO-RS |
||
All other Instance Level DICOM Attributes passed as {attributeID} query keys that are supported by the service provider as matching or return attributes |
||
All other Study, Series or Instance Level DICOM Attributes passed as "includefield" query values that are supported by the service provider as return attributes |
||
All available Instance Level DICOM Attributes if the "includefield" query key is included with a value of "all" |
||
If {StudyInstanceUID} is not specified, all Study-level attributes specified in Table 6.7.1-2 |
||
If {SeriesInstanceUID} is not specified, all Series-level attributes specified in Table 6.7.1-2a |
The above list is consistent with the attributes required for IHE RAD-14 (see http://www.ihe.net/Technical_Framework/upload/IHE_RAD_TF_Vol2.pdf Table 4.14-1 and Table 4.14-2).
The server shall support returning query results as:
The result format used shall depend on the Accept header of the request.
Content-Type: multipart/related; type="application/dicom+xml"
The response is a multipart message body where each part is a DICOM PS3.19 XML NativeDicomModel element containing the attributes for one matching Study, Series or Instance (see Section A.1 in PS3.19 ).
The provider of the QIDO service may use a BulkData reference at its discretion (see Table A.1.5-2 in PS3.19 and Section 6.5.6). For example, this might be done to avoid encoding a large DICOM Value Field, such as an image thumbnail.
If there are no matching results, the message body will be empty.
Each part in the multipart response will contain the following HTTP headers:
Content-Type: application/dicom+json
The response is a DICOM JSON message containing a DICOM JSON property for each matching study, series or instance containing sub-properties describing the matching attributes for each study, series or instance (see Section F.2).
The provider of the QIDO service may use a BulkDataURI reference at its discretion (see Section F.2.6). For example, this might be done to avoid encoding a large DICOM Value Field, such as an image thumbnail.
If there are no matching results, the JSON message is empty.
Table 6.7-1 lists the HTTP status codes that shall be used to report any of the associated error and warning situations. Other error codes may be present for other error and warning situations.
Table 6.7-1. QIDO-RS HTTP Status Codes
DICOM RS Capabilities Service defines a single transaction type which shall be supported by all implementations
The Retrieve Server Options transaction can be requested for the following resources:
All responses are http single part messages. A successful response will return a Web Application Description Language (WADL) document encoded in a Media Type consistent with the Accept header of the request.
The WADL document shall contain one top-level "application" element.
The "application" element shall contain one "resources" element whose "base" attribute value is {SERVICE}, where {SERVICE} is the base URL for the service. This may be a combination of protocol (either http or https), host, port, and application.
Additionally, the WADL content shall include a "resource" element for the resource specified in the request (see 6.8.1.1) describing all methods (see 6.8.1.2.2.2 for description and examples) and child resources (see 6.8.1.2.2.1 for description and examples) for the specified resource and each of its children.
The full WADL resource tree follows directly and unambiguously from the RESTful resource endpoints defined in 6.5, 6.6, 6.7 and 6.9.
For informative purposes, the full resource tree and the methods defined for each resource are described in Table 6.8-1.
The Retrieve methods define the capabilities of a WADO-RS resource (see 6.5) or a RetrieveUPS resource (see 6.9.4).
The Retrieve methods shall contain the following attributes:
The Retrieve methods shall contain a "request" element with "param" elements documenting the following:
The Retrieve methods shall contain one or more "response" elements documenting the following:
<method name="GET" id="RetrieveStudies"> <request> <param name="Accept" style="header" default="multipart/related; type=application/dicom"> <option value="multipart/related; type=application/dicom" /> <option value="multipart/related; type=application/dicom"; transfer-syntax=1.2.840.10008.1.2 /> <option value="multipart/related; type=application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 /> <option value="multipart/related; type=application/octet-stream" /> <option value="multipart/related; type=image/dicom+jpx" /> <option value="multipart/related; type=image/dicom+jpx; transfer-syntax=1.2.840.10008.1.2.4.92" /> <option value="multipart/related; type= video/mpeg; transfer-syntax=1.2.840.10008.1.2.4.100" /> </param> </request> <response status="200,206"> <representation mediaType="multipart/related; type=application/dicom"; transfer-syntax=1.2.840.10008.1.2 /> <representation mediaType="multipart/related; type=application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 /> <representation mediaType="multipart/related; type=application/octet-stream" /> <representation mediaType="multipart/related; type= image/dicom+jpx" /> <representation mediaType="multipart/related; type= image/dicom+jpx; transfer-syntax=1.2.840.10008.1.2.4.92" /> <representation mediaType="multipart/related; type= video/mpeg; transfer-syntax=1.2.840.10008.1.2.4.100" /> </response> <response status="400 404 406 410 503" /> </method>
The Store methods define the capabilities of a STOW-RS resource (see 6.6) or a CreateUPS resource (see 6.9.1).
The Store methods shall contain the following attributes:
The Store methods shall contain a "request" element with "param" elements documenting the following:
The Store methods shall contain one or more "response" elements documenting the following:
<method name="GET" id="StoreInstances"> <request> <param name="Accept" style="header" default="application/dicom+xml"> <option value="application/dicom+xml" /> </param> <representation mediaType="multipart/related; type=application/dicom" /> <representation mediaType="multipart/related; type=application/dicom; transfer-syntax=1.2.840.10008.1.2" /> <representation mediaType="multipart/related; type=application/dicom; transfer-syntax=1.2.840.10008.1.2.1" /> <representation mediaType="multipart/related; type=application/dicom+xml" /> <representation mediaType="multipart/related; type=application/dicom+xml; transfer-syntax=1.2.840.10008.1.2" /> <representation mediaType="multipart/related; type=application/dicom+xml; transfer-syntax=1.2.840.10008.1.2.1" /> <representation mediaType="multipart/related; type=application/dicom+xml; transfer-syntax=1.2.840.10008.1.2.4.92" /> <representation mediaType="multipart/related; type=application/dicom+xml; transfer-syntax=1.2.840.10008.1.2.4.100" /> </request> <response status="200" /> <response status="202,409"> <representation mediaType="application/dicom+xml" /> </response> <response status="400,401,403,503" /> </method>
The Search methods define the capabilities of a QIDO-RS resource (see 6.7) or a SearchForUPS resource (see 6.9.3).
The Search methods shall contain the following attributes:
The Search methods shall contain a "request" element with "param" elements documenting the following:
The Search methods shall contain one or more "response" elements documenting the following:
<method name="GET" id="SearchForStudies"> <request> <param name="Accept" style="header" default="application/dicom+json"> <option value="multipart/related; type=application/dicom+xml" /> <option value="application/dicom+json" /> </param> <param name="Cache-control" style="header"> <option value="no-cache" /> </param> <param name="limit" style="query" /> <param name="offset" style="query" /> <param name="fuzzymatching" style="query" /> <param name="StudyDate" style="query" /> <param name="00080020" style="query" /> <param name="StudyTime" style="query" /> <param name="00080030" style="query" /> … <param name="includefield" style="query" repeating="true" /> <option value="all" /> <option value="00081049" /> <option value="PhysiciansOfRecordIdentificationSequence" /> <option value="00081060" /> <option value="NameOfPhysiciansReadingStudy" /> … </param> </request> <response status="200"> <representation mediaType="multipart/related; type=application/dicom+xml" /> <representation mediaType="application/dicom+json" /> </response> <response status="400 401 403 413 503" /> </method>
The Update methods define the capabilities of an UpdateUPS, a ChangeUPSState or a RequestUPSCancellation resource (see 6.9.2).
The Update methods shall contain the following attributes:
The Update methods shall contain a "request" element with "param" elements documenting the following:
The Update methods shall contain one or more "response" elements documenting the following:
<method name="POST" id="UpdateUPS"> <request> <representation mediaType="application/dicom+xml" /> <representation mediaType="application/dicom+json" /> </request> <response status="200"> <param name="Warning" style="header" fixed="299 {+SERVICE}: The UPS was created with modifications." /> <param name="Warning" style="header" fixed="299 {+SERVICE}: Requested optional Attributes are not supported." /> </response> <response status="409"> <pa