FORGE Studio

Appearance

Workflow YAML Reference ​

FORGE Studio workflows are YAML files that define a multi-stage reconstruction pipeline. Bundled workflows live in resources/workflows/; user workflows are saved to ~/.forge-studio/workflows/.

Top-Level Fields ​

yaml
schema_version: 1          # required — always 1
id: my-workflow            # required — unique identifier (filename without .yaml)
name: My Workflow          # required — display name
description: …             # optional — shown in the workflow browser
version: 1                 # required — integer, increment when updating
author: Your Name          # optional
tags: [cs, 3d, cartesian]  # optional — used for filtering in the UI

stages: []                 # required — see Stages below

# Optional sections
protocol_match: …
viewer: …
yarra: …

Stages ​

Each entry in stages defines one processing stage.

yaml
stages:
  - name: Sensitivity Calibration   # required — display name
    type: preprocessing              # required — see Stage Types
    backend: python                  # required — see Backends
    enabled: true                    # optional (default: true)
    auto_approve: false              # optional — for interactive stages only
    steps:
      - …                            # see Steps

Stage Types ​

ValueDescription
preprocessingData preparation before reconstruction
reconstructionCore image reconstruction
postprocessingImage-space processing after reconstruction
customGeneral-purpose stage
interactivePauses for user review (e.g. mask editing)

Backends ​

ValueRuntime
forgeBundled C++/CUDA FORGE binaries
matlabExternal MATLAB installation
runmatBundled MATLAB Compiled Runtime
pythonExternal Python 3
juliaExternal Julia

Steps ​

Each stage contains one or more steps. A step maps to a single module call.

yaml
steps:
  - id: espirit_calib          # required — unique within the workflow
    name: ESPIRiT Calibration  # required — display name
    module: espirit_calib      # required — module/function name passed to backend
    enabled: true              # optional (default: true)
    params:
      calibration_size: …      # see Parameters below
      regularization: …

Parameters ​

Parameters are defined under params as a map of key → parameter definition. Each definition must have a type field.

Common Fields (all types) ​

FieldTypeDescription
typestringParameter type — see types below
labelstringDisplay name shown in the inspector
descriptionstringTooltip text shown next to the label
groupstringGroup name for collapsible sections. "Advanced" starts collapsed
defaultvariesDefault value

int — Integer number ​

yaml
calibration_size:
  type: int
  label: Calibration region size
  description: Size of the central k-space region in pixels
  default: 24
  min: 4        # optional — validation minimum
  max: 128      # optional — validation maximum
  step: 4       # optional — spinner step size

float — Decimal number ​

yaml
regularization:
  type: float
  label: Regularization (λ)
  description: L2 Tikhonov regularization strength
  default: 0.001
  min: 0.0
  max: 1.0
  step: 0.0001   # optional — overrides precision-based step
  scale: log     # optional — "linear" (default) or "log"
  precision: 4   # optional — decimal places; controls default step size
  unit: a.u.     # optional — shown in range hint
  group: Advanced

bool — Checkbox ​

yaml
use_gpu:
  type: bool
  label: GPU acceleration
  description: Use GPU for computation when available
  default: true

enum — Dropdown ​

yaml
solver:
  type: enum
  label: Iterative solver
  description: Optimization algorithm
  values: [CG, ADMM, FISTA, POGM]   # required — list of raw values
  labels:                            # optional — human-readable display names
    CG: Conjugate Gradient
    ADMM: ADMM (split Bregman)
    FISTA: FISTA
    POGM: POGM (fastest convergence)
  default: CG

string — Text / file path ​

yaml
output_mask_path:
  type: string
  label: Output sensitivity map file
  description: Path to save sensitivity maps (empty = auto-name)
  default: ""
  file_picker: true          # optional — shows Browse button in UI
  file_types: [h5, hdf5]    # optional — file filter for the picker dialog
  group: Advanced

int_array — Array of integers ​

yaml
matrix_size:
  type: int_array
  label: Reconstruction matrix size
  description: Output dimensions [readout, phase, partition]
  default: [256, 256, 96]
  length: 3     # optional — renders as N individual inputs when ≤ 6
  min: 16       # optional — per-element validation
  max: 1024

float_array — Array of decimals ​

yaml
resolution_mm:
  type: float_array
  label: Spatial resolution (mm)
  description: Target voxel size [x, y, z]
  default: [1.0, 1.0, 2.5]
  length: 3
  min: 0.1
  max: 10.0
  group: Advanced

When length is defined and ≤ 6, the UI renders individual number inputs side by side. For longer or variable-length arrays, a comma-separated text input is shown instead.

Parameter Groups ​

Any parameter can have a group field. Parameters without a group are shown first. Named groups are rendered as collapsible sections below ungrouped params. The "Advanced" group starts collapsed by default; all other group names start expanded.

Optional: Protocol Match ​

Automatically suggest this workflow when a file is loaded that matches the protocol patterns.

yaml
protocol_match:
  patterns:
    - ".*3D_VIBE.*"
    - ".*CS_SENSE.*"
  platform: [VE, XA]   # optional — Siemens platform filter
  priority: 10          # optional — higher = preferred when multiple match

Optional: Viewer Config ​

yaml
viewer:
  base_colormap: gray          # default colormap in NiiVue viewer
  orientation: radiological    # "radiological" or "neurological"
  interpolation: linear        # "nearest" or "linear"
  show_crosshairs: true
  show_colorbar: false

Optional: Yarra Config ​

yaml
yarra:
  module_name: MyReconModule   # Yarra module name for export
  tag: my_tag                  # optional tag
  export_enabled: true

Complete Example ​

yaml
schema_version: 1
id: cs-sense-3d
name: 3D CS-SENSE
description: Compressed-sensing SENSE for 3D Cartesian acquisitions
version: 2
author: FORGE Studio Team
tags: [cs, sense, 3d, cartesian]

protocol_match:
  patterns: [".*CS_SENSE.*"]
  priority: 10

stages:
  - name: Sensitivity Calibration
    type: preprocessing
    backend: python
    steps:
      - id: espirit_calib
        name: ESPIRiT Calibration
        module: espirit_calib
        params:
          calibration_size:
            type: int
            label: Calibration region size
            default: 24
            min: 4
            max: 128
            step: 4
          use_gpu:
            type: bool
            label: GPU acceleration
            default: true

  - name: CS-SENSE Reconstruction
    type: reconstruction
    backend: forge
    steps:
      - id: cs_sense
        name: CS-SENSE
        module: cs_sense
        params:
          iterations:
            type: int
            label: Max iterations
            default: 40
            min: 1
            max: 200
            step: 5
          lambda:
            type: float
            label: Wavelet regularization (λ)
            default: 0.01
            min: 0.0
            max: 1.0
            scale: log
            precision: 4
          solver:
            type: enum
            label: Iterative solver
            values: [CG, ADMM, FISTA, POGM]
            labels:
              CG: Conjugate Gradient
              ADMM: ADMM (split Bregman)
              FISTA: FISTA
              POGM: POGM (fastest convergence)
            default: CG

FORGE Studio