DICOM conformance statement

DICOM stores within the Cloud Healthcare API support a subset of the RESTful web services specified in the DICOM PS3.18 2018a - Web Services standard (commonly referred to as DICOMweb). Specifically, they support the Studies Service and Resources (previously referred to as the WADO-RS, STOW-RS, and QIDO-RS services).

Additionally, the Cloud Healthcare API supports a proprietary web service for deleting DICOM instances.

Retrieve Transaction

The Retrieve Transaction is a RESTful web service for retrieving DICOM imaging data.

The Cloud Healthcare API supports the following action types:

  • RetrieveStudy
  • RetrieveSeries
  • RetrieveInstance
  • RetrieveFrames
  • RetrieveRendered
  • RetrieveMetadata

It does not currently support the following action type:

  • RetrieveBulkdata

RetrieveStudy/RetrieveSeries/RetrieveInstance

The following Accept Headers are supported:

  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 (default)
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.90
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.91
  • multipart/related; type="application/dicom"; transfer-syntax=*
  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1
  • multipart/related; type="application/octet-stream"; transfer-syntax=*
  • multipart/related; type="image/jpeg"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="image/png"

RetrieveInstance

In addition to the above Accept Headers, RetrieveInstance supports single part content types for convenience:

  • application/dicom; transfer-syntax=1.2.840.10008.1.2.1
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.50
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.90
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.91
  • application/dicom; transfer-syntax=*

This is not part of the official DICOMweb standard.

RetrieveFrames

The following Accept Headers are supported:

  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (default)
  • multipart/related; type="application/octet-stream"; transfer-syntax=*
  • multipart/related; type="image/jpeg"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="image/png"

A transfer syntax of * allows the user to request no transcoding be done, so the transfer syntax of the uploaded file will be used. For application/octet-stream the bulk data will be returned in whatever format it appears in the uploaded DICOM file.

RetrieveRendered

The following Accept Headers are supported:

  • image/jpeg (default)
  • image/png

Only retrieving of Instance or Frame resources is supported.

No URL parameters are supported.

RetrieveMetadata

The following Accept Headers are supported:

  • application/dicom+json (default)
  • multipart/related; type=application/dicom+xml

RetrieveMetadata does not return any attribute which has a DICOM Value Representation of OB, OD, OF, OL, OW, or UN.

Supported Transfer Syntaxes

The above Accept headers describe what media types & transfer syntaxes you can request from the API, but this may not always be possible depending on the transfer syntax of the original file that was uploaded. In particular, transcoding is only possible from the following transfer syntaxes:

  • 1.2.840.10008.1.2 (Little Endian Implicit)
  • 1.2.840.10008.1.2.1 (Little Endian Explicit)
  • 1.2.840.10008.1.2.4.50 (JPEG Baseline Process 1)
  • 1.2.840.10008.1.2.4.57 (JPEG Lossless)
  • 1.2.840.10008.1.2.4.70 (JPEG Lossless Selection Value 1)
  • 1.2.840.10008.1.2.4.90 (JPEG 2000 Lossless Only)
  • 1.2.840.10008.1.2.4.91 (JPEG 2000)
  • 1.2.840.10008.1.2.5 (RLE Lossless)

If the original file has a transfer syntax other than that in the above list and you request transcoding to another format, an error will be returned.

In order to disable transcoding and retrieve any file from the API you can set transfer-syntax=* in your Accept header.

Store Transaction

The Store Transaction is a RESTful web service for storing DICOM imaging data.

The following Content-Types are supported:

  • multipart/related; type=application/dicom
  • multipart/related; type=application/dicom+json
  • application/dicom

No coercing or replacing of attributes is done by the server.

Note that for convenience, the Store Transaction also accepts a single part HTTP request with a single DICOM instance with content type application/dicom. This is not part of the official DICOMweb standard.

JSON Metadata and Bulk Data Requests

When storing instances using JSON metadata and bulk data, the first multipart part must consist of a JSON array of DICOM instances.

