Skip to content

Add equirectangular projection for WebP output and refactor compute shaders into chunks#247

Merged
slimbuck merged 6 commits into
playcanvas:mainfrom
slimbuck:equi-dev
May 26, 2026
Merged

Add equirectangular projection for WebP output and refactor compute shaders into chunks#247
slimbuck merged 6 commits into
playcanvas:mainfrom
slimbuck:equi-dev

Conversation

@slimbuck
Copy link
Copy Markdown
Member

Summary

Adds a native 360°×180° equirectangular projection mode to the WebP image output (--projection equirect) so users can export a panorama of a Gaussian-splat scene from a single camera position, and reorganizes the GPU rasterizer's eight compute shaders out of one ~1600-LOC file into per-shader source files plus 14 small WGSL chunks under src/lib/gpu/shaders/, using PlayCanvas's cincludes/cdefines preprocessor (see engine/src/platform/graphics/shader.js) so chunk files are pure WGSL and projection/SH-band variants flip via #ifdef PROJECTION_EQUIRECT / #ifdef SH_BAND_{1,2,3}.

The equirect path is implemented inside the existing tile-binning GPU rasterizer rather than as a cube-face stitch: the project shader swaps the perspective screen mapping and EWA Jacobian for spherical (atan2/asin) equivalents, the CPU depth sort uses radial distance, the tile-bin emit-pairs shader wraps the X tile range across the ±π longitude seam (modular tile indices), and the rasterize-binned shader wraps per-pixel dx into [-W/2, W/2] so seam-straddling splats pull their footprint from the nearer copy. A POLE_EPS clamp on rxz keeps the latitude Jacobian bounded near zenith/nadir. The structure follows the PlayCanvas engine's own fisheye-projection compute path in compute-gsplat-common.js as a precedent.

The chunk refactor consolidates the JS↔WGSL uniform layout into a single co-located uniforms.ts (struct chunk + matching UniformFormat[]), moves scalar tunables from render/config.ts (TILE_SIZE, SIGMA_CUTOFF, JACOBIAN_LIMIT_FACTOR, etc.) into a shared WGSL const chunk so the shader files contain no ${...} template interpolation, and extracts the projection screen-mapping, Jacobian, tile-AABB, SH-band-evaluation, quaternion-to-rotation, and 3D-covariance blocks into named chunks. gpu-splat-rasterizer.ts shrinks from ~1600 to ~800 LOC (orchestrator class only).

A small follow-up replaces magic literals in gpu-dilation.ts (0u/1u/2u/0x9E3779B9u) with named BLOCK_EMPTY/BLOCK_SOLID/BLOCK_MIXED/FIBONACCI_HASH WGSL consts for readability in the extract and compact shaders.

Test plan

  • npm run lint && npm run build && npm test — full suite (490 tests) passes.
  • Render-golden tests byte-identical: node --import tsx --test test/render-golden.test.mjs produces byte-exact matches for both committed fixtures (tiny.webp 320×240 and mid.webp 640×360), confirming the pinhole path is unchanged.
  • Equirect end-to-end: splat-transform input.ply --projection equirect --camera 0,1,0 --look-at 0,1,1 out.webp (default 2048×1024), then open in a panorama viewer (e.g. Pannellum) and verify the horizon sits at mid-image, the --look-at direction maps to image-x = W/2, and the left/right edges of the image are continuous (no visible seam).
  • Equirect input validation: --fov with --projection equirect errors out; non-2:1 --resolution errors out; default resolution is 2048×1024 when neither width nor height is supplied.
  • GPU dilation byte-identical: splat-transform input.ply --voxel-params 0.5,0.1 --voxel-external-fill 1.6 --seed-pos 100,100,100 out.voxel.json produces a byte-identical .voxel.json + .voxel.bin pair to a pre-PR run on main.

@slimbuck slimbuck requested a review from Copilot May 26, 2026 11:04
@slimbuck slimbuck self-assigned this May 26, 2026
@slimbuck slimbuck added the enhancement New feature or request label May 26, 2026
@slimbuck slimbuck requested review from Copilot and removed request for Copilot May 26, 2026 11:26
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

@slimbuck slimbuck marked this pull request as ready for review May 26, 2026 13:10
@slimbuck slimbuck requested a review from a team May 26, 2026 13:10
@slimbuck slimbuck merged commit b62a588 into playcanvas:main May 26, 2026
3 checks passed
@slimbuck slimbuck deleted the equi-dev branch May 26, 2026 13:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants