The DICOM standard includes figures describing the "DICOM model of the real-world."

This is not identical to the XNAT data model, and in fact the XNAT data model originated before XNAT support existed for DICOM. (The MR scan and session types were based on Siemens Analyze, though they've become more DICOM-ish over time; PET was based on ECAT and still hasn't drifted much DICOMward.)

Apart from the differences in the data model, the concrete representation of XNAT's data model is vastly different from how DICOM is represented. DICOM metadata storage is massively denormalized, with every image file containing all of the metadata pertaining to that image; whereas the XNAT XML is a unified, compact representation of the experiment metadata. Notes: 1. this is the last time you will hear me call XML "compact"; 2. I'm asserting that the experiment XML is the canonical representation of XNAT metadata. You could argue for other canonical representations (e.g., the SQL database) but you'd be wrong.

The project dicom-xnat, composed of the subprojects dicom-xnat-mx, dicom-xnat-sop, and dicom-xnat-util, defines our mapping from the DICOM data model to XNAT, and from individual DICOM metadata elements to fields in an XNAT experiment document. The primary interface to dicom-xnat is through the class org.nrg.dcm.xnat.DICOMSessionBuilder, defined in dicom-xnat-mx. When the DICOM session builder is called, it walks the experiment file tree and creates a temporary HSQL database with one row per DICOM file and one column per DICOM attribute that might contribute to an XNAT field. (In some cases, this is instead one column per translated XNAT field value; this is common for HCP customizations that use fields parsed from Siemens shadow headers.) This database is then used to compute the XNAT metadata fields: by series for scan-level attributes, and by study for experiment-level attributes.

The session builder is normally run by XNAT when the C-STORE session timeout expires, or when the upload applet indicates that session transfer is complete. The session builder can also be invoked on archived sessions via the REST API, by issuing a (blank entity) PUT to the session resource with the query parameter pullDataFromHeaders=true .

Customizing metadata translation

To add a new XNAT attribute:

  1. Add the attribute to the schema
    1. It's possible to use addparams instead; there's a lot of this in HCP MR scans. This is such a common thing to do that there's a type (XnatAttrDef.AddParam) and a utility method (wrap()) to make it easy.
  2. Write the attribute conversion class
    1. This is complicated. "Attribute translation" below provides some details and lots of examples.
    2. Often there's a class that already does what you want. Be sure to look through XnatAttrDef and the various attribute lists to see if what you need is already implemented.
    3. If you're doing simple text conversion, you won't even need a class, you can just provide the XNAT attribute name and the DICOM tag
  3. Add the attribute to the session/scan class (see "Attribute definition" below), as one more s.add(...) line
  4. Rebuild the dicom-xnat-mx jar, changing the version number if that makes sense for you
  5. Replace plugin-resources/repository/dcm/jars/dicom-xnat-mx-... with your modified version
  6. Update and restart the webapp

Mechanics of metadata translation

The heart of the DICOM-to-XNAT metadata translation code is the class DICOMSessionBuilder, defined in the project dicom-xnat-mx. Most of the action takes place in the method call(), which returns a modality-specific subclass of XnatImagesessiondataBean:

The scan builder is broadly similar to the session builder, though there are differences in the details:

The logic for mapping DICOM modalities and SOP classes to XNAT types is accessed via static methods on SOPModel, but defined in text resource files interpreted at class load time.

As a practical matter, most metadata translation customization can be done without modifying any of this base functionality. Changing the details of file storage (e.g., by replacing the current catalog file structure) will likely require changes to at least DICOMScanBuilder.

Attribute definition

The translation operations that build individual XNAT attributes from DICOM metadata are specified in modality- (MR, PET, CT) and level- (session, scan, image) specific classes in the package org.nrg.dcm.xnat of dicom-xnat-mx.

For example, all session-level types (mrSessionData, ctSessionData) build on a base of attributes defined in ImageSessionAttributes. The attributes defined in this class are a representative sample of attribute translation definitions.

The more common point of customization is the modality-specific class. Let's consider MRScanAttributes:

Attribute translation

Classes that define the translation from DICOM metadata to one XNAT attribute must implement the interface XnatAttrDef or its superclass ExtAttrDef<DicomAttributeIndex>.

The most complicated custom attribute definitions are in the HCP IntraDB. The attribute parameters/deltaTE, derived by the class DeltaTEAttr, has a somewhat complex value aggregation.