HDR Gamut Plot Developer Reference

• Tool shell: tool/general/gamut-and-rendering/hdr-gamut-plot/index.html contains metadata, hero content, guide banner, tab navigation, controls, canvases, action controls, standards, formulas, references, research panels, toast node, fullscreen chart overlay, and script includes.
• Tool engine: js/tool/hdr-gamut-plot.js contains the standalone runtime, rendering code, transfer math, exports, state, URL restore, and public API.
• Library binding: js/library/tool-bindings.js registers /tool/general/gamut-and-rendering/hdr-gamut-plot/ as tool id hdr-gamut-plot, category Gamut & Rendering, asset type preset.
• Shared runtime capture: js/library/tool-bindings.js also maps hdrGamut to window.AAHdrGamutPlot.getState and restore to window.AAHdrGamutPlot.restoreState.
• Discovery outputs: documentation changes must be reflected in data/documentation.json, RSS, feed, sitemaps, PWA cache manifest, and search index by running the discovery scripts.

• Application root: hg-app wraps the tool with role="application".
• Tabs: tab buttons use data-hg-tab and panel ids p-hg-lab, p-hg-actions, p-hg-standards, p-hg-formulas, p-hg-refs, and p-hg-research.
• Control ids: the engine reads hg-color-space, hg-overlay-toggles, hg-adv-toggles, hg-axes, hg-observer, hg-peak, hg-curve-type, hg-hlg-env, hg-signal-level, hg-plot-mode, and hg-tmo.
• Label ids: runtime labels include hg-peak-val, hg-curve-peak-label, hg-axes-label, hg-axes-status, hg-hlg-gamma, and hg-ictcp-I-label.
• Canvas ids: primary render targets are hg-gamut-canvas, hg-curve-canvas, hg-ictcp-canvas, hg-compare-canvas, hg-eotf-canvas, and hg-boundary-canvas.
• Action ids: buttons include hg-copy-json, hg-copy-css, hg-copy-csv, hg-export-diagram, hg-export-curve, hg-export-ictcp, hg-copy-link, hg-compare-btn, hg-boundary-btn, hg-upload-btn, hg-batch-run, and hg-batch-csv.
• Do not rename ids casually: the engine uses direct id lookups. Any id change must be reflected in event binding, restore, export handlers, Library capture expectations, and tests.

The authoritative state is produced by readState() in js/tool/hdr-gamut-plot.js.

• colorSpace: active working key, default Rec2020 in the page and sRGB fallback in the engine.
• overlays: object keyed by sRGB, P3, and Rec2020 with boolean checkbox state.
• spectral: whether to draw the spectral locus.
• purples: whether to draw the line of purples.
• ictcpMarker: whether the ICtCp sample marker option is active.
• axes: xy or uvp.
• observer: observer label state, currently 1931-2 or 2015-10.
• peakNits: display or mastering peak in nits, parsed from hg-peak.
• curveType: gamma22, gamma24, pq, or hlg.
• hlgEnv: dark, dim, or bright.
• signalLevel: normalized 0 to 1 sample level.
• plotMode: ictcp or jzazbz.
• tmo: reinhard, hable, aces, or uchimura.

updateAll() debounces redraw with requestAnimationFrame, refreshes labels, redraws the three primary canvases, updates metrics, and writes the share URL field.

• SPACES: built-in gamut registry with sRGB/Rec.709, Display-P3, and Rec.2020 labels, RGB primary xy coordinates, and D65 white point.
• SP_CLR: display colors for the three gamuts.
• Spectral locus: L2 is a flat CIE 1931 2 degree xy array from 380 nm to 700 nm in 5 nm steps.
• sRGB matrices: M_S2X and M_X2S convert D65 sRGB values to and from XYZ.
• BT.2020 matrix: M_BT_XYZ supports HDR perceptual conversion paths and JzAzBz calculations.
• ICtCp matrices: M_BT_LMS and M_LMS_BT support BT.2100-style LMS conversion before PQ encoding.
• PQ constants: PQ_M1, PQ_M2, PQ_C1, PQ_C2, PQ_C3, and PQ_MAX drive pqEotf(), pqOetf(), and pqEncode().
• HLG helpers: hlgOetf(), hlgEotf(), and hlgSysGamma() drive curve generation and HLG environment labeling.
• Tone curves: curvePoints() creates plotted samples for gamma, PQ, and HLG modes.
• Tone mapping: tmReinhard(), tmHable(), tmAces(), tmUchimura(), and applyTMO() provide the operator options exposed in the UI.

• sRGB helpers: srgbGamma(), srgbLinear(), rgbToXyz(), xyzToSrgb(), hexToRgb(), and rgbToHex() support hover, batch, and color fill workflows.
• CIELAB: xyzToLab() is used by hover sampling and batch output.
• Chromaticity: xyToUpVp() converts xy into u-prime v-prime, while coordForAxes() returns coordinates for the active diagram mode.
• ICtCp: pqEncodeLMS(), rgbToICtCp(), and ictcpToRgb() convert HDR RGB values into intensity and chroma components.
• JzAzBz: xyzToJzAzBz() converts absolute XYZ values into Jz, Az, and Bz for the perceptual plane and boundary calculations.
• Gamut area: triArea() and gamutArea() calculate triangle area in the selected axes and power metrics, CSV, CSS, and comparison output.

• Theme helpers: canvas renderers use theme color helpers so diagrams remain legible in light and dark modes.
• Chromaticity diagram: drawChromDiagram() renders background fill, spectral locus, line of purples, visible gamut triangles, labels, current working space context, and hover-ready coordinates.
• Fill cache: changing overlay checkboxes or axes clears fillCache so chromaticity fill can be recomputed safely.
• Tone curve: drawToneCurve() plots the selected curve and labels output luminance against the selected peak.
• Perceptual plane: drawPerceptualPlane() renders ICtCp Ct/Cp or JzAzBz Az/Bz output using the active plot mode, signal level, peak, and tone mapping context.
• Metrics table: updateMetrics() fills hg-metrics-body with transformed primaries, white point coordinates, Rec.2020-normalized coverage, and reference labeling.
• Hover sampler: mouse movement over hg-gamut-canvas maps screen position back to xy, derives XYZ and Lab, computes ICtCp from the current signal level, and writes hg-hover-info.

• EOTF comparison: drawEotfComparison() draws PQ, HLG at 1000 nits, and gamma 2.2 on a log luminance grid from 0.1 to 10000 nits.
• Boundary rings: drawGamutBoundary() draws ICtCp or JzAzBz rings at 0.1, 1, 10, 100, 500, 1000, 4000, and 10000 nits for enabled overlays.
• Comparison chart: compareSpaces() renders a normalized bar chart and updateCompareTable() fills hg-compare-tbody.
• Batch conversion: runBatch() parses six-digit hex colors from comma-separated or line-separated input, calculates Lab, ICtCp, and JzAzBz values, writes an HTML table, and returns rows for CSV copy.
• Image analysis: analyseImage() samples every fourth pixel from a local canvas, estimates peak and average luminance from peakNits, and writes estimated gamut coverage to hg-image-results.
• Image cap: uploaded image canvases are capped to 1024 pixels in each dimension before analysis to keep the browser responsive.

• PNG export: exportPNG() serializes the selected canvas with toDataURL("image/png") and downloads it through a temporary anchor.
• Clipboard helper: copyText() uses navigator.clipboard.writeText() and reports success or failure through the toast.
• JSON export: buildGamutJSON() exports all built-in gamut definitions plus metadata for axes, peak nits, curve type, and tool name.
• CSV export: buildCSV() exports RGB primary coordinates, white point, area, and Rec.2020-normalized coverage.
• CSS export: buildCSSVars() exports coverage variables, primary coordinate variables, peak nits, and selected curve type.
• Share state: stateToURL() stores axes, peak, curve, and mode.
• URL restore: loadFromURL() applies those four query parameters before event binding and initial render.
• Share limitation: overlays, observer, HLG environment, signal level, and tone mapping operator are not encoded in the share URL. Full Library restore handles a wider state object.

