feat: Stage 1 Additional customisation and tooltips #141

New Issue

2026-08-29T17:28:15+01:00

gronod commented

2026-08-29 17:28:15 +01:00

Description

Expand Stage 1 (targen) so that production users can control the high-value patch-generation parameters that are currently hard-coded or missing from the UI, and give every control a clear, accurate tooltip so both novices and experienced colourists understand the practical effect on the resulting profile.

To avoid cluttering or overwhelming the UX, the new controls must be grouped into a collapsible "Advanced" section.

Today the UI only exposes:

UI control	CLI mapping	Notes
Colour Space (RGB/CMYK)	`-d 2` / `-d 4`	Present
Patch Count (preset/custom)	`-f N`	Present
White Patches	`-e N`	Present (under “Neutral Axis Boost”)
Black Patches	`-B N`	Present
Target basename + cwd	positional	Present

Everything else (-g, -s, -n, -l, -G, -A, -N, -V, -c, -p, algorithm selection, …) is unreachable from the UI and is therefore unavailable to presets.

Scope & Technical Requirements

1. New / expanded Stage 1 controls

Expose the following parameters. They must be grouped logically in the UI into "Basic" and "Advanced" sections. All values flow through an extended TargenConfig and into build_targen_args.

A. Basic Settings (Always Visible)
These are the most common settings needed for generating a target.

Control	CLI	Type / range	Default (when empty)	Notes
Colour Space	`-d 2`/`-d 4`	select (RGB/CMYK)	RGB	Already present
Patch Count	`-f N`	number 50–10 000 or preset	800	Already present
White Patches	`-e N`	0–100	4 (RGB) / 4 (CMYK)	Already present
Black Patches	`-B N`	0–100	4 (RGB) / 0 (CMYK)	Already present – make default colour-space aware
Target Basename & Dir	positional	text / folder picker	none	Already present

B. Advanced Settings (Inside a Collapsible <details> Section)
These features should be within an "Advanced" section in stage 1 to avoid cluttering / overwhelming the UX.

Control	CLI	Type / range	Default	Notes
Grey / Combined Axis Steps	`-g N`	0–256	0	New – equal RGB or CMY wedges
Single-Channel Steps	`-s N`	0–256	0	New – per-colorant wedges
Preconditioning Profile	`-c <path>`	file picker (.icc/.icm)	none	Optional previous profile for this or similar device
Neutral Axis Steps	`-n N`	0–256	0	Requires a preconditioning profile
Neutral Axis Concentration	`-N 0.0–1.0`	slider	0.50	Emphasis of neutral region in OFPS / perceptual distributions
Optimisation Quality	`-G`	checkbox “High quality”	off	Fast → Good OFPS
OFPS Adaptation	`-A 0.0–1.0`	slider	0.1 (or 1.0 when `-c` supplied)	Degree of adaptation to the preconditioning profile
Full-spread Algorithm	mutually exclusive flags	select: OFPS (default) / Incremental Far Point (`-t`) / Device random (`-r`) / Perceptual random (`-R`) / Device quasi-random (`-q`) / Perceptual quasi-random (`-Q`) / Device BCC (`-i`) / Perceptual BCC (`-I`)	OFPS
Total Ink Limit (TAC)	`-l N`	0–400 (%)	none	Critical for CMYK; recommend setting ≥ final profile TAC + 10 %
Dark Region Emphasis	`-V 1.0–4.0`	slider	1.0	Concentrates patches toward dark tones
Device Value Power	`-p N`	0.1–4.0	none	Power-like remapping of device values (rare; advanced)

C. UI / UX

Every control (including existing ones) carries a tooltip.
Tooltips appear on hover (mouse) and on long-press / focus (touch).
Optional global toggle “Show help for all options” that keeps tooltip text visible (or shows a side help panel) while the user explores the form.
Group all advanced controls (-g, -s, -c, -n, -N, -G, -A, algorithm, -l, -V, -p) inside a collapsible <details> “Advanced options” section so the default view stays clean.
Colour-space change must dynamically adjust defaults and enable/disable CMYK-only controls (ink limit, etc.).
Preconditioning profile path is stored relative to the working directory or as an absolute path that is validated before launch.
All new fields are serialised into ProfilingPreset / settings.json so existing presets continue to work and new presets capture the expanded state.

2. Backend changes

Extend TargenConfig (and the corresponding preset schema in settings.rs):

pub struct TargenConfig {
    // existing
    pub colour_space: String,
    pub patch_count: u32,
    pub white_patches: Option<u32>,
    pub black_patches: Option<u32>,
    pub total_patches: Option<u32>,
    pub basename: String,
    pub cwd: String,

    // new
    pub grey_steps: Option<u32>,          // -g
    pub single_channel_steps: Option<u32>,// -s
    pub neutral_steps: Option<u32>,       // -n
    pub preconditioning_profile: Option<String>, // -c
    pub neutral_concentration: Option<f64>,      // -N
    pub ofps_high_quality: bool,                 // -G
    pub ofps_adaptation: Option<f64>,            // -A
    pub full_spread_algorithm: Option<String>,   // "ofps"|"t"|"r"|"R"|"q"|"Q"|"i"|"I"
    pub total_ink_limit: Option<u32>,            // -l
    pub dark_emphasis: Option<f64>,              // -V
    pub device_power: Option<f64>,               // -p
}

build_targen_args must emit the corresponding flags only when the value is present / non-default, preserving current behaviour for callers that omit the new fields.

3. Accurate tooltip text (copy-paste ready)

Use the following strings (short enough for a tooltip, accurate to Argyll documentation).

Colour Space

Choose the device colour model for the test chart.
• RGB (Printer Driver) – for printers driven by an RGB driver or host colour management.
• CMYK (RIP) – for printers controlled by a RIP or when you need explicit CMYK separation.
This sets the targen -d colourant combination (2 = Print RGB, 4 = CMYK).

Patch Count

Total number of colour patches that will appear in the final chart.
Higher counts improve profile accuracy (especially in smooth gradients and near the neutrals) but increase print time, paper usage and measurement time.
Typical guidance:
• 400 – quick draft / preliminary profile
• 800 – good everyday quality
• 1500 – high-quality photo / proofing
• 2500+ – maximum quality or N-colour work.
The value is passed to targen -f.

White Patches (-e)

Number of pure-white patches included in the chart.
White defines the paper white point that the ICC profile is made relative to. Measuring several white patches improves robustness against measurement noise and local paper variation.
Default is 4. Values of 4–8 are common.

Black Patches (-B)

Number of pure-black patches included in the chart.
Black is especially important for additive (RGB) devices; measuring multiple black patches improves black-point accuracy.
Default is 4 for RGB / grey and 0 for CMYK. Values of 4–8 are typical for RGB.

Grey / Combined Axis Steps (-g)

Number of evenly-spaced steps along the combined grey axis (equal R=G=B or C=M=Y).
These patches improve the profile’s neutral-axis rendering and are useful when the device will later be used as a source colour space.
0 = none (default). A value around the cube-root of total patch count is a good starting point.

Single-Channel Steps (-s)

Number of steps for each individual colorant wedge (R, G, B or C, M, Y, K).
Useful for diagnosing per-channel non-linearity and for source-space characterisation.
0 = none (default). Total patches added = steps × number of colorants.

Neutral Axis Steps (-n)

Number of patches placed along the true neutral axis as estimated by a preconditioning profile.
Requires a Preconditioning Profile. Improves neutral rendering of the final profile.
A sensible starting value is the cube-root of the total patch count. Too high a density can push full-spread patches away from the neutrals.

Preconditioning Profile (-c)

Optional previous ICC/ICM (or MPP) profile of this or a similar device.
Used by targen to estimate perceptual distances, colourspace curvature and the true neutral axis.
Enables adaptive OFPS placement and the Neutral Axis Steps control. Leave empty for the built-in device-space model.

Neutral Axis Concentration (-N)

How strongly the patch distribution should favour the neutral axis (0 = none, 1 = maximum).
Default 0.5. Most effective with a preconditioning profile and a high OFPS Adaptation value.
Helps maximise visual quality where the eye is most sensitive.

Optimisation Quality (-G)

