Palette Card Authoring

The workflow palette is a library of pre-configured stage and step templates that can be inserted into any workflow from the Stages and Steps tabs in the workflow editor.

---

Card Types

There are two kinds of palette cards:

Type	Key	Description
Stage card	stage:	A complete stage with type, backend, and one or more pre-configured steps
Step card	step:	A single step with params, scoped to specific backends

---

Card Locations

Location	Source	Read/Write
resources/palette/ (in app bundle)	Bundled cards shipped with FORGE Studio	Read-only
~/.forge-studio/palette/	User cards created via the UI or manually	Read/Write

Cards in both locations are loaded at startup. The user palette directory is created automatically on first launch.

---

Stage Card Format

palette_version: 1                  # required — always 1
id: espirit-calib                   # required — unique slug (used as filename)
display_name: ESPIRiT Calibration   # required — shown in the palette
category: Sensitivity Maps          # required — used for grouping
description: Estimates coil sensitivity maps using ESPIRiT  # optional
tags: [calibration, preprocessing]  # optional — used in search

stage:                              # required — full WorkflowStage definition
  name: Sensitivity Calibration
  type: preprocessing               # preprocessing | reconstruction | postprocessing | custom | interactive
  backend: python                   # forge | matlab | runmat | python | julia
  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

---

Step Card Format

Step cards additionally require compatible_backends so the UI can filter them when a particular stage backend is selected.

palette_version: 1
id: coil-compression
display_name: PCA Coil Compression
category: Preprocessing Utilities
description: Reduces coil count via PCA before reconstruction
tags: [preprocessing, coil, pca]
compatible_backends: [python, julia]   # required for step cards

step:                                  # required — full WorkflowStep definition
  id: coil_compress
  name: Coil Compression
  module: coil_compress
  params:
    target_coils:
      type: int
      label: Target coil count
      default: 8
      min: 1
      max: 64
    method:
      type: enum
      label: Compression method
      values: [pca, gcc, rss]
      labels:
        pca: PCA (recommended)
        gcc: GCC
        rss: Root-Sum-of-Squares
      default: pca

---

Interactive Gate Cards

Stage cards with type: interactive get amber visual treatment in the palette (instead of the standard accent blue) to signal that they pause the pipeline for user review.

palette_version: 1
id: brain-mask-gate
display_name: Brain Mask Gate
category: Interactive Gates
description: Pauses the pipeline for manual brain mask review

stage:
  name: Brain Mask Review
  type: interactive
  backend: python
  auto_approve: false           # false = always pause; true = skip gate in batch mode
  steps:
    - id: brain_mask
      name: Brain Mask
      module: brain_mask_auto
      params:
        threshold:
          type: float
          label: Mask threshold
          default: 0.1
          min: 0.0
          max: 1.0
          precision: 3

---

Categories

Categories are free-form strings — use whatever makes sense for your domain. Suggested conventions:

Category	Contents
Sensitivity Maps	Coil sensitivity estimation (ESPIRiT, Walsh, etc.)
Reconstruction	Core image reconstruction algorithms
Preprocessing Utilities	Steps that run before reconstruction
Postprocessing	Image-space filtering, normalisation
Interactive Gates	Stages that pause for user review
Transfer & Export	Output formatting, file conversion

Cards within the same category are grouped together in the palette panel.

---

Search and Filtering

The palette search box matches against display_name, category, and tags. For step cards, when a stage is selected in the pipeline the Steps tab automatically filters to only show cards whose compatible_backends includes the selected stage's backend.

---

Adding Cards via the UI

1. In the workflow editor, select a stage in the Pipeline tab.
2. Click the + icon in the top-right of the stage inspector header.
3. Fill in the display name, category, and optional description.
4. Click Save to Palette — the card is written to ~/.forge-studio/palette/<id>.yaml.

The card will appear in the Stages tab of the palette immediately (no restart needed, as the palette is reloaded each time the editor opens).

---

Adding Cards Manually

Drop a .yaml file matching the format above into ~/.forge-studio/palette/. The filename should match the id field (e.g. espirit-calib.yaml for id: espirit-calib). The card will be loaded the next time the workflow editor is opened.

---

Exporting Cards

Right-click any user card in the palette and choose Export… to save it as a standalone YAML file that can be shared with colleagues or checked into a shared repository.

---

Bundled Cards

FORGE Studio ships with five bundled cards:

ID	Display Name	Type	Category
espirit-calib	ESPIRiT Calibration	Stage	Sensitivity Maps
cs-sense-recon	CS-SENSE Reconstruction	Stage	Reconstruction
brain-mask-gate	Brain Mask Gate	Stage (interactive)	Interactive Gates
coil-compression	PCA Coil Compression	Step	Preprocessing Utilities
grappa-recon	GRAPPA Reconstruction	Stage	Reconstruction