Bt2020 Png Generation

BT.2020 HDR PNG Generation

Use this skill when generating BT.2020/BT.2100 HDR PNG analysis artifacts. The goal is to stop repeating one-off scripts for the same PNG/PQ/cICP plumbing.

Related smaller skills

• Use hdr-test-pattern-generation first when the task is to design ramps, sweeps, charts, banding panels, checkerboards, or other synthetic validation inputs.
• Use analysis-graphing when the task is to plot curves, hue sweeps, gamut comparisons, LUT statistics, or readable graph images.
• Use this skill for the final BT.2020/PQ/cICP/ICC PNG output path and validation after the input image or analysis data already exists.

Boundaries

• Focus on PNG/HDR image generation and validation, not shader changes.
• Keep scratch outputs in a temporary output path unless the user asks for durable analysis artifacts.
• Prefer a reusable script or helper under tools/analysis/ for repeated workflows; do not keep cloning the same write_png_rgb16_with_cicp and pq_oetf_st2084 code into new one-off experiments.
• Do not embed graphing or synthetic-pattern design rules here; delegate those to analysis-graphing and hdr-test-pattern-generation.
• If the work becomes shader-side tonemap/LUT math, switch to the SDR tonemap/LUT workflow instead.
• Do not add ICC profiles, AVIF gain maps, JPEG metadata, or platform upload experiments unless the user explicitly asks for that output type. If they ask about Discord, Chrome preview, or Chromium issue 40239687, include the optional HDR ICC path below.

Canonical output

Generate a 16-bit RGB PNG whose pixel values are PQ/ST 2084 encoded absolute nits and whose PNG contains a native cICP chunk:

The PNG cICP payload bytes are therefore:

09 10 00 01

Do not use matrix coefficient 6 for RGB PNG samples. 9/16/6 is useful for YUV BT.2020 NCL encodes such as many AVIF/video paths, not native RGB PNG pixels.

Optional HDR ICC / Discord preview mode

Use this only when the user asks for Discord preview, Chrome HDR ICC, cicpTag, or Chromium issue 40239687 behavior. Keep the normal analysis output as native PNG cICP unless ICC compatibility is the point of the test.

Chromium issue 40239687 tracks Chrome's backwards-compatible HDR image support through a CICP tag embedded in an ICC profile. Chrome uses the ICC cicpTag to discover PQ/HLG HDR signaling for image formats such as JPEG, PNG, and WebP. The ICC transform itself should still be a reasonable SDR/tone-mapped fallback for decoders that ignore the cicpTag.

For the RenoDX Discord tests, the important behavior is:

Reference notes live in:

• docs/AVIF_HDR_FINDINGS.md
• Chromium issue 40239687: "Backwards-compatible HDR images via CICP in ICC profiles"

Rules for ICC mode:

• Only attach a HDR/PQ ICC when the pixels are actually PQ-encoded HDR pixels in the matching gamut.
• Do not tag SDR/gamma pixels with a HDR/PQ ICC.
• For RGB PNG/WebP/JPEG HDR ICC signaling, the embedded ICC cicpTag should advertise BT.2020 primaries, PQ transfer, RGB/identity matrix, and full range: 9/16/0/full.
• If both native PNG cICP and ICC are present, keep them semantically aligned. PNG native cICP is expected to take precedence, while Discord WebP preview relies on ICC because WebP lacks native CICP.
• Treat Discord preview success as metadata-driven HDR over 8-bit WebP. It does not prove high-bit-depth precision survived the preview path.
• Preserve a no-ICC/native-cICP output when the goal is a clean local analysis artifact rather than a Discord upload experiment.

Expected agent output

When invoked, produce these sections:

1. Input assumptions - file/data source, source gamut, white point, transfer, and whether values are scene-linear, display-linear nits, or already PQ.
2. Conversion path - matrices/adaptation used to reach BT.2020 D65 linear RGB.
3. Nits mapping - diffuse white nits, peak/clip linear, and explicit clipping policy.
4. PNG signaling - bit depth, PQ encode, cICP tuple, and whether ICC/profile metadata is intentionally absent or intentionally attached.
5. Validation - stats, read-back cICP check, and any viewer/upload caveats.
6. Reuse plan - existing utility/helper used, or the reusable helper that should be promoted instead of another one-off clone.

