DICOMweb in practicehow a web viewer opens a study
DICOMweb carries the DICOM services over HTTP. A web viewer searches with a GET on /studies, reads the metadata, fetches pixels, and a scanner stores with a POST. This diagram follows those requests in a typical order, with the details of each one from PS3.18.
- DICOMweb (HTTP)
- Internal action
- Dashed = reply
Tip: click an arrow or box in the diagram to jump to that step. Time flows top to bottom.
The radiologist opens a study
Core stepWhat happens
The viewer starts from what the user chose: a patient and a date, or a link that already holds a Study Instance UID. If it only has the patient, it has to search first.
Why it is needed
Every retrieve URL in DICOMweb is built from UIDs. The search turns what a person knows into those UIDs.
Technical details
- Base URI of the service, for example https://pacs.example.org/dicomweb
- Patient ID or Accession Number from the worklist
- No UID yet: the Search Transaction finds it
Search for the study (QIDO-RS)
Core stepWhat happens
The viewer sends a GET to the All Studies resource. The matching keys are attributes, as a keyword or an 8-digit tag, in the query string. It asks for JSON.
Why it is needed
The Search Transaction is the web form of C-FIND: it matches on the same keys and returns the same kind of attributes.
Technical details
- GET /studies?PatientID=11235813&StudyDate=20130509-20130510
- Accept: application/dicom+json
- includefield=... asks for more attributes; limit and offset page the results
- fuzzymatching, emptyvaluematching and multiplevaluematching are optional
The server returns the matches
ConfirmationWhat happens
The server answers 200 with a list of matching studies, each with Study Date, Accession Number, Modalities in Study, Patient Name and ID, the Study Instance UID, and the number of related series and instances. A Retrieve URL (0008,1190) is present when the study can be retrieved.
Why it is needed
A search with no matches is also a 200 with an empty list, not an error. A Warning header says when more results can be requested.
Technical details
- Content-Type: application/dicom+json
- Study Instance UID (0020,000D) is the unique key
- No matches: 200 with an empty payload ([])
- Warning: 299 ... There are <n> additional results that can be requested
Search for the series
Core stepWhat happens
With the Study Instance UID the viewer lists the series: modality, series number, description and the number of instances in each.
Why it is needed
A viewer builds its series list and thumbnails from this answer, before it loads any pixels.
Technical details
- Resource: Study's Series, /studies/{study}/series{?search*}
- Series level: Modality, Series Instance UID, Series Number, Number of Series Related Instances
- Series Description is returned if known
Read the metadata (WADO-RS)
Core stepWhat happens
The viewer asks for the metadata of the whole study (or one series or instance). The answer has all attributes of each instance, without the large values.
Why it is needed
The viewer needs rows, columns, pixel spacing and positions to lay out and scroll the images, and it does not have to download the pixels to learn them.
Technical details
- Resources: /studies/{study}/metadata, .../series/{series}/metadata, .../instances/{instance}/metadata
- Accept: application/dicom+json (default) or multipart/related; type="application/dicom+xml"
- Large values may be replaced by a BulkDataURI
- No File Meta Information (group 0002) in the metadata
The server returns the metadata
ConfirmationWhat happens
The server returns the metadata of all instances in one JSON array. A value that would be large can be a Bulk Data URI that the viewer retrieves separately.
Why it is needed
The viewer now knows the whole structure of the study, and every image is one more GET away.
Technical details
- Content-Type: application/dicom+json
- JSON metadata for several instances is one top-level array
- BulkDataURI may be absolute, relative with an absolute path, or relative to the request
Fetch an image
Core stepWhat happens
For a quick view the viewer asks for the instance in a rendered media type. The server applies windowing and scaling and returns a JPEG. For the diagnostic pixels the viewer would ask for the frames or the instance instead.
Why it is needed
The rendered resource lets a simple client show an image without handling DICOM encodings. The rendering follows the presentation state pipeline of PS3.4.
Technical details
- Resources: .../rendered, .../frames/{frames}/rendered, .../thumbnail
- Accept: image/jpeg (default for a single frame image)
- Optional parameters: viewport=w,h window=center,width,function quality=1..100 annotation=patient,technique
- Diagnostic pixels: GET .../frames/{frames} or the instance, with a transfer-syntax parameter
The server returns the image
ConfirmationWhat happens
The server returns the rendered image. If none of the media types in the Accept header can be supplied it answers 406 Not Acceptable, and if the resource is too large it answers 413.
Why it is needed
The Accept header decides the format, so a mismatch shows as 406 and not as a broken image.
Technical details
- 200: the representations are in the payload
- 404: the resource does not exist, 410: it was deleted
- 406: none of the Acceptable Media Types is supported
- 413: the resource is too large to return
A scanner stores instances (STOW-RS)
Core stepWhat happens
A scanner or importer posts one or more instances to the Studies resource. The body is a multipart payload with one DICOM file per part, or metadata and bulk data parts. POST /studies/{study} limits it to one study.
Why it is needed
This is the web form of C-STORE. It lets a browser based tool or a cloud modality store without a DICOM association.
Technical details
- POST /studies, or /studies/{study} for a single study
- Content-Type: multipart/related; type="application/dicom"
- Each representation is a PS3.10 file, or metadata plus bulk data
- The Store Transaction has no query parameters
The server answers the store
ConfirmationWhat happens
The server answers 200 when every instance was stored, 202 when some were stored and others had warnings or failures, and 409 when none could be stored because of a conflict such as an unsupported SOP Class or a Study Instance UID mismatch.
Why it is needed
The status code, and the Store Instances Response in the body, say which instances were stored. If the server coerced an attribute it records the original in the Original Attribute Sequence.
Technical details
- 200 (OK): all stored 202 (Accepted): some stored
- 400: bad syntax 409: conflict 415: unsupported media type
- Original Attribute Sequence (0400,0561) when an attribute was coerced
- Warning header may carry a DICOM status code, for example A700
All steps at a glance
Glossary
- DICOMweb
- The DICOM services over HTTP, defined in PS3.18: Studies, Worklist and the other web services.
- User agent / origin server
- The client that sends the request and the server that holds the resources and answers.
- QIDO-RS
- The Search Transaction of the Studies Service: a GET that searches studies, series and instances.
- WADO-RS
- The Retrieve Transaction of the Studies Service: a GET that returns instances, metadata, rendered images and more.
- STOW-RS
- The Store Transaction of the Studies Service: a POST that stores instances.
- Media Type
- The format of a payload, such as application/dicom+json or image/jpeg, named in the Accept and Content-Type headers.
- Bulk Data URI
- A link in the metadata to a large value, such as pixel data, that is retrieved separately.
Summary
- DICOMweb Search is a
GETon/studies,/seriesor/instances(QIDO-RS). Matching keys are query parameters. - Retrieve is a
GETon/studies/{study}and its sub-resources: instances,/metadata,/rendered,/thumbnail,/bulkdata,/pixeldataand frames (WADO-RS). - Store is a
POSTto/studiesor/studies/{study}with a multipart body (STOW-RS). - A search with no matches is
200with an empty list.202means a store was only partly done. 406means none of the requested media types is available, and415means the server does not accept the media type you sent.- The order of requests is up to the viewer. The standard defines the transactions and their rules.
The 10 steps in plain text
The radiologist opens a study
The viewer starts from what the user chose: a patient and a date, or a link that already holds a Study Instance UID. If it only has the patient, it has to search first.
Why: Every retrieve URL in DICOMweb is built from UIDs. The search turns what a person knows into those UIDs.
Search for the study (QIDO-RS)
The viewer sends a GET to the All Studies resource. The matching keys are attributes, as a keyword or an 8-digit tag, in the query string. It asks for JSON.
Why: The Search Transaction is the web form of C-FIND: it matches on the same keys and returns the same kind of attributes.
The server returns the matches
The server answers 200 with a list of matching studies, each with Study Date, Accession Number, Modalities in Study, Patient Name and ID, the Study Instance UID, and the number of related series and instances. A Retrieve URL (0008,1190) is present when the study can be retrieved.
Why: A search with no matches is also a 200 with an empty list, not an error. A Warning header says when more results can be requested.
Search for the series
With the Study Instance UID the viewer lists the series: modality, series number, description and the number of instances in each.
Why: A viewer builds its series list and thumbnails from this answer, before it loads any pixels.
Read the metadata (WADO-RS)
The viewer asks for the metadata of the whole study (or one series or instance). The answer has all attributes of each instance, without the large values.
Why: The viewer needs rows, columns, pixel spacing and positions to lay out and scroll the images, and it does not have to download the pixels to learn them.
The server returns the metadata
The server returns the metadata of all instances in one JSON array. A value that would be large can be a Bulk Data URI that the viewer retrieves separately.
Why: The viewer now knows the whole structure of the study, and every image is one more GET away.
Fetch an image
For a quick view the viewer asks for the instance in a rendered media type. The server applies windowing and scaling and returns a JPEG. For the diagnostic pixels the viewer would ask for the frames or the instance instead.
Why: The rendered resource lets a simple client show an image without handling DICOM encodings. The rendering follows the presentation state pipeline of PS3.4.
The server returns the image
The server returns the rendered image. If none of the media types in the Accept header can be supplied it answers 406 Not Acceptable, and if the resource is too large it answers 413.
Why: The Accept header decides the format, so a mismatch shows as 406 and not as a broken image.
A scanner stores instances (STOW-RS)
A scanner or importer posts one or more instances to the Studies resource. The body is a multipart payload with one DICOM file per part, or metadata and bulk data parts. POST /studies/{study} limits it to one study.
Why: This is the web form of C-STORE. It lets a browser based tool or a cloud modality store without a DICOM association.
The server answers the store
The server answers 200 when every instance was stored, 202 when some were stored and others had warnings or failures, and 409 when none could be stored because of a conflict such as an unsupported SOP Class or a Study Instance UID mismatch.
Why: The status code, and the Store Instances Response in the body, say which instances were stored. If the server coerced an attribute it records the original in the Original Attribute Sequence.
Common questions
What is DICOMweb?
The DICOM services over HTTP, defined in PS3.18. The Studies Service has three transactions: Search (QIDO-RS), Retrieve (WADO-RS) and Store (STOW-RS). Other services cover worklists (UPS-RS), non-patient instances, storage commitment and procedure steps.
What is the difference between QIDO-RS, WADO-RS and STOW-RS?
They are the three transactions of the Studies Service. QIDO-RS searches with a GET and returns a list of matches. WADO-RS retrieves with a GET: instances, metadata, rendered images, thumbnails, bulk data or frames. STOW-RS stores with a POST.
Is DICOMweb a replacement for DIMSE?
It is an alternative transport for the same kinds of service. A DICOMweb server can be a native implementation, or a proxy that converts web requests into DIMSE requests and the responses back. Both can exist next to each other on one PACS.
What does a search with no results return?
A 200 (OK) with an empty payload: an empty JSON array when the media type is application/dicom+json. Older releases of the standard used 204 (No Content), but the current text uses 200.
Which format does a search return?
DICOM JSON, application/dicom+json, is the default. The server must also support multipart/related; type="application/dicom+xml".
How does a viewer get pixel data?
In three ways: as a rendered image (/rendered, a JPEG by default for a single frame image), as frames or pixel data in a compressed or uncompressed bulk data media type, or as the whole instance with application/dicom and a transfer-syntax parameter. The metadata carries Bulk Data URIs for the large values.
Does the standard define login and access control?
No. PS3.18 only says that the objects are likely to contain protected health information and that the implementers and deployers have to meet the privacy rules that apply. It also notes that a server may answer 404 instead of 401 or 403 so it does not reveal that a resource exists.