KomaMRI

User Interface

KomaMRI.KomaUI Function

KomaUI(; kwargs...)

Open Koma's desktop UI, or serve the same UI with browser=true.

Browser mode starts a server at host="127.0.0.1", port=9384 and logs its URL; it does not launch Electron or a browser on the server. Use ui_status(w).url to retrieve the actual address. For a remote host, connect through an SSH tunnel. The Julia process must remain running. The server is for one user's UI, with no built-in authentication; keep the default loopback host when tunneling.

Dark mode is the default. Switch themes at the bottom of the sidebar or start with darkmode=false for the light theme.

Use KomaWorkspace to show independent windows together in a browser grid. Numbers belong to workspace tiles, not standalone windows.

Set return_window=true to return the KomaWindow, and show_window=false to build the UI without opening a window or starting a server. close(w) stops the window/server and releases its listeners; wait(w) waits for its lifetime, not for an operation. isopen(w) reports whether the window/server is running.

Each window owns its observables: w.seq, w.obj, w.sys, w.physio, w.raw, w.img, w.sim_params, and w.rec_params. Assign values with [] (for example, w.seq[] = seq) to update that window's data and view.

Use load_file!, simulate!, and reconstruct! for synchronous operations with returned results and propagated errors. ui_status(w) reports operation progress and failures, and ui_actions(w) lists navigation/button actions for click!.

See the browser-based UI guide and Julia control examples.

source

KomaMRI.KomaWorkspace Type

KomaWorkspace([w1, w2, ...]; host="127.0.0.1", port=9384)
KomaWorkspace(; host="127.0.0.1", port=9384)

Show independent KomaUI windows in a browser grid on one server. Tile numbers belong to this workspace and stay stable when a tile is expanded. Each member keeps its own data, device, controls, and operation status.

Create members with KomaUI(; show_window=false, return_window=true), or adopt one existing browser window without restarting its server. Desktop windows and members already attached to a workspace cannot be adopted. The no-argument form starts with one window; use Add window or add_window! for more.

workspace.windows contains the Julia handles. Use the tile's Close button to close its window and remove it from the workspace. close(w) closes only that window; close(workspace) closes all members and the server. Forward the workspace's single printed port when using SSH.

source

KomaMRI.add_window! Function

add_window!(workspace; kwargs...)

Create an independent workspace member and return its KomaWindow. Keywords configure its inputs and options as in KomaUI; the workspace owns its display. Adding a member does not reload existing tiles.

source

KomaMRI.load_file! Function

load_file!(w, target, filename)

Load a file as if selected in KomaUI's file picker. target is :sequence, :phantom, :scanner, :raw_data, or :configuration (explicit because .h5 has multiple uses). Configuration TOML files merge [sim_params] and [recon_params] into the window's current parameters; omitted settings are unchanged. Both sections are parsed and converted before applying either. Returns the merged parameter dictionaries. Updates the input, filename, toast, and plot, and remembers the path for reload. Returns the loaded object after updating the view and checking sequence geometry and ADC labels. Warnings are displayed in the UI; loading/check failures throw. Calls block until complete and reject concurrent loads, simulation, or reconstruction. Does not run simulation or reconstruction.

source

KomaMRI.simulate! Function

simulate!(w; sim_params=w.sim_params[])

Simulate the current window's phantom, sequence, scanner, and physiology. Update w.raw and its view, save the reloadable MRD file, and return the raw data. Blocks until complete; errors propagate and are recorded by ui_status(w). Rejects another load/simulation/reconstruction while busy. For asynchronous use, keep a Julia task (task = @async simulate!(w)) and retrieve it with fetch(task).

source

KomaMRI.reconstruct! Function

reconstruct!(w; rec_params=w.rec_params[])

Reconstruct the current window's raw data, update w.img and its view, and return the reconstruction result. Blocks until complete; errors propagate and are recorded by ui_status(w). Rejects another load/simulation/reconstruction while busy. Use task = @async reconstruct!(w) and fetch(task) for asynchronous callers. Set rec_params[:recon_policy] to override label handling or coil combination, for example (COIL=:rss,).

source

KomaMRI.export_results Function

export_results(w, output; path)

Save the current :raw_data_mrd, :raw_data_mat, or :image_mat output to an explicit file path, without a picker, download, or view change. The output key determines the format, not the filename extension. MAT exports contain one file without parameter sidecars.

The path is on the machine running Julia; its parent directory must exist. Existing files are overwritten. Returns (; path, url) with the absolute path and a download URL in browser mode (nothing otherwise). The URL remains valid while the UI server runs and the file exists. For a remote server, retrieve it through the SSH tunnel, substituting its local forwarded port if different.