The first part must have a Content-Type of application/dicom+json; transfer-syntax=TransferSyntaxUID where TransferSyntaxUID is the transfer syntax which was used to encode binary data in InlineBinary objects. If no InlineBinary objects are present in the metadata, the transfer-syntax parameter can be omitted.

The following DICOM elements are required to be present in every instance in the JSON metadata:

  • MediaStorageSOPClassUID
  • MediaStorageSOPInstanceUID
  • SpecificCharacterSet
  • TransferSyntaxUID
  • SOPClassUID
  • StudyInstanceUID
  • SeriesInstanceUID
  • SOPInstanceUID

The following attributes must have the same value:

  • MediaStorageSOPClassUID and SOPClassUID
  • MediaStorageSOPInstanceUID and SOPInstanceUID

The SpecificCharacterSet element must be set to ISO_IR 192, and the JSON metadata must be encoded in unicode UTF-8. The TransferSyntaxUID must not be set to any of the following unsupported transfer syntaxes:

  • 1.2.840.10008.1.2.2 (Explicit VR Big Endian)
  • 1.2.840.10008.1.2.1.99 (Deflated Explicit VR Little Endian)

Within the JSON metadata, the user can specify multiple BulkDataURIs for DICOM tags with VRs of OB, OW, or UN. These BulkDataURIs indicate that the binary data for the tag which contains the URI will be sent in a following part which has the Content-Location header set to the BulkDataURI.

Each instance in the JSON metadata can have at most one BulkDataURI. There must not be any duplicate BulkDataURIs in the JSON metadata. Compressed image bulk data must only be sent for the PixelData tag, and when sent, the transfer syntax specified in the bulk data part must match the value of the instance's TransferSyntaxUID element.

The following Content-Types are supported for bulk data parts:

  • application/octet-stream
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.70
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.50
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​51
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​57
  • image/x-dicom-rle; transfer-syntax=1.2.840.10008.1.2.5
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.​4.​80
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.4.81
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.90
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.91
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.92
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.93

An alternative method to specify binary data is to encode it as an InlineBinary base64 encoded string. This is supported for all tags except PixelData, which must be sent as a bulk data part. When InlineBinary objects are used in the JSON metadata, the transfer syntax which was used for encoding must be specified in the Content-Type of the JSON metadata part.

The server does not derive image pixel description macro attributes.

Response

On an error, either an additional FailureDetail (0009, 0097) tag (for XML responses) or FailureDetailJSON (0009,1097) tag (for JSON responses) will be returned. The FailureDetail tag provides a human-readable description of the error.

If an identical DICOM instance already exists in the DICOM store, a WarningReason (0008, 1196) tag is returned containing the 45070 status code. This is followed by either a WarningDetail (0009, 0096) tag (for XML responses) or a WarningDetailJSON (0009, 1096) tag (for JSON responses). The WarningDetail provides a human-readable description of the warning. If a DICOM instance is not identical to an existing one but has the same <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID> tuple as one in the DICOM store, then a Processing failure error will be returned with an "already exists" FailureDetail tag.

The response can be in either JSON or XML format which can be controlled via the following Accept header values:

  • application/dicom+xml (default)
  • application/dicom+json

Search Transaction

The Search Transaction is a RESTful web service for querying DICOM imaging metadata.

The Cloud Healthcare API supports searching for studies, series and instances.

Search Parameters

Searching by the following tags is supported

  • StudyInstanceUID
  • SeriesInstanceUID
  • SOPInstanceUID
  • PatientName
  • PatientID
  • AccessionNumber
  • Modality
  • ReferringPhysicianName
  • StudyDate
  • ModalitiesInStudy

Only single value, exact matching is supported, except for StudyDate which supports range queries and PatientName which supports fuzzy matching.

The following additional URL parameters are supported:

  • fuzzymatching: If set to true, fuzzy matching will be applied to the PatientName tag. Fuzzy matching will perform tokenization and normalization of both the value of PatientName in the query and the stored value. It will match if any search token is a prefix of any stored token. For example, if PatientName is "John^Doe", then "jo", "Do" and "John Doe" will all match. However "ohn" will not match.

