WADO-URI Web Service

URI Web Service retrieves representations of its resources (SOP Instances). Mainly for non-DICOM systems to access DICOM dataset or rendered image. URI Service does not define resources in the form of a Target Resource Path, such as {/resource}. Instead, Target Resource is identified using query parameter values.

There are two transactions defined, Retrieve DICOM Instance and Retrieve Rendered Instance, in different media types.

• All URI transactions use the query component of the URI in the request message to specify the transaction.
• The functionality of the URI Web Service transactions is similar but more limited than, the Retrieve Transaction of the Studies Web Service.
• The Query Parameters may appear in any order.

• The user agent shall supply Mandatory Query Parameters and the origin server shall support. (Requires the UIDs of the higher levels of DICOM hierarchy).

  Name	Values	User Agent	Origin Server
  requestType	"WADO"	M	M
  studyUID	uid	M	M
  seriesUID	uid	M	M
  objectUID	uid	M	M

• Request Type - This parameter specifies that this is a URI service request. The parameter name shall be "requestType", and the value shall be "WADO". It has the following syntax:

  requestType = %s"requestType=" token

  where:

  • token = "WADO". If the value is other than "WADO", and the origin server does not support the value, the response shall be 400 (Bad Request), and may include a payload containing an appropriate error message.
• Study UID - study = %s"studyUID=" uid and the value is Study Instance UID.
• Series UID - series = %s"seriesUID=" uid and the value is a Series Instance UID.
• SOP Instance UID - instance = %s"objectUID=" uid and value of this parameter is a SOP Instance UID.

• Optional Query Parameters - optional for all URI requests.

  Key	Values	User Agent	Origin Server
  contentType	media-type	O	O
  charset	token	O	O

• Acceptable Media Types - The Accept Query Parameter specifies the Acceptable Media Types for the response payload.

  • The case-sensitive name of the parameter is "contentType". It has the following syntax:
    accept = %s"contentType=" dicom / 1#rendered-media-type

  • The value of this parameter, if present, shall be either application/dicom, or one or more of the Rendered Media Types (e.g., image/jpeg, image/png, video/mp4, etc.)

  • The DICOM Media Type transfer-syntax and character set parameters are forbidden in the request. If either are present, the response shall be 400 (Bad Request), and may include a payload containing an appropriate error message.
  • The response to a request without an Accept header field shall be 406 (Not Acceptable).
  • If the Acceptable Media Types contains both DICOM and Rendered Media Types, the origin server shall return 400 (Bad Request).
  • The origin server should support the application/dicom media type and Rendered Media Types.
  • Rendered images shall contain no more than 8 bits per channel.
  • Structured Report could be rendered into a text/html, text/plain, or application/pdf Rendered Media Type.
  • A multi-frame image in a lossless Transfer Syntax could be rendered into a video/mpeg, video/mp4 or video/H265 Rendered Media Type.
  • An image could be rendered into the image/jpeg or image/png Rendered Media Type.

• Acceptable Character Sets. It has the following syntax:

  charset-qp = %s"charset=" 1#(charset [weight])

  • The value of this parameter is a comma-separated list of one or more character-set identifiers.

Retrieve DICOM Instance Transaction

Retrieves a single Instance in the application/dicom media type.

Request

The request shall have the following syntax:

GET SP / ?{requestType}&{study}&{series}&{instance}  
  {&accept} 
  {&charset} 
  {&anonymize} 
  {&annotate} 
  {&transferSyntax} 
  SP HTTP/1.1 CRLF 
Accept: uri-media-type CRLF 
*(header-field CRLF) 
CRLF 

Query Parameters

The origin server shall support Query Parameters as required in Table 9.4.1-1.

• Anonymize. It has the following syntax:

  anonymize = %s"anonymize=" token

  where token = "yes"

  • See Annex E of PS3.15 for guidance to remove PII information.
  • If the Target Resource has not already been de-identified, the returned instance shall have a new SOP Instance UID.

• Annotation - rendered images shall be annotated with patient and/or procedure information. It has the following syntax:

  annotation = 1#( %s"patient" / %s"technique" )

  where:

  • "patient" - rendered images shall be annotated with patient information (e.g., patient name, birth date, etc.).
  • "technique" - indicates that the rendered images shall be annotated with information about the procedure that was performed (e.g., image number, study date, image position, FOV, etc.).

Header Fields

The user agent shall supply in the request header fields and the origin server shall support as required.

• Request Type - If the Query Parameter is not present; or if it is present with a value other than "WADO" and the origin server does not support the value, then the origin server shall return a 400 (Bad Request) response.
• Study, Series, and Instance UIDs - If the Study, Series, or Instance UID Query Parameters are not present, the origin server shall return a 400 (Bad Request) response.
• Transfer Syntax UID - Query Parameter is supported and present with a value that is a valid Transfer Syntax UID, the response payload shall be encoded in the specified Transfer Syntax.
  • If it is not present, the response payload shall be encoded in the default Transfer Syntax for DICOM Web Services, which is Explicit VR Little Endian Uncompressed.
  • The number of parameter values is not equal to one, or the parameter value is not a valid UID, then the origin server shall return a 400.
  • If the value is a valid Transfer Syntax UID, but is not supported by the origin server, the response shall be 406 (Not Acceptable), and may include a payload containing a list of the Transfer Syntaxes supported by the origin server.

Payload

No payload.

Behavior

A success response shall contain the Target Resource in an Acceptable DICOM Media Type.

Response

The response shall have the following syntax:

version SP status-code SP reason-phrase CRLF 
[Content-Type: media-type CRLF] 
[(Content-Length: uint / Transfer-Encoding: encoding) CRLF] 
Content-Location: url CRLF 
*(header-field CRLF) 
CRLF 
[payload / status-report] 

Header Fields

The origin server shall support the following header fields:

Payload

• A successful response shall have a payload containing the Target Resource in the application/dicom media type.
• A failure response payload may contain a Status Report describing any failures, warnings, or other useful information.

Status Codes

Refer to PS3.18 section 8.5 for full list. The followings are some common status codes corresponding to this transaction:

• 200 (OK) – Success

• Failure

  • 400 (Bad Request)
  • 404 (Not Found)

  • 410 (Gone) - UIDs in the Query Parameters, once existed, but no longer exists.

Retrieve Rendered Instance Transaction

Retrieves a single instance in a Rendered Media Type.

• User agent can ask to render SOP instance using a W/L value or presentation state to DICOM SR rendered as PDF or HTML, etc.
• It allows the user agent to supply ROI as a source rectangle and view port as a destination rectangle (scale).
• This transaction returns a single DICOM instance in a Rendered Media Type.
• The Acceptable Media Type shall not be application/dicom. If it is, the response should be 406 (Not Acceptable) response.
• Origin server shall be able to render all Photometric Interpretations that are defined in the IOD for that SOP class.

Request

The request shall have the following syntax:

GET SP /?{requestType}&{study}&{series}&{instance}{&frameNumber} 
  {&accept} 
  {&charset} 
  {&rows} 
  {&columns} 
  {&region} 
  {&windowCenter} 
  {&windowWidth} 
  {&imageQuality} 
  {&annotation} 
  {&presentationSeriesUID} 
  {&presentationUID} 
SP HTTP/1.1 CRLF 
Accept: 1#media-type CRLF 
*(header-field CRLF) 
CRLF 

Target Resource

An instance of a Composite SOP class.

Query Parameters

Included in a request only if the DICOM Category of the Target Resource is Single Frame, Multi-Frame, or Video.

• Frame Number - frame-number = %s"frameNumber" "=" uint.

• Image Annotation - Text burned into image and don't apply annotation if this parameter is not present. Its name is "annotation" and its value is a comma-separated list of one or more keywords. It has the following syntax:

  annotation = %s"annotation=" 1#( %s"patient" / %s"technique")

  where:

  • "patient" – (patient name, sex, birth date, etc.)
  • "technique" – information about the procedure that was performed (e.g., image number, study date, FOV, image position, etc.)

• Image Quality - Quality = %s"quality=" uint. An unsigned integer between 1 and 100 inclusive, with 100 being the best quality. If the value of this parameter is missing or is not an integer between 1 and 100 inclusive, the response shall be 400.

• Viewport - Specifies the dimensions of the user agent's viewport.
  • Viewport Rows and Columns parameters specify the height and width, in pixels, of the returned image.
  • Viewport Rows - Rows = %s"rows" "=" uint. (name is "rows" and its value shall be a positive integer).
  • Viewport Columns - Columns = %s"columns" "=" uint. (name is "columns" and its value shall be a positive integer).