• Boot: boot() loads URL state, binds events, renders the tool, then exposes window.AAHdrGamutPlot.
• API shape: window.AAHdrGamutPlot = { getState, restoreState }. getState() returns readState(). restoreState(saved) applies known fields, restores overlay checkboxes, calls updateAll(), and returns true for valid objects.
• Restored fields: restore maps colorSpace, axes, observer, peakNits, curveType, hlgEnv, signalLevel, plotMode, and tmo to their matching control ids.
• Overlay restore: if saved.overlays exists, each checkbox in hg-overlay-toggles is set from the matching key.
• Simple binding: attachTool() matches the HDR route, uses tool id hdr-gamut-plot, name HDR Gamut Plot, href /tool/general/gamut-and-rendering/hdr-gamut-plot/, category Gamut & Rendering, and asset type preset.
• Capture fallback: Library capture first calls firstToolCanvas() and saves HDR gamut plot as a canvas image. If no canvas exists, it falls back to captureFormPreset({ name: "HDR gamut preset" }).
• Binding restore: the generic form binding triggers hdr-render and hdr-update. Prefer the public API restore when a full saved state object is available.

1. Add new RGB gamuts to SPACES with a stable key, label, red, green, blue, and white xy arrays.
2. Add a display color to SP_CLR and update overlay controls if the new gamut should be user-toggleable.
3. Update metrics, JSON, CSS, CSV, comparison, and docs if the new gamut should appear in exports.
4. When adding a transfer curve, update curvePoints(), keyboard shortcuts, labels, formula copy, share URL expectations, and tests.
5. When adding a perceptual model, update drawPerceptualPlane(), drawGamutBoundary(), batch conversion, result headings, and exports.
6. When changing state fields, update readState(), restoreState(), stateToURL() if appropriate, Library capture notes, and documentation.
7. When changing canvas ids or dimensions, update export handlers, Library canvas capture behavior, fullscreen helpers, responsive CSS, and smoke tests.
8. When changing image analysis, document whether pixels are assumed SDR, display-referred, or scene-referred so users do not treat estimates as calibrated measurements.
9. Regenerate documentation discovery outputs after article edits with scripts/generate-discovery.mjs, scripts/generate-pwa-cache-manifest.mjs, and search/client/build-index.js.
10. Keep standard names exact: Rec.709, Display-P3, Rec.2020, BT.2100, ST 2084 PQ, HLG, ICtCp, and JzAzBz.

• Boot: verify the Lab tab appears, controls have defaults, the three primary canvases render, and the metrics table populates.
• Controls: exercise every color space, overlay toggle, advanced toggle, axes mode, observer value, peak value, curve type, HLG environment, signal level, plot mode, and tone mapping operator.
• Keyboard: test 1, 2, 3, 4, and A outside form controls.
• Hover: move over the chromaticity diagram in xy and u-prime v-prime modes and verify the coordinate readout updates without console errors.
• Actions: test JSON, CSS, CSV, link copy, compare chart, diagram PNG, curve PNG, and perceptual plane PNG.
• Research: open the Research tab, confirm EOTF comparison draws, compute gamut boundary, upload a sample image, run batch conversion, and copy batch CSV.
• URL: create a share URL, reload it, and verify axes, peak, curve, and plot mode restore before first render.
• Library: save a preset snapshot, confirm the canvas preview, restore full runtime state, and verify overlay checkboxes return to saved values.
• Numerical risk: changes to PQ constants, HLG gamma, matrices, spectral locus, or JzAzBz constants will alter diagrams, batch output, exported JSON, and comparison metrics.
• Interpretation risk: xy area, u-prime v-prime area, ICtCp/JzAzBz plots, and browser image estimates answer different questions. Keep UI copy and docs explicit about what each result means.