KomaMRIFiles

Sequence

KomaMRIFiles.read_seq Function

seq = read_seq(filename)

Returns the Sequence struct from a Pulseq file with .seq extension.

Explicit Nx, Ny, and Nz definitions are recommended for reconstruction. Missing dimensions remain absent from seq.DEF; raw-data export infers them from imaging ADCs, LIN/PAR labels, and FOV/k-space coverage. Slices come only from SLC labels, never from RF frequency offsets or the number of ADC events.

Arguments

• filename: (::String) absolute or relative path of the sequence file .seq

Keywords

• verify_signature: (::Bool, =false) verify the optional Pulseq [SIGNATURE] hash while loading

• apply_rotations: (::Bool, =true) apply Pulseq ROTATIONS extensions to the gradients while keeping the extension events in seq.EXT

• verbose: (::Bool, =true) show informational loading messages

Returns

• seq: (::Sequence) Sequence struct

Examples

julia> seq_file = joinpath(dirname(pathof(KomaMRI)), "../examples/1.sequences/spiral.seq")

julia> seq = read_seq(seq_file)

julia> plot_seq(seq)

source

KomaMRIFiles.read_seq_data Function

data = read_seq_data(filename)

Read a Pulseq file into Pulseq's native block/event-library representation without materializing repeated Koma Sequence events.

source

KomaMRIFiles.write_seq Function

write_seq(seq, filename)

Writes a Sequence struct to a Pulseq file with .seq extension.

Arguments

• seq: (::Sequence) Sequence struct

• filename: (::String) absolute or relative path of the sequence file .seq

• sys: optional scanner used for hardware-limit validation and export raster times. If passed, sys raster times take precedence over seq.DEF.

• significant_digits: significant digits used when writing Pulseq floats. Defaults to Koma's 12-digit writer; use 6 to match MATLAB Pulseq event libraries.

• shape_significant_digits: significant digits used for Pulseq shape samples. Defaults to significant_digits; use 9 to match MATLAB Pulseq shapes. For MATLAB Pulseq parity, use significant_digits=6, shape_significant_digits=9.

• verbose: (::Bool, =true) show writing/checking messages and export-conversion warnings

Examples

julia> seq = Sequence()
julia> @addblock seq += RF(2e-6, 3e-3)
julia> @addblock seq += ADC(100, 100e-3)
julia> write_seq(seq, "fid.seq")

source

KomaMRIFiles.write_seq_data Function

data = write_seq_data(seq; sys=nothing, check_timing=true, check_hw_limits=true, verbose=true)

Prepare a Koma Sequence as PulseqSequenceData without writing a file. Without sys, timing and hardware checks use metadata stored in seq.DEF. With sys, timing, hardware checks, and export raster times use sys.

source

KomaMRIFiles.PulseqSequenceData Type

PulseqSequenceData

Pulseq-native sequence representation used by read_seq_data and write_seq_data. It stores block event ids, event libraries, definitions, the Pulseq version, and the optional signature without materializing repeated Koma RF, Grad, and ADC objects.

Event amplitudes are stored in SI units (RF: T, gradients: T/m). Serialized time fields are normalized from μs/ns to seconds.

source

Phantom

KomaMRIFiles.read_phantom_jemris Function

obj = read_phantom_jemris(filename)

Returns the Phantom struct from a JEMRIS phantom file .h5.

Arguments

• filename: (::String) the absolute or relative path of the phantom file .h5

Returns

• obj: (::Phantom) Phantom struct

Examples

julia> obj_file = joinpath(dirname(pathof(KomaMRI)), "../examples/2.phantoms/brain.h5")

julia> obj = read_phantom_jemris(obj_file)

julia> plot_phantom_map(obj, :ρ)

source

KomaMRIFiles.read_phantom_MRiLab Function

obj = read_phantom_MRiLab(filename)

Returns the Phantom struct from a MRiLab phantom file .mat.

Arguments

• filename: (::String) the absolute or relative path of the phantom file .mat

Returns

• obj: (::Phantom) Phantom struct

Examples

julia> obj_file = joinpath(dirname(pathof(KomaMRI)), "../examples/2.phantoms/brain.mat")

julia> obj = read_phantom_MRiLab(obj_file)

julia> plot_phantom_map(obj, :ρ)

source

KomaMRIFiles.read_phantom Function

phantom = read_phantom(filename)

Reads a (.phantom) file and creates a Phantom structure from it

source

KomaMRIFiles.write_phantom Function

write_phantom(ph, filename; compression=true)

Writes a (.phantom) file from a Phantom struct. Array datasets use lossless byte shuffle and DEFLATE compression at HDF5's default level. Set compression=false to write unfiltered, contiguous datasets.

source

Scanner

Create or load an HDF5 .sys file:

write_scanner(sys, "scanner.sys")
sys = read_scanner("scanner.sys")

KomaMRIFiles.read_scanner Function

sys = read_scanner(filename)

Read an HDF5 .sys file written by write_scanner, reconstructing the scanner's hardware limits and gradient, receive, and transmit models. Model names are resolved from the loaded scanner subtypes, as for phantom motion; file contents are never evaluated as Julia code.

