@speridlabs/visus 0.1.0 → 0.2.0

package/dist/main.umd.js

@@ -0,0 +1,286 @@
+(function(C,_){typeof exports=="object"&&typeof module<"u"?_(exports,require("three")):typeof define=="function"&&define.amd?define(["exports","three"],_):(C=typeof globalThis<"u"?globalThis:C||self,_(C.Visus={},C.THREE))})(this,function(C,_){"use strict";var Mt=Object.defineProperty;var zt=(C,_,j)=>_ in C?Mt(C,_,{enumerable:!0,configurable:!0,writable:!0,value:j}):C[_]=j;var f=(C,_,j)=>zt(C,typeof _!="symbol"?_+"":_,j);if(typeof THREE>"u")throw new Error(`Visus UMD build requires Three.js as a global "THREE".
+Please include <script src="https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.min.js"><\/script> before loading visus/main.umd.js`);function j(B){const t=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(B){for(const r in B)if(r!=="default"){const e=Object.getOwnPropertyDescriptor(B,r);Object.defineProperty(t,r,e.get?e:{enumerable:!0,get:()=>B[r]})}}return t.default=B,Object.freeze(t)}const o=j(_);class X{constructor(){f(this,"min",new o.Vector3(1/0,1/0,1/0));f(this,"max",new o.Vector3(-1/0,-1/0,-1/0));f(this,"center",new o.Vector3);f(this,"halfExtents",new o.Vector3)}reset(){this.min.set(1/0,1/0,1/0),this.max.set(-1/0,-1/0,-1/0),this.center.set(0,0,0),this.halfExtents.set(0,0,0)}expandByPoint(t){this.min.x=Math.min(this.min.x,t.x),this.min.y=Math.min(this.min.y,t.y),this.min.z=Math.min(this.min.z,t.z),this.max.x=Math.max(this.max.x,t.x),this.max.y=Math.max(this.max.y,t.y),this.max.z=Math.max(this.max.z,t.z),this.updateDerived()}expandByBox(t){this.min.x=Math.min(this.min.x,t.min.x),this.min.y=Math.min(this.min.y,t.min.y),this.min.z=Math.min(this.min.z,t.min.z),this.max.x=Math.max(this.max.x,t.max.x),this.max.y=Math.max(this.max.y,t.max.y),this.max.z=Math.max(this.max.z,t.max.z),this.updateDerived()}updateDerived(){this.center.addVectors(this.min,this.max).multiplyScalar(.5),this.halfExtents.subVectors(this.max,this.min).multiplyScalar(.5)}containsPoint(t){return t.x>=this.min.x&&t.x<=this.max.x&&t.y>=this.min.y&&t.y<=this.max.y&&t.z>=this.min.z&&t.z<=this.max.z}toBox3(){return new o.Box3().set(this.min,this.max)}clone(){const t=new X;return t.min.copy(this.min),t.max.copy(this.max),t.center.copy(this.center),t.halfExtents.copy(this.halfExtents),t}}class it{constructor(t=0){f(this,"numSplats",0);f(this,"positions");f(this,"rotations");f(this,"scales");f(this,"colors");f(this,"opacities");f(this,"centers");f(this,"boundingBox",new X);this.numSplats=t,this.allocateBuffers(t)}allocateBuffers(t){this.positions=new Float32Array(t*3),this.rotations=new Float32Array(t*4),this.scales=new Float32Array(t*3),this.colors=new Float32Array(t*3),this.opacities=new Float32Array(t),this.centers=new Float32Array(t*3)}setSplat(t,r,e,n,s,i){if(t>=this.numSplats)throw new Error(`Splat index out of bounds: ${t} >= ${this.numSplats}`);const a=t*3,c=t*4,h=t*3,v=t*3;this.positions[a]=r.x,this.positions[a+1]=r.y,this.positions[a+2]=r.z,this.rotations[c]=e.x,this.rotations[c+1]=e.y,this.rotations[c+2]=e.z,this.rotations[c+3]=e.w,this.scales[h]=n.x,this.scales[h+1]=n.y,this.scales[h+2]=n.z,this.colors[v]=s.r,this.colors[v+1]=s.g,this.colors[v+2]=s.b,this.opacities[t]=i,this.centers[a]=r.x,this.centers[a+1]=r.y,this.centers[a+2]=r.z}getSplat(t){if(t>=this.numSplats)throw new Error(`Splat index out of bounds: ${t} >= ${this.numSplats}`);const r=t*3,e=t*4,n=t*3,s=t*3;return{position:new o.Vector3(this.positions[r],this.positions[r+1],this.positions[r+2]),rotation:new o.Quaternion(this.rotations[e],this.rotations[e+1],this.rotations[e+2],this.rotations[e+3]),scale:new o.Vector3(Math.exp(this.scales[n]),Math.exp(this.scales[n+1]),Math.exp(this.scales[n+2])),color:new o.Color(this.colors[s],this.colors[s+1],this.colors[s+2]),opacity:this.opacities[t]}}calculateBoundingBox(){this.boundingBox.reset();const t=new o.Vector3;for(let r=0;r<this.numSplats;r++){const e=r*3;t.set(this.positions[e],this.positions[e+1],this.positions[e+2]),this.boundingBox.expandByPoint(t)}return this.boundingBox}createDebugGeometry(){const t=new o.BufferGeometry;t.setAttribute("position",new o.BufferAttribute(this.positions,3));const r=new Float32Array(this.numSplats*3),e=new o.Quaternion,n=new o.Euler;for(let s=0;s<this.numSplats;s++){const i=s*4,a=s*3;e.set(this.rotations[i],this.rotations[i+1],this.rotations[i+2],this.rotations[i+3]),n.setFromQuaternion(e),r[a]=n.x,r[a+1]=n.y,r[a+2]=n.z}return t.setAttribute("rotation",new o.BufferAttribute(r,3)),t.setAttribute("scale",new o.BufferAttribute(this.scales,3)),t.setAttribute("color",new o.BufferAttribute(this.colors,3)),t.setAttribute("opacity",new o.BufferAttribute(this.opacities,1)),t}}class at extends o.EventDispatcher{constructor(){super();f(this,"worker");f(this,"centers",null);f(this,"orderTexture",null);f(this,"chunks",null);f(this,"lastCameraPosition",new o.Vector3);f(this,"lastCameraDirection",new o.Vector3);const r=this.createWorkerCode(),e=new Blob([r],{type:"application/javascript"});this.worker=new Worker(URL.createObjectURL(e)),this.worker.onmessage=this.onWorkerMessage.bind(this)}onWorkerMessage(r){if(!this.orderTexture||!this.orderTexture.image)return console.error("SplatSorter: Order texture not initialized!");const{order:e,count:n}=r.data,s=this.orderTexture.image.data;if(!(s instanceof Uint32Array))return console.error("SplatSorter: Order texture data is not a Uint32Array!");s.set(new Uint32Array(e)),this.orderTexture.needsUpdate=!0;const i=s.buffer.slice(0),a={order:i};this.worker.postMessage(a,[i]),this.dispatchEvent({type:"updated",count:n})}init(r,e,n){if(!r||!(r.image.data instanceof Uint32Array))throw new Error("SplatSorter: Invalid orderTexture provided. Must be DataTexture with Uint32Array data.");if(!e||e.length%3!==0)throw new Error("SplatSorter: Invalid centers array provided. Length must be multiple of 3.");if(r.image.data.length<e.length/3)throw new Error("SplatSorter: orderTexture data buffer is smaller than the number of splats.");const s=e.length/3;this.orderTexture=r,this.centers=e.slice();const i=this.orderTexture.image.data;for(let g=0;g<s;g++)i[g]=g;this.orderTexture.needsUpdate=!0;const a=i.buffer.slice(0),c=this.centers.buffer.slice(0),h={order:a,centers:c},v=[a,c];if(n){this.chunks=n.slice();const g=this.chunks.buffer.slice(0);h.chunks=g,v.push(g)}this.worker.postMessage(h,v)}setMapping(r){if(!this.centers)return console.warn("SplatSorter: Cannot set mapping before initialization.");let e;const n=[];if(!r){const c=this.centers.buffer.slice(0);return e={centers:c,mapping:null},n.push(c),this.worker.postMessage(e,n)}const s=new Float32Array(r.length*3);for(let c=0;c<r.length;c++){const h=r[c];if(h*3+2>=this.centers.length){console.warn(`SplatSorter: Mapping index ${h} out of bounds.`);continue}const v=h*3,g=c*3;s[g+0]=this.centers[v+0],s[g+1]=this.centers[v+1],s[g+2]=this.centers[v+2]}const i=s.buffer.slice(0),a=r.buffer.slice(0);e={centers:i,mapping:a},n.push(i,a),this.worker.postMessage(e,n)}setCamera(r,e){const n=this.lastCameraPosition.distanceToSquared(r)>1e-7,s=this.lastCameraDirection.dot(e)<.9999;if(!n&&!s)return;this.lastCameraPosition.copy(r),this.lastCameraDirection.copy(e);const i={cameraPosition:{x:r.x,y:r.y,z:r.z},cameraDirection:{x:e.x,y:e.y,z:e.z}};this.worker.postMessage(i)}dispose(){this.worker&&this.worker.terminate(),this.orderTexture=null,this.centers=null,this.chunks=null}createWorkerCode(){return`(${(function(){let e=null,n=null,s=null,i=null,a=null,c=null,h=!1;const v={x:0,y:0,z:0},g={x:0,y:0,z:0},p={x:0,y:0,z:0},u={x:0,y:0,z:0};let l=null,b=null;const A=32,q=new Array(A).fill(0),W=new Array(A).fill(0),R=new Array(A).fill(0),H=(V,z,D)=>{for(;V<=z;){const M=z+V>>1,m=D(M);if(m>0)V=M+1;else if(m<0)z=M-1;else return M}return~V},N=()=>{if(!e||!n||!a||!c)return;if(n.length===0){const y={order:e.buffer,count:0};self.postMessage(y,[e.buffer]),e=null;return}const V=a.x,z=a.y,D=a.z,M=c.x,m=c.y,F=c.z,O=1e-4,P=Math.abs(V-v.x)>O||Math.abs(z-v.y)>O||Math.abs(D-v.z)>O,x=Math.abs(M-g.x)>O||Math.abs(m-g.y)>O||Math.abs(F-g.z)>O;if(!h&&!P&&!x)return;h=!1,v.x=V,v.y=z,v.z=D,g.x=M,g.y=m,g.z=F;let d=1/0,S=-1/0;for(let y=0;y<8;++y){const k=y&1?p.x:u.x,E=y&2?p.y:u.y,w=y&4?p.z:u.z,U=k*M+E*m+w*F;d=Math.min(d,U),S=Math.max(S,U)}const T=n.length/3,Y=S-d,I=(1<<Math.max(10,Math.min(20,Math.ceil(Math.log2(T/4)))))+1;if((!l||l.length!==T)&&(l=new Uint32Array(T)),!b||b.length!==I?b=new Uint32Array(I):b.fill(0),Y<1e-7){for(let y=0;y<T;++y)l[y]=0;b[0]=T}else if(s&&s.length>0){const y=s.length/6;q.fill(0);for(let w=0;w<y;++w){const U=w*6,J=s[U+0],K=s[U+1],tt=s[U+2],G=s[U+3],Z=J*M+K*m+tt*F-d,et=Z-G,Q=Z+G,nt=Math.max(0,Math.floor(et*A/Y)),ot=Math.min(A,Math.ceil(Q*A/Y));for(let $=nt;$<ot;++$)q[$]++}let k=0;for(let w=0;w<A;++w)k+=q[w];R[0]=0,W[0]=0;for(let w=1;w<A;++w)R[w-1]=q[w-1]/k*I>>>0,W[w]=W[w-1]+R[w-1];R[A-1]=q[A-1]/k*I>>>0;const E=Y/A;for(let w=0;w<T;++w){const U=w*3,J=n[U+0],K=n[U+1],tt=n[U+2],G=J*M+K*m+tt*F,et=(S-G)/E,Q=Math.max(0,Math.min(A-1,Math.floor(et))),nt=et-Q,ot=W[Q]+R[Q]*nt>>>0,$=Math.min(ot,I-1);l[w]=$,b[$]++}}else{const y=(I-1)/Y;for(let k=0;k<T;++k){const E=k*3,w=n[E+0],U=n[E+1],J=n[E+2],K=w*M+U*m+J*F,G=(S-K)*y>>>0,Z=Math.min(G,I-1);l[k]=Z,b[Z]++}}for(let y=1;y<I;y++)b[y]+=b[y-1];for(let y=T-1;y>=0;y--){const k=l[y],E=--b[k];e[E]=i?i[y]:y}const wt=V*M+z*m+D*F,ut=y=>{if(!e)return-1/0;const k=e[y],E=k;if(!n||E*3+2>=n.length)return-1/0;const w=E*3;return n[w]*M+n[w+1]*m+n[w+2]*F-wt};let dt=T;if(T>0&&ut(T-1)<0){const y=H(0,T-1,ut);dt=y<0?~y:y}const bt={order:e.buffer,count:dt};self.postMessage(bt,[e.buffer]),e=null};self.onmessage=V=>{const z=V.data;z.order&&(e=new Uint32Array(z.order));let D=!1;if(z.centers&&(n=new Float32Array(z.centers),D=!0,h=!0),Object.prototype.hasOwnProperty.call(z,"mapping")&&(i=z.mapping?new Uint32Array(z.mapping):null,h=!0),z.chunks){if(s=new Float32Array(z.chunks),s.length>0&&s[3]>0)for(let M=0;M<s.length/6;++M){const m=M*6,F=s[m+0],O=s[m+1],P=s[m+2],x=s[m+3],d=s[m+4],S=s[m+5];s[m+0]=(F+x)*.5,s[m+1]=(O+d)*.5,s[m+2]=(P+S)*.5,s[m+3]=Math.sqrt((x-F)**2+(d-O)**2+(S-P)**2)*.5}h=!0}if(D&&n&&n.length>0){p.x=u.x=n[0],p.y=u.y=n[1],p.z=u.z=n[2];for(let M=1;M<n.length/3;M++){const m=M*3;p.x=Math.min(p.x,n[m+0]),u.x=Math.max(u.x,n[m+0]),p.y=Math.min(p.y,n[m+1]),u.y=Math.max(u.y,n[m+1]),p.z=Math.min(p.z,n[m+2]),u.z=Math.max(u.z,n[m+2])}}else D&&n&&n.length===0&&(p.x=u.x=p.y=u.y=p.z=u.z=0);z.cameraPosition&&(a=z.cameraPosition),z.cameraDirection&&(c=z.cameraDirection),N()}}).toString()})();`}}const ft=(B,t)=>{const r=Math.max(0,Math.min(65535,Math.round((B+1)/2*65535))),e=Math.max(0,Math.min(65535,Math.round((t+1)/2*65535)));return r<<16|e},pt=new ArrayBuffer(4),ct=new DataView(pt),mt=B=>(ct.setUint32(0,B,!0),ct.getFloat32(0,!0));class lt{constructor(t){f(this,"transformA");f(this,"transformB");f(this,"colorTexture");f(this,"orderTexture");f(this,"textureWidth");f(this,"textureHeight");const r=t.numSplats;this.textureWidth=Math.ceil(Math.sqrt(r)),this.textureHeight=Math.ceil(r/this.textureWidth),this.transformA=this.createTransformATexture(t),this.transformB=this.createTransformBTexture(t),this.colorTexture=this.createColorTexture(t),this.orderTexture=this.createOrderTexture(r)}createTransformATexture(t){const r=t.numSplats,e=new Float32Array(this.textureWidth*this.textureHeight*4);for(let s=0;s<r;s++){const i=s*4,a=s*3,c=s*4;e[i]=t.positions[a],e[i+1]=t.positions[a+1],e[i+2]=t.positions[a+2];const h=t.rotations[c+1],v=t.rotations[c+2],g=ft(h,v);e[i+3]=mt(g)}const n=new o.DataTexture(e,this.textureWidth,this.textureHeight,o.RGBAFormat,o.FloatType);return n.needsUpdate=!0,n.magFilter=o.NearestFilter,n.minFilter=o.NearestFilter,n}createTransformBTexture(t){const r=t.numSplats,e=new Float32Array(this.textureWidth*this.textureHeight*4);for(let s=0;s<r;s++){const i=s*4,a=s*3,c=s*4;e[i]=t.scales[a],e[i+1]=t.scales[a+1],e[i+2]=t.scales[a+2],e[i+3]=t.rotations[c]}const n=new o.DataTexture(e,this.textureWidth,this.textureHeight,o.RGBAFormat,o.FloatType);return n.needsUpdate=!0,n.magFilter=o.NearestFilter,n.minFilter=o.NearestFilter,n}createColorTexture(t){const r=t.numSplats,e=new Float32Array(this.textureWidth*this.textureHeight*4);for(let s=0;s<r;s++){const i=s*4,a=s*3;e[i]=t.colors[a],e[i+1]=t.colors[a+1],e[i+2]=t.colors[a+2],e[i+3]=t.opacities[s]}const n=new o.DataTexture(e,this.textureWidth,this.textureHeight,o.RGBAFormat,o.FloatType);return n.needsUpdate=!0,n}createOrderTexture(t){const r=new Uint32Array(this.textureWidth*this.textureHeight);for(let n=0;n<t;n++)r[n]=n;const e=new o.DataTexture(r,this.textureWidth,this.textureHeight,o.RedIntegerFormat,o.UnsignedIntType);return e.needsUpdate=!0,e}dispose(){this.transformA.dispose(),this.transformB.dispose(),this.colorTexture.dispose(),this.orderTexture.dispose()}}const xt=`
+precision highp float;
+precision highp int;
+precision highp usampler2D;
+precision highp sampler2D;
+
+// --- Uniforms (Provided by Three.js) ---
+// uniform mat4 modelViewMatrix; // Don't redeclare
+// uniform mat4 projectionMatrix; // Don't redeclare
+uniform vec2 viewport;          // Viewport dimensions (width, height)
+uniform uint numSplats;         // Total number of splats potentially renderable by sorter
+
+// Textures
+uniform highp sampler2D transformA;   // vec4: pos.xyz, packed_rot.yz
+uniform highp sampler2D transformB;   // vec4: log_scale.xyz, rot.x
+uniform highp sampler2D splatColor;   // vec4: color.rgb, opacity
+uniform highp usampler2D splatOrder;  // uint: original splat index
+
+// --- Attributes ---
+// Instancing attribute: base index for this block of splats
+attribute uint splatInstanceIndex;
+
+// Per-vertex attribute of the quad (Built-in, don't redeclare 'position')
+// attribute vec3 position; // Use the built-in 'position'
+// position.xy: corner coords (-1..1)
+// position.z: index within the instance block (0..INSTANCE_BUFFER_SIZE-1)
+
+// --- Varyings ---
+varying vec4 vColor;
+varying vec2 vUv; // For gaussian calculation in fragment shader
+
+// --- Constants ---
+#define INSTANCE_BUFFER_SIZE 128.0 // Must match the size in SplatMesh
+
+// --- Helper Functions ---
+
+// Unpack two 16-bit floats (halfs) from a single 32-bit float (packed as uint bits)
+vec2 unpackHalf2x16FromFloat(float packedFloat) {
+    uint packedUInt = floatBitsToUint(packedFloat);
+    uint y_bits = packedUInt >> 16;
+    uint z_bits = packedUInt & uint(0xFFFF);
+
+    // NOTE: This assumes packing used "packNormalizedFloatToUint16Pair"
+    // which maps [-1, 1] to [0, 65535]. Adjust if packing method changes.
+    float y = (float(y_bits) / 65535.0) * 2.0 - 1.0;
+    float z = (float(z_bits) / 65535.0) * 2.0 - 1.0;
+    return vec2(y, z);
+}
+
+// Reconstruct quaternion from packed components (x, yz_packed)
+vec4 unpackRotation(float yz_packed, float x) {
+    vec2 yz = unpackHalf2x16FromFloat(yz_packed);
+    float y = yz.x;
+    float z = yz.y;
+    float w_squared = 1.0 - x*x - y*y - z*z;
+    float w = (w_squared < 0.0) ? 0.0 : sqrt(w_squared); // Calculate w
+    return vec4(x, y, z, w);
+}
+
+// Convert quaternion to 3x3 rotation matrix
+mat3 quatToMat3(vec4 q) {
+    float x = q.x, y = q.y, z = q.z, w = q.w;
+    float x2 = x + x, y2 = y + y, z2 = z + z;
+    float xx = x * x2, xy = x * y2, xz = x * z2;
+    float yy = y * y2, yz = y * z2, zz = z * z2;
+    float wx = w * x2, wy = w * y2, wz = w * z2;
+
+    return mat3(
+        1.0 - (yy + zz), xy + wz, xz - wy,
+        xy - wz, 1.0 - (xx + zz), yz + wx,
+        xz + wy, yz - wx, 1.0 - (xx + yy)
+    );
+}
+
+// Calculate model-space covariance components R * S^2 * transpose(R)
+void getModelCovariance(vec3 scale, vec4 rotation, out vec3 covA, out vec3 covB) {
+    mat3 R = quatToMat3(rotation);
+
+    // Define M = R * S (where S is the diagonal scale matrix)
+    // Note R is column-major, so R[0] is the first column, etc.
+    // We want M's rows to be R's rows scaled by the corresponding scale factor.
+    mat3 M = mat3(
+        R[0][0] * scale.x, R[0][1] * scale.y, R[0][2] * scale.z, // Row 0 = (R_row0 * S)
+        R[1][0] * scale.x, R[1][1] * scale.y, R[1][2] * scale.z, // Row 1 = (R_row1 * S)
+        R[2][0] * scale.x, R[2][1] * scale.y, R[2][2] * scale.z  // Row 2 = (R_row2 * S)
+    );
+
+    // Now compute Vrk = M * transpose(M)
+    // Vrk[i][j] = dot(M[i], M[j]) where M[i] is the i-th row vector of M.
+    covA = vec3(dot(M[0], M[0]), dot(M[0], M[1]), dot(M[0], M[2])); // Vrk[0][0], Vrk[0][1], Vrk[0][2]
+    covB = vec3(dot(M[1], M[1]), dot(M[1], M[2]), dot(M[2], M[2])); // Vrk[1][1], Vrk[1][2], Vrk[2][2]
+}
+
+// --- Main Function ---
+void main(void) {
+    // Calculate the final splat index for this vertex
+    uint instanceOffset = uint(position.z); // Read index within instance from Z
+    uint orderedSplatIndex = splatInstanceIndex + instanceOffset;
+
+    // Discard if this splat index is beyond the sorted count
+    if (orderedSplatIndex >= numSplats) {
+        gl_Position = vec4(2.0, 2.0, 2.0, 1.0); // Off-screen
+        return;
+    }
+
+    // --- Source Data Lookup ---
+    uint texWidth = uint(textureSize(splatOrder, 0).x);
+    ivec2 orderUV = ivec2(orderedSplatIndex % texWidth, orderedSplatIndex / texWidth);
+    uint originalSplatIndex = texelFetch(splatOrder, orderUV, 0).r;
+
+    ivec2 dataUV = ivec2(originalSplatIndex % texWidth, originalSplatIndex / texWidth);
+
+    // Fetch data from textures
+    vec4 texTransformA = texelFetch(transformA, dataUV, 0);
+    vec4 texTransformB = texelFetch(transformB, dataUV, 0);
+    vec4 texColor = texelFetch(splatColor, dataUV, 0);
+
+    vec3 splatPosition = texTransformA.xyz;
+    vec3 splatLogScale = texTransformB.xyz; // Assume stored as log scale
+    vec4 splatRotation = unpackRotation(texTransformA.w, texTransformB.w); // Unpack rot yz, x
+    vec3 splatColor = texColor.rgb;
+    float splatOpacity = texColor.a;
+
+    vec3 splatScale = exp(splatLogScale); // Convert log scale to actual scale
+
+    // --- Center Projection ---
+
+    // Compute normalized view-space center
+    vec4 centerClipRaw = modelViewMatrix * vec4(splatPosition, 1.0);
+    vec3 centerView  = centerClipRaw.xyz / centerClipRaw.w;
+
+    // Early out if splat is behind the camera
+    if (centerView.z > -0.2) { // Use small epsilon
+        gl_Position = vec4(2.0, 2.0, 2.0, 1.0);
+        return;
+    }
+
+    // Project to clip space
+    vec4 centerClip = projectionMatrix * centerClipRaw;
+
+    // --- Covariance Calculation & Projection ---
+
+    // Calculating model space covariance (Vrk)
+    vec3 covA, covB;
+    getModelCovariance(splatScale, splatRotation, covA, covB);
+    mat3 Vrk = mat3(
+        covA.x, covA.y, covA.z,
+        covA.y, covB.x, covB.y, // covB.x is Vrk[1][1]
+        covA.z, covB.y, covB.z  // covB.y is Vrk[1][2], covB.z is Vrk[2][2]
+    );
+
+    // Calculate Jacobian J (screen space change wrt view space change)
+    //    Requres focal lenghts and view-space center depth (tz)
+    float focalX = viewport.x * projectionMatrix[0][0];
+    float focalY = viewport.y * projectionMatrix[1][1];
+    float tz = centerView.z;
+    float tz2 = tz * tz;
+
+    // Jacobian J = [fx/tz,  0,    -fx*tx/tz^2]
+    //              [0,     fy/tz, -fy*ty/tz^2]
+    mat3 J = mat3(
+        focalX / tz,     0.0,  -focalX * centerView.x / tz2,
+        0.0,     focalY / tz,  -focalY * centerView.y / tz2,
+        0.0,             0.0,                0.0
+    );
+
+    // Calculate W 
+    mat3 W = transpose(mat3(modelViewMatrix));
+    // Calculate T = W * J
+    mat3 T = W * J;
+    // Calculate Projected 2D Covariance: SigmaProj = transpose(T) * Vrk * T
+    mat3 SigmaProj = transpose(T) * Vrk * T;
+
+    // Extract 2D components and add bias
+    float cov2D_11 = SigmaProj[0][0] + 0.3;
+    float cov2D_12 = SigmaProj[0][1];
+    float cov2D_22 = SigmaProj[1][1] + 0.3;
+
+    // --- Calculate 2D Screen Space Rotation & Scale ---
+
+    float det = cov2D_11 * cov2D_22 - cov2D_12 * cov2D_12;
+    // Ensure determinant is non-negative before sqrt
+    if (det <= 0.0) {
+      gl_Position = vec4(2.0, 2.0, 2.0, 1.0); // Discard degenerated
+      return;
+    }
+
+    float trace = cov2D_11 + cov2D_22;
+    float traceOver2 = 0.5 * trace;
+    float discriminantSqrt = sqrt(max(traceOver2 * traceOver2 - det, 0.0)); // Avoid sqrt(negative)
+
+    float lambda1 = traceOver2 + discriminantSqrt; // Larger eigenvalue
+    float lambda2 = max(0.1, traceOver2 - discriminantSqrt); // Smaller eigenvalue, clamped
+
+    // Compute eigenvectors 
+
+    vec2 v1_eigen, v2_eigen;
+    
+    // Handle diagonal case
+    if(abs(cov2D_12) < 1e-16) {
+        v1_eigen = vec2(1.0, 0.0);
+    } else {
+        v1_eigen = normalize(vec2(cov2D_12, lambda1 - cov2D_11)); // diagonal choice
+    }
+
+    v2_eigen = vec2(-v1_eigen.y, v1_eigen.x); // Perpendicular eigenvector
+
+    // Calculate SCALED vectors (l1, l2, incorparate factor)
+    float scaleFactor = 2.0 * sqrt(2.0); // ~2.8284
+    float l1 = sqrt(lambda1) * scaleFactor; // scaleX
+    float l2 = sqrt(lambda2) * scaleFactor; // scaleY
+
+    // Early out tiny splats
+    if (l1 < 2.0 && l2 < 2.0) { // Check if smaller than ~2 pixel
+         gl_Position = vec4(2.0, 2.0, 2.0, 1.0);
+         return;
+    }
+
+    // Scaled eigenvectors for offset calculation
+    vec2 v1_scaled = l1 * v1_eigen;
+    vec2 v2_scaled = l2 * v2_eigen;
+
+    // --- FRUSTUM CHECK  ---
+
+    vec2 clipRadius = vec2(max(l1, l2)) * (centerClip.w / viewport);
+
+    // Check if the bounding circle's edge is outside the [-w, w] range in clip space for x or y
+    if (any(greaterThan(abs(centerClip.xy) + clipRadius, vec2(abs(centerClip.w))))) {
+         gl_Position = vec4(2.0, 2.0, 2.0, 1.0); // Off-screen
+         return;
+    }
+
+    // --- END FRUSTUM CHECK ---
+
+    // --- Final Vertex Position ---
+
+    vec2 cornerOffset = position.xy; // (-1,-1) to (1,1)
+
+    // Clip the quad so only high-alpha core is visible
+    float alpha = max(splatOpacity, 1e-6);     // avoid log(0)
+    float clip  = min(1.0, sqrt(-log(1.0 / 255.0 / alpha)) / 2.0);
+
+    // Apply clip to the corner offset *before* calculating screen space offset
+    vec2 clippedCornerOffset = cornerOffset * clip;
+    vec2 screenOffsetPixels = clippedCornerOffset.x * v1_scaled + clippedCornerOffset.y * v2_scaled;
+    //vec2 screenOffsetPixels = vec2(clippedCornerOffset.x, clippedCornerOffset.y);
+
+    // Convert pixel offset to clip space offset
+    vec2 clipOffset = screenOffsetPixels * (centerClip.w / viewport);
+
+
+    // Apply offset to center clip position
+    gl_Position = centerClip + vec4(clipOffset, 0.0, 0.0);
+
+    // --- Pass data to Fragment Shader ---
+
+    vColor = vec4(splatColor, splatOpacity);
+    vUv = clippedCornerOffset;
+}
+`,yt=`
+precision highp float;
+
+varying vec4 vColor; // Color and opacity passed from vertex shader
+varying vec2 vUv;    // Quad UV coordinates (-1 to 1) passed from vertex shader
+
+void main(void) {
+
+    float distSq = dot(vUv, vUv); // Calculate squared distance from center (in the quad's coordinate system)
+    if (distSq > 1.0) discard; // Discard fragments outside the circle inscribed in the quad
+
+    // Calculate Gaussian function: alpha = opacity * exp(-distSq * factor)
+    // The factor 4.0 corresponds to the original implementation's scaling.
+    // factor = 1 / (2 * sigma^2), where sigma controls the spread.
+    // Using 4.0 implies sigma^2 = 1/8.
+    float alpha = exp(-distSq * 4.0) * vColor.a;
+
+    if (alpha < 1.0 / 255.0) discard; // Discard fragments with very low alpha
+
+    // Premultiply color by alpha (required for correct blending)
+    gl_FragColor = vec4(vColor.rgb * alpha, alpha);
+}
+`;class ht extends o.ShaderMaterial{constructor(t={}){const r={transformA:{value:null},transformB:{value:null},splatColor:{value:null},splatOrder:{value:null},viewport:{value:new o.Vector2(1,1)},numSplats:{value:0}};super({vertexShader:xt,fragmentShader:yt,uniforms:r,transparent:!0,blending:o.CustomBlending,blendSrc:o.OneFactor,blendDst:o.OneMinusSrcAlphaFactor,blendSrcAlpha:o.OneFactor,blendDstAlpha:o.OneMinusSrcAlphaFactor,blendEquation:o.AddEquation,blendEquationAlpha:o.AddEquation,depthTest:!0,depthWrite:!1,side:o.DoubleSide,alphaTest:t.alphaTest!==void 0?t.alphaTest:0,toneMapped:t.toneMapped!==void 0?t.toneMapped:!1}),t.alphaHash&&(this.alphaHash=!0,this.depthWrite=!0,this.blending=o.NoBlending)}updateViewport(t,r){this.uniforms.viewport.value.set(t,r)}setTransformA(t){this.uniforms.transformA.value=t}setTransformB(t){this.uniforms.transformB.value=t}setColorTexture(t){this.uniforms.splatColor.value=t}setOrderTexture(t){this.uniforms.splatOrder.value=t}setNumSplats(t){this.uniforms.numSplats.value=t}}const L=class L extends o.Mesh{constructor(r,e={}){const n=new ht(e),s=L.createInstancedGeometry(r.numSplats,L.INSTANCE_SIZE);super(s,n);f(this,"sorter");f(this,"splatData");f(this,"options");f(this,"textureManager");f(this,"material");f(this,"geometry");f(this,"lastCameraPositionLocal",new o.Vector3);f(this,"lastCameraDirectionLocal",new o.Vector3);f(this,"invModelMatrix",new o.Matrix4);this.geometry=s,this.material=n,this.splatData=r,this.frustumCulled=!1,this.options={autoSort:!0,...e},this.textureManager=new lt(r),this.sorter=new at;let i=this.createChunks()||void 0;i===null&&console.warn("Visus: Could not create sorter chunks, bounding box might be invalid."),i=void 0,this.sorter.init(this.textureManager.orderTexture,this.splatData.centers,i??void 0),this.sorter.addEventListener("updated",a=>{const c=a.count;this.geometry.instanceCount=Math.ceil(c/L.INSTANCE_SIZE),this.material.setNumSplats(c)}),this.material.setTransformA(this.textureManager.transformA),this.material.setTransformB(this.textureManager.transformB),this.material.setColorTexture(this.textureManager.colorTexture),this.material.setOrderTexture(this.textureManager.orderTexture),this.material.setNumSplats(0),this.geometry.boundingBox=r.boundingBox.toBox3(),this.geometry.boundingSphere=new o.Sphere,this.geometry.boundingBox.getBoundingSphere(this.geometry.boundingSphere)}static createInstancedGeometry(r,e){const n=Math.ceil(r/e),s=new o.BufferGeometry,i=new Float32Array([-1,-1,0,1,-1,0,1,1,0,-1,1,0]),a=new Uint16Array([0,1,2,0,2,3]),c=new Float32Array(4*3*e);for(let p=0;p<e;p++){const u=p*4*3;for(let l=0;l<4;l++)c[u+l*3+0]=i[l*3+0],c[u+l*3+1]=i[l*3+1],c[u+l*3+2]=p}const h=new Uint32Array(6*e);for(let p=0;p<e;p++){const u=p*6,l=p*4;h[u+0]=a[0]+l,h[u+1]=a[1]+l,h[u+2]=a[2]+l,h[u+3]=a[3]+l,h[u+4]=a[4]+l,h[u+5]=a[5]+l}s.setAttribute("position",new o.BufferAttribute(c,3)),s.setIndex(new o.BufferAttribute(h,1));const v=new o.InstancedBufferGeometry;v.index=s.index,v.setAttribute("position",s.getAttribute("position"));const g=new Uint32Array(n);for(let p=0;p<n;p++)g[p]=p*e;return v.setAttribute("splatInstanceIndex",new o.InstancedBufferAttribute(g,1,!1)),v.instanceCount=0,v}createChunks(){const r=this.splatData.boundingBox;return r.min.x===1/0||r.max.x===-1/0?null:new Float32Array([r.min.x,r.min.y,r.min.z,r.max.x,r.max.y,r.max.z])}updateViewport(r,e){this.material.updateViewport(r,e)}sort(r){const e=new o.Vector3,n=new o.Vector3;r.getWorldPosition(e),r.getWorldDirection(n),this.invModelMatrix.copy(this.matrixWorld).invert();const s=e.applyMatrix4(this.invModelMatrix),i=n.transformDirection(this.invModelMatrix),a=this.lastCameraPositionLocal.distanceToSquared(s)>1e-6,c=this.lastCameraDirectionLocal.dot(i)<.999;this.options.autoSort&&(a||c)&&(this.lastCameraPositionLocal.copy(s),this.lastCameraDirectionLocal.copy(i),this.sorter.setCamera(s,i))}onBeforeRender(r,e,n){this.sort(n);const s=r.getSize(new o.Vector2);let{width:i,height:a}=s;const c=r.xr;if(c.enabled&&c.isPresenting){const h=c.getCamera().cameras[0].view;h&&(i=h.width,a=h.height)}this.updateViewport(i,a)}dispose(){this.sorter.dispose(),this.geometry.dispose(),this.material.dispose(),this.textureManager.dispose()}};f(L,"INSTANCE_SIZE",128);let rt=L;class gt extends o.Loader{load(t,r,e,n){const s=new o.FileLoader(this.manager);s.setResponseType("arraybuffer"),s.setRequestHeader(this.requestHeader),s.setPath(this.path),s.setWithCredentials(this.withCredentials),s.load(t,i=>{try{if(r){const a=this.parse(i);r(a)}}catch(a){n?n(a):console.error(a),this.manager.itemError(t)}},e,n)}loadAsync(t,r){return new Promise((e,n)=>{const s=new o.FileLoader(this.manager);s.setResponseType("arraybuffer"),s.setRequestHeader(this.requestHeader),s.setPath(this.path),s.setWithCredentials(this.withCredentials),s.load(t,i=>{try{const a=this.parse(i);e(a)}catch(a){n(a),this.manager.itemError(t)}},r,i=>{n(i),this.manager.itemError(t)})})}parse(t){const r=new TextDecoder,e=new Uint8Array(t),n=[112,108,121,10],s=`
+end_header
+`;for(let x=0;x<n.length;x++)if(e[x]!==n[x])throw new Error("Invalid PLY file: Missing magic bytes");let i=0;for(let x=0;x<e.length-s.length;x++){let d=!0;for(let S=0;S<s.length;S++)if(e[x+S]!==s.charCodeAt(S)){d=!1;break}if(d){i=x+s.length;break}}if(i===0)throw new Error("Invalid PLY file: Could not find end of header");const c=r.decode(e.slice(0,i)).split(`
+`),h=[];let v=null;for(let x=1;x<c.length;x++){const d=c[x].trim();if(d===""||d==="end_header")continue;const S=d.split(" ");switch(S[0]){case"format":v=S[1];break;case"element":h.push({name:S[1],count:parseInt(S[2],10),properties:[]});break;case"property":if(h.length===0)throw new Error("Invalid PLY file: Property without element");h[h.length-1].properties.push({type:S[1],name:S[2],storage:null});break}}if(v!=="binary_little_endian")throw new Error(`Unsupported PLY format: ${v}`);const g=h.find(x=>x.name==="vertex");if(!g)throw new Error("Invalid PLY file: No vertex element found");const p=new it(g.count),u=new DataView(t);let l=i;const b=x=>g.properties.findIndex(d=>d.name===x),A=b("x"),q=b("y"),W=b("z"),R=[b("rot_0"),b("rot_1"),b("rot_2"),b("rot_3")],H=[b("scale_0"),b("scale_1"),b("scale_2")],N=[b("f_dc_0"),b("f_dc_1"),b("f_dc_2")],V=b("opacity");if([A,q,W,...R,...H,...N,V].some(x=>x===-1))throw new Error("Invalid PLY file: Missing required properties");const D=.28209479177387814,M=x=>{if(x>0)return 1/(1+Math.exp(-x));const d=Math.exp(x);return d/(1+d)},m=new o.Vector3,F=new o.Quaternion,O=new o.Vector3,P=new o.Color;for(let x=0;x<g.count;x++){const d=[];for(let T=0;T<g.properties.length;T++){const st=g.properties[T].type;let I;switch(st){case"char":I=u.getInt8(l),l+=1;break;case"uchar":I=u.getUint8(l),l+=1;break;case"short":I=u.getInt16(l,!0),l+=2;break;case"ushort":I=u.getUint16(l,!0),l+=2;break;case"int":I=u.getInt32(l,!0),l+=4;break;case"uint":I=u.getUint32(l,!0),l+=4;break;case"float":I=u.getFloat32(l,!0),l+=4;break;case"double":I=u.getFloat64(l,!0),l+=8;break;default:throw new Error(`Unsupported property type: ${st}`)}d.push(I)}m.set(d[A],d[q],d[W]),F.set(d[R[1]],d[R[2]],d[R[3]],d[R[0]]).normalize(),O.set(d[H[0]],d[H[1]],d[H[2]]),P.set(.5+d[N[0]]*D,.5+d[N[1]]*D,.5+d[N[2]]*D),P.r=Math.max(0,Math.min(1,P.r)),P.g=Math.max(0,Math.min(1,P.g)),P.b=Math.max(0,Math.min(1,P.b));const S=M(d[V]);p.setSplat(x,m,F,O,P,S)}return p.calculateBoundingBox(),p}}const vt="0.2.0";C.BoundingBox=X,C.PlyLoader=gt,C.SplatData=it,C.SplatMaterial=ht,C.SplatMesh=rt,C.SplatSorter=at,C.TextureManager=lt,C.VERSION=vt,Object.defineProperty(C,Symbol.toStringTag,{value:"Module"})});

package/dist/react.d.ts

@@ -0,0 +1,19 @@
+import type { FC } from 'react';
+import type { ThreeElements } from '@react-three/fiber';
+import type { PlyLoader, SplatMesh, SplatMeshOptions } from '@speridlabs/visus';
+
+/**
+ * Props for the <Splat> component.
+ */
+export interface SplatProps extends Omit<ThreeElements['mesh'], 'args'> {
+    /** URL of the .ply file to load */
+    plyUrl: string;
+    /** Options passed to the underlying SplatMesh */
+    splatOptions?: SplatMeshOptions;
+}
+
+/**
+ * React wrapper for Visus’s SplatMesh.
+ */
+export declare const Splat: FC<SplatProps>;
+export type { PlyLoader, SplatMesh, SplatMeshOptions };