Storage URL Attribute
| Tag | (0040,4073) |
|---|---|
| Type | Required (1) |
| Keyword | StorageURL |
| Value Multiplicity | 1 |
| Value Representation | URL (UR) |
URI/URL specifying the location of the STOW-RS storage service to which Instances will be stored.
The value shall be a fully specified URI with protocol, authority and path, in accordance with [RFC3986] and Section 10.5 “Store Transaction” in PS3.18.
[RFC3986]
[RFC3986] IETF. Uniform Resource Identifiers (URI): Generic Syntax. http://tools.ietf.org/html/rfc3986 .
Section 10.5 “Store Transaction” in PS3.18
10.5 Store Transaction
This transaction uses the POST method to Store representations of Studies, Series, and Instances contained in the request payload.
The Store transaction supports only DICOM resources. The resource can be supplied as a single Instance, or as separate Metadata and Bulkdata.
10.5.1 Request
The request shall have the following syntax:
POST SP "/" {/resource} SP version CRLF
Accept: 1#media-type CRLF
Content-Type: dicom-media-type CRLF
(Content-Length: uint / Content-Encoding: encoding) CRLF
*(header-field CRLF)
CRLF
payload
10.5.1.1 Target Resources
10.5.1.1.1 DICOM Resources
Table 10.5.1-1 defines the resources used to store Instances.
Table 10.5.1-1. Store Transaction DICOM Resources
|
Resource |
URI Template |
Description |
|---|---|---|
|
Studies |
/studies |
Stores a set of representations that may have different Study Instance UIDs. |
|
Study |
/studies/{study}
|
Stores a set of representations that belong to the same Study, i.e., each representation shall have the same Study Instance UID. |
10.5.1.2 Query Parameters
The Store transaction has no Query Parameters.
10.5.1.3 Request Header Fields
The origin server shall support Header Fields as required in Table 10.5.1-2.
The user agent shall supply in the request Header Fields as required in Table 10.5.1-2.
Table 10.5.1-2. Request Header Fields
|
Name |
Values |
Usage |
Description |
|
|---|---|---|---|---|
|
User Agent |
Origin Server |
|||
|
Content-Type |
media-type |
M |
M |
The DICOM Media Type of the request payload Shall be present if the request has a payload |
|
Content-Length |
uint |
C |
M |
Shall be present if a content encoding has not been applied to the payload |
|
Content-Encoding |
encoding |
C |
M |
Shall be present if a content encoding has been applied to the payload |
See also Section 8.4.
10.5.1.4 Request Payload
The request payload shall be present and shall contain one or more representations specified by the Content-Type header field.
The payload may contain Instances from more than one Study if the Study Instance UID is not specified in the Target URI.
The request payload shall consist of either:
-
PS3.10 SOP Instances, or
-
Metadata accompanied by Bulkdata.
PS3.10 binary instances shall be encoded with one message part per DICOM Instance.
Metadata and Bulkdata requests will be encoded in the following manner (see Figure 8.6-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 10.5.2-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 10.5.2-1.
-
Bulkdata (with the exception of Encapsulated Document (0042,0011) 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 Bulkdata item.
-
Compressed pixel data shall be encoded in one of two ways:
-
single-frame pixel data encoded using a single-frame media type (one message part);
-
multi-frame or video pixel data encoded using a multi-frame media type (multiple frames in one message part).
-
Uncompressed Bulkdata shall be encoded as application/octet-stream.
An Encapsulated Document (0042,0011) Bulkdata element shall be encoded using the media-type from the MIME Type of the Encapsulated Document (0042,0012) Attribute with one message part per document.
10.5.2 Behavior
The origin server stores Instances from the representations contained in the request payload.
The stored Instance(s) shall fully conform to the IOD and encoding requirements of PS3.3 and PS3.5, respectively.
This Transaction stores one or more new Instances, and adds them to new or existing Series and Studies.
While creating resources from the representations, the origin server may coerce or replace the values of data elements. For example, Patient Name, Patient ID, and Accession Number might be coerced when importing media from an external institution, reconciling the Instances against a master patient index, or reconciling them against an imaging procedure order. The origin server may also fix incorrect values, such as Patient Name or Patient ID; for example, because an incorrect work list item was chosen, or an operator input error has occurred.
If any Attribute 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 Store Instances Response Module (see Annex I) in the response.
Note
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 Bulkdata into an appropriate DICOM Transfer Syntax, as defined in Table 10.5.2-1.
If the request message contains compressed Bulkdata with a Content Type that is one of the media types specified in Table 10.5.2-1, the request may omit the Image Pixel Description Macro Attributes and the origin server will derive them from the compressed octet 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.
Note
-
This allows a user agent to use consumer media types to encode the pixel data even though it may not have:
-
the pixel data in a form that directly corresponds to a lossless (reversible) DICOM Transfer Syntax, or
-
an API to access the information required to populate the Image Pixel Description Macro.
-
-
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.
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 10.5.2-1.
If the supplied compressed octet 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. Table 10.5.2-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 10.5.2-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.
Table 10.5.2-1. Media Type Transformation to Transfer Syntaxes
|
Media Type |
Requirement |
|---|---|
|
image/gif |
Transform |
|
Image/jp2 |
Unchanged |
|
image/jpeg |
Unchanged |
|
image/jpx |
Unchanged |
|
image/png |
Transform |
|
video/mp4 |
Unchanged |
|
video/mpeg2 |
Unchanged |
Note
-
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 by transforming the frame deltas into fully decoded frames; image/png does not support animation, and Multiple-image Network Graphics (MNG) is not included in Table 10.5.2-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. The actual pixel value used to replace transparent pixels (e.g., black or white) is at the discretion of the implementation, but if the value used does not appear elsewhere in the image, it may be useful to record it in Pixel Padding Value (0028,0120).
-
If an alpha channel is supplied in an image/png file, the alpha channel will be discarded (i.e., considered to consist of all opaque values, consistent with the policy of discarding any transparency information).
-
In the case of pixel data that contains a single channel in the absence of metadata describing the interpretation of the pixel values, the Photometric Interpretation may be assumed by the origin server to be MONOCHROME2 (zero is interpreted as black).
10.5.3 Response
The response shall have the following syntax:
version SP status-code SP reason-phrase CRLF
[Content-Type: media-type CRLF]
[(Content-Length: uint CRLF / Content-Encoding: encoding CRLF) ]
*(header-field CRLF)
CRLF
store-instances-response-module
The response shall contain an appropriate status code.
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 Store Instances Response Module (see Annex I) in the response.
10.5.3.1 Status Codes
Table 10.5.3-1 shows some common status codes corresponding to this transaction. See also Section 8.5 for additional status codes.
Table 10.5.3-1. Status Code Meaning
|
Status |
Code |
Description |
|---|---|---|
|
Success |
200 (OK) |
The origin server successfully stored all Instances. |
|
202 (Accepted) |
The origin server stored some of the Instances but warnings or failures exist for others. Additional information regarding this error may be found in the response message body. |
|
|
Failure |
400 (Bad Request) |
The origin server was unable to store any instances due to bad syntax. |
|
409 (Conflict) |
The request was formed correctly but the origin server was unable to store any instances due to a conflict in the request (e.g., unsupported SOP Class or Study Instance UID mismatch). This may also be used to indicate that the origin server was unable to store any instances for a mixture of reasons. Additional information regarding the instance errors may be found in the payload. |
|
|
415 (Unsupported Media Type) |
The origin server does not support the media type specified in the Content-Type header field of the request |
10.5.3.2 Response Header Fields
The origin server shall support header fields as required in Table 10.5.3-2.
Table 10.5.3-2. Response Header Fields
|
Name |
center |
Origin Server Usage |
Description |
|---|---|---|---|
|
Content-Type |
media-type |
M |
The media type of the response payload, if present. |
|
Content-Encoding |
encoding |
C |
Shall be present if the response payload has a content encoding. See Section 8.4.3. |
|
Content-Length |
uint |
C |
Shall be present if the response payload does not have a content encoding. See Section 8.4.3. |
|
Content-Location |
url |
C |
Shall be present if a new resource was created. The value is the URL of the representation contained in the request payload. May be present otherwise |
|
Location |
url |
C |
Shall be present if a new resource was created. The value is the URL of the created resource. May be present otherwise |
All success responses shall also contain the Content Representation (see Section 8.4.2) and Payload header fields (see Section 8.4.3) with appropriate values.
It is recommended that the text returned in the Warning header field (see [RFC7234] Section 5.5) contain a DICOM Status Code (see PS3.4 and Annex C “Status Type Encoding (Normative)” in PS3.7) and descriptive reason. For example:
Warning: A700 <service>: Out of memory
See also Section 8.4.
10.5.3.3 Response Payload
A success response payload shall contain a Store Instances Response Module. See Annex I.
A failure response payload may contain a Status Report describing any failures, warnings, or other useful information.
10.5.4 Media Types
The origin server shall support the default and required media types in the media type category specified in Table 10.5.4-1.
Table 10.5.4-1. Default, Required, and Optional Media Types
|
Media Type |
Usage |
Section |
|---|---|---|
|
application/dicom |
Required |
|
|
application/dicom+json |
Default |
|
|
multipart/related; type="application/dicom+xml" |
Required |
|
|
multipart/related; type="application/octet-stream" |
Required |
10.5.5 Conformance Statement
An implementation conforming to the Store transaction shall support the resources and media types specified in Section 10.5.
An implementation shall declare in its Conformance Statement the SOP Classes supported for the Store transaction, and whether it plays the role of origin server or user agent, or both.
Implementation specific warning and error codes shall be included in the Conformance Statement.