Gradients YAML schema

Schema reference for the gradient library file on disk. Useful if you want to hand-edit, share libraries between machines, or generate gradients from a script.

Where the file lives

The paint app looks for the gradient library at $XDG_CONFIG_HOME/<org>/<app>/gradients.yaml. On most Linux desktops this resolves to $HOME/.config/<org>/<app>/gradients.yaml. On Windows / macOS the path follows the platform's QStandardPaths::AppConfigLocation convention.

On first launch (or whenever the file is missing or empty), the app seeds it with the six bundled starter gradients and writes it out so subsequent launches read from a real file. After that, every edit you make in the GradientEditorActivity rewrites the file in place.

File layout

version: 1
gradients:
  - name: Sunset
    uuid: 11111111-1111-1111-1111-000000000003
    interpMode: lab-lerp
    stops:
      - t: 0.0
        color: [0.0103, 0.0117, 0.0421, ..., 0.0214, 1.0]   # 80 spectral bands + alpha
      - t: 0.3333
        color: [...]
      - t: 0.6666
        color: [...]
      - t: 1.0
        color: [...]
  - name: Steel
    uuid: 11111111-1111-1111-1111-000000000004
    interpMode: multiply
    stops: [...]

Top-level keys

Key	Type	Required	Notes
`version`	int	yes	Schema version. Currently `1`.
`gradients`	list	yes	The library, in display order. Empty list is legal (the app shows zero rows in the library activity and the brush falls back to flat color).

Per-gradient keys

Key	Type	Required	Notes
`name`	string	yes	Display name. Library enforces uniqueness — a load that finds two entries with the same name auto-renames the second on next save.
`uuid`	string	yes	Stable identifier. Brush stores this in `brushGradientUuid` to recall the selection across launches. Restore bundled keys off this.
`interpMode`	string	yes	The blend mode used between adjacent stops. See "Interpolation modes" below. Unknown names fall back to `multiply` with a logged warning.
`stops`	list	yes	At least two stops. First stop must have `t == 0.0`, last `t == 1.0`, and all stops in strictly increasing `t` order.

Per-stop keys

Key	Type	Required	Notes
`t`	float	yes	Position along the gradient, `0.0 ≤ t ≤ 1.0`.
`color`	list of 81 floats	yes	80 linear spectral band values (380 nm to 775 nm at 5 nm intervals) plus a final alpha. Values are normally in `[0, 1]` but the format doesn't enforce a range.

Interpolation modes

interpMode accepts any of the stable short names from the brush blend-mode picker. Common ones:

`interpMode`	Behavior between stops
`km`	Kubelka-Munk single-coat mix. The default — produces pigment-like ramps.
`lab-lerp`	Linear lerp in perceptual CIE Lab*. Good for smooth perceived ramps; avoids the muddy-greens problem of pure pigment mixes.
`multiply`	Per-band multiplicative — darker stops dominate.
`srcover` / `plus` / other modes without a mix-ratio	Fall back to linear-RGB lerp at sample time (the §GR-4.2 fallback).

The picker shows every supported mode in the order they appear in paint::allBlendDescriptors().

Hand-editing tips

Adding a stop — insert a new entry in the stops list with the desired t and color. The list will be re-sorted on the next load.
Replacing the color at an existing stop — overwrite the color list in place. If you don't know the exact spectral values, the editor can do this for you: open the entry, pick the color from the spectral library, save, and re-read the file.
Renaming — change the name; keep the uuid so the brush selection survives the rename.
Sharing across machines — copy the file. Same uuid keeps the brush's brushGradientUuid selection working after the import.

Bundled-starter uuids

These are reserved for the six bundled gradients. Restore bundled in the library activity recognizes them by uuid and re-adds whichever are missing from the user file.

Name	uuid
Greyscale	`11111111-1111-1111-1111-000000000001`
Rainbow	`11111111-1111-1111-1111-000000000002`
Sunset	`11111111-1111-1111-1111-000000000003`
Steel	`11111111-1111-1111-1111-000000000004`
Foliage	`11111111-1111-1111-1111-000000000005`
Skin	`11111111-1111-1111-1111-000000000006`

If you create your own gradients, use random uuids (uuidgen or any UUID v4 generator) so future bundled additions never collide with yours.