Step 1: Classify the input

Do not normalize or matrix-convert blindly. Identify the source first:

Keep negative and out-of-gamut values long enough to report stats. Clip only at the explicit output boundary.

Step 2: Convert to BT.2020 D65 linear RGB

Use stable, explicit matrices from existing analysis scripts when available. Existing references include:

• tools/analysis/build_hdr_png_cicp.py for AP0/D60 EXR to BT.2020 PQ PNG and cICP read/write helpers.
• tools/analysis/export_energy_bw_hdr_png.py and tools/analysis/export_energy_comparison_hdr.py for scalar/energy-map HDR PNG patterns.
• tools/analysis/synthetic_neutwo_energy_reapply_bt2020.py for synthetic BT.2020 PQ outputs.

If the same helper code is needed in a new durable script, prefer extracting or reusing a shared utility instead of pasting another copy into a scratch script.

Step 3: Map scene values to absolute nits

Use explicit luminance mapping:

nits = max(bt2020_linear, 0) * diffuse_white_nits

Common RenoDX analysis defaults:

Do not silently scale image max to 1.0. If normalization is intentionally part of the experiment, name it and record it in stats.

Step 4: Encode PQ/ST 2084

Use the ST 2084 OETF constants consistently:

m1 = 2610 / 16384
m2 = 2523 / 32
c1 = 3424 / 4096
c2 = 2413 / 128
c3 = 2392 / 128
V = ((c1 + c2 * (L / 10000)^m1) / (1 + c3 * (L / 10000)^m1))^m2

Clamp nits to [0, 10000] before encoding, then quantize with rounding to uint16:

png16 = round(saturate(pq) * 65535)

Step 5: Write the PNG correctly

For a dependency-light path, write RGB16 PNG bytes directly:

• PNG signature: 89 50 4E 47 0D 0A 1A 0A.
• IHDR: bit depth 16, color type 2 (truecolor RGB), no interlace.
• Store 16-bit samples big-endian.
• Use filter type 0 per row unless testing filters/compression.
• Insert cICP before IDAT with bytes 09 10 00 01.
• Write IDAT and IEND with correct CRCs.

BT.2020 PQ PNG template contains a small reusable Python implementation for ST 2084 encoding and RGB16 PNG cICP writing. Prefer adapting it over cloning another scratch writer.

Avoid Pillow unless the current environment is known to preserve 16-bit RGB exactly. Many easy Pillow paths downcast, reorder, or treat RGB16 inconsistently.

Step 6: Validate every generated PNG

At minimum, report:

Useful stats keys:

pixels_total
source_min/source_max
bt2020_min/bt2020_max
negative_bt2020_channels_clipped
over_10000_nits_channels_clipped
diffuse_white_nits
peak_linear
cicp_cp_tc_mc_range
icc_present
icc_cicp_cp_tc_mc_range

Common mistakes to avoid

• Do not write an 8-bit PNG for HDR precision tests unless testing an 8-bit preview path.
• Do not use sRGB or gamma 2.2 encoding for HDR PNG pixels.
• Do not tag SDR/gamma pixels as PQ/BT.2020.
• Do not PQ-encode data that is already PQ.
• Do not use 9/16/6 for native RGB PNG samples.
• Do not assume a native PNG cICP chunk will survive Discord's WebP preview path.
• Do not assume a Discord HDR preview means the preview kept more than 8-bit precision.
• Do not attach a primary HDR ICC to AVIF when Windows preview compatibility matters.
• Do not omit cICP and assume a viewer will infer HDR.
• Do not hide clipping by normalizing the image max.
• Do not add a new one-off script when the task is just EXR/linear/scalar to BT.2020 PQ PNG.

Promotion rule

If an experiment repeats any two of these pieces, make or reuse a common utility instead of a scratch clone:

• ST 2084 PQ encode/decode.
• RGB16 PNG byte writing.
• PNG cICP insertion/read-back.
• HDR ICC cicpTag insertion/read-back.
• AP0/AP1/BT.709 to BT.2020 conversion.
• clip/stat CSV generation.