@math.gl/geometry 5.0.0-alpha.2 → 5.0.0-alpha.20

package/src/utils/attribute-compression.ts

@@ -0,0 +1,234 @@
+// math.gl
+// SPDX-License-Identifier: MIT AND Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright 2011-2018 CesiumJS Contributors
+// SPDX-FileComment: Derived from Cesium. See the repository LICENSE for upstream attribution and Apache-2.0 terms.
+
+// Derived from Cesium under the Apache 2.0 license.
+// https://github.com/CesiumGS/cesium/blob/main/LICENSE.md
+
+import {Vector2, Vector3, assert, clamp, _MathUtils} from '@math.gl/core';
+
+type Vector4 = {x: number; y: number; z: number; w: number};
+
+const RIGHT_SHIFT = 1 / 256;
+const LEFT_SHIFT = 256;
+const scratchVector2 = new Vector2();
+const scratchVector3 = new Vector3();
+const scratchEncodeVector2 = new Vector2();
+const octEncodeScratch = new Vector2();
+const uint8ForceArray = new Uint8Array(1);
+
+function forceUint8(value: number): number {
+  uint8ForceArray[0] = value;
+  return uint8ForceArray[0];
+}
+
+function fromSNorm(value: number, rangeMaximum = 255): number {
+  return (clamp(value, 0, rangeMaximum) / rangeMaximum) * 2 - 1;
+}
+
+function toSNorm(value: number, rangeMaximum = 255): number {
+  return Math.round((clamp(value, -1, 1) * 0.5 + 0.5) * rangeMaximum);
+}
+
+function signNotZero(value: number): number {
+  return value < 0 ? -1 : 1;
+}
+
+/**
+ * Encodes a normalized vector into two SNORM values following octahedral encoding.
+ *
+ * @param vector Normalized vector to encode.
+ * @param rangeMaximum Maximum value of the SNORM range.
+ * @param result Target for the two encoded components.
+ */
+export function octEncodeInRange(vector: Vector3, rangeMaximum: number, result: Vector2): Vector2 {
+  assert(vector);
+  assert(result);
+  scratchVector3.from(vector);
+  assert(Math.abs(scratchVector3.magnitudeSquared() - 1) <= _MathUtils.EPSILON6);
+
+  const denominator = Math.abs(vector.x) + Math.abs(vector.y) + Math.abs(vector.z);
+  result.x = vector.x / denominator;
+  result.y = vector.y / denominator;
+
+  if (vector.z < 0) {
+    const x = result.x;
+    const y = result.y;
+    result.x = (1 - Math.abs(y)) * signNotZero(x);
+    result.y = (1 - Math.abs(x)) * signNotZero(y);
+  }
+
+  result.x = toSNorm(result.x, rangeMaximum);
+  result.y = toSNorm(result.y, rangeMaximum);
+  return result;
+}
+
+/** Encodes a normalized vector into two 8-bit octahedral components. */
+export function octEncode(vector: Vector3, result: Vector2): Vector2 {
+  return octEncodeInRange(vector, 255, result);
+}
+
+/** Encodes a normalized vector into four 8-bit octahedral components. */
+export function octEncodeToVector4(vector: Vector3, result: Vector4): Vector4 {
+  octEncodeInRange(vector, 65535, octEncodeScratch);
+  result.x = forceUint8(octEncodeScratch.x * RIGHT_SHIFT);
+  result.y = forceUint8(octEncodeScratch.x);
+  result.z = forceUint8(octEncodeScratch.y * RIGHT_SHIFT);
+  result.w = forceUint8(octEncodeScratch.y);
+  return result;
+}
+
+/**
+ * Decodes two SNORM octahedral components into a normalized vector.
+ *
+ * @param x First encoded component.
+ * @param y Second encoded component.
+ * @param rangeMaximum Maximum value of the SNORM range.
+ * @param result Target for the decoded vector.
+ */
+export function octDecodeInRange(
+  x: number,
+  y: number,
+  rangeMaximum: number,
+  result: Vector3
+): Vector3 {
+  assert(result);
+  if (x < 0 || x > rangeMaximum || y < 0 || y > rangeMaximum) {
+    throw new Error(`x and y must be unsigned normalized integers between 0 and ${rangeMaximum}`);
+  }
+
+  result.x = fromSNorm(x, rangeMaximum);
+  result.y = fromSNorm(y, rangeMaximum);
+  result.z = 1 - (Math.abs(result.x) + Math.abs(result.y));
+
+  if (result.z < 0) {
+    const oldX = result.x;
+    result.x = (1 - Math.abs(result.y)) * signNotZero(oldX);
+    result.y = (1 - Math.abs(oldX)) * signNotZero(result.y);
+  }
+  return result.normalize();
+}
+
+/** Decodes two 8-bit octahedral components into a normalized vector. */
+export function octDecode(x: number, y: number, result: Vector3): Vector3 {
+  return octDecodeInRange(x, y, 255, result);
+}
+
+/** Decodes four 8-bit octahedral components into a normalized vector. */
+export function octDecodeFromVector4(encoded: Vector4, result: Vector3): Vector3 {
+  assert(encoded);
+  assert(result);
+  const {x, y, z, w} = encoded;
+  if (x < 0 || x > 255 || y < 0 || y > 255 || z < 0 || z > 255 || w < 0 || w > 255) {
+    throw new Error('x, y, z, and w must be unsigned normalized integers between 0 and 255');
+  }
+  return octDecodeInRange(x * LEFT_SHIFT + y, z * LEFT_SHIFT + w, 65535, result);
+}
+
+/** Packs an octahedrally encoded two-component vector into one number. */
+export function octPackFloat(encoded: Vector2): number {
+  scratchVector2.from(encoded);
+  return 256 * scratchVector2.x + scratchVector2.y;
+}
+
+/** Encodes a normalized vector into an octahedral representation packed into one number. */
+export function octEncodeFloat(vector: Vector3): number {
+  octEncode(vector, scratchEncodeVector2);
+  return octPackFloat(scratchEncodeVector2);
+}
+
+/** Decodes an octahedral representation packed into one number. */
+export function octDecodeFloat(value: number, result: Vector3): Vector3 {
+  assert(Number.isFinite(value));
+  const temporary = value / 256;
+  const x = Math.floor(temporary);
+  const y = (temporary - x) * 256;
+  return octDecode(x, y, result);
+}
+
+/** Packs three normalized vectors into two numeric octahedral values. */
+export function octPack(
+  vector1: Vector3,
+  vector2: Vector3,
+  vector3: Vector3,
+  result: Vector2
+): Vector2 {
+  assert(vector1);
+  assert(vector2);
+  assert(vector3);
+  assert(result);
+  const encoded1 = octEncodeFloat(vector1);
+  const encoded2 = octEncodeFloat(vector2);
+  const encoded3 = octEncode(vector3, scratchEncodeVector2);
+  result.x = 65536 * encoded3.x + encoded1;
+  result.y = 65536 * encoded3.y + encoded2;
+  return result;
+}
+
+/** Decodes three normalized vectors packed by {@link octPack}. */
+export function octUnpack(
+  packed: Vector2,
+  vector1: Vector3,
+  vector2: Vector3,
+  vector3: Vector3
+): void {
+  let temporary = packed.x / 65536;
+  const x = Math.floor(temporary);
+  const encodedFloat1 = (temporary - x) * 65536;
+  temporary = packed.y / 65536;
+  const y = Math.floor(temporary);
+  const encodedFloat2 = (temporary - y) * 65536;
+  octDecodeFloat(encodedFloat1, vector1);
+  octDecodeFloat(encodedFloat2, vector2);
+  octDecode(x, y, vector3);
+}
+
+/** Packs two normalized texture coordinates into one number with 12 bits per component. */
+export function compressTextureCoordinates(textureCoordinates: Vector2): number {
+  const x = (textureCoordinates.x * 4095) | 0;
+  const y = (textureCoordinates.y * 4095) | 0;
+  return 4096 * x + y;
+}
+
+/** Decompresses texture coordinates packed by {@link compressTextureCoordinates}. */
+export function decompressTextureCoordinates(compressed: number, result: Vector2): Vector2 {
+  const temporary = compressed / 4096;
+  const x = Math.floor(temporary);
+  result.x = x / 4095;
+  result.y = (compressed - x * 4096) / 4095;
+  return result;
+}
+
+/** Decodes delta- and ZigZag-encoded vertex buffers in place. */
+export function zigZagDeltaDecode(
+  uBuffer: Uint16Array,
+  vBuffer: Uint16Array,
+  heightBuffer?: Uint16Array | number[]
+): void {
+  assert(uBuffer);
+  assert(vBuffer);
+  assert(uBuffer.length === vBuffer.length);
+  if (heightBuffer) {
+    assert(uBuffer.length === heightBuffer.length);
+  }
+
+  let u = 0;
+  let v = 0;
+  let height = 0;
+  for (let index = 0; index < uBuffer.length; index++) {
+    u += zigZagDecode(uBuffer[index]);
+    v += zigZagDecode(vBuffer[index]);
+    uBuffer[index] = u;
+    vBuffer[index] = v;
+    if (heightBuffer) {
+      height += zigZagDecode(heightBuffer[index]);
+      heightBuffer[index] = height;
+    }
+  }
+}
+
+function zigZagDecode(value: number): number {
+  return (value >> 1) ^ -(value & 1);
+}

package/src/utils/attribute-iterator.ts

@@ -0,0 +1,28 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {TypedArray, TypedArrayConstructor} from '@math.gl/core/types';
+
+/**
+ * Iterates over the fixed-size elements of a typed array.
+ *
+ * For performance, each iteration reuses the same typed-array view-sized value.
+ */
+export function* makeAttributeIterator(values: TypedArray, size: number): Iterable<TypedArray> {
+  if (!Number.isInteger(size) || size <= 0) {
+    throw new Error('Attribute size must be a positive integer');
+  }
+  if (values.length % size !== 0) {
+    throw new Error('Attribute length must be divisible by its size');
+  }
+
+  const ArrayType = values.constructor as TypedArrayConstructor;
+  const element = new ArrayType(size);
+  for (let index = 0; index < values.length; index += size) {
+    for (let componentIndex = 0; componentIndex < size; componentIndex++) {
+      element[componentIndex] = values[index + componentIndex]!;
+    }
+    yield element;
+  }
+}

package/src/utils/compute-vertex-normals.ts

@@ -0,0 +1,63 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {Vector3} from '@math.gl/core';
+import {GL} from './constants';
+import type {Geometry} from './geometry';
+import {getAttributeValues, getPositionAttribute} from './geometry';
+import {makePrimitiveIterator} from './primitive-iterator';
+
+/** Computes smooth, area-weighted vertex normals for a triangle geometry. */
+export function computeVertexNormals(geometry: Geometry): Float32Array {
+  if (
+    geometry.mode !== GL.TRIANGLES &&
+    geometry.mode !== GL.TRIANGLE_STRIP &&
+    geometry.mode !== GL.TRIANGLE_FAN
+  ) {
+    throw new Error('Triangle geometry is required');
+  }
+
+  const position = getPositionAttribute(geometry);
+  const positions = getAttributeValues(position);
+  const positionSize = position.size || 3;
+  if (positionSize < 3) {
+    throw new Error('Position attributes must have at least three components');
+  }
+
+  const vertexCount = positions.length / positionSize;
+  const normals = new Float32Array(vertexCount * 3);
+  const vectorA = new Vector3();
+  const vectorB = new Vector3();
+  const vectorC = new Vector3();
+  const edgeCB = new Vector3();
+  const edgeAB = new Vector3();
+
+  for (const primitive of makePrimitiveIterator(geometry)) {
+    const {i1, i2, i3} = primitive;
+    if (i2 === undefined || i3 === undefined) {
+      continue;
+    }
+    vectorA.fromArray(positions, i1 * positionSize);
+    vectorB.fromArray(positions, i2 * positionSize);
+    vectorC.fromArray(positions, i3 * positionSize);
+    const faceNormal = edgeCB
+      .subVectors(vectorC, vectorB)
+      .cross(edgeAB.subVectors(vectorA, vectorB));
+
+    for (const vertexIndex of [i1, i2, i3]) {
+      normals[vertexIndex * 3] += faceNormal.x;
+      normals[vertexIndex * 3 + 1] += faceNormal.y;
+      normals[vertexIndex * 3 + 2] += faceNormal.z;
+    }
+  }
+
+  const normal = new Vector3();
+  for (let vertexIndex = 0; vertexIndex < vertexCount; vertexIndex++) {
+    normal.fromArray(normals, vertexIndex * 3);
+    if (normal.magnitudeSquared() > 0) {
+      normal.normalize().toArray(normals, vertexIndex * 3);
+    }
+  }
+  return normals;
+}

package/src/utils/constants.ts

@@ -0,0 +1,42 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+/** Portable point, line, and triangle primitive types. */
+export const GL_PRIMITIVE = {
+  POINTS: 0x0000,
+  LINES: 0x0001,
+  TRIANGLES: 0x0004
+} as const;
+
+/** WebGL-compatible primitive topology constants. */
+export const GL_PRIMITIVE_MODE = {
+  POINTS: 0x0000,
+  LINES: 0x0001,
+  LINE_LOOP: 0x0002,
+  LINE_STRIP: 0x0003,
+  TRIANGLES: 0x0004,
+  TRIANGLE_STRIP: 0x0005,
+  TRIANGLE_FAN: 0x0006
+} as const;
+
+/** WebGL-compatible vertex component type constants. */
+export const GL_TYPE = {
+  BYTE: 5120,
+  UNSIGNED_BYTE: 5121,
+  SHORT: 5122,
+  UNSIGNED_SHORT: 5123,
+  INT: 5124,
+  UNSIGNED_INT: 5125,
+  FLOAT: 5126,
+  DOUBLE: 5130,
+  UNSIGNED_SHORT_4_4_4_4: 32819,
+  UNSIGNED_SHORT_5_5_5_1: 32820,
+  UNSIGNED_SHORT_5_6_5: 33635
+} as const;
+
+/** WebGL-compatible constants used by geometry utilities. */
+export const GL = {
+  ...GL_PRIMITIVE_MODE,
+  ...GL_TYPE
+} as const;

