Skip to content

Fix SPZ v3 quaternion parsing#185

Open
azadbal wants to merge 2 commits intoplaycanvas:mainfrom
azadbal:codex/fix-spz-v3-quaternion
Open

Fix SPZ v3 quaternion parsing#185
azadbal wants to merge 2 commits intoplaycanvas:mainfrom
azadbal:codex/fix-spz-v3-quaternion

Conversation

@azadbal
Copy link

@azadbal azadbal commented Mar 20, 2026

Summary

Fix SPZ v3 import parsing by handling the v3 rotation payload correctly and adding regression coverage.

What changed

  • read 4-byte packed rotations for SPZ v3 instead of treating them like the 3-byte v2 payload
  • decode v3 smallest-three quaternions directly from the packed uint32 value
  • keep the existing v2 quaternion path intact
  • add clearer validation around unsupported SH degrees / malformed payload sizes
  • add an SPZ v3 regression test that verifies quaternion decoding against known expected values
  • add a prepare script so git-based installs build dist/, which lets the stacked supersplat follow-up consume this branch before an npm release exists

Root cause

The current v3 reader had three issues:

  • it used the v2 rotation payload size for v3
  • it read packed v3 quaternions at the wrong byte stride
  • it then treated decoded v3 quaternion values like raw bytes and normalized them again

That combination made v3 rotation data decode incorrectly.

Validation

  • npm run build
  • npm run lint
  • SPZ v2 import test still passes
  • new SPZ v3 regression test passes
  • local supersplat validation also succeeds when pointed at this patched package and loading a real v3 file

Follow-up

There is a stacked supersplat PR that pins this branch commit temporarily so SPZ v3 support can be reviewed end-to-end before the npm package release. The expectation is to merge this PR first, then replace that temporary git pin with the published package version before merging the consumer PR.

Notes

FYI, I did not include SPZ v4 support here (which we're planning on releasing soon). This change is scoped to making the existing v3 support to work proprely.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant