Skip to content

Latest commit

 

History

History
343 lines (233 loc) · 16.7 KB

use-dicom-web-standard-apis-with-curl.md

File metadata and controls

343 lines (233 loc) · 16.7 KB
Raw

Use DICOMWeb™ Standard APIs with cURL

This tutorial uses cURL to demonstrate working with the Medical Imaging Server for DICOM.

For the tutorial we will use the DICOM files here: Sample DICOM files. The file name, studyUID, seriesUID and instanceUID of the sample DICOM files is as follows:

File StudyUID SeriesUID InstanceUID
green-square.dcm 1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420 1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652 1.2.826.0.1.3680043.8.498.12714725698140337137334606354172323212
red-triangle.dcm 1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420 1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652 1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395
blue-circle.dcm 1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420 1.2.826.0.1.3680043.8.498.77033797676425927098669402985243398207 1.2.826.0.1.3680043.8.498.13273713909719068980354078852867170114

NOTE: Each of these files represent a single instance and are part of the same study. Also green-square and red-triangle are part of the same series, while blue-circle is in a separate series.

Prerequisites

In order to use the DICOMWeb™ Standard APIs, you must have an instance of the Medical Imaging Server for DICOM deployed. If you have not already deployed the Medical Imaging Server, Deploy the Medical Imaging Server to Azure.