package/src/utils/coordinates.ts

@@ -0,0 +1,8 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+/** Wraps a number into the half-open range `[0, 1)`. */
+export function emod(value: number): number {
+  return ((value % 1) + 1) % 1;
+}

package/src/utils/geometry.ts

@@ -0,0 +1,49 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {TypedArray} from '@math.gl/core/types';
+
+/** A typed geometry attribute with either loaders.gl-style `value` or legacy `values` storage. */
+export type GeometryAttribute = {
+  value?: TypedArray;
+  values?: TypedArray;
+  size?: number;
+};
+
+/** Minimal geometry shape understood by the geometry utilities. */
+export type Geometry = {
+  mode: number;
+  indices?: GeometryAttribute | TypedArray;
+  attributes: Record<string, GeometryAttribute>;
+};
+
+/** Returns whether a value has the minimal geometry shape. */
+export function isGeometry(value: unknown): value is Geometry {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  const geometry = value as Partial<Geometry>;
+  return typeof geometry.mode === 'number' && Boolean(geometry.attributes);
+}
+
+/** Returns the typed array stored in a geometry attribute. */
+export function getAttributeValues(attribute: GeometryAttribute | TypedArray): TypedArray {
+  if (ArrayBuffer.isView(attribute)) {
+    return attribute as TypedArray;
+  }
+  const values = attribute.value || attribute.values;
+  if (!values) {
+    throw new Error('Geometry attribute does not contain typed-array values');
+  }
+  return values;
+}
+
+/** Returns a geometry's position attribute. */
+export function getPositionAttribute(geometry: Geometry): GeometryAttribute {
+  const position = geometry.attributes['POSITION'] || geometry.attributes['positions'];
+  if (!position) {
+    throw new Error('Geometry does not contain a position attribute');
+  }
+  return position;
+}

package/src/utils/gl-type.ts

@@ -0,0 +1,87 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {TypedArray, TypedArrayConstructor} from '@math.gl/core/types';
+import {GL_TYPE} from './constants';
+
+const GL_TYPE_TO_ARRAY_TYPE: Record<number, TypedArrayConstructor> = {
+  [GL_TYPE.DOUBLE]: Float64Array,
+  [GL_TYPE.FLOAT]: Float32Array,
+  [GL_TYPE.UNSIGNED_SHORT]: Uint16Array,
+  [GL_TYPE.UNSIGNED_INT]: Uint32Array,
+  [GL_TYPE.UNSIGNED_BYTE]: Uint8Array,
+  [GL_TYPE.BYTE]: Int8Array,
+  [GL_TYPE.SHORT]: Int16Array,
+  [GL_TYPE.INT]: Int32Array,
+  [GL_TYPE.UNSIGNED_SHORT_4_4_4_4]: Uint16Array,
+  [GL_TYPE.UNSIGNED_SHORT_5_5_5_1]: Uint16Array,
+  [GL_TYPE.UNSIGNED_SHORT_5_6_5]: Uint16Array
+};
+
+const NAME_TO_GL_TYPE: Record<string, number> = Object.fromEntries(
+  Object.entries(GL_TYPE).map(([name, glType]) => [name, glType])
+);
+
+const TYPE_CONVERSION_ERROR = 'Failed to convert GL type';
+
+/** Converts between WebGL component constants and JavaScript typed arrays. */
+export default class GLType {
+  /** Returns the WebGL component constant for a typed array or typed-array constructor. */
+  static fromTypedArray(arrayOrType: TypedArray | TypedArrayConstructor): number {
+    const arrayType = ArrayBuffer.isView(arrayOrType) ? arrayOrType.constructor : arrayOrType;
+    if (arrayType === Uint8ClampedArray) {
+      return GL_TYPE.UNSIGNED_BYTE;
+    }
+    for (const [glType, candidateArrayType] of Object.entries(GL_TYPE_TO_ARRAY_TYPE)) {
+      if (candidateArrayType === arrayType) {
+        return Number(glType);
+      }
+    }
+    throw new Error(TYPE_CONVERSION_ERROR);
+  }
+
+  /** Returns a WebGL component constant from its uppercase name. */
+  static fromName(name: string): number {
+    const glType = NAME_TO_GL_TYPE[name];
+    if (glType === undefined) {
+      throw new Error(TYPE_CONVERSION_ERROR);
+    }
+    return glType;
+  }
+
+  /** Returns the typed-array constructor for a WebGL component constant. */
+  static getArrayType(glType: number): TypedArrayConstructor {
+    const ArrayType = GL_TYPE_TO_ARRAY_TYPE[glType];
+    if (!ArrayType) {
+      throw new Error(TYPE_CONVERSION_ERROR);
+    }
+    return ArrayType;
+  }
+
+  /** Returns the size in bytes of one element of a WebGL component type. */
+  static getByteSize(glType: number): number {
+    return GLType.getArrayType(glType).BYTES_PER_ELEMENT;
+  }
+
+  /** Returns whether a value is a supported WebGL component type. */
+  static validate(glType: number): boolean {
+    return Boolean(GL_TYPE_TO_ARRAY_TYPE[glType]);
+  }
+
+  /** Creates a typed view over an ArrayBuffer or an existing ArrayBuffer view. */
+  static createTypedArray(
+    glType: number,
+    buffer: ArrayBufferLike | ArrayBufferView,
+    byteOffset = 0,
+    length?: number
+  ): TypedArray {
+    const ArrayType = GLType.getArrayType(glType);
+    const arrayBuffer = ArrayBuffer.isView(buffer) ? buffer.buffer : buffer;
+    const viewByteOffset = ArrayBuffer.isView(buffer) ? buffer.byteOffset : 0;
+    const resolvedByteOffset = viewByteOffset + byteOffset;
+    const resolvedLength =
+      length ?? Math.floor((buffer.byteLength - byteOffset) / ArrayType.BYTES_PER_ELEMENT);
+    return new ArrayType(arrayBuffer as ArrayBuffer, resolvedByteOffset, resolvedLength);
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,55 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export type {TypedArray, TypedArrayConstructor} from '@math.gl/core/types';
+
+export {GL, GL_TYPE, GL_PRIMITIVE, GL_PRIMITIVE_MODE} from './constants';
+export {default as GLType} from './gl-type';
+
+export type {Geometry, GeometryAttribute} from './geometry';
+export {isGeometry} from './geometry';
+
+export type {Primitive} from './primitive-iterator';
+export {makeAttributeIterator} from './attribute-iterator';
+export {makePrimitiveIterator} from './primitive-iterator';
+export {computeVertexNormals} from './compute-vertex-normals';
+
+export {encodeRGB565, decodeRGB565} from './rgb565';
+export {concatTypedArrays} from './typed-array-utils';
+
+export {
+  octEncodeInRange,
+  octEncode,
+  octEncodeToVector4,
+  octDecodeInRange,
+  octDecode,
+  octDecodeFromVector4,
+  octPackFloat,
+  octEncodeFloat,
+  octDecodeFloat,
+  octPack,
+  octUnpack,
+  compressTextureCoordinates,
+  decompressTextureCoordinates,
+  zigZagDeltaDecode
+} from './attribute-compression';
+
+export {emod} from './coordinates';
+
+export {
+  transformGeometry,
+  mergeGeometries,
+  weldGeometry,
+  getDegenerateTriangles
+} from './mesh-processing';
+export type {WeldGeometryOptions, WeldGeometryResult} from './mesh-processing';
+
+export {interpolatePackedAttributes} from './interpolate-packed-attributes';
+export type {
+  PackedAttributeType,
+  PackedAttributeInterpolation,
+  PackedAttribute,
+  AttributeInterpolationProvenance,
+  PackedAttributeInterpolationOptions
+} from './interpolate-packed-attributes';