• Source Image Region - Specifies a rectangular region of the Target Resource. Its name is "region" and its values shall be a comma-separated list of four positive decimal numbers.
  • region = %s"region" "=" xmin "," ymin "," xmax "," ymax
  • The region is specified using a normalized coordinate system (0.0 to 1.0) relative to the size of the original image matrix.
  • 0.0, 0.0 corresponds to the top row and left column and 1.0, 1.0 corresponds to the bottom row and right column of the image.
• Viewport Scaling - The "Region" parameter specifies a rectangular region of the source image(s) or video to be cropped, and a rectangular region corresponding to the size of the user agent's viewport (e.g. Rows and Columns) to which the cropped image or video should be scaled.
• Windowing - Window Center and Window Width. if either is present, both shall be present. The URI Service does not support the "function" Query Parameter (LUT function).
  • Name is "windowCenter" and its value shall be a decimal number: window-center = %s"windowCenter" "=" decimal
  • Name is "windowWidth" and its value shall be a decimal number: window-width = %s"windowWidth" "=" decimal
• Presentation State - Specifies the Series and SOP Instance UIDs of a Presentation State.
  • Presentation State parameters are present, then the only other optional parameters that may be present are Annotation, Image Quality, Region, and Viewport.
  • Presentation Series UID: presentation-series = %s"presentationSeriesUID" "=" uid
  • Presentation UID: presentation-instance = %s"presentationUID" "=" uid

Header Fields

The Acceptable Media Types shall contain only Rendered Media Types:

Payload

No payload.

Response

The response shall have the following syntax:

version SP status-code SP reason-phrase CRLF 
[Content-Type: rendered-media-type CRLF] 
[(Content-Length: uint / Transfer-Encoding: encoding) CRLF] 
[Content-Location: url CRLF] 
*(header-field CRLF) 
CRLF 
[payload / status-report] 

Header Fields

Origin server shall support header fields as required in following table:

Payload

• A success response shall contain a single rendered image encoded in the Selected Media Type.
• A failure response payload may contain a Status Report describing failures, warnings, or other useful information.

Status Codes

• 200 (OK) – Success
• 400 (Bad Request)

Notes

• Both Retrieve DICOM Instance and Retrieve Rendered Instance transactions have the same "requestType" type but are differentiated by their Selected Media Type.
• If there is no "contentType" Query Parameter and the Accept header field is '*/*', then the Selected Media Type will be set to the default value 'image/jpeg' media type and the transaction will be set to the default value Retrieve Rendered Instance.

Examples

Retrieving DICOM instance

Retrieving a DICOM image object using the baseline 8-bit lossy JPEG transfer syntax, and de-identified:

http://www.medical-webservice.st/RetrieveDocument?requestType=WADO 
&studyUID=1.2.250.1.59.40211.12345678.678910 
&seriesUID=1.2.250.1.59.40211.789001276.14556172.67789 
&objectUID=1.2.250.1.59.40211.2678810.87991027.899772.2 
&contentType=application%2Fdicom 
&anonymize=yes 
&transferSyntax=1.2.840.10008.1.2.4.50 

Retrieve Rendered Instance

Retrieving a Simple DICOM image in JPEG:

http://www.hospital-stmarco/radiology/wado.php?requestType=WADO 
&studyUID=1.2.250.1.59.40211.12345678.678910 
&seriesUID=1.2.250.1.59.40211.789001276.14556172.67789 
&objectUID=1.2.250.1.59.40211.2678810.87991027.899772.2 
Accept: image/jpeg 

Retrieving a DICOM SR in HTML

http://server234/script678.asp?requestType=WADO 
&studyUID=1.2.250.1.59.40211.12345678.678910 
&seriesUID=1.2.250.1.59.40211.789001276.14556172.67789 
&objectUID=1.2.250.1.59.40211.2678810.87991027.899772.2 
&charset=UTF-8 
Accept: text/html 

Retrieving a Region of A DICOM Image

Retrieving a region of a DICOM image, converted if possible in JPEG2000, with annotations burned into the image containing the patient name and technical information, and mapped into a defined image size:

https://aspradio/imageaccess.js?requestType=WADO 
&studyUID=1.2.250.1.59.40211.12345678.678910 
&seriesUID=1.2.250.1.59.40211.789001276.14556172.67789 
&objectUID=1.2.250.1.59.40211.2678810.87991027.899772.2 
&contentType=image%2Fjp2;level=1,image%2Fjpeg;q=0.5 
&annotation=patient,technique 
&columns=400 
&rows=300 
&region=0.3,0.4,0.5,0.5 
&windowCenter=-1000 
&windowWidth=2500 

See Also

RESTful Web Services