| Documentation | Build Status |
|---|---|
Native Julia port of the twixtools / pymapVBVD / Matlab mapVBVD tools for reading Siemens raw MRI data (twix .dat files).
Supports both VB and VD/VE/XA software versions.
using Pkg
Pkg.add("MRITwixTools")Or in development mode:
Pkg.develop("MRITwixTools")using MRITwixTools
# Read a twix file (returns raw data by default — no processing)
twixObj = read_twix("meas_MID00305.dat")
# For multi-raid files (VD/VE/XA), twixObj is a Vector{TwixObj}
# For single-raid files (VB), it is a single TwixObj
# Read image data
data = getdata(twixObj.image)
# Or with slicing (1-based Julia indexing)
data = twixObj.image[1:128, :, :]
# Check available scan types
MDH_flags(twixObj) # e.g. ["image", "noise", "refscan"]By default, read_twix returns raw data with no processing. Enable processing either at load time or afterwards:
# At load time
twixObj = read_twix("meas.dat", removeOS=true, squeeze=true)
# Or afterwards
twixObj.image.removeOS = true
twixObj.image.squeeze = true
data = getdata(twixObj.image)Available flags (all false by default):
twixObj.image.removeOS = true # Remove 2× readout oversampling
twixObj.image.regrid = true # Ramp sample regridding
twixObj.image.doAverage = true # Average across averages
twixObj.image.averageReps = true # Average across repetitions
twixObj.image.averageSets = true # Average across sets
twixObj.image.ignoreSeg = true # Collapse segments dimension
twixObj.image.squeeze = true # Drop singleton dimensions
twixObj.image.disableReflect = true # Skip readout reflection correction
twixObj.image.ignoreROoffcenter = true # Ignore readout off-center shiftsHeaders support tab-completion at every level:
hdr = twixObj.hdr
# Dot access (tab-completable)
hdr.MeasYaps.sKSpace.lBaseResolution # => 256.0
# Path string access
hdr["MeasYaps"]["sKSpace.lBaseResolution"] # => 256.0
# Search across all header sections (matches key paths)
search(hdr, "lBaseRes")
# => ["MeasYaps.sKSpace.lBaseResolution" => 256.0,
# "Phoenix.sKSpace.lBaseResolution" => 128.0]
# Search with multiple terms (AND logic)
search(hdr, "sTXSPEC", "Nucleus")
# => ["MeasYaps.sTXSPEC.asNucleusInfo.0.tNucleus" => "\"1H\""]
# Search by value (also matches against leaf values)
search(hdr, "1H", search_values=true)
# => ["MeasYaps.sTXSPEC.asNucleusInfo.0.tNucleus" => "\"1H\""]
# Combined: path contains "Nucleus" AND value contains "1H"
search(hdr, "Nucleus", "1H", search_values=true)
# List all leaf values
leaves(hdr)If a scan contains MDH_SYNCDATA packets (e.g. PMU/physio traces or
sequence-specific binary blobs written by custom pulse sequences), their raw
payload bytes are exposed on the TwixObj:
twx = read_twix("meas.dat")
if haskey(getfield(twx, :_data), "syncdata")
for pkt in twx.syncdata # Vector{Vector{UInt8}}
# search for a sequence-specific tag and parse whatever binary layout follows
end
endMRITwixTools does not attempt to interpret these payloads because their layout is entirely sequence-specific. See the SYNCDATA guide for a worked example.
Several tools exist for reading Siemens twix (.dat) files:
- mapVBVD — the original MATLAB tool by Philipp Ehses
- pymapVBVD — Python port by Will Clarke
- twixtools — Python reader/writer with low-level mdb access by Philipp Ehses
| mapVBVD (MATLAB) | pymapVBVD (Python) | twixtools (Python) | MRITwixTools.jl | |
|---|---|---|---|---|
| Indexing | 1-based | 0-based | 0-based | 1-based |
removeOS |
false |
True |
False |
false |
regrid |
false |
True |
False |
false |
| mapVBVD | pymapVBVD | twixtools | MRITwixTools.jl | |
|---|---|---|---|---|
| Read data | twix.image() |
twix.image[''] |
loop over mdb list |
getdata(twix.image) |
| Slice data | twix.image(:,:,1) |
twix.image[:,:,0] |
— | twix.image[:,:,1] |
| Squeeze | twix.image{''} |
.squeeze = True |
manual | .squeeze = true |
| Set flag | .flagRemoveOS = 1 |
.flagRemoveOS = True |
.flags['remove_os'] |
.removeOS = true |
| Header | hdr.MeasYaps (struct) |
hdr.MeasYaps[tuple] |
hdr['MeasYaps'] |
hdr.MeasYaps.sKSpace... |
| Search | — | search_header_for_keys |
— | search(hdr, terms...) |
| mapVBVD | pymapVBVD | twixtools | MRITwixTools.jl | |
|---|---|---|---|---|
| Write support | — | — | ✓ | — |
| Low-level mdb access | — | — | ✓ | — |
| Multi-raid (VD/VE/XA) | ✓ | ✓ | ✓ | ✓ |
- FFTW.jl — FFT for oversampling removal
- Interpolations.jl — Ramp sample regridding
- ProgressMeter.jl — Progress bars
This is a native Julia port of the Python pymapVBVD by Will Clarke, which is itself a port of Philipp Ehses' original Matlab mapVBVD. See also Philipp Ehses' twixtools, which provides reading, writing, and low-level mdb access for twix files in Python.
Released under the MIT License.