How an MRI protocol sits inside a DICOM file
By Shank
I have been exploring DICOMpare, the MRI tool on Neurodesk. You give it a study and it puts the acquisitions side by side. You can compare two sessions, or check one against a schema.
I got stuck one step before that. The input is a folder of DICOM files, so where is the protocol?
The settings of the scan that already happened are written in the same DICOM file as the image. This is that explanation, in the order it became clear to me. Once the file made sense, I wrote a small reader with fo-dicom to pull the numbers out. The cli reader comes at the end.
What is inside one DICOM file
The start of the file is easy. The first 128 bytes can be ignored. Then you see the four letters DICM. After that is a short block, group 0002. It says what kind of object this file is, and how the rest of the bytes are encoded. Everything after that block is the dataset.
The dataset is a list. Each item is a data element, and each element has four parts.
- A tag, which is the address. Two numbers, group and element, written like
(0018,0080). - A type, two letters. Text, a date, a decimal, or a nested list.
- A length, so you know where this value ends and the next tag begins.
- The value.
Sometimes the type letters are in the file. Sometimes you take them from the DICOM dictionary. Either way, you go to the tag.
flowchart LR A["128 bytes, ignore"] --> B["DICM"] B --> C["File info, group 0002"] C --> D["List of tags"] D --> E["The image, 7FE0,0010"]
For an MRI study ideally we need to remember a few groups.
| Item | Group |
|---|---|
| Patient | Group 0010 |
| Modality, dates, series description | Group 0008 |
| Which study, which series, where the slice sat | Group 0020 |
| How the scan was acquired | Group 0018 |
| Rows, columns, pixel spacing | Group 0028 |
| The image bytes | (7FE0,0010) |
The image is the heavy element, (7FE0,0010), plain samples or something compressed such as JPEG. Repetition time and echo time are short numbers in group 0018. Odd-numbered groups are private, a scanner’s own extra detail. I left those closed.
Which of those tags is the protocol
I had mixed up two different things, both called protocol.
One is the label. Protocol Name, (0018,1030), and Series Description, (0008,103E), are text somebody typed. Both are optional. A label can say “T1” on two series whose timing is different. The name is not the protocol.
The protocol is the acquisition: how the sequence was run. These are public tags. They are not a guaranteed set. On a classic MR image the standard uses four rules.
- Must be filled. The tag has to be present, and it has to contain a value.
- Tag expected, value may be empty. The tag should be present. If the number is unknown, the value may be blank.
- Only some scans. Required for one kind of sequence. Other scans may omit it. When it is required, the value may still be blank.
- Optional. A legal file can leave the tag out.
In the standard those four rules are called Type 1, Type 2, Type 2C, and Type 3.
On a classic file, only two acquisition tags must be filled. Scanning Sequence says the family. Sequence Variant says a small extra on that family. They do not give you TR or TE.
Scanning Sequence is the method used to make the echo. A spin echo, code SE, sends a second radiofrequency pulse so the signal comes back together. A gradient echo, code GR, skips that second pulse and makes the echo by reversing a gradient. Inversion recovery, code IR, adds a preparation pulse before the rest, which is why an inversion time belongs to that family. Echo planar, code EP, reads many lines quickly after one excitation. Research, code RM, is a sequence the standard does not try to name.
Sequence Variant is not a second timing number. Spoiled, code SP, means leftover signal is wiped before the next shot. Steady state, code SS, means that leftover signal is kept. Segmented k-space, code SK, means the raw data for one image were collected in pieces. NONE means there is no extra of this kind. A plain spin echo is often SE with NONE.
These two tags are words. GR and SP tell me the method. They do not tell me that the echo arrived at 3 ms, or that the next excitation waited 2000 ms. Two scans can both be spoiled gradient echo and still differ in TR, TE, and flip angle. Those times are the other tags in the table.
The picture grid is stricter than the timing. Rows, columns, and pixel spacing must be filled. That is the size of the image. It is not the pulse sequence.
| What | Tag | Unit | On a classic file | What it means |
|---|---|---|---|---|
| Scanning sequence | (0018,0020) |
code | Must be filled | SE spin echo, IR inversion recovery, GR gradient echo, EP echo planar, or RM research |
| Sequence variant | (0018,0021) |
code | Must be filled | For example spoiled, steady state, segmented k-space, or none |
| Rows and columns | (0028,0010), (0028,0011) |
pixels | Must be filled | Height and width of the image |
| Pixel spacing | (0028,0030) |
mm | Must be filled | Size of one pixel. This is the grid, not the timing |
| 2D or 3D | (0018,0023) |
2D or 3D | Tag expected, value may be empty | How the data were encoded |
| Echo time, TE | (0018,0081) |
ms | Tag expected, value may be empty | From the middle of the excitation pulse to the echo peak |
| Echo train length | (0018,0091) |
count | Tag expected, value may be empty | K-space lines collected per excitation |
| Slice thickness | (0018,0050) |
mm | Tag expected, value may be empty | Thickness of the slice |
| Repetition time, TR | (0018,0080) |
ms | Only some scans | Time from one excitation to the next. Required unless the scan is echo planar and not segmented k-space |
| Inversion time | (0018,0082) |
ms | Only some scans | Required when the scanning sequence is inversion recovery |
| Flip angle | (0018,1314) |
degrees | Optional | How far the magnetisation is tipped |
| Spacing between slices | (0018,0088) |
mm | Optional | Distance between slice centres |
| Acquisition matrix | (0018,1310) |
counts | Optional | Frequency and phase sizes before reconstruction |
| Phase-encode direction | (0018,1312) |
ROW or COL | Optional | Which image axis was phase encoded |
| Field strength | (0018,0087) |
tesla | Optional | For example 1.5 or 3 |
| Protocol name | (0018,1030) |
text | Optional | The typed label |
| Series description | (0008,103E) |
text | Optional | Another typed label |
So the honest answer is small. A conformant classic MRI file must tell you the sequence family and the image grid. It should carry TE, echo train length, 2D or 3D, and slice thickness, but those values may be empty. TR is required on most sequences and may be absent on some echo-planar ones. Flip angle, the slice gap, the matrix, the phase-encode direction, the field strength, and both names are optional. A folder of real scans is looser still: a scanner can skip a required tag, or write 0 where it means “not used”.
Enhanced MR, the 2002 object, is the place where the timing gets stricter. When a frame is an original acquisition, the timing list must include repetition time, flip angle, and echo train length, and the frame must include an effective echo time. A repetition time of 0 there means the volume was excited once. That is the nearest thing to a guaranteed timing set, and it applies to that enhanced original frame, not to every classic file.
Classic and enhanced: two ways of writing the same list
Since 1993, one DICOM file has been one slice. A scan of 160 slices is 160 files. When the scanner wrote TR, TE, or flip angle, they sit at the top of each file. Many studies still arrive this way.
In 2002 a second way was added. Supplement 49, Enhanced MR, was finished on 26 March 2002, after work from about 1999 to 2003. Diffusion, function and perfusion are many frames, and those frames do not share one echo time. A functional run can be 10,000 to 64,000 images. One file per image repeats the common description thousands of times.
Enhanced MR puts many frames in one file. What stays the same is written once. What changes is written on the frame. Related tags sit together in a small nested list, called a functional group.
One more name matters, because old archives use it. Supplement 157, 25 June 2013, calls this legacy converted: old slices packed into the multi-frame file when they do not have enough detail for a full enhanced object. I read that file the same way as enhanced.
flowchart TB
subgraph classic["Classic, since 1993"]
C1["One file is one slice"]
C1 --> C2["TR, TE, flip angle at the top of the file"]
C1 --> C3["One block of pixels"]
end
subgraph enhanced["Enhanced, since 2002"]
E1["One file, many frames"]
E1 --> E2["Shared list 5200,9229<br/>written once"]
E1 --> E3["Per-frame list 5200,9230<br/>one entry per frame"]
E3 --> E4["Each frame can have its own echo time"]
end
When the reader opens a file, it decides which kind it is. It is enhanced if the object type says Enhanced MR, Enhanced MR Color, or Legacy Converted Enhanced MR, or if simply it finds the per-frame list (5200,9230).
The shared list, (5200,9229), has one entry. Timing, pixel size and coils that are true for every frame go there. The per-frame list has one entry per frame, in order, and the first entry is frame 1. I use the frame’s own value when it has one, and the shared value when it does not. A group may sit in either list. Same TR on every frame, and it can be shared. Different values, and it moves to the frame. The talk and the standard both say this, so I look in both places.
Echo time is the one I had to handle by hand. Classic files keep one number at the top, (0018,0081). Enhanced files can give each frame its own, Effective Echo Time (0018,9082), inside the MR Echo list (0018,9114). Same measurement: milliseconds from the middle of the excitation pulse to the echo peak. I read every frame and save it as echo time, so both kinds of series land in one column. One value stays a number. Several become a sorted list, and that list is a multi-echo series.
Four small rules change the number you will see.
- If the top of the file already has a value, I keep it. The frame lists only fill a gap. Echo time is the exception. For echo time, the frames win.
- Missing TR, flip angle or echo train length comes from the timing list
(0018,9112). - Missing slice thickness or pixel spacing comes from the pixel-measures list
(0028,9110). - A zero in TR, TE, inversion time, flip angle, thickness or echo train length is dropped on a classic file. I treat it as unused. On an enhanced file, a TR of zero is kept, because the timing list says zero means the volume was excited once.
How the reader walks a folder
With the two layouts clear, the command-line reader is just those steps on a folder.
fo-dicom opens each file and hands me the tags. Anything larger than about 4 MB is left out, which keeps the header and drops the pixels. I skip DICOMDIR and I keep a file only when the modality is MR. From there it is the split above, and then I group by study, protocol name, and series.
flowchart TD
A["A folder of DICOM files"] --> B["Read the header, leave the pixels"]
B --> C{"Is it an MR image?"}
C -->|no| D["Skip it"]
C -->|yes| E{"Classic or enhanced?"}
E -->|classic| F["Read TR, TE, flip angle from the top"]
E -->|enhanced| G["Read the shared entry, then each frame"]
F --> H["Group into study, protocol name, series"]
G --> H
H --> I["One card on screen, and one JSON file"]
If two slices in one series disagree on TR or flip angle, I keep the first value and mark the series inconsistent, so the disagreement stays visible. If echo time, inversion time or the diffusion b-value changes inside the series, I keep the list, because that change is part of the protocol.
Each series prints as one card: TR, TE, inversion time, flip angle, then 2D or 3D, matrix, voxel size, phase-encode direction, and the plane. I turn the orientation into axial, sagittal or coronal so the card stays short. The same record is written as JSON, which is what a second study can be compared with.
The pages I kept open
- DICOMpare, where I started
- Dicomr.Cli, the command-line reader that walks a study folder
- How a DICOM file is laid out, and how a data element is built
- Supplement 49, March 2002, the enhanced MR object, and Supplement 157, June 2013, the converted legacy one
- Wim Corbijn’s 2013 talk in Bengaluru, on why the multi-frame file exists
- Shared and per-frame lists, the timing list, and the echo-time list
- NACC’s MRI dictionary, which already reads the series name and the field strength from the header
- Claroty’s walk through the same file bytes