Question about position encoding

[javagl]

This is going to be embarrassing. Maybe for me, but that's a risk that I'm willing to take.

I encountered some issues with SPZ-encoded data versus the original PLY data. The following is an archive that contains the original data as ASCII- and BinaryLE PLY data, as well as in SPZ format, once created with my own tools, and once created with the SPZ library:

spzPositions-2025-08-23.zip

It's not tremendously complex. In fact, this is the ASCII version of the PLY data:

ply
format ascii 1.0
element vertex 8
property float x
property float y
property float z
property float f_dc_0
property float f_dc_1
property float f_dc_2
property float opacity
property float scale_0
property float scale_1
property float scale_2
property float rot_0
property float rot_1
property float rot_2
property float rot_3
end_header
-2050.0 -0.0 -0.0 1.7724539 1.7724539 1.7724539 20.0 1.0 1.0 1.0 1.0 0.0 -0.0 -0.0
-2000.0 -0.0 -0.0 1.7724539 1.7724539 1.7724539 20.0 1.0 1.0 1.0 1.0 0.0 -0.0 -0.0
-2050.0 -50.0 -0.0 1.7724539 1.7724539 1.7724539 20.0 1.0 1.0 1.0 1.0 0.0 -0.0 -0.0
-2000.0 -50.0 -0.0 1.7724539 1.7724539 1.7724539 20.0 1.0 1.0 1.0 1.0 0.0 -0.0 -0.0
-2050.0 -0.0 -50.0 1.7724539 1.7724539 1.7724539 20.0 1.0 1.0 1.0 1.0 0.0 -0.0 -0.0
-2000.0 -0.0 -50.0 1.7724539 1.7724539 1.7724539 20.0 1.0 1.0 1.0 1.0 0.0 -0.0 -0.0
-2050.0 -50.0 -50.0 1.7724539 1.7724539 1.7724539 20.0 1.0 1.0 1.0 1.0 0.0 -0.0 -0.0
-2000.0 -50.0 -50.0 1.7724539 1.7724539 1.7724539 20.0 1.0 1.0 1.0 1.0 0.0 -0.0 -0.0

Yeah, it's a "unit cube" (rather one with an edge length of 50), somewhere at x=-2000.

Dragging-and-dropping the BinaryLE-PLY file into the BabylonJS sandbox shows the expected result:

When converting this data into SPZ, using the SPZ library, and dragging-and-dropping the resulting file into BabylonJS, then this is the result:

That doesn't look right.

I've inserted some debug statements after this line in packGaussians

    // XXX TEST
    {
      // Decode 24-bit fixed point coordinates
      float scaled = 1.0 / (1 << packed.fractionalBits);
      int32_t fixed32d = packed.positions[i * 3 + 0];
      fixed32d |= packed.positions[i * 3 + 1] << 8;
      fixed32d |= packed.positions[i * 3 + 2] << 16;
      fixed32d |= (fixed32d & 0x800000) ? 0xff000000 : 0;  // sign extension
      float resultPosition = static_cast<float>(fixed32d) * scaled;
      std::cout << "Position " << i << " was " << g.positions[i] << " fixed32 is " << fixed32 << " converted to " << (int)packed.positions[i * 3 + 0] << " " << (int)packed.positions[i * 3 + 1] << " " << (int)packed.positions[i * 3 + 2] << " back to " << fixed32d << " sign check " << (fixed32d & 0x800000) << " back to result " << resultPosition << std::endl;
   }

This is doing what is done during the decoding, to print what the actual encoded information will become.

The output of this debug part is