Once you have deployed an instance of the Medical Imaging Server for DICOM, retrieve the URL for your App Service:

  1. Sign into the Azure Portal.
  2. Search for App Services and select your Medical Imaging Server for DICOM App Service.
  3. Copy the URL of your App Service.
  4. Append the version you would like to use to the end of your app service (ex. https://<app_service_url>/v<version>/) and use this as the base url for your DICOM service in all the following examples. For more information on versioning visit the Api Versioning Documentation.

For this code, we'll be accessing an unsecured dev/test service. Please don't upload any private health information (PHI).

Working with the Medical Imaging Server for DICOM

The DICOMweb™ standard makes heavy use of multipart/related HTTP requests combined with DICOM specific accept headers. Developers familiar with other REST-based APIs often find working with the DICOMweb™ standard awkward. However, once you have it up and running, it's easy to use. It just takes a little finagling to get started.

The cURL commands each contain at least one, and sometimes two, variables that much be replaced. To simplify running the commands, do a search and replace for the following variables, replacing them with your specific values:

  • {base-url} : this is the url your created in the steps of above including the service url and version.
  • {path-to-dicoms} : path to the directory which contains the red-triangle.dcm file, such as C:/dicom-server/docs/dcms
    • Be sure to use forward slashes as separators and end the directory without a trailing forward slash.

Uploading DICOM Instances (STOW)

Store-instances-using-multipart/related

This request intends to demonstrate how to upload DICOM files using multipart/related.

NOTE: The Medical Imaging Server for DICOM is more lenient than the DICOM standard. The example below, however, demonstrates a POST request that complies tightly to the standard.

Details:

  • Path: ../studies
  • Method: POST
  • Headers:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
  • Body:
    • Content-Type: application/dicom for each file uploaded, separated by a boundary value

Some programming languages and tools behave differently. For instance, some require you to define your own boundary. For those, you may need to use a slightly modified Content-Type header. The following have been used successfully.

  • Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
  • Content-Type: multipart/related; boundary=ABCD1234
  • Content-Type: multipart/related

curl --location --request POST "{base-url}/studies" --header "Accept: application/dicom+json" --header "Content-Type: multipart/related; type=\"application/dicom\"" --form "file1=@{path-to-dicoms}/red-triangle.dcm;type=application/dicom" --trace-ascii "trace.txt"

Store-instances-for-a-specific-study

This request demonstrates how to upload DICOM files using multipart/related to a designated study.

Details:

  • Path: ../studies/{study}
  • Method: POST
  • Headers:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
  • Body:
    • Content-Type: application/dicom for each file uploaded, separated by a boundary value

Some programming languages and tools behave differently. For instance, some require you to define your own boundary. For those, you may need to use a slightly modified Content-Type header. The following have been used successfully.

  • Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
  • Content-Type: multipart/related; boundary=ABCD1234
  • Content-Type: multipart/related

curl --request POST "{base-url}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420" --header "Accept: application/dicom+json" --header "Content-Type: multipart/related; type=\"application/dicom\"" --form "file1=@{path-to-dicoms}/blue-circle.dcm;type=application/dicom"

Store-single-instance

NOTE: This is a non-standard API that allows the upload of a single DICOM file without the need to configure the POST for multipart/related. Although cURL handles multipart/related well, this API allows tools like Postman to upload files to the Medical Imaging Server for DICOM.

The following is required to upload a single DICOM file.

Details:

  • Path: ../studies
  • Method: POST
  • Headers:
    • Accept: application/dicom+json
    • Content-Type: application/dicom
  • Body:
    • Contains a single DICOM file as binary bytes.

curl --location --request POST "{base-url}/studies" --header "Accept: application/dicom+json" --header "Content-Type: application/dicom" --data-binary "@{path-to-dicoms}/green-square.dcm"

Retrieving DICOM (WADO)

Retrieve-all-instances-within-a-study

This request retrieves all instances within a single study, and returns them as a collection of multipart/related bytes.

Details:

  • Path: ../studies/{study}
  • Method: GET
  • Headers:
    • Accept: multipart/related; type="application/dicom"; transfer-syntax=*

curl --request GET "{base-url}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420" --header "Accept: multipart/related; type=\"application/dicom\"; transfer-syntax=*" --output "suppressWarnings.txt"

This cURL command will show the downloaded bytes in the output file (suppressWarnings.txt), but these are not direct DICOM files, only a text representation of the multipart/related download.

Retrieve-metadata-of-all-instances-in-study

This request retrieves the metadata for all instances within a single study.

Details:

  • Path: ../studies/{study}/metadata
  • Method: GET
  • Headers:
    • Accept: application/dicom+json

This cURL command will show the downloaded bytes in the output file (suppressWarnings.txt), but these are not direct DICOM files, only a text representation of the multipart/related download.

curl --request GET "{base-url}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/metadata" --header "Accept: application/dicom+json"

Retrieve-all-instances-within-a-series

This request retrieves all instances within a single series, and returns them as a collection of multipart/related bytes.

Details:

  • Path: ../studies/{study}/series/{series}
  • Method: GET
  • Headers:
    • Accept: multipart/related; type="application/dicom"; transfer-syntax=*

This cURL command will show the downloaded bytes in the output file (suppressWarnings.txt), but it is not the DICOM file, only a text representation of the multipart/related download.

curl --request GET "{base-url}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652" --header "Accept: multipart/related; type=\"application/dicom\"; transfer-syntax=*" --output "suppressWarnings.txt"

Retrieve-metadata-of-all-instances-within-a-series

This request retrieves the metadata for all instances within a single study.

Details:

  • Path: ../studies/{study}/series/{series}/metadata
  • Method: GET
  • Headers:
    • Accept: application/dicom+json

curl --request GET "{base-url}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/metadata" --header "Accept: application/dicom+json"

Retrieve-a-single-instance-within-a-series-of-a-study

This request retrieves a single instance, and returns it as a DICOM formatted stream of bytes.

Details:

  • Path: ../studies/{study}/series{series}/instances/{instance}
  • Method: GET
  • Headers:
    • Accept: application/dicom; transfer-syntax=*

curl --request GET "{base-url}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395" --header "Accept: application/dicom; transfer-syntax=*" --output "suppressWarnings.txt"

Retrieve-metadata-of-a-single-instance-within-a-series-of-a-study

This request retrieves the metadata for a single instances within a single study and series.

Details:

  • Path: ../studies/{study}/series/{series}/instances/{instance}/metadata
  • Method: GET
  • Headers:
    • Accept: application/dicom+json

curl --request GET "{base-url}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395/metadata" --header "Accept: application/dicom+json"

Retrieve-one-or-more-frames-from-a-single-instance

This request retrieves one or more frames from a single instance, and returns them as a collection of multipart/related bytes. Multiple frames can be retrieved by passing a comma separated list of frame numbers. All DICOM instances with images have at minimum one frame, which is often just the image associated with the instance itself.

Details:

  • Path: ../studies/{study}/series{series}/instances/{instance}/frames/1,2,3
  • Method: GET
  • Headers:
    • Accept: multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (Default) or
    • Accept: multipart/related; type="application/octet-stream"; transfer-syntax=* or
    • Accept: multipart/related; type="application/octet-stream";

curl --request GET "{base-url}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395/frames/1" --header "Accept: multipart/related; type=\"application/octet-stream\"; transfer-syntax=1.2.840.10008.1.2.1" --output "suppressWarnings.txt"

Query DICOM (QIDO)

In the following examples, we search for items using their unique identifiers. You can also search for other attributes, such as PatientName.

Search-for-studies

This request enables searches for one or more studies by DICOM attributes.

Please see the Conformance.md file for supported DICOM attributes.

Details:

  • Path: ../studies?StudyInstanceUID={study}
  • Method: GET
  • Headers:
    • Accept: application/dicom+json

curl --request GET "{base-url}/studies?StudyInstanceUID=1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420" --header "Accept: application/dicom+json"

Search-for-series

This request enables searches for one or more series by DICOM attributes.

Please see the Conformance.md file for supported DICOM attributes.

Details:

  • Path: ../series?SeriesInstanceUID={series}
  • Method: GET
  • Headers:
    • Accept: application/dicom+json

curl --request GET "{base-url}/series?SeriesInstanceUID=1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652" --header "Accept: application/dicom+json"

Search-for-series-within-a-study

This request enables searches for one or more series within a single study by DICOM attributes.

Please see the Conformance.md file for supported DICOM attributes.

Details:

  • Path: ../studies/{study}/series?SeriesInstanceUID={series}
  • Method: GET
  • Headers:
    • Accept: application/dicom+json

curl --request GET "{base-url}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series?SeriesInstanceUID=1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652" --header "Accept: application/dicom+json"

Search-for-instances

This request enables searches for one or more instances by DICOM attributes.

Please see the Conformance.md file for supported DICOM attributes.

Details:

  • Path: ../instances?SOPInstanceUID={instance}
  • Method: GET
  • Headers:
    • Accept: application/dicom+json

curl --request GET "{base-url}/instances?SOPInstanceUID=1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395" --header "Accept: application/dicom+json"

Search-for-instances-within-a-study

This request enables searches for one or more instances within a single study by DICOM attributes.

Please see the Conformance.md file for supported DICOM attributes.

Details:

  • Path: ../studies/{study}/instances?SOPInstanceUID={instance}
  • Method: GET
  • Headers:
    • Accept: application/dicom+json

curl --request GET "{base-url}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/instances?SOPInstanceUID=1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395" --header "Accept: application/dicom+json"

Search-for-instances-within-a-study-and-series

This request enables searches for one or more instances within a single study and single series by DICOM attributes.

Please see the Conformance.md file for supported DICOM attributes.

Details:

  • Path: ../studies/{study}/series/{series}/instances?SOPInstanceUID={instance}
  • Method: GET
  • Headers:
    • Accept: application/dicom+json

curl --request GET "{base-url}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances?SOPInstanceUID=1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395" --header "Accept: application/dicom+json"

Delete DICOM

Delete-a-specific-instance-within-a-study-and-series

This request deletes a single instance within a single study and single series.

Delete is not part of the DICOM standard, but has been added for convenience.

Details:

  • Path: ../studies/{study}/series/{series}/instances/{instance}
  • Method: DELETE
  • Headers: No special headers needed

curl --request DELETE "{base-url}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"

Delete-a-specific-series-within-a-study

This request deletes a single series (and all child instances) within a single study.

Delete is not part of the DICOM standard, but has been added for convenience.

Details:

  • Path: ../studies/{study}/series/{series}
  • Method: DELETE
  • Headers: No special headers needed

curl --request DELETE "{base-url}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652"

Delete-a-specific-study

This request deletes a single study (and all child series and instances).

Delete is not part of the DICOM standard, but has been added for convenience.

Details:

  • Path: ../studies/{study}
  • Method: DELETE
  • Headers: No special headers needed

curl --request DELETE "{base-url}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"