DICOM Connector Technical Reference

Introduction

This document provides comprehensive technical specifications for the Flywheel DICOM Connector, including metadata mapping rules, data processing logic, and system architecture details.

Data Processing Workflow

The DICOM Connector follows this processing sequence:

1. Discovery: Queries PACS or scanner at regular intervals for new data items
2. Readiness Assessment: Determines if series are complete and ready for upload
3. Anonymization: Remove or obfuscates sensitive metadata following rules configured via de-identification profiles
4. Metadata Extraction: Parses DICOM headers for organizational and descriptive information
5. Routing Resolution: Uses routing strings to determine target Flywheel containers
6. Upload Process: Transfers complete series to appropriate locations
7. Monitoring: Continues monitoring for changes to uploaded items

Series Completion Logic

The Connector uses the following logic to determine when to upload data:

1. Change Detection: Has the number of images in the series (NumberOfSeriesRelatedInstances header) changed since last check?
2. If yes: Assumes scan still in progress, waits for next check cycle

3. If no: Proceeds to next check

4. Upload Status Check: Has this item already been uploaded?

5. If yes: Continues monitoring for changes

6. If no: Proceeds to upload

7. Upload Execution: Uploads the complete series to Flywheel

8. Continued Monitoring: Monitors for state changes that might trigger re-upload

The definition for "item", "state", and "change" varies for different data types or modalities.

DICOM Metadata Mapping

Default Field Mappings

The following table shows standard mappings from DICOM tags to Flywheel fields:

PatientName Parsing

The PatientName field is parsed using these rules:

1. Caret Delimiter: If ^ character is present, split as {lastname}^{firstname}
2. Space Delimiter: If no ^, split on space as {firstname} {lastname}
3. No Delimiter: Entire string goes to subject.lastname, subject.firstname remains empty
4. Capitalization: Both fields are automatically capitalized

PatientName Examples

SeriesInstanceUID Processing

Special processing rules apply to SeriesInstanceUID values:

Derived Series Handling

DICOMs with ImageType values DERIVED\SECONDARY\SCREEN SAVE or DERIVED\SECONDARY\VXTL STATE receive a "decremented" UID:

• Original: SeriesInstanceUID=4.5.6
• Processed: acquisition.uid=4.5.5

AcquisitionNumber Suffix

For non-Siemens manufacturers, when AcquisitionNumber > 1, the UID is suffixed with _{AcquisitionNumber}:

Timestamp Parsing

Timestamp fields combine date and time DICOM tags:

• session.timestamp: Parsed from StudyDate + StudyTime
• acquisition.timestamp: Parsed from AcquisitionDate + AcquisitionTime

Siemens-Specific Behavior

For Siemens scanners (Manufacturer = Siemens):

• acquisition.timestamp uses SeriesDate + SeriesTime instead of AcquisitionDate + AcquisitionTime
• If SeriesDate/SeriesTime cannot be parsed, defaults to session.timestamp

Timezone Configuration

Timestamps use the timezone specified by the --timezone configuration option (defaults to UTC).

Complete Mapping Example

Routing String Processing

Format Specification

Valid routing strings follow this format:

1

fw://group/project/subject/session

Processing Rules

The Connector parses routing strings according to these rules:

Container Resolution Logic

The following flowchart describes how the DICOM Connector determines container placement:

Data Organization Structure

Flywheel Container Hierarchy

The DICOM Connector places data in the Flywheel hierarchy:

1
2
3
4
5
6

Group (Institution/Department)
└── Project (Study/Research Initiative)
    └── Subject (Participant/Patient)
        └── Session (Scan Visit/Date)
            └── Acquisition (Scan Series)
                └── Files (Image Files)

Container Creation Rules

• Groups: Desired group should be manually created in advance.
  • Unknown group is automatically created if desired group does not exist or if mapping string is missing or cannot be parsed.
• Projects: Created based on routing string.
  • Ideally, the desired project is manually created in advance with the preferred settings. Otherwise, the DICOM connector will create it with default settings.
  • Unsorted project is created if mapping string is missing or cannot be parsed.
• Subjects: Created based on routing string or derived from DICOM metadata (e.g., PatientID)
• Sessions: Created based on routing string or derived from DICOM metadata (e.g., StudyDescription)
• Acquisitions: Always created for each unique SeriesDescription

Classification Integration

Automated Classification

The DICOM Connector integrates with Flywheel's automated classification system:

1. Upload Completion: After successful upload, classification gears are triggered
2. Header Analysis: Classification examines DICOM headers and series descriptions
3. Pattern Matching: Matches acquisition names against classification rules
4. Metadata Application: Applies appropriate classification metadata to acquisitions

Refer to the documentation on Preparing Acquisitions for Automated Classification for further details.