xeokit Geometry Compression / Decompression Utilities

This module provides geometry compression and decompression utilities used internally within SceneModel.createGeometry. These functions are exposed publicly, allowing users to pre-compress geometry data before passing it to SceneModel.createGeometryCompressed for optimized rendering and storage.

Compression Techniques

The utilities in this module utilize the following compression techniques to reduce the size of 3D geometry data:

• Merges duplicate vertex positions and updates indices to minimize data redundancy
• Generates edge indices for triangle meshes to facilitate faster rendering
• Omits normals (which are auto-generated by shaders during rendering)
• Converts positions to relative-to-center (RTC) coordinates for improved compression efficiency
• Quantizes positions and UVs as 16-bit unsigned integers for compact storage
• Compresses bounding box data and provides necessary matrices for efficient decompression

Installation

npm install @xeokit/sdk
Copy

Usage

The following examples demonstrate how to use the compression functions in this module:

1. Compressing Positions with AABB3 (Axis-Aligned Bounding Box)

To compress a set of vertex positions, use the compressPositions3 function, which quantizes the positions based on an AABB3:

import {compressPositions3} from "@xeokit/sdk/compression";

const positions = [0, 0, 0, 1, 1, 1, 2, 2, 2];
const aabb = [0, 0, 0, 2, 2, 2]; // The bounding box of the geometry

const { quantized, decompressMatrix } = compressPositions3(positions, aabb);

console.log(quantized); // The compressed (quantized) positions
console.log(decompressMatrix); // The matrix used for decompression
Copy

2. Decompressing 3D Positions with a 4x4 Matrix

To decompress a set of quantized positions using a transformation matrix, use the decompressPositions3WithMat4 function:

import {decompressPositions3WithMat4} from "@xeokit/sdk/compression";

const quantizedPositions = [32767, 32767, 32767]; // Quantized data
const decompressMatrix = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]; // Example identity matrix

const decompressedPositions = decompressPositions3WithMat4(quantizedPositions, decompressMatrix);

console.log(decompressedPositions); // The decompressed positions
Copy

3. Compressing UV Coordinates

The compressUVs function compresses UV coordinates using a similar approach to position compression:

import {compressUVs} from "@xeokit/sdk/compression";

const uvs = [0.0, 0.0, 0.5, 0.5, 1.0, 1.0];
const minUV = [0.0, 0.0];
const maxUV = [1.0, 1.0];

const { quantized, decompressMatrix } = compressUVs(uvs, minUV, maxUV);

console.log(quantized); // The compressed (quantized) UVs
console.log(decompressMatrix); // The matrix for UV decompression
Copy

4. Decompressing 3D Position with AABB3

To decompress a point from quantized data back into real-world coordinates, you can use decompressPoint3WithAABB3:

import {decompressPoint3WithAABB3} from "@xeokit/sdk/compression";

const compressedPoint = [32767, 32767, 32767]; // Example quantized point
const aabb = [0, 0, 0, 1, 1, 1]; // The AABB3 used during compression

const decompressedPoint = decompressPoint3WithAABB3(compressedPoint, aabb);

console.log(decompressedPoint); // The real-world coordinates of the point
Copy