Skip to content

ziviDomeLive 1.5 Calibration Tool and Compatibility Baseline

This qualification note records the baseline lock for the final 1.x line. It is not a claim that every listed behavior is fully correct. Known defects are kept visible so they can be fixed in the baseline-correctness PR without drifting the visual contract by accident.

This remains the historical 1.4 baseline record. The consolidated 1.5 release status is tracked in 1.5-release-readiness.md.

Confirmed Local Baseline

  • Branch at audit time: main
  • HEAD at implementation start: d54bc3e22f0e14d7c5d348e7252869cfb9ef534b
  • Declared Gradle version: 1.4.0
  • Java toolchain: 17
  • Processing core: 4.5.6
  • Devolay: io.github.vicvalentim:devolay:2.2.0-vic.1
  • JUnit: 5.10.0
  • Latest local release tag: v1.4.0
  • Commits after v1.4.0: 17

Automated Lock

The first compatibility tests cover:

  • public facade name, constructor, key lifecycle methods and accessors;
  • enum order for ViewType, InitState, output types and logging modes;
  • Scene.sceneRender(PGraphicsOpenGL) and default lifecycle/event methods;
  • spherical preview resolution policy: min(1024, max(256, min(windowWidth, windowHeight)));
  • Standard output aspect buckets for 16:9, 16:10, 4:3 and 1:1;
  • independent output routing defaults and per-output view selection.

Run:

./gradlew clean qualificationTests

Optional release artifact check:

./gradlew buildReleaseArtifacts

Visual Harness

examples/CalibrationTool/ contains two complementary scenes for GPU, projection, focus, color, and output qualification. Scene 1 maps six GLSL 4.10 targets and their annotations onto explicit local coordinates of a closed cube, then leaves pitch, yaw, and roll to the shared spherical capture matrix. Scene 2 selects among Paul Bourke's original, unmodified 2400 x 1200, 4096 x 2048, 4800 x 2400, and 8192 x 4096 v14 equirectangular patterns according to the active output bucket, or the nearest window bucket when outputs are disabled. It maps the selected source onto a complete 1800-unit sphere centered at (0, 0, 0), with its north pole at +Z. The sketch deliberately does not call ziviDome.draw() from its draw() function because the library registers its own Processing draw hook.

This tool establishes the 1.5 visual reference after qualification. It is more diagnostic than the historical 1.4 scene and is not expected to match that older scene pixel for pixel. The Bourke asset's authorship, integrity hash, and redistribution conditions are recorded beside the example in THIRD_PARTY.md.

Manual controls:

  • Left/Right arrows: switch between the cube and Bourke scenes
  • 1: fisheye domemaster
  • 2: equirectangular
  • 3: cubemap skybox layout
  • 4: Standard
  • [ / ]: decrease/increase Size%
  • - / =: decrease/increase FOV
  • p: step pitch
  • y: step yaw
  • r: step roll
  • f: toggle floating domemaster preview
  • 0: restore the canonical calibration state
  • Scene 2 Space: toggle one 360-degree revolution per 60 seconds
  • Scene 2 t: toggle the time-quantized 30 fps/1800-frame or 60 fps/3600-frame rotation profile without changing Processing's global frame rate
  • Scene 2 , / .: rotate by one degree and pause
  • Scene 2 c: restore source orientation and pause

Visual Qualification Matrix

Behavior What To Check Evidence
Face identity face indices and +X, -X, +Y, -Y, +Z, -Z labels remain distinguishable GPU capture
Alignment 24 x 24 grids, safe-area frames, circles, spokes, and crosshairs remain centered and undistorted GPU capture
Orientation UP, R, and corner markers expose rotation or mirroring GPU capture
Face mapping each procedural target and its composited annotation layer remain UV-mapped to one quad and follow continuous pitch/yaw/roll without screen-space drift GPU capture
Focus lines 1, 2, 4, and 8 pixel vertical/horizontal pairs remain separately resolvable GPU/output capture
Points and stars 1, 2, 3, and 4 pixel points and starbursts reveal focus, blooming, and resampling GPU/output capture
Color continuous GLSL RGB/CMY ramps and pure RGB/CMY/W/K bars remain distinct and correctly ordered GPU/output capture
Luminance continuous grayscale, nine steps, and near-black/near-white patches reveal banding or clipping GPU/output capture
Cubemap layout face order and edge continuity match the qualified baseline GPU capture
Bourke 360-degree map north and south poles reach +Z and -Z; longitude closes without a texture seam GPU capture
Slow rotation one revolution takes 60 seconds without cadence discontinuity or shimmer beyond expected resampling GPU/output capture
Pitch/yaw/roll 90 degree steps rotate the spherical domain consistently GPU capture
FOV 0..360, default 210, no unexpected clipping at common values GPU capture
Size% domemaster scales around center and remains useful for calibration GPU capture
Standard Standard view remains independent from spherical cubemap capture GPU capture
Floating preview domemaster thumbnail can coexist with Standard main view GPU capture
Outputs NDI, Syphon and Spout publish the selected view independently Hardware

Baseline Defects Recorded For PR 2

At the locked d54bc3e baseline:

  • examples and docs called ziviDome.draw() manually;
  • examples/SphereParticle/Scene1.pde owned beginDraw() / endDraw();
  • ControlManager could toggle outputs from both widget callbacks and handleEvent();
  • recreating FisheyeDomemaster reset Size% to 100;
  • pause() destroyed outputs without restoring publication on resume();
  • NDI metadata defaulted to 150/1 and INTERLEAVED;
  • renderer initialization failures could still advance or stall the lifecycle;
  • dependency bootstrap used mutable assets without checksum validation.

The fix/1.5-baseline-correctness branch addresses each item above. NDI now defaults to the configured Processing target frame rate and marks complete frames as progressive. The local Java CI workflow already contains push, pull-request and manual triggers; enabling a workflow disabled in GitHub settings remains an external maintainer action and is not changed here.

Out Of Scope For This Lock

  • No RenderMode API is introduced here.
  • No renderer backend is replaced.
  • No GL_TEXTURE_CUBE_MAP, samplerCube, PBO, OpenGL fences or 2.0 placeholder classes are introduced.
  • No golden images are fabricated in this repository.