CMY+N (multi-channel) support in the TI2 layout editor + patch generators

[itsab1989]

Goal

Extend the TI2 layout editor (and its New-chart / Add-patches dialogs) so it can create and edit CMY + N-colorant charts, not just RGB — with a targen device-type selector, dynamically-revealed colorant slots (like the manual Create Chart tab's -d / -D), and the patch generators (#37) made available where they are meaningful.

The hard finding from the design discussion: the perceptual generators (skin tones, blues, greens, sunrises, pastels, image-palette, near-neutral) are colour-appearance constructs and have no meaning in an N-channel device space without a colour model. A preconditioning ICC profile supplies exactly that model, breaking the chicken-and-egg. So the feature is gated in three states, and only the smallest tier requires the profile.

Scope note: this is a plan only. No code has been written. Everything below is grounded in a verified read of the current code + the ArgyllCMS 3.5.0 source (/Users/Basti/Downloads/Argyll_V3.5.0_orig). File:line anchors are given so a fresh session can navigate immediately.

---

The three-state UX model

State	Trigger	What's available
1. RGB (default)	Device type = Print RGB (-d2) / Video RGB (-d3)	Everything as today. No preconditioning field shown.
2. CMY+N, no profile	A multi-channel -d chosen (or a non-RGB .ti2 loaded)	targen-OFPS coverage, device grey ramp (-g), white/black anchors, literal N-channel corners. Preconditioning field shown but optional. Perceptual generators greyed.
3. CMY+N + valid profile	State 2 + a channel-matching preconditioning ICC supplied	Perceptual generators unlock: Lab target → xicclu backward → device values; XYZ for the .ti1 from xicclu forward.

Rationale, gating scope, and caveats (separation-collapse, refine-only) were settled in discussion. The key UX rule: gate the perceptual-region subset only, never the whole generator panel — a first-ever CMY+N chart has no profile by definition and must still be buildable (via targen).

---

UI mockups (New-chart / Add-patches dialog — _NewChartDialog)

State 1 — RGB (unchanged; no profile field)

┌─ New chart ───────────────────────────────────────────┐
│ Instrument:  [ i1Pro 2            ▾ ]                   │
│ Paper:       [ A4                 ▾ ]                   │
│ Device type: [ Print RGB (-d2)    ▾ ]   ← NEW, default  │
│                                                        │
│ Source:  ◉ Generate colour sets                        │
│          ○ Seed from targen   ○ Blank   ○ Load file     │
│                                                        │
│  ┌ Generate colour sets ───────────────────────────┐  │
│  │ ☑ RGB cube            [ 9 ]³  = 729              │  │
│  │ ☑ Near-neutral greys  steps[16] rings[1]         │  │
│  │ ☑ Skin tones          per[6] ranges[3]           │  │
│  │ ☑ Blues  ☑ Greens  ☑ Sunrises  ☑ Pastels         │  │
│  │ ☑ Gamut edges  ☑ Gamut faces                     │  │
│  │ ☑ Highlights & shadows   ☑ From image…           │  │
│  │ ☑ Fill gaps to [1200]   ☑ White/Black ×[1]       │  │
│  │                         Total: 1187 patches      │  │
│  └──────────────────────────────────────────────────┘  │
│                                   [ Cancel ] [ Create ] │
└────────────────────────────────────────────────────────┘

State 2 — CMY+N chosen, no profile yet (perceptual sets greyed; profile field revealed, optional)

┌─ New chart ───────────────────────────────────────────┐
│ Instrument:  [ i1Pro 2            ▾ ]                   │
│ Paper:       [ A4                 ▾ ]                   │
│ Device type: [ CMYK (-d4)         ▾ ]                   │
│   + colorant: [ Orange (-D5)      ▾ ] [+]   ← reveals    │
│   + colorant: [ Green  (-D7)      ▾ ] [+]     next slot  │
│                                  → effective set: CMYKOG │
│                                                        │
│ Preconditioning profile (optional):                    │
│   [ (none — perceptual sets need a profile)   ] [Browse]│
│   ⓘ Needed to map skin/blue/green… to this device's inks│
│                                                        │
│  ┌ Generate colour sets ───────────────────────────┐  │
│  │ ☑ targen coverage (OFPS)   patches[1000]         │  │
│  │ ☑ Device grey ramp    steps[16]                  │  │
│  │ ☑ N-channel corners                              │  │
│  │ ░ Skin tones        (needs profile) ──────────┐  │  │
│  │ ░ Blues ░ Greens ░ Sunrises ░ Pastels         │  │  │
│  │ ░ From image…   ░ Near-neutral (perceptual)   │  │  │
│  │ ☑ White/Black ×[1]              greyed = locked│  │  │
│  │                         Total: 1024 patches    │  │  │
│  └──────────────────────────────────────────────────┘  │
│                                   [ Cancel ] [ Create ] │
└────────────────────────────────────────────────────────┘

State 3 — CMY+N + valid profile (perceptual sets unlocked)

┌─ New chart ───────────────────────────────────────────┐
│ Device type: [ CMYK (-d4)  ▾ ]  + Orange + Green       │
│                                  → effective set: CMYKOG │
│ Preconditioning profile:                               │
│   [ runs/run1/profile.icc  ✓ CMYK, 4-ch — matches ]  [×]│
│                                                        │
│  ┌ Generate colour sets ───────────────────────────┐  │
│  │ ☑ targen coverage (OFPS)   patches[800]          │  │
│  │ ☑ Device grey ramp   ☑ N-channel corners         │  │
│  │ ☑ Skin tones   per[6] ranges[3]   (via profile)  │  │
│  │ ☑ Blues  ☑ Greens  ☑ Sunrises  ☑ Pastels         │  │
│  │ ☑ From image…   ☑ Near-neutral greys             │  │
│  │ ☑ Fill gaps to [1500]   ☑ White/Black ×[1]       │  │
│  │                         Total: 1500 patches      │  │
│  └──────────────────────────────────────────────────┘  │
│  Note: profile-inverted patches are placement hints —   │
│  measurement governs the profile, not the nominal value.│
└────────────────────────────────────────────────────────┘

Validation behaviour: when a profile is picked whose colorspace/channel-count does not match the chosen device type, reject inline at the field (don't defer to a targen/xicclu failure). Auto-fill from the current run's preconditioning.icc / a loaded chart's recorded profile when present.

UI consistency: reuse the inline progressive-reveal pattern (check a colorant slot → next slot appears), mirroring the manual tab's -D stacking — not a modal pop-up.

---

Verified current state (RGB-only chokepoints)

Patch generators — workflow/patch_generators.py (972 lines): every generator returns (R,G,B) on 0..100. Constructs are intrinsically 3-D perceptual: rgb_cube (N³), gamut_edges/gamut_faces (literal RGB-cube wireframe/surface), skin_tones (CIELab→sRGB), blues/greens/sunrises/pastels (HSV), near_neutral_greys (RGB neutral axis rings), image_palette (Lab k-means→sRGB), fill_gaps/deduplicate (3-D RGB Voronoi/grid). deduplicate, fill_gaps, white_black, count_white_black, overlap_count, dedupe_against, only_new all assume 3-tuples.

Editor core — workflow/ti2_relayout.py (1669 lines):

• ChartSpec.from_ti2 (L124) is already channel-generic — dev_fields parsed from COLOR_REP. Good.
• ChartSpec.new (L197) hardcodes ["RGB_R","RGB_G","RGB_B"], iRGB.
• write_ti1 (L592) raises NotImplementedError for any non-RGB (L619) and delegates to the RGB-only emitter.
• load_rgb_program (L489) rejects non-RGB sources (L513).
• seed_from_targen (L532) parses RGB only (_first_table_rgb, L564).
• recolor_spacers (L1261) + _imread_rgb (L1356) do .convert("RGB") and write photometric="rgb" → would collapse/corrupt device channels on a Separated TIFF.
• analyze_randomisation / _read_ti2_strips (L786) hardcode RGB_R/G/B.

.ti1 emitter — workflow/i1profiler_import.py (write_ti1, L298): emits a fixed 7-field table SAMPLE_ID RGB_R RGB_G RGB_B XYZ_X XYZ_Y XYZ_Z, COLOR_REP "iRGB", RGB cube-corner _DENSITY_EXTREMES (8 rows) + _DEVICE_COMBINATIONS (9 rows), XYZ synthesized from sRGB with 1% flare. RGB-only by construction.

Dialog — ui/dialogs/ti2_relayout_dialog.py (5455 lines): _NewChartDialog (L699) has instrument/paper combos, source-mode radios, _build_generate_panel (L1380), _build_generated_program (L1915), _collect_gen_state/_apply_gen_state (L1224) for recipe persistence, and calls ChartSpec.new(self._instr.currentData(), paper_code) at L2283. _AddPatchesDialog(_NewChartDialog) (L2346). Main editor Ti2RelayoutDialog (L2578).

Already multi-channel (reuse, don't rebuild):

• targen device types -d0..15 + add/remove colorant -D — data/parameters.yaml (device_type L~20-51, -D L53-96), assembled in workflow/chart_creator.py::_build_targen_args (L952).
• Ink-channel maps — ui/tiff_preview.py: _D_TYPE_CHANNELS (device→ordered ink codes), _D_FLAG_CODE, _N_CHANNELS_FALLBACK, resolve_ink_channels (L181), the Generic-CMYK ICC transform (_cmyk_to_srgb_transform).
• Multi-channel display: _load_frame / _tifffile_load_frame read Separated TIFFs (>4 ch via tifffile) and composite to RGB. Read-only.
• ICC inspection — workflow/icc_info.py::read_icc exposes the colorspace signature (RGB/CMYK/nCLR), usable for channel-match validation.
• Preconditioning plumbing — chart_creator._import_external_preconditioning (L637), Run.preconditioning_icc, Project.new_run(preconditioning_from=…).

---

Verified Argyll facts (printtarg + xicclu)

From target/printtarg.c (3.5.0):

• printtarg fully supports DeviceN charts: reads COLOR_REP → icx_char2inkmask → nmask (L3485-3488). Device fields are read by colorant-mask-derived names "<bident>_<inkchar>" (e.g. CMYK_C, or GRAY_<c> for W/K), L3513-3527.
• XYZ_X/Y/Z are required fields — printtarg errors out if absent (L3531-3539), in all three tables that carry device values. Even under -r they must be present.
• The 2nd table (density extremes) must have exactly 8 sets (error ("Expect second set of data to have 8 sets…")) with the N device columns + XYZ. It is the spacer palette + min/max-density refs; white-first ordering matters for label rendering.
• Table count must be 2 or 3 (L3426); the 3rd table (device combinations) is optional (if (icg->ntables >= 3), L3639).
• -r sets rand = 0 (L3131); with rand=0 the strip-reorder optimization (simulated annealing) is skipped (L1506 if (… || !rand || npat < 3)). So under -r XYZ values affect spacer-colour choice but not patch order → XYZ need only be plausible, not exact.
• XYZ drives col_convert → icx_XYZ2Tdens (density) + icx_XYZ2sRGB (display) for spacer contrast (L1055-1083).

From xicclu (-h): -f f|b|ib (forward / backward / inverted-backward), -p x|X|l|L|… PCS format (X = XYZ×100, l = Lab), -i a|r|p|s intent, -k z|h|x|r|… black generation (GCR/UCR control — confirms separation-collapse is real and tunable), -s scale device-range scale. Device I/O is 0..1 (scale ×100 for the TI1). Reads queries on stdin, writes results to stdout. (Exact stdin/stdout token format must be smoke-tested — see Tasks.)

---

Recommended architecture

Two generation engines, one .ti1 path:

1. Coverage (states 2 & 3): run targen with the chosen -d/-D (+ -g/-e/-B). targen is the authority — it emits a complete, valid N-channel .ti1 with correct COLOR_REP, plausible XYZ (its own device model), the 8-row density-extremes table, and the device-combinations table. Reuse _build_targen_args logic.

2. Perceptual (state 3 only): each generator produces its Lab/appearance target (skin_tones already builds in Lab; HSV sets → sRGB → Lab; image_palette already Lab). Feed Lab → xicclu -fb (backward) through the preconditioning profile → N-channel device values. Get each patch's XYZ via xicclu -ff (forward) for the .ti1.

.ti1 assembly — never hand-reconstruct the N-channel format. Always obtain a targen-emitted skeleton for the device type (run targen once), then overwrite table 1's data rows with the union of kept coverage patches + perceptual/white/black/grey patches, attaching XYZ from xicclu -ff (state 3) or a device-model fallback (state 2: the Generic-CMYK ICC for CMYK, naive subtractive for extended inks). Borrow tables 2 & 3 + COLOR_REP from the skeleton verbatim. This sidesteps reconstructing icx_char2inkmask mapping and the 8-row density-extremes by hand. Then the editor relayouts via printtarg -r, exactly as today.

Spacer recolour in N-channel: the TIFF post-process path (recolor_spacers) is RGB-only and corrupts Separated TIFFs. For v1, restrict N-channel charts to the native-palette spacers (from the targen skeleton's density-extremes) and disable custom per-spacer recolour; defer Separated-TIFF read/paint/write to a later tier. Reorder + generate are the core asks and don't need it.

---

Work breakdown (by tier)

Tier A — N-channel .ti1 + editor relayout (no generators yet)

• workflow/ti2_relayout.py:
  • ChartSpec.new(device_type, instrument, paper) — derive dev_fields + color_rep from the device type (via a targen skeleton or _D_TYPE_CHANNELS + an ink-code→COLOR_REP map; prefer reading them back from the skeleton).
  • New write_ti1_nchannel(...) (or generalize write_ti1): assemble table 1 from device tuples + XYZ, borrow tables 2/3 + header from a targen skeleton. Drop the NotImplementedError gate for the N-channel path.
  • Generalize _read_ti2_strips / analyze_randomisation to N device columns (use ChartSpec.dev_fields).
  • seed_from_targen → return N-tuples (generalize _first_table_rgb).
• workflow/i1profiler_import.py: either generalize write_ti1/_table to N device columns + parametric COLOR_REP, or move N-channel emission into ti2_relayout. Keep the RGB path byte-identical (regression-sensitive — see its density-extremes ordering comments).
• New helper workflow/xicclu_runner.py: forward (device→XYZ) + backward (Lab→device) lookups via QProcess/subprocess; intent + -k knobs; stdin/stdout parsing. Smoke-test format first.

Tier B — device-type + colorant + profile UI

• ui/dialogs/ti2_relayout_dialog.py::_NewChartDialog:
  • Add Device type combo (reuse parameters.yaml labels) + dynamic colorant slots (progressive reveal, mirror manual -D). Compute effective colorant set + count.
  • Add Preconditioning profile field (revealed only for non-RGB), with inline channel-match validation via icc_info.read_icc vs _D_TYPE_CHANNELS[device].length. Auto-fill from run / loaded chart.
  • Thread device_type + profile into ChartSpec.new (replaces the hardcoded call at L2283) and into _collect_gen_state/_apply_gen_state + editor_recipe/meta.json persistence.
  • State machine: enable/grey generator rows per state.
• _AddPatchesDialog: same device-type/profile awareness; loading a non-RGB .ti2 puts the dialog in state 2/3.

Tier C — generators in N-channel

• Coverage generators: device grey ramp, N-channel corners, targen-OFPS passthrough (new "engine = targen" branch in _build_generated_program, L1915).
• Perceptual generators (state 3): wrap each generator's Lab target → xicclu backward → device. skin_tones/image_palette expose Lab directly; add Lab-target variants (or a thin *_lab() companion) for the HSV sets. Reuse existing count functions for the live totals.
• N-channel deduplicate/fill_gaps/white_black/overlap_count (Euclidean in N-D device space) — generalize the 3-tuple assumption. New white_black/corners in N-D.

Tier D (later) — Separated-TIFF custom spacer recolour

• N-channel _imread/recolor that preserves device channels (tifffile, paint device values, write Separated TIFF). Generalize assert_patches_untouched. Out of scope for v1.

---

Hard problems / decisions to confirm

1. XYZ source without a profile (state 2 non-targen patches). Prefer letting targen own the patches; only attach fallback XYZ to hand-added white/black/grey/corners (Generic-CMYK ICC for CMYK; naive for extended). Acceptable because XYZ only steers spacer colour under -r.
2. COLOR_REP / colorant ordering must match icx_char2inkmask. Decision: read it back from the targen skeleton rather than reconstruct.
3. Separation collapse (xicclu -k): profile-inverted patches sample one separation. Document as placement hints; expose nothing fancy in v1 (default -k r).
4. Spacer recolour: v1 = native palette only for N-channel; custom recolour disabled (Tier D).
5. PIL vs tifffile for any N-channel pixel I/O: use tifffile (PIL silently drops >4 channels — already noted in _load_frame).

---

Testing

• Unit: N-channel write_ti1 round-trips through ChartSpec.from_ti2; printtarg -r accepts it (golden CMYK + CMYKOG .ti1); density-extremes = 8 rows, white-first; assert_data_integrity generalized to N device values.
• xicclu runner: forward/backward round-trip a known patch within tolerance against a real profile.
• Generator N-channel: deduplicate/fill_gaps uniqueness in N-D; counts match.
• Regression: RGB path byte-identical (the emitter's ordering quirks are load-bearing).
• Run under QT_QPA_PLATFORM=offscreen pytest (see CLAUDE.md). GUI is intrusive — prefer headless.

Open questions

• Should N-channel coverage default to pure targen-OFPS (ignoring most generator checkboxes), with generators as additive top-ups? (Leaning yes.)
• Do we expose xicclu intent/black-generation in the UI, or hardcode relative-colorimetric + ramp-K for v1? (Leaning hardcode.)
• Where does the preconditioning profile for a new (non-refine) project come from — only the refine flow, or a free Browse? (Browse, validated.)

---

Plan generated from a verified read of the codebase + ArgyllCMS 3.5.0 source. No code changes made.

[itsab1989]

Superseded by #72 — the actionable implementation plan lives there. Closing to keep a single source of truth.