Paging is supported using the limit and offset query parameters. There is no Warning response header if no more results are available. You must execute an extra query to determine if there are more results.

  • limit: Maximum number of results that should be returned, up to a maximum of 5,000 for studies/series and 50,000 for instances. The default number of results is 100 for studies/series and 1,000 for instances.

  • offset: Number of results to skip in the beginning.

Timezone Offset From UTC is not supported.

Returned Results

The response can be in either JSON or XML format which can be controlled via the following Accept header values:

  • application/dicom+json (default)
  • multipart/related; type=application/dicom+xml

By default the following attributes will be returned:

  • Studies:
    • SpecificCharacterSet
    • StudyDate
    • StudyTime
    • AccessionNumber
    • InstanceAvailability
    • ReferringPhysicianName
    • TimezoneOffsetFromUTC
    • RetrieveURL
    • PatientName
    • PatientID
    • PatientBirthDate
    • PatientSex
    • StudyInstanceUID
    • StudyID
  • Series:
    • SpecificCharacterSet
    • Modality
    • TimezoneOffsetFromUTC
    • SeriesDescription
    • RetrieveURL
    • SeriesInstanceUID
    • PerformedProcedureStepStartDate
    • PerformedProcedureStepStartTime
    • RequestAttributesSequence
  • Instances:
    • SpecificCharacterSet
    • SOPClassUID
    • SOPInstanceUID
    • InstanceAvailability
    • TimezoneOffsetFromUTC
    • RetrieveURL
    • InstanceNumber
    • Rows
    • Columns
    • BitsAllocated
    • NumberOfFrames

For includefield=all, the default attributes will be returned along with the following attributes:

  • Studies:
    • PersonIdentificationCodeSequence
    • PersonAddress
    • PersonTelephoneNumbers
    • PersonTelecomInformation
    • InstitutionName
    • InstitutionAddress
    • InstitutionCodeSequence
    • ReferringPhysicianIdentificationSequence
    • ConsultingPhysicianName
    • ConsultingPhysicianIdentificationSequence
    • IssuerOfAccessionNumberSequence
    • LocalNamespaceEntityID
    • UniversalEntityID
    • UniversalEntityIDType
    • StudyDescription
    • PhysiciansOfRecord
    • PhysiciansOfRecordIdentificationSequence
    • NameOfPhysiciansReadingStudy
    • PhysiciansReadingStudyIdentificationSequence
    • RequestingServiceCodeSequence
    • ReferencedStudySequence
    • ProcedureCodeSequence
    • ReasonForPerformedProcedureCodeSequence
  • Series:
    • SeriesNumber
    • Laterality
    • SeriesDate
    • SeriesTime
  • Instances: all attributes present in the DICOM instance except for any attribute which has a DICOM Value Representation of OB, OD, OF, OL, OW, or UN.

Inconsistent/Invalid Metadata

In the case of SearchForStudies/SearchForSeries there is a potential for inconsistent study/series level metadata across multiple instances. For example, two instances could be uploaded with the same StudyInstanceUID but have different StudyDates. In this case, the search behavior is not well defined. Searching by that value may work in some cases, but not others and the returned value may vary across different calls.

Deletion

The Cloud Healthcare API supports the following proprietary action types:

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

These use the same request paths as their WADO-RS counterparts (RetrieveStudy, RetrieveSeries, and RetrieveInstance, respectively). Instead of an HTTP GET request, a DELETE request is used. The effect is that the specified study, series, or instance is deleted along with all the DICOM resources contained in it.

Accept Headers

Some of the above methods provide the ability to control the response format using HTTP Accept headers. Wildcard matching is supported at both the top level (e.g. */*) and subtype (e.g. image/*). Specifying a q value is also supported to indicate relative preference. If a q value is not specified for an Accept header, it is set to the default value of 1.0.

In the event that multiple Accept headers are specified and there is a tie between the highest preference Accept headers, the server will choose the Accept header. Clients should not depend on the server's choice of Accept header in this scenario.

Var denne siden nyttig? Si fra hva du synes:

Send tilbakemelding om ...

Cloud Healthcare API