When checked, targen runs the OFPS algorithm in “good” mode (more iterations) instead of the faster default.
Produces a more evenly distributed set of patches at the cost of longer generation time.
Recommended for final production charts.

OFPS Adaptation (-A)

Degree to which the default OFPS algorithm adapts to the known device behaviour supplied by the preconditioning profile (0 = ignore profile, 1 = fully adapt).
Default is 0.1; automatically rises to 1.0 when a preconditioning profile is supplied. Lower the value if the previous profile is a poor match for the current media/ink.

Full-spread Algorithm

Algorithm used to place the remaining “full-spread” patches after white, black, grey and single-channel patches have been added.
• OFPS (default) – Optimised Farthest Point Sampling; best evenness in most cases.
• Incremental Far Point – used automatically for >4 channels; can be forced.
• Device / Perceptual random or quasi-random – alternative space-filling methods.
• Body-centred cubic (device or perceptual) – regular grid with centre points; efficient packing.
Leave on OFPS unless you have a specific reason to change it.

Total Ink Limit (TAC) (-l)

Maximum total ink coverage (Total Area Coverage) allowed for any generated patch, in percent.
Essential for CMYK to avoid over-inking and to match press or RIP limits.
Good practice: set the chart limit at least 10 % higher than the final profile TAC.
The limit is written into the .ti1 and carried through to colprof. Leave empty for no limit (or the limit estimated from a preconditioning profile).

Dark Region Emphasis (-V)

Concentrates more patches toward the dark end of the tone scale (1.0 = none, up to 4.0 = strong).
Useful for devices that exhibit strong non-linearity or important detail in shadows. Default 1.0.

Device Value Power (-p)

Optional power-like remapping applied to all device values after generation.
Values > 1 tighten spacing near 0; values < 1 tighten spacing near 1.
Rarely needed; mainly for highly non-linear devices or special calibration charts. Leave empty for linear spacing.

Target Basename

Base name used for all generated files (.ti1, later .ti2, .ti3, .icc/.icm).
Do not include an extension. The files are written into the selected working directory.

Working Directory

Folder where the .ti1 (and subsequent artefacts) will be created.
Must be writable. Use the Browse button to choose a location.

4. Tooltip implementation notes

Prefer native title attributes for simplicity, or a lightweight custom tooltip component that matches the existing dark theme (readable contrast, max-width ≈ 280 px, arrow pointing to the control).
On touch devices, long-press or focus should show the same text.
The optional “Show help for all options” toggle can either:
- force all tooltips to remain visible, or
- open a side panel / expandable help list that mirrors the tooltip content.
Tooltips must never obscure adjacent form controls or the primary “Generate” button.

Acceptance Criteria

All listed new controls appear in Stage 1, correctly wired to TargenConfig and build_targen_args.
Controls are logically grouped into "Basic Settings" and a collapsible "Advanced Options" section.
Generated .ti1 contains the expected flags (verifiable by inspecting the process log or the .ti1 header).
Every Stage 1 control (existing + new) has a tooltip whose text matches the wording above (or an equally accurate paraphrase).
Tooltips work with both mouse hover and touch long-press / focus.
“Show help for all options” toggle functions as specified.
Changing Colour Space updates defaults and enables/disables CMYK-specific controls (ink limit, etc.).
Existing presets still load and apply correctly; new fields are optional / defaulted.
New presets capture and restore the expanded set of values.
Advanced section is collapsed by default; opening it does not break layout on 1280×800 minimum window size.
Unit tests for build_targen_args cover the new optional flags (present and absent cases).

Dependencies & Ordering

Milestone: Milestone 10 (v0.5.0)
Ordering: Step 3
Dependencies: None (independent of logging and .ti2-resume features)