Position 0 was -2050 fixed32 is -8396800 converted to 0 224 127 back to 8380416 sign check 0 back to result 2046
Position 1 was -0 fixed32 is 0 converted to 0 0 0 back to 0 sign check 0 back to result 0
Position 2 was -0 fixed32 is 0 converted to 0 0 0 back to 0 sign check 0 back to result 0
Position 3 was -2000 fixed32 is -8192000 converted to 0 0 131 back to -8192000 sign check 8388608 back to result -2000
Position 4 was -0 fixed32 is 0 converted to 0 0 0 back to 0 sign check 0 back to result 0
Position 5 was -0 fixed32 is 0 converted to 0 0 0 back to 0 sign check 0 back to result 0
Position 6 was -2050 fixed32 is -8396800 converted to 0 224 127 back to 8380416 sign check 0 back to result 2046
Position 7 was -50 fixed32 is -204800 converted to 0 224 252 back to -204800 sign check 8388608 back to result -50
Position 8 was -0 fixed32 is 0 converted to 0 0 0 back to 0 sign check 0 back to result 0
Position 9 was -2000 fixed32 is -8192000 converted to 0 0 131 back to -8192000 sign check 8388608 back to result -2000
Position 10 was -50 fixed32 is -204800 converted to 0 224 252 back to -204800 sign check 8388608 back to result -50
Position 11 was -0 fixed32 is 0 converted to 0 0 0 back to 0 sign check 0 back to result 0
Position 12 was -2050 fixed32 is -8396800 converted to 0 224 127 back to 8380416 sign check 0 back to result 2046
Position 13 was -0 fixed32 is 0 converted to 0 0 0 back to 0 sign check 0 back to result 0
Position 14 was -50 fixed32 is -204800 converted to 0 224 252 back to -204800 sign check 8388608 back to result -50
Position 15 was -2000 fixed32 is -8192000 converted to 0 0 131 back to -8192000 sign check 8388608 back to result -2000
Position 16 was -0 fixed32 is 0 converted to 0 0 0 back to 0 sign check 0 back to result 0
Position 17 was -50 fixed32 is -204800 converted to 0 224 252 back to -204800 sign check 8388608 back to result -50
Position 18 was -2050 fixed32 is -8396800 converted to 0 224 127 back to 8380416 sign check 0 back to result 2046
Position 19 was -50 fixed32 is -204800 converted to 0 224 252 back to -204800 sign check 8388608 back to result -50
Position 20 was -50 fixed32 is -204800 converted to 0 224 252 back to -204800 sign check 8388608 back to result -50
Position 21 was -2000 fixed32 is -8192000 converted to 0 0 131 back to -8192000 sign check 8388608 back to result -2000
Position 22 was -50 fixed32 is -204800 converted to 0 224 252 back to -204800 sign check 8388608 back to result -50
Position 23 was -50 fixed32 is -204800 converted to 0 224 252 back to -204800 sign check 8388608 back to result -50

The negative x-coordinate (for the first splat) is encoded in a way that when decoding it, the coordinate becomes positive. Given that this seems like a pretty fundamental issue, I wanted to confirm that I didn't do something embarassingly wrong here. I'm prepared for a "🤦‍♂️", but right now, I'm pretty stumped.

[javagl]

OK, after a lunch break and some further debugging, I realized that 13+12>24.

This is caused by the fractionalBits being 12 by default. Values smaller than -2048 or larger than 2047 just cannot be encoded correctly when this is supposed to be squeezed into 24 bits. The line in the encoding just drops the sign bits for values outside of this range, and this means that the attempted sign extension in the decoding cannot reconstruct the original value.

The limit cases, dissected:

value          : -2048.0
fixed32        : -8388608   hex: ff800000 bin: 11111111100000000000000000000000
byte 0         : 0          hex: 00 bin: 00000000
byte 1         : 0          hex: 00 bin: 00000000
byte 2         : 128        hex: 80 bin: 10000000
decoded fixed32: -8388608   hex: ff800000 bin: 11111111100000000000000000000000
result         : -2048.0

value          : -2049.0
fixed32        : -8392704   hex: ff7ff000 bin: 11111111011111111111000000000000
byte 0         : 0          hex: 00 bin: 00000000
byte 1         : 240        hex: f0 bin: 11110000
byte 2         : 127        hex: 7f bin: 01111111
decoded fixed32: 8384512    hex: 007ff000 bin: 00000000011111111111000000000000
result         : 2047.0

value          : 2047.0
fixed32        : 8384512    hex: 007ff000 bin: 00000000011111111111000000000000
byte 0         : 0          hex: 00 bin: 00000000
byte 1         : 240        hex: f0 bin: 11110000
byte 2         : 127        hex: 7f bin: 01111111
decoded fixed32: 8384512    hex: 007ff000 bin: 00000000011111111111000000000000
result         : 2047.0

value          : 2048.0
fixed32        : 8388608    hex: 00800000 bin: 00000000100000000000000000000000
byte 0         : 0          hex: 00 bin: 00000000
byte 1         : 0          hex: 00 bin: 00000000
byte 2         : 128        hex: 80 bin: 10000000
decoded fixed32: -8388608   hex: ff800000 bin: 11111111100000000000000000000000
result         : -2048.0

Now... I'm not sure what do do with that. It should at least be pointed out prominently in the README.md. (Also see #42 )

[javagl]

I considered to close this one, after summarizing the main point at #42 (comment). But I think that it could be worthwhile to keep it open, because in terms of usability (in the sense of using the SPZ library in an actual application) and the principle of least astonishment, the current behavior is still questionable. The function to encode the data simply assumes that the default value for fractionalBits makes sense for the given data. It does not even report an error/warning when this assumption is wrong. It just generates wrong results. The user has no way to reasonably anticipate that or to determine the right fractionalBits beforehand. The lack of documentation comes on top of that, so there's no chance to blame that on the user.

So one could at least consider a fix in the SPZ library itself. A ... "less astonishing"... solution would be to let the encoding function examine the input data, compute the bounding box of that, and choose the fractionalBits accordingly, automatically.

[ProjitB]

Thanks for pointing this out! Would you be willing to submit a PR with changes to the readme that would help this be "less astonishing"?

[javagl]

I'd see this as part of #42 . I could probably allocate some time to create a small PR to point this out, but ... are you aware of any other efforts for specifying more details here?