Add IccProfilePlot: data-first profile visualization API + CLI

[colourbill-ctrl]

Re-homed from #1264 to clear the fork-PR CI gate. This is the same IccProfilePlot change, now on an in-repo branch so it can pass Risk Analysis Gate / Workflow Security Audit. As a fork PR, #1264 necessarily modified Build/Cmake (the new tool's CMake wiring), which the Fork-PR Maintainer-Automation gate hard-blocks on the untrusted path — so #1264 could never go green. This PR carries @xsscx's ci-refactor-cmake-pr1264 branch (the same work rebased on current master, with the -Wodr CIccProfile/icHeader build-warning fix and a Unicode→ASCII punctuation cleanup), and runs through ci-pr-action green. Per @xsscx's request on #1264 ("add this PR from an iccDEV:branch").

Review history is on #1264 and is preserved, not discarded:

• @ChrisCoxArt — APPROVED (2026-06-08), conditional on @maxderhak agreeing to the approach.
• @xsscx — APPROVED (2026-06-18) after manual code review, then CHANGES_REQUESTED (2026-06-22) asking specifically for this in-repo re-home to resolve the CI gate.
• Still required: @maxderhak design sign-off (the substantive approval Chris's was conditional on). Relocation is a CI/process mechanic only — it does not change the code or substitute for that review.

Supersedes #1264 (which will be closed with a pointer here). Continue review on this PR.

---

What this is

A new, standalone command-line tool — iccProfilePlot — under Tools/CmdLine/IccProfilePlot/, built on a new data-first visualization model, IccVizModel. Where iccProfileVisualize renders a finished PDF/TIFF report, IccVizModel returns the underlying data for each visualization:

• Graphs (tone curves, the CIE 1931 chromaticity chart, named/colorant a*b* and xy scatters) come back as point series + axis hints.
• The nD CLUT lattice comes back as ICC-normalized samples + geometry.

A caller then draws, colour-manages, or exposes individual graphs and their data however it likes — into a PDF, an SVG, JSON, or an interactive UI.

Developed in parallel to iccProfileVisualize, on purpose

This is effectively a major refactor of the iccProfileVisualize visualization code toward a data-first API. For regression and safety, that refactor is being carried out outside the iccProfileVisualize codebase rather than in place — iccProfileVisualize is left completely untouched, so there is no risk to the actively-developed tool, and the two can be diffed and validated independently. The intent is a parallel track that can later converge, not an in-place rewrite.

Faithful to the original where it counts

As much as possible, the original guard rails, commenting, and structure have been preserved, so the two read alike:

• the per-condition CLUT/curve/named-colour guards and their recovery behaviour are carried over,
• the inline domain comments travel with the code they explain,
• diagnostics emit the same text as the original (Skipping <tag>: invalid CLUT width, WARNING - tile count overflow., …).

A silent mode lets the caller turn the CLI/stderr diagnostic echo on or off to suit its context: by default the model echoes diagnostics to stderr exactly like iccProfileVisualize (so the CLI behaves identically out of the box); a library embedding (e.g. WASM/browser) calls SetSilent(true) to suppress it, while still receiving every reason as structured data. A per-call Verbosity can override the global switch either way.

The API

See the usage guide at the top of IccVizModel.hpp, echoed as a worked example in iccProfilePlot.cpp:

Enumerate(pIcc)            -> [Descriptor{ kind, output, id, title }, ...]
RenderGraph (pIcc, id)     -> Graph  { series[], xAxis, yAxis }
RenderRaster(pIcc, id)     -> Raster { width,height,channels,..., samples }

Pick a visualization by Kind, supply a CIccProfile*, and render the one you want as graph data or raster samples.

Scope note: the demo tool does not emit PDF (yet)

iccProfilePlot is a demonstration consumer of the API — it lists visualizations and serializes the returned graph/raster data (JSON / raw samples). It deliberately does not emit a PDF at this point; producing a finished report would require drawing the returned data into MiniPDF (the rendering layer iccProfileVisualize uses), which is intentionally left out so the model and this tool stay dependency-light (IccProfLib only). The commented walkthrough in iccProfilePlot.cpp shows exactly where a PDF generator would slot in.

Build / test

• New Build/Cmake/Tools/IccProfilePlot/CMakeLists.txt, registered in the top-level CMake; builds clean against IccProfLib via the standard CMake build.
• CLI verified: iccProfilePlot <profile> list | graph <id> | raster <id> [out.raw].

🤖 Generated with Claude Code

---

Update — second commit (bbd8109): a PDF/TIFF report tool on the engine

The scope note above ("the demo tool does not emit PDF yet") is now addressed: a
second tool draws finished artifacts through the engine.

iccProfileVisualize (in the same Tools/CmdLine/IccProfilePlot/ dir — a parallel,
data-first reimplementation; the standalone tool of the same name is left untouched)
reproduces that tool's PDF (tone curves, chromaticity, named-colour scatters) and
per-tag TIFF output. Instead of walking the profile and computing geometry inline,
it enumerates and renders through IccVizModel and draws the returned data with
the dependency-free Mini{PDF,SVG,TIFF} writers. The engine is the single source of
the maths; the tool is just a drawing front-end.

Changes (all under Tools/CmdLine/IccProfilePlot/, plus the tool's CMake target)

• New iccProfileVisualize.cpp — processLuts() calls iccviz::Enumerate(),
  then per descriptor RenderGraph / RenderRaster, drawing each with the Mini
  writers (renderChromaticityGraph, renderCurveGraph, the reused
  graphNamedColorsPDF, and WriteTIFF straight from the raster). The original
  drawing primitives and reference-geometry XObjects are preserved verbatim; the
  now-superseded inline extractors were removed (lineage noted in comments).
• New MiniPDF / MiniSVG / MiniTIFF — the dependency-free writers carried
  over from the standalone tool. No third-party libraries.
• IccVizModel.{hpp,cpp} — Enumerate(pIcc, Order order = Order::Canonical):
  Canonical is the existing fixed, cross-module/WASM-safe order; the opt-in
  Order::TagTable reorders the same descriptors to the profile's tag-table page
  sequence so a report matches the original. Also v5 named colours in
  collectNamedColors (icSigTagArrayType: NamedColorArray / ColorantInfoArray —
  PCS float arrays → Lab, names via UTF8/UTF16/Text/MLU, tint-% suffixes), with the
  PCS basis aligned to the profile header PCS.
• Build/Cmake/Tools/IccProfilePlot/CMakeLists.txt — registers an
  iccProfileVisualizePlot executable (distinct output name so it doesn't clash
  with the standalone iccProfileVisualize on install). Verified to configure and
  build in-tree.

Testing

Built both tools against the same IccProfLib and ran them over a 90-profile corpus
(RGB matrix, CMYK / N-colour CLUT, named/spot, wide-gamut, iccMAX), comparing every
artifact byte-for-byte against the original standalone iccProfileVisualize:

	Result
Crashes	0 / 0
Per-tag TIFFs	355 / 355 byte-identical
PDFs	77 / 77 byte-identical (page order matched via Order::TagTable)
Artifact-name-set mismatches	0

IccVizModel.cpp compiles clean under -Wall -Wextra. One intentional difference: a
present-but-malformed curve (e.g. bad-bluecurve.icc) is enumerated and rendered with
a diagnostic, where the original silently dropped the page — consistent with IccViz's
"surface the reason" design.

[xsscx]

PR Status

2026-06-22 19:34:57 UTC

@colourbill-ctrl I will be making changes to the Failing Dockerfile at 2026-06-22 19:38:00 UTC and likely aquick Rebase on master with a clean linear commit history.

• xml sha pin issue.. will be fixed shortly.. testing locall now at 2026-06-22 19:40:42 UTC

[xsscx]

PR Status

2026-06-22 19:56:44 UTC

• Local CTest in progress
• ETA 2026-06-22 20:10:00 UTC

[xsscx]

2026-06-26 03:00:29 UTC