source

KomaMRIFiles.write_scanner Function

write_scanner(sys, filename)

Write a scanner to an HDF5 .sys file. The limits, gradient, receiver, and transmitter groups mirror the fields of Scanner. Each group has a type attribute, scalar parameters as attributes, and arrays as datasets. Coordinates and hardware limits use SI units; complex receive maps retain their values and (x, y, z, coil) dimensions.

Supports HardwareLimits, LinearXYZ, UniformCoilSens, BirdcageCoilSens, ArbitraryCoilSens, and UniformTransmit. The root Version attribute records the KomaMRIFiles version, as in .phantom files.

source

MATLAB exports

The following formats are used by KomaMRI's UI and CLI exports. UI individual exports use data_raw.mat, data_sequence.mat, and data_image.mat; All uses raw.mat, seq_sequence.mat, and image.mat. CLI output filenames are user-specified.

Format change: raw is now a struct, replacing the old numeric [time, signal] matrix. Label-aware image exports now contain a reconstruction struct instead of the previous separate image, labels, source_labels, and recon_policy variables. Plain-array image exports still contain the original image variable.

Raw data

raw.params preserves the MRD metadata. raw.profiles is a cell array, with one struct per acquired readout:

Field	Contents
head	Full MRD acquisition header, including flags, timestamps, discard counts, and idx label counters
traj	Stored trajectory, coordinates × samples; copied without rescaling
data	Complex signal, samples × receive coils
role	Acquisition role derived from the MRD flags, such as imaging or navigator

Profiles retain their own sample counts and trajectory dimensions, so 1D navigators, 2D images, and 3D acquisitions can coexist. No coils are discarded, no Inf separators are inserted, and timestamps are not synthesized. New Koma MRD exports store reconstruction-ready coordinates, used directly by MRIReco. The numeric parameters raw.params.userParameters.KomaTrajectoryScaleX/Y/Z contain reconSize ./ FOV_m: multiply each stored coordinate by its factor to recover physical k-space in cycles/m. Without FOV, export uses legacy global normalization and saves that factor on every axis.

Raw data also exports when userParameters is absent. When present, those parameters are additionally saved in sim_params.mat. Dictionary keys replace Δ with d for MATLAB compatibility, for example Δt_rf becomes dt_rf.

s = load('data_raw.mat');
p = s.raw.profiles{1};
signal = p.data(:, 1);       % All samples from receive coil 1
k = p.traj;                 % Original stored coordinates for this readout
slice_label = p.head.idx.slice;

Sequence data

sequence retains the waveform fields Gx, Gy, Gz, RF_AM, RF_FM, and ADCS, and adds definitions and adc. Each sequence.adc vector has one entry per ADC event: block is the one-based Julia sequence-block index, num_samples is its sample count, and labels contains named vectors of all accumulated ADC label values. Label values are preserved, including zero; they are not converted to MATLAB indices.

s = load('data_sequence.mat');
adc_blocks = s.sequence.adc.block;
repetitions = s.sequence.adc.labels.REP;

Reconstructed images

reconstruction.policy records the reconstruction policy. Each cell in reconstruction.images contains one reconstruction batch with data, size, labels, source, axes_mm, voxel_spacing_mm, and trajectory_scale. labels identifies the batch; source retains its original acquisition counters. The six data dimensions are x, y, z, echo, coil, repetition. The explicit six-element size vector preserves trailing singleton dimensions that MATLAB does not display.

axes_mm.x, .y, and .z contain the reconstructed physical coordinates in millimetres, including any FOV correction. voxel_spacing_mm preserves x/y/z spacing even on singleton axes. trajectory_scale records the k-space rescaling factor (1 when no rescaling was needed). Use these coordinates rather than inferring geometry from the array size or the original sequence definitions.

s = load('data_image.mat');
batch = s.reconstruction.images{1};
I = reshape(batch.data, batch.size(:).');
echo = 1; coil = 1; repetition = 1; z = 1;
plane = I(:, :, z, echo, coil, repetition);
if batch.size(2) == 1 && batch.size(3) == 1
    plot(batch.axes_mm.x, abs(plane(:, 1))); xlabel('x (mm)');
else
    imagesc(batch.axes_mm.y, batch.axes_mm.x, abs(plane)); axis image;
    xlabel('y (mm)'); ylabel('x (mm)');
end
volume = I(:, :, :, echo, coil, repetition);

Select a different batch for separate acquisition labels, such as SLC or REP. Select z within a batch for a reconstructed 3D partition. MATLAB array indices are one-based, independently of the stored label values. Explicit indexing above avoids collapsing coil or echo dimensions with squeeze.

Profile and image collections remain cell arrays even with one element, for a consistent format across supported MAT.jl versions 0.10, 0.11, and 0.12.

Scanner data

scanner contains limits, gradient, receiver, and transmitter structs, each with its model type and fields. For example, scanner.limits.B0 is the main field strength, and scanner.receiver.coil_sens stores complex maps for ArbitraryCoilSens. This replaces the previous flat limits-only struct.