pcbjam/tests/3d-regression/README.md

3D Renderer Regression Suite (OpenGL → WebGL port)

Screenshot-baseline TDD harness for porting KiCad's 3D viewer OpenGL renderer (RENDER_3D_OPENGL, pure GL 1.x fixed-function) to WebGL2 — the same approach used for the 2D GAL port (tests/gal-regression/), but compared with the CI pixelmatch engine instead of ImageMagick.

Shared C++ scenarios call real KiCad 3D-viewer code (draw helpers, display lists, materials, camera, stencil hole-subtraction, VBO models…) and are compiled two ways:

• native/ — macOS app on real desktop OpenGL (2.1 compatibility context via the vendored glad loader). Renders each scenario into a fixed 800×600 offscreen FBO (GL_RGBA8 + GL_DEPTH24_STENCIL8, the EDA_3D_CANVAS::RenderToFrameBuffer recipe) → golden baselines.
• wasm/ — the same scenario TUs compiled with em++, linked against the wasm/gl1 GL1→WebGL2 emulation layer (the port itself — see wasm/gl1/README.md). Since the port landed, all 47 scenarios render under the parity floor with zero per-scenario overrides.

Directory layout

scenarios/        shared scenario sources (native + wasm) — the registry in
                  scene3d_test_scenarios.cpp is the single source of truth
native/           golden generator (CMake; homebrew wxWidgets + OpenGL.framework)
wasm/             WebGL harness (planned)
baseline/         committed native goldens: 3d-<name>.png
baseline-webgl/   committed browser renders (port era, CI-promoted)
output/           run output + diffs (gitignored)
manifest.json     {width,height,scenarios[]} written by the native harness;
                  committed — the anti-drift anchor for specs and orchestrator
floors.json       pixelmatch verdict floors per comparison level

Running

./scripts/test-3d-regression.sh            # build + render + gate (native; webgl when present)
./scripts/test-3d-regression.sh native     # native phase only
./scripts/test-3d-regression.sh compare    # comparisons only
./scripts/test-3d-regression.sh promote    # promote output/native -> baseline/ (byte-diff guarded)

Logs land in logs/test-3d-regression/ (build logs in tests/logs/).

Comparison levels

Engine: tests/tools/screenshots/compare-dirs.ts (pixelmatch {threshold: 0.1, includeAA: false} — AA edge pixels ignored), floors from floors.json. Diff triptychs/heatmaps + report.json land in output/diff/<level>/.

Level	Pair	Floor (changedRatio)	Role
native-self	baseline/ vs output/native/	0.001 (measured noise: exactly 0 on Apple M5)	gating regression check on the dev Mac
webgl-vs-native	baseline/ vs output/webgl/	0.02, report-only	the TDD port-progress meter (npm run 3d:check:parity)
webgl-self	baseline-webgl/ vs output/webgl/	0.005	browser regression anchor (once the port renders)

npm scripts (from tests/): 3d:check, 3d:check:webgl, 3d:check:parity, 3d:compare (generic dir pair), 3d:test:webgl.

Updating baselines

Baselines are generated on the dev Mac (CI has no native GL — same model as the GAL suite). After an intentional render change:

1. ./scripts/test-3d-regression.sh native (fails with triptychs in output/diff/native-self/ — eyeball them),
2. ./scripts/test-3d-regression.sh promote (byte-diff-guarded copy, zero churn) and commit baseline/ + manifest.json.

The orchestrator cmps the freshly-written manifest against the committed one every run, so a scenario registry change can't silently drift past the baselines. Scenario names are append-only — never rename or renumber (they are the PNG names and the WebGL test IDs).

Port status (was: TDD red state)

The suite drove the port TDD-style: the harness started against no-op FFP stubs (~100% changed everywhere), and the wasm/gl1 emulation layer ground the parity report down milestone by milestone (substrate → lighting → display lists/arrays → GLU quadrics). Current state: 47/47 under the 0.02 parity floor, no floors.json overrides needed.

Two caveats the parity floor cannot see (verified by eyeballing renders):

• Small-geometry scenarios (the GLU arrows, the spheres gizmo, sparse grids) fit under the floor even when absent — a regression there needs the triptych/eyeball check, not just the report.
• glLineWidth > 1 is clamped to 1 by browsers (gizmo axes, native width 2–4 lines render thinner); the affected coverage is small enough to stay under the floor.

Scenario tiers (47 scenarios)

• Tier 1 (30) — standalone TUs: opengl_utils (arrows/segments/bbox/half-cylinder), ogl_utils (background gradient, materials, textures), TRIANGLE_DISPLAY_LIST/OPENGL_RENDER_LIST (display lists, seg-ends alpha-test texture, DrawCulled stencil subtraction, z-transform, transparency), MODEL_3D (VBO/IBO, material modes, bboxes), SPHERES_GIZMO, camera (perspective/ortho/preset views, isolated lights).
• Tier 2 (14) — RENDER_3D_OPENGL private generators (generateCylinder/Disk/Dimple/InvCone, all five addObjectTriangles overloads, appendPostMachiningGeometry, via composite, the four grid densities, setupMaterials/setLayerMaterial/setArrowMaterial, createBoard) via the rob-template accessor (native/render3d_test_accessor.*) over the synthetic BOARD_ADAPTER (native/board_adapter_test_impl.cpp — its InitSettings is the test-data seam).
• Tier 3 (3) — full reload() + Redraw() composites over the synthetic mini-board: redraw-empty, redraw-mini-board (copper/silk/mask/stencil holes), redraw-mini-board-navigator (grid + gizmo — the port-complete gate).

Known upstream bug (documented by 3d-post-machining.png)

appendPostMachiningGeometry's COUNTERSINK path adds middle-contour quads with AddQuad but never calls AddNormal, so the normals array ends up half the vertex count and OPENGL_RENDER_LIST::generate_middle_triangles rejects the whole middle list — a countersunk hole silently erases the walls of any geometry batched into the same TRIANGLE_DISPLAY_LIST (the real viewer has the same defect). The scenario keeps counterbore and countersink in separate lists so the counterbore renders correctly while the countersink half records the buggy (empty) upstream output.

Lighting semantics worth knowing: init_lights() runs once at context init under the identity modelview, so the two directional lights are anchored in eye space (they follow the camera) — the harness replicates that (SCENE3D_CTX::InitOnce), and only the headlight is repositioned per frame like Redraw() does. Also avoid toggling GL_LIGHTx between draws inside one frame: the Apple GL driver drops the first draw after a mid-frame toggle (the real renderer never does this; the isolated-light scenarios use one light per frame instead).