Data requirements
This page lists the data requirements for the Flywheel viewer to operate as expected.
DICOM requirements
Introduction
The Flywheel Hierarchy closely matches the DICOM Model of the Real World , but with slightly different nomenclature.
Patient
becomesSubject
in FlywheelStudy
becomesSession
in FlywheelSeries
(roughly) becomesAcquisition
in Flywheel
Note
Series
to Acquisition
mapping is not strictly enforced. Generally raw data from a scanner will map 1:1 (meaning two Series
that come in from a scanner will usually be in two different Acquisitions
) , but sometimes a derived series with a different SeriesNumber
and SeriesInstanceUID
will be placed in the same acquisition by the running of a utility gear.
Depending on how DICOM data is imported into Flywheel, the mapping between DICOM tags and Flywheel hierarchy fields might differ. Please check the following pages for more information:
Assumptions
DICOM UIDs uniqueness
The V2 viewer relies on DICOM data to be indexed in the Flywheel's DICOM Web service. Since that DICOM Web service enforces the DICOM hierarchy, it means that there cannot be two DICOM files with the same SeriesInstanceUID
or StudyInstanceUID
within the same Flywheel project. If that's the case, the V2 Viewer will not open one of the files with a duplicate UID. See also Viewer indexing errors.
The V3 viewer relies on a different data service that does not have the constraints of the DICOM hierarchy, therefore there is no requirements about DICOM UIDS uniqueness for the V3 viewer.
Zip files
DICOM files sharing the same SeriesInstanceUID are expected to be zipped in a single zip archive and that zip archive must only contain DICOM files belonging to the same SeriesInstanceUID.
Hidden Files
One must take care when uploading zip files that only the DICOM files are in there. On Macs there are often hidden files such as thumbs.db
or .__MACOSX
folders, which will need to be removed.
V2 Viewer
The V2 viewer requires the following tags:
Tag | VR | Name |
---|---|---|
(0020,000E) | UI | SeriesInstanceUID |
(0020,000D) | UI | StudyInstanceUID |
(0008,0060) | CS | Modality |
(0020,0011) | IS | SeriesNumber |
(0040,0009) | SH | ScheduledProcedureStepID |
(0040,1001) | SH | RequestedProcedureID |
(0008,0020) | DA | StudyDate |
(0008,0030) | DM | StudyTime |
(0020,0010) | SH | StudyID |
(0020,0011) | IS | SeriesNumber |
(0010,0020) | LO | PatientID |
V3 viewer
DICOM tags required for all images to open in the viewer
Tag | VR | Name | Description |
---|---|---|---|
(0020,000D) | UI | StudyInstanceUID | Unique identifier for the study |
(0020,000E) | UI | SeriesInstanceUID | Unique identifier for the series |
(0008,0018) | UI | SOPInstanceUID | Unique identifier for the object |
(0028,0004) | CS | PhotometricInterpretation | Color space of the image |
(0028,0010) | US | Rows | Dimension of the image |
(0028,0011) | US | Columns | Dimension of the image |
(0028,0103) | US | PixelRepresentation | Indicates how pixel data should be interpreted |
(0008,0060) | CS | Modality | Type of modality (e.g. CT, MR, etc.) |
(0028,0100) | US | BitsAllocated | Number of bits allocated for each pixel sample |
(0008,0016) | UI | SOPClassUID | Specifies the DICOM service class of the object |
(0020,0013) | IS | InstanceNumber | Identifies the instance |
Note: Only standard SOPClassUIDs are supported. See the list of SOPClassUIDs currently supported by the viewer here.
DICOM tags required to render images in advanced layouts (MPR and 3D rendering)
All data
- Series must have more than 1 image.
- Series should not be a 4D dataset.
- All images should have
Pixel Spacing (0028,0030)
(some exceptions for multi-frame data, see below).
Single-frame data
Rows (0028,0010)
andColumns (0028,0011)
must be the same for all instances.SamplePerPixel (0028,0002)
must match across all instances.- All instances must have
ImageOrientationPatient (0020,0037)
values within a small tolerance in vector directions, default is 0.01. ImagePositionPatient (0020,0032)
should exist in all instances.- The spacing between consecutive frames, as determined by the
ImagePositionPatient
value for each frame, should be equal to the average spacing between frames with a 0.2mm tolerance. - If slice spacing is approximately an integer multiple of the average spacing (e.g., 2×, 3×), it is assumed that frames are missing. The dataset is still reconstructible and the missing frames are tracked.
Multi-frame data
-
Pixel measurement information is required from any one of these tags:
PerFrameFunctionalGroupsSequence.[0].PixelMeasuresSequence(0028,9110)
SharedFunctionalGroupsSequence.PixelMeasuresSequence(0028,9110)
PixelSpacing(0028 0030)
either withSliceThickness(0018,0050)
orSpacingBetweenFrames(0018,0088)
-
Orientation information is required from any one of these tags:
SharedFunctionalGroupsSequence.PlaneOrientationSequence(0020,9116)
PerFrameFunctionalGroupsSequence.PlaneOrientationSequence(0020,9116)
ImageOrientationPatient(0020,0037)
DetectorInformationSequence.[0].ImageOrientationPatient(0020,0037)
-
Position information is required from any one of these tags:
PlanePositionSequence(0020,9113)
CTPositionSequence(0018,9326)
ImagePositionPatient(0020,0032)
DetectorInformationSequence.[0].ImagePositionPatient(0020,0032)
NM modality
ImageType.[2] (0008,0008)
should be eitherRECON TOMO
orRECON GATED TOMO
DICOM tags required for segmentation overlay
Segmentation files (DICOM SEG and DICOM RTSTRUCT) cannot be loaded in the viewer without a reference image series. The reference image series for a segmentation file is defined as an image series that has SOPInstanceUIDs
that match the ReferencedSOPInstanceUIDs
from the ReferencedSeriesSequence
of the segmentation file.
When loading a segmentation file into a viewport, the viewer will return an error message if no reference image series is found in the left-side panel.
Additionally segmentation files require specific tags/sequences:
DICOM SEG files
FrameOfReferenceUID (0020,0052)
-
sequences:
ReferencedSeriesSequence (0008,1115)
SharedFunctionalGroupsSequence (5200,9229)
PerFrameFunctionalGroupsSequence (5200,9230)
DICOM RTSTRUCT files
FrameOfReferenceUID (0020,0052)
-
sequences:
ROIContourSequence(3006,0039)
StructureSetROISequence(3006,0020)
ReferencedFrameOfReferenceSequence(3006,0010)
DICOM tags required for measurements
All modalities
Pixel Spacing (0028,0030)
Ultrasound data
SequenceOfUltrasoundRegions(0018,6011)
DICOM tags required for PET data conversion to SUV units
For PET data, pixel values will be displayed in SUV units if:
-
Units (0054, 1001)
=BQML
,CNTS
orGML
-
Pixel values will be displayed according to the value of the
Units (0054,1001)
tag if the value is different from the three values above. See here for possible units values. -
Pixel values won’t have any unit if the
Units (0054,1001)
is missing or has no value.
If the condition above is met, the following DICOM tags are required to convert PET data in SUV units:
RadiopharmaceuticalInformationSequence (0054,0016)
Radionuclide Half Life (0x0018,0x1075)
(in seconds)Radiopharmaceutical Start DateTime (0018,1078)
or `Radiopharmaceutical Start Time (0x0018,0x1072)Radionuclide Total Dose (0x0018,0x1074)
SeriesDate (0008,0021)
SeriesTime (0008,0031)
CorrectedImage (0028,0051)
: needs to containATTN
andDECY
Units (0054, 1001)
DecayCorrection (0054,1102)
→ needs to beSTART
AcquisitionDate (0008,0022)
AcquisitionTime (0008,0032)
PatientWeight (0010,1030)
SUVs are calculated from DICOM metadata based on the logic summarized by the Quantitative Imaging Biomarkers Alliance on their wiki page.
Known limitations and unsupported data
V3 viewer
Non-standard SOPClassUIDs
Non-standard SOPClassUIDs are currently not supported. Please refer to the list of supported SOPClassUIDs.
Series with multiple multi-frame images
A multi-frame image is defined as one file containing multiple images. The viewer currently does not support image series that consist in multiple multi-frame images.
Maximum number of images in a series
The viewer currently only supports series with a maximum number of 5,000 single images.
Ultrasound data
Data with PhotometricInterpretation (0028,0004)
= PALETTE COLOR
is currently not supported.