Private DICOM Headers Within Orthanc

DICOM files, the most common format for exchanging data in medical imaging, consists of two pieces of information: key/value metadata (usually specified in a header) and image/pixel data. The header metadata contains information about the patient, acquisition parameters for the study, dimensions, matrix size, color space and encoding, and a broad set of additional parameters. Many of the metadata tags that appear in the header are defined by the DICOM standard and are described as "standard data elements." The terms data elements, headers, and tags are often used interchangeably.

Even though there are thousands of defined elements that help to facilitate many parts of working with medical images, sometimes data is needed that is not included in the standard tags. To allow for such data to be stored and passed, DICOM files can also have "private" data elements. Private data elements work the same as standard data elements and contain a set of fields that specify what group a tag belongs to, what it encodes, its data type, and its length. The difference with the standard tags is that they are not explicitly laid out in the DICOM standard.

Orthanc is a popular open source system for working with medical imaging data stored in the DICOM format. It provides a powerful interface for indexing imaging studies and working with both meta and pixel data via an easy to use RESTful interface. It is used within the Sonador medical imaging platform as a database and work-engine for building machine learning and data streaming applications.

In this article, we'll look at what support Orthanc provides for private tags, briefly discuss how private tags are indexed, what happens when requests include private tags that are outside of the supported set, and how additional private tags can be added to Orthanc via the Dictionary section of the Orthanc configuration file.

Private Tags in Orthanc

Orthanc, via the DCMTK library it uses to parse DICOM files, is able to work with thousands of common tags. To inspect the supported values, refer to private.dic in libdcmt14. On Ubuntu 20.04, this file can be found at /usr/share/libdcmtk14/private.dic.

If a private tag is one of the supported tags within DCMTK, it is possible to work with it within Orthanc just as you would with a standard tag. They can be included in resource queries, will appear within the JSON retrieved from the /instances/{{ uid }}/simplified-tags endpoint (available via the tags property of the Sonador client), and can be modified via the /instances/{{ uid }}/modify endpoint. This level of convenience makes them a great way to store ad-hoc data about an imaging study or series, such as a label for a machine learning model.

Even though private tags are broadly supported within Orthanc, however, there are a few rules to be aware of. Private tags are considered to be instance level attributes and do not appear in the metadata for resources such as series, studies, or patients. Additionally, they only appear with the full tag set (tags property), rather than the common tags commonly retrieved via the /instances/{{ uid }} endpoint. This means that to view private tag values when working with a collection, you first must retrieve an instance and then access its tags. Private tags supported by DCMTK can be changed using the modify method of any resource. If using modify from a patient, study, or series; the private tag for all instances within that collection will be updated.

Performance Considerations

Because they are stored as an instance property, you should exercise care when submitting queries that include a private header. When using the PostgreSQL cache plugin, standard tags, such as PatientName or SeriesDescription will be kept inside of the database and can be queried efficiently, even if the Orthanc instance stores a very large number of studies. Queries that utilize private tags may trigger a linear scan of file resources, which requires significantly more time to process (particularly if the instance is large).

This doesn't mean that private tags shouldn't be included as part of a query, however. In places where you would like to filter by a private tag, a good practice is to use it as a secondary query parameter alongside standard tags. The standard query will be used to filter via the database, and the private tag becomes a secondary filter only applied to a subset of the total resources.

Unsupported Headers

If a DICOM image is uploaded with a private tag not supported by DCMTK, it will be written to Orthanc and available in the full tag metadata. Unfortunately, it cannot be modified using the modify REST endpoint, however. If you submit a request with an unsupported private tag, Orthanc will respond with a 400 status code (Bad Request). The Sonador client throws a client operation exception.

Adding Additional Tags to Orthanc

Orthanc can be configured to support additional private tags by adding entries to the Dictionary key of Orthanc's Configuration.json. The JSON in the listing below shows an example:

For each new tag that you wish to register:

• First, you provide a tag -- comprised of a group number (first component of the key) and an element number (second component of the key) -- each formatted as hexadecimal numbers.
• Next, you need to specify the value representation for the tag (value representations are two uppercase characters referring to the DICOM tag data type, refer to the DICOM standard for details).
• Third, you provide a nickname for the tag. This is the value that Orthanc will include in JSON output.
• The fourth and fifth components of the value refer to the minimum and maximum "multiplicity" of the value, which refers to the number of values that can be stored in the tag.
• Finally, you specify the "private creator" for the tag. The Private Creator is a short string that specifies the tag as belonging to a specific organization or specification. It is very important to avoid the collision of tags, as Orthanc uses a combination of private creator, private group, and tag offset to ensure distinction of private tags.