### Description Expand Stage 1 (`targen`) so that production users can control the high-value patch-generation parameters that are currently hard-coded or missing from the UI, and give every control a clear, accurate tooltip so both novices and experienced colourists understand the practical effect on the resulting profile. To avoid cluttering or overwhelming the UX, the new controls must be grouped into a collapsible "Advanced" section. Today the UI only exposes: | UI control | CLI mapping | Notes | |-------------------------|----------------------|-------| | Colour Space (RGB/CMYK) | `-d 2` / `-d 4` | Present | | Patch Count (preset/custom) | `-f N` | Present | | White Patches | `-e N` | Present (under “Neutral Axis Boost”) | | Black Patches | `-B N` | Present | | Target basename + cwd | positional | Present | Everything else (`-g`, `-s`, `-n`, `-l`, `-G`, `-A`, `-N`, `-V`, `-c`, `-p`, algorithm selection, …) is unreachable from the UI and is therefore unavailable to presets. ### Scope & Technical Requirements #### 1. New / expanded Stage 1 controls Expose the following parameters. They must be grouped logically in the UI into "Basic" and "Advanced" sections. All values flow through an extended `TargenConfig` and into `build_targen_args`. **A. Basic Settings (Always Visible)** *These are the most common settings needed for generating a target.* | Control | CLI | Type / range | Default (when empty) | Notes | |----------------------------|--------------|---------------------------------------|----------------------|-------| | Colour Space | `-d 2`/`-d 4`| select (RGB/CMYK) | RGB | Already present | | Patch Count | `-f N` | number 50–10 000 or preset | 800 | Already present | | White Patches | `-e N` | 0–100 | 4 (RGB) / 4 (CMYK) | Already present | | Black Patches | `-B N` | 0–100 | 4 (RGB) / 0 (CMYK) | Already present – make default colour-space aware | | Target Basename & Dir | positional | text / folder picker | none | Already present | **B. Advanced Settings (Inside a Collapsible `<details>` Section)** *These features should be within an "Advanced" section in stage 1 to avoid cluttering / overwhelming the UX.* | Control | CLI | Type / range | Default | Notes | |---------------------------------|------------------|-----------------------------|---------|-------| | Grey / Combined Axis Steps | `-g N` | 0–256 | 0 | **New** – equal RGB or CMY wedges | | Single-Channel Steps | `-s N` | 0–256 | 0 | **New** – per-colorant wedges | | Preconditioning Profile | `-c <path>` | file picker (.icc/.icm) | none | Optional previous profile for this or similar device | | Neutral Axis Steps | `-n N` | 0–256 | 0 | Requires a preconditioning profile | | Neutral Axis Concentration | `-N 0.0–1.0` | slider | 0.50 | Emphasis of neutral region in OFPS / perceptual distributions | | Optimisation Quality | `-G` | checkbox “High quality” | off | Fast → Good OFPS | | OFPS Adaptation | `-A 0.0–1.0` | slider | 0.1 (or 1.0 when `-c` supplied) | Degree of adaptation to the preconditioning profile | | Full-spread Algorithm | mutually exclusive flags | select: OFPS (default) / Incremental Far Point (`-t`) / Device random (`-r`) / Perceptual random (`-R`) / Device quasi-random (`-q`) / Perceptual quasi-random (`-Q`) / Device BCC (`-i`) / Perceptual BCC (`-I`) | OFPS | | | Total Ink Limit (TAC) | `-l N` | 0–400 (%) | none | Critical for CMYK; recommend setting ≥ final profile TAC + 10 % | | Dark Region Emphasis | `-V 1.0–4.0` | slider | 1.0 | Concentrates patches toward dark tones | | Device Value Power | `-p N` | 0.1–4.0 | none | Power-like remapping of device values (rare; advanced) | **C. UI / UX** - Every control (including existing ones) carries a tooltip. - Tooltips appear on hover (mouse) and on long-press / focus (touch). - Optional global toggle “Show help for all options” that keeps tooltip text visible (or shows a side help panel) while the user explores the form. - Group all advanced controls (`-g`, `-s`, `-c`, `-n`, `-N`, `-G`, `-A`, algorithm, `-l`, `-V`, `-p`) inside a collapsible `<details>` “Advanced options” section so the default view stays clean. - Colour-space change must dynamically adjust defaults and enable/disable CMYK-only controls (ink limit, etc.). - Preconditioning profile path is stored relative to the working directory or as an absolute path that is validated before launch. - All new fields are serialised into `ProfilingPreset` / `settings.json` so existing presets continue to work and new presets capture the expanded state. #### 2. Backend changes Extend `TargenConfig` (and the corresponding preset schema in `settings.rs`): ```rust pub struct TargenConfig { // existing pub colour_space: String, pub patch_count: u32, pub white_patches: Option<u32>, pub black_patches: Option<u32>, pub total_patches: Option<u32>, pub basename: String, pub cwd: String, // new pub grey_steps: Option<u32>, // -g pub single_channel_steps: Option<u32>,// -s pub neutral_steps: Option<u32>, // -n pub preconditioning_profile: Option<String>, // -c pub neutral_concentration: Option<f64>, // -N pub ofps_high_quality: bool, // -G pub ofps_adaptation: Option<f64>, // -A pub full_spread_algorithm: Option<String>, // "ofps"|"t"|"r"|"R"|"q"|"Q"|"i"|"I" pub total_ink_limit: Option<u32>, // -l pub dark_emphasis: Option<f64>, // -V pub device_power: Option<f64>, // -p } ``` `build_targen_args` must emit the corresponding flags only when the value is present / non-default, preserving current behaviour for callers that omit the new fields. #### 3. Accurate tooltip text (copy-paste ready) Use the following strings (short enough for a tooltip, accurate to Argyll documentation). **Colour Space** > Choose the device colour model for the test chart. > • RGB (Printer Driver) – for printers driven by an RGB driver or host colour management. > • CMYK (RIP) – for printers controlled by a RIP or when you need explicit CMYK separation. > This sets the `targen -d` colourant combination (2 = Print RGB, 4 = CMYK). **Patch Count** > Total number of colour patches that will appear in the final chart. > Higher counts improve profile accuracy (especially in smooth gradients and near the neutrals) but increase print time, paper usage and measurement time. > Typical guidance: > • 400 – quick draft / preliminary profile > • 800 – good everyday quality > • 1500 – high-quality photo / proofing > • 2500+ – maximum quality or N-colour work. > The value is passed to `targen -f`. **White Patches** (`-e`) > Number of pure-white patches included in the chart. > White defines the paper white point that the ICC profile is made relative to. Measuring several white patches improves robustness against measurement noise and local paper variation. > Default is 4. Values of 4–8 are common. **Black Patches** (`-B`) > Number of pure-black patches included in the chart. > Black is especially important for additive (RGB) devices; measuring multiple black patches improves black-point accuracy. > Default is 4 for RGB / grey and 0 for CMYK. Values of 4–8 are typical for RGB. **Grey / Combined Axis Steps** (`-g`) > Number of evenly-spaced steps along the combined grey axis (equal R=G=B or C=M=Y). > These patches improve the profile’s neutral-axis rendering and are useful when the device will later be used as a source colour space. > 0 = none (default). A value around the cube-root of total patch count is a good starting point. **Single-Channel Steps** (`-s`) > Number of steps for each individual colorant wedge (R, G, B or C, M, Y, K). > Useful for diagnosing per-channel non-linearity and for source-space characterisation. > 0 = none (default). Total patches added = steps × number of colorants. **Neutral Axis Steps** (`-n`) > Number of patches placed along the true neutral axis as estimated by a preconditioning profile. > Requires a Preconditioning Profile. Improves neutral rendering of the final profile. > A sensible starting value is the cube-root of the total patch count. Too high a density can push full-spread patches away from the neutrals. **Preconditioning Profile** (`-c`) > Optional previous ICC/ICM (or MPP) profile of this or a similar device. > Used by `targen` to estimate perceptual distances, colourspace curvature and the true neutral axis. > Enables adaptive OFPS placement and the Neutral Axis Steps control. Leave empty for the built-in device-space model. **Neutral Axis Concentration** (`-N`) > How strongly the patch distribution should favour the neutral axis (0 = none, 1 = maximum). > Default 0.5. Most effective with a preconditioning profile and a high OFPS Adaptation value. > Helps maximise visual quality where the eye is most sensitive. **Optimisation Quality** (`-G`) > When checked, `targen` runs the OFPS algorithm in “good” mode (more iterations) instead of the faster default. > Produces a more evenly distributed set of patches at the cost of longer generation time. > Recommended for final production charts. **OFPS Adaptation** (`-A`) > Degree to which the default OFPS algorithm adapts to the known device behaviour supplied by the preconditioning profile (0 = ignore profile, 1 = fully adapt). > Default is 0.1; automatically rises to 1.0 when a preconditioning profile is supplied. Lower the value if the previous profile is a poor match for the current media/ink. **Full-spread Algorithm** > Algorithm used to place the remaining “full-spread” patches after white, black, grey and single-channel patches have been added. > • OFPS (default) – Optimised Farthest Point Sampling; best evenness in most cases. > • Incremental Far Point – used automatically for >4 channels; can be forced. > • Device / Perceptual random or quasi-random – alternative space-filling methods. > • Body-centred cubic (device or perceptual) – regular grid with centre points; efficient packing. > Leave on OFPS unless you have a specific reason to change it. **Total Ink Limit (TAC)** (`-l`) > Maximum total ink coverage (Total Area Coverage) allowed for any generated patch, in percent. > Essential for CMYK to avoid over-inking and to match press or RIP limits. > Good practice: set the chart limit at least 10 % higher than the final profile TAC. > The limit is written into the .ti1 and carried through to colprof. Leave empty for no limit (or the limit estimated from a preconditioning profile). **Dark Region Emphasis** (`-V`) > Concentrates more patches toward the dark end of the tone scale (1.0 = none, up to 4.0 = strong). > Useful for devices that exhibit strong non-linearity or important detail in shadows. Default 1.0. **Device Value Power** (`-p`) > Optional power-like remapping applied to all device values after generation. > Values > 1 tighten spacing near 0; values < 1 tighten spacing near 1. > Rarely needed; mainly for highly non-linear devices or special calibration charts. Leave empty for linear spacing. **Target Basename** > Base name used for all generated files (.ti1, later .ti2, .ti3, .icc/.icm). > Do not include an extension. The files are written into the selected working directory. **Working Directory** > Folder where the .ti1 (and subsequent artefacts) will be created. > Must be writable. Use the Browse button to choose a location. #### 4. Tooltip implementation notes - Prefer native `title` attributes for simplicity, or a lightweight custom tooltip component that matches the existing dark theme (readable contrast, max-width ≈ 280 px, arrow pointing to the control). - On touch devices, long-press or focus should show the same text. - The optional “Show help for all options” toggle can either: - force all tooltips to remain visible, or - open a side panel / expandable help list that mirrors the tooltip content. - Tooltips must never obscure adjacent form controls or the primary “Generate” button. ### Acceptance Criteria - [ ] All listed new controls appear in Stage 1, correctly wired to `TargenConfig` and `build_targen_args`. - [ ] Controls are logically grouped into "Basic Settings" and a collapsible "Advanced Options" section. - [ ] Generated `.ti1` contains the expected flags (verifiable by inspecting the process log or the .ti1 header). - [ ] Every Stage 1 control (existing + new) has a tooltip whose text matches the wording above (or an equally accurate paraphrase). - [ ] Tooltips work with both mouse hover and touch long-press / focus. - [ ] “Show help for all options” toggle functions as specified. - [ ] Changing Colour Space updates defaults and enables/disables CMYK-specific controls (ink limit, etc.). - [ ] Existing presets still load and apply correctly; new fields are optional / defaulted. - [ ] New presets capture and restore the expanded set of values. - [ ] Advanced section is collapsed by default; opening it does not break layout on 1280×800 minimum window size. - [ ] Unit tests for `build_targen_args` cover the new optional flags (present and absent cases). ### Dependencies & Ordering - **Milestone**: Milestone 10 (`v0.5.0`) - **Ordering**: Step 3 - **Dependencies**: None (independent of logging and .ti2-resume features)

gronod added this to the Milestone 10: Production Ready Features (v0.6.0) milestone 2026-08-29 17:28:15 +01:00

gronod added the Kind/Feature

Reviewed

Confirmed

1

labels 2026-08-29 17:28:15 +01:00

gronod referenced this issue from a commit

2026-08-29 17:51:28 +01:00

feat(stage1): add advanced targen options, collapsible section, tooltips and preset integration (resolves #141)

gronod referenced a pull request that will close this issue

2026-08-29 17:51:31 +01:00

feat(stage1): add advanced targen options, collapsible section, tooltips and preset integration (resolves #141) #144