source

KomaMRI.ui_status Function

ui_status(w)

Return a snapshot of the latest load, simulation, reconstruction, or device selection: action, state (:idle, :running, :succeeded, or :failed), progress (fraction in [0, 1], or nothing when unknown), and message (warning or error text). elapsed_seconds and eta_seconds are simulation-only (nothing for other operations or before the first update). ETA is a block-based estimate and can fluctuate during warmup. Also includes the current view, a copy of loaded files, browser url (or nothing), and whether a browser/desktop session is connected. Completion means Julia data and view updates have finished; it does not wait for the browser to finish painting the plot.

source

Actions

KomaMRI.click! Function

click!(w, action; kwargs...)

Activate a KomaUI menu or button action through the same handler as a UI click. This runs the action directly, without finding or clicking a browser element. It is synchronous and propagates errors. Use simulate!, reconstruct!, or load_file! when the returned data is needed; click! returns nothing. Use ui_actions(w) to discover actions and ui_status(w) to inspect operation status.

Actions are :home, :toggle_sidebar, :toggle_theme, :view_sequence, :view_sequence_definitions, :view_kspace, :view_moment0, :view_moment1, :view_moment2, :view_slew_rate, :view_phantom, :view_hardware_limits, :view_phantom_slice, :view_coil_sensitivities, :view_raw_data, :view_image, :view_log_kspace, :view_configuration, :view_simulation_options, :view_reconstruction_options, :simulate, and :reconstruct. Reload actions are :reload_sequence, :reload_phantom, :reload_scanner, :reload_raw_data, and :reload_configuration; they do nothing until a file is loaded. MAT export actions are :export_all, :export_sequence, :export_phantom, :export_scanner, :export_raw_data, and :export_image. Export raw data as ISMRMRD with :export_mrd. Use export_results(w, output; path=...) to save without an interactive picker.

Select the next simulation's device with click!(w, :select_device; gpu=false) for CPU or click!(w, :select_device; gpu=true, id=device_id) for a GPU listed by get_devices(). Omitting id selects the backend's current GPU. GPU selection requires a loaded, functional backend; unavailable devices throw without changing the settings. Selection is recorded by ui_status(w) and rejected while busy.

source

KomaMRI.ui_actions Function

ui_actions(w)

Return the supported click! action names as a sorted vector of symbols.

source

Window data

Each window owns its data and parameters:

w.seq[] = seq        # Sequence
w.obj[] = obj        # Phantom
w.sys[] = sys        # Scanner
w.physio[] = physio  # Physiological signal
w.raw[] = raw        # Raw data
w.img[] = img        # Image
w.sim_params[] = sim_params  # Dict{String,Any}
w.rec_params[] = rec_params  # Dict{Symbol,Any}

Assignments refresh that window's view without changing filenames or reload paths. In-place edits require notify(observable) to refresh the view. Simulation, reconstruction, and export read the current values.

The :recon_policy entry in w.rec_params[] controls label handling and coil combination, e.g. (COIL=:rss,). It is displayed with the reconstruction parameters and applied by reconstruct!.

Sequence assignment resets the physiological signal to its default. Scanner updates show coil sensitivities when the receiver changes, otherwise hardware limits when limits change. With neither changed, the current Scanner view refreshes, or coil sensitivities open if another section is displayed.

Scanner is immutable; receiver replacement preserves the other components:

sys = w.sys[]
w.sys[] = Scanner(; limits=sys.limits, gradient=sys.gradient,
    transmitter=sys.transmitter, receiver=BirdcageCoilSens())

Reconstruction

KomaMRI.reconstruct_with_labels Function

reconstruct_with_labels(
    raw,
    ;
    rec_params=Dict{Symbol,Any}(),
    recon_policy=get(rec_params, :recon_policy, NamedTuple()),
)

Reconstruct MRD data with MRIReco after applying a policy to its acquisition labels. recon_policy contains optional overrides of DEFAULT_RECON_POLICY, whose documentation defines every dimension, action (:separate, :axis, :encoding, :combine, :ignore, :rss), and acquisition role. It can also be supplied as rec_params[:recon_policy]; an explicit recon_policy keyword takes precedence. Koma consumes that entry before passing the remaining options to MRIReco. Each batch's MRD reconSize determines its image matrix.

Profiles are separated by role and policy before determining geometry or normalizing trajectories. Only coordinate variation within that batch determines its encoding axes; storing three k-space coordinates does not make every role a 3D acquisition. Axis-aligned 1D readouts in x, y, or z use MRIReco's padded 2D path internally and return a single line. For a line within a multi-dimensional acquisition, the retained ADC sample count supplies its matrix size instead of the imaging matrix. Geometry and scaling exclude MRD samples marked for discarding, as MRIReco does. The input MRD data is not modified.

New Koma MRD coordinates within ±0.5 are reconstruction-ready and used unchanged. Multiplying by the saved KomaTrajectoryScaleX/Y/Z factors recovers physical k-space in cycles/m. Out-of-range batches use one common rescaling factor, warn to check Nx/Ny/Nz and FOV in [DEFINITIONS], and reduce the reconstructed spatial axes' FOV accordingly. Old files or data without a known FOV use legacy global-maximum normalization. Lines inheriting an imaging matrix/FOV also use that fallback.

With other labels fixed, SLC=:separate and REP=:separate turn observed (SLC, REP) pairs (0, 0), (0, 1), and (1, 0) into three independent images, not four. KomaUI provides SLC and REP controls and only offers combinations present in the data.

With all other labels fixed and two ECO values, ECO=:axis produces one AxisArray with two echoes through one MRIReco call; ECO=:separate produces two entries through two calls. Both provide an ECO control in KomaUI. Neither action averages the echoes. Likewise, AVG=:separate keeps individual acquisitions, while AVG=:combine sums their matching complex data before reconstruction; COIL=:rss instead combines coil magnitudes after reconstruction.

The result is a named tuple (policy, images). Each element of images is a named tuple (labels, source, image, trajectory_scale, magnitude_limits), where image is MRIReco's AxisArray. trajectory_scale records the out-of-range rescaling factor, or 1 when none was needed. magnitude_limits contains one display-range pair per source.ECO value, computed once after reconstruction. Ranges are shared across slices, partitions, averages, repetitions, phases, segments, and coils, but separate for each (ROLE, DIM, SET, ECO) combination. They use KomaUI's magnitude scaling by the first two image dimensions; phase and k-space display ranges remain fixed. Treat the returned images as immutable or recompute their limits after changing image data.

source

KomaMRI.reconstruction_policy Function

reconstruction_policy(overrides=NamedTuple())

Validate and merge the partial overrides named tuple with DEFAULT_RECON_POLICY. See that policy's documentation for every dimension, allowed action, and default.

source

KomaMRI.DEFAULT_RECON_POLICY Constant

DEFAULT_RECON_POLICY

Default label handling for reconstruct_with_labels. Pass a partial named tuple such as recon_policy=(AVG=:combine, COIL=:rss) to override the configurable actions.

Dimension	Meaning	Default	Alternative
ROLE	Acquisition purpose, derived from MRD flags	:separate	—
DIM	Stored trajectory coordinate count, not image rank	:separate	—
LIN	Phase-encoding line index	:encoding	—
PAR	Partition-encoding index within a volume	:encoding	—
SLC	Separate acquired slice	:separate	—
SEG	Segments contributing to an image	:combine	:separate
REP	Repetition counter	:separate	—
AVG	Repeated acquisition for averaging	:separate	:combine
SET	Acquisition set counter	:separate	—
ECO	Echo label, stored as MRD contrast	:axis	:separate
PHS	Physiological phase counter, not complex signal phase	:separate	—
ACQ	Acquisition counter, stored in MRD idx.user[1]	:ignore	—
TRID	Interpreter-specific counter, in MRD idx.user[2]	:ignore	—
COIL	Receiver channels, not an ADC label	:axis	:rss

Actions describe both the MRIReco call boundary and the returned image organization:

• :separate: split profiles by every observed combination of the separate labels. Each combination gets its own MRIReco call and entry in result.images; absent combinations are not created.

• :axis: keep the values together in one MRIReco call and retain its echo or coil axis in one image AxisArray. Values are not averaged or otherwise combined.

• :encoding: retain LIN/PAR as k-space encoding indices within an image, not as separate images. These indices do not determine stored trajectory dimensionality.

• :combine: AVG sums the complex signals of matching profiles with identical trajectories; SEG joins segment profiles for one reconstruction without averaging.

• :ignore: do not split or combine using this counter. Original counter values are still retained in each entry's source metadata.

• :rss: replace reconstructed coil images with sqrt(sum(abs2, coils)). This is magnitude-only combination, without coil-sensitivity estimation or retained phase.

ROLE is selected by MRD flag precedence: noise, phase correction, navigator, calibration-and-imaging, calibration, phase-stabilization reference, phase stabilization, feedback, dummy, then surface-coil correction. Unflagged and calibration-and-imaging profiles are imaging. Imaging, navigator, phase-correction, calibration, and both phase-stabilization roles are reconstructable; the other roles are excluded.

source