@math.gl/geometry 4.2.0-alpha.5

package/src/geometries/sphere-geometry.ts

@@ -0,0 +1,42 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Geometry} from '../lib/geometry';
+import {assertPositive, assertSegments, type PrimitiveGeometryProps} from './geometry-helpers';
+import {makeSurfaceOfRevolution, type ProfileRing} from './surface-of-revolution';
+
+export type SphereGeometryProps = PrimitiveGeometryProps & {
+  radius?: number;
+  nlat?: number;
+  nlong?: number;
+};
+
+/** Tessellates the glTF sphere shape. */
+export class SphereGeometry extends Geometry {
+  constructor(props: SphereGeometryProps = {}) {
+    const {radius = 0.5, nlat = 10, nlong = 10} = props;
+    assertPositive(radius, 'radius');
+    assertSegments(nlat, 'nlat', 2);
+    assertSegments(nlong, 'nlong', 3);
+    const rings: ProfileRing[] = [];
+    for (let latitude = 0; latitude <= nlat; latitude++) {
+      const angle = -Math.PI / 2 + (latitude / nlat) * Math.PI;
+      const normalRadius = Math.cos(angle);
+      const normalY = Math.sin(angle);
+      rings.push({radius: radius * normalRadius, y: radius * normalY, normalRadius, normalY});
+    }
+    const mesh = makeSurfaceOfRevolution(rings, nlong);
+    super({
+      id: props.id,
+      topology: 'triangle-list',
+      indices: mesh.indexArray,
+      attributes: {
+        POSITION: {size: 3, value: new Float32Array(mesh.positions)},
+        NORMAL: {size: 3, value: new Float32Array(mesh.normals)},
+        TEXCOORD_0: {size: 2, value: new Float32Array(mesh.texCoords)},
+        ...props.attributes
+      }
+    });
+  }
+}

package/src/geometries/surface-of-revolution.ts

@@ -0,0 +1,43 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {makeIndices, type MeshData} from './geometry-helpers';
+
+export type ProfileRing = {radius: number; y: number; normalRadius: number; normalY: number};
+
+export function makeSurfaceOfRevolution(
+  rings: ProfileRing[],
+  nradial: number
+): MeshData & {indexArray: Uint16Array | Uint32Array} {
+  const positions: number[] = [];
+  const normals: number[] = [];
+  const texCoords: number[] = [];
+  const indices: number[] = [];
+  const stride = nradial + 1;
+  for (let ringIndex = 0; ringIndex < rings.length; ringIndex++) {
+    const ring = rings[ringIndex];
+    for (let radial = 0; radial <= nradial; radial++) {
+      const u = radial / nradial;
+      const angle = u * Math.PI * 2;
+      const sin = Math.sin(angle);
+      const cos = Math.cos(angle);
+      positions.push(sin * ring.radius, ring.y, cos * ring.radius);
+      normals.push(sin * ring.normalRadius, ring.normalY, cos * ring.normalRadius);
+      texCoords.push(u, ringIndex / (rings.length - 1));
+    }
+  }
+  for (let ring = 0; ring < rings.length - 1; ring++) {
+    for (let radial = 0; radial < nradial; radial++) {
+      const a = ring * stride + radial;
+      const b = a + 1;
+      const c = a + stride;
+      const d = c + 1;
+      indices.push(a, b, d, a, d, c);
+    }
+  }
+  return {
+    ...{positions, normals, texCoords, indices},
+    indexArray: makeIndices(positions.length / 3, indices)
+  };
+}

package/src/geometries/truncated-cone-geometry.ts

@@ -0,0 +1,129 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Geometry} from '../lib/geometry';
+import {
+  assertNonNegative,
+  assertPositive,
+  assertSegments,
+  makeIndices,
+  type PrimitiveGeometryProps
+} from './geometry-helpers';
+
+export type TruncatedConeGeometryProps = PrimitiveGeometryProps & {
+  topRadius?: number;
+  bottomRadius?: number;
+  topCap?: boolean;
+  bottomCap?: boolean;
+  height?: number;
+  nradial?: number;
+  nvertical?: number;
+  verticalAxis?: 'x' | 'y' | 'z';
+};
+
+/** General truncated cone primitive, adapted from luma.gl's CPU tessellator. */
+export class TruncatedConeGeometry extends Geometry {
+  constructor(props: TruncatedConeGeometryProps = {}) {
+    const {
+      topRadius = 0,
+      bottomRadius = 0,
+      topCap = false,
+      bottomCap = false,
+      height = 1,
+      nradial = 10,
+      nvertical = 1,
+      verticalAxis = 'y'
+    } = props;
+    assertNonNegative(topRadius, 'topRadius');
+    assertNonNegative(bottomRadius, 'bottomRadius');
+    if (topRadius === 0 && bottomRadius === 0)
+      throw new Error('At least one radius must be greater than zero');
+    assertPositive(height, 'height');
+    assertSegments(nradial, 'nradial', 3);
+    assertSegments(nvertical, 'nvertical');
+
+    const positions: number[] = [];
+    const normals: number[] = [];
+    const texCoords: number[] = [];
+    const indices: number[] = [];
+    const stride = nradial + 1;
+    const slope = (bottomRadius - topRadius) / height;
+    const normalScale = 1 / Math.hypot(1, slope);
+
+    const addRing = (
+      radius: number,
+      y: number,
+      normalRadius: number,
+      normalY: number,
+      v: number
+    ): number => {
+      const ring = positions.length / 3 / stride;
+      for (let radial = 0; radial <= nradial; radial++) {
+        const u = radial / nradial;
+        const angle = u * Math.PI * 2;
+        const sin = Math.sin(angle);
+        const cos = Math.cos(angle);
+        const point = orient([sin * radius, y, cos * radius], verticalAxis);
+        const normal = orient([sin * normalRadius, normalY, cos * normalRadius], verticalAxis);
+        positions.push(...point);
+        normals.push(...normal);
+        texCoords.push(u, v);
+      }
+      return ring;
+    };
+    const connect = (lower: number, upper: number): void => {
+      for (let radial = 0; radial < nradial; radial++) {
+        const a = lower * stride + radial;
+        const b = a + 1;
+        const c = upper * stride + radial;
+        const d = c + 1;
+        indices.push(a, b, d, a, d, c);
+      }
+    };
+
+    let previous: number | undefined;
+    if (bottomCap) {
+      const center = addRing(0, -height / 2, 0, -1, 0);
+      const edge = addRing(bottomRadius, -height / 2, 0, -1, 1);
+      connect(center, edge);
+      previous = addRing(bottomRadius, -height / 2, normalScale, slope * normalScale, 0);
+    }
+    for (let vertical = 0; vertical <= nvertical; vertical++) {
+      const v = vertical / nvertical;
+      const radius = bottomRadius + (topRadius - bottomRadius) * v;
+      const ring = addRing(radius, (v - 0.5) * height, normalScale, slope * normalScale, v);
+      if (previous !== undefined && !(bottomCap && vertical === 0)) connect(previous, ring);
+      previous = ring;
+    }
+    if (topCap && previous !== undefined) {
+      const edge = addRing(topRadius, height / 2, 0, 1, 1);
+      const center = addRing(0, height / 2, 0, 1, 0);
+      connect(edge, center);
+    }
+
+    const vertexCount = positions.length / 3;
+    super({
+      id: props.id,
+      topology: 'triangle-list',
+      indices: makeIndices(vertexCount, indices),
+      attributes: {
+        POSITION: {size: 3, value: new Float32Array(positions)},
+        NORMAL: {size: 3, value: new Float32Array(normals)},
+        TEXCOORD_0: {size: 2, value: new Float32Array(texCoords)},
+        ...props.attributes
+      }
+    });
+  }
+}
+
+function orient(vector: readonly number[], axis: 'x' | 'y' | 'z'): number[] {
+  switch (axis) {
+    case 'x':
+      return [vector[1], vector[2], vector[0]];
+    case 'z':
+      return [vector[2], vector[0], vector[1]];
+    default:
+      return [vector[0], vector[1], vector[2]];
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export {Geometry} from './lib/geometry';
+export type {
+  GeometryProps,
+  GeometryAttribute,
+  GeometryAttributeInput,
+  GeometryAttributes,
+  PrimitiveTopology
+} from './lib/geometry';
+export {unpackIndexedGeometry} from './lib/geometry-utils';
+
+export {BoxGeometry, CubeGeometry} from './geometries/box-geometry';
+export type {BoxGeometryProps, CubeGeometryProps} from './geometries/box-geometry';
+export {CapsuleGeometry} from './geometries/capsule-geometry';
+export type {CapsuleGeometryProps} from './geometries/capsule-geometry';
+export {CylinderGeometry, ConeGeometry} from './geometries/cylinder-geometry';
+export type {CylinderGeometryProps, ConeGeometryProps} from './geometries/cylinder-geometry';
+export {PlaneGeometry} from './geometries/plane-geometry';
+export type {PlaneGeometryProps} from './geometries/plane-geometry';
+export {SphereGeometry} from './geometries/sphere-geometry';
+export type {SphereGeometryProps} from './geometries/sphere-geometry';
+export {TruncatedConeGeometry} from './geometries/truncated-cone-geometry';
+export type {TruncatedConeGeometryProps} from './geometries/truncated-cone-geometry';
+export {IcoSphereGeometry} from './geometries/ico-sphere-geometry';
+export type {IcoSphereGeometryProps} from './geometries/ico-sphere-geometry';

package/src/lib/geometry-utils.ts

@@ -0,0 +1,35 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TypedArray, TypedArrayConstructor} from '@math.gl/types';
+import type {GeometryAttribute} from './geometry';
+
+type GeometryLike = {
+  indices?: GeometryAttribute;
+  attributes: Record<string, GeometryAttribute | undefined>;
+};
+
+/** Expands indexed attributes into a non-indexed geometry-like object. */
+export function unpackIndexedGeometry<T extends GeometryLike>(geometry: T): GeometryLike {
+  if (!geometry.indices) return geometry;
+  const indices = geometry.indices.value;
+  const attributes: Record<string, GeometryAttribute> = {};
+  for (const [name, attribute] of Object.entries(geometry.attributes)) {
+    if (!attribute) continue;
+    if (attribute.constant || !attribute.size) {
+      attributes[name] = attribute;
+      continue;
+    }
+    const ArrayType = attribute.value.constructor as TypedArrayConstructor;
+    const value = new ArrayType(indices.length * attribute.size) as TypedArray;
+    for (let i = 0; i < indices.length; i++) {
+      for (let component = 0; component < attribute.size; component++) {
+        value[i * attribute.size + component] =
+          attribute.value[Number(indices[i]) * attribute.size + component];
+      }
+    }
+    attributes[name] = {...attribute, value};
+  }
+  return {attributes};
+}

package/src/lib/geometry.ts

@@ -0,0 +1,140 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TypedArray} from '@math.gl/types';
+
+export type PrimitiveTopology =
+  | 'point-list'
+  | 'line-list'
+  | 'line-strip'
+  | 'triangle-list'
+  | 'triangle-strip';
+
+export type GeometryAttribute = {
+  size?: number;
+  value: TypedArray;
+  constant?: boolean;
+  normalized?: boolean;
+  [key: string]: unknown;
+};
+
+export type GeometryAttributeInput = GeometryAttribute | TypedArray;
+export type GeometryAttributes = Record<string, GeometryAttribute | undefined> & {
+  indices?: GeometryAttribute & {size: 1; value: Uint16Array | Uint32Array};
+};
+
+export type GeometryProps = {
+  id?: string;
+  topology: PrimitiveTopology;
+  vertexCount?: number;
+  attributes: Record<string, GeometryAttributeInput>;
+  indices?: GeometryAttributeInput;
+};
+
+let geometryId = 0;
+
+/** A renderer-independent, typed-array-backed geometry container. */
+export class Geometry {
+  readonly id: string;
+  readonly topology: PrimitiveTopology;
+  readonly vertexCount: number;
+  readonly indices?: GeometryAttribute;
+  readonly attributes: Record<string, GeometryAttribute>;
+  userData: Record<string, unknown> = {};
+
+  constructor(props: GeometryProps) {
+    this.id = props.id || `geometry-${++geometryId}`;
+    this.topology = props.topology;
+    this.attributes = {};
+
+    let indices = props.indices ? normalizeAttribute(props.indices) : undefined;
+    for (const [name, input] of Object.entries(props.attributes || {})) {
+      const attribute = normalizeAttribute(input);
+      if (name === 'POSITION' || name === 'positions') {
+        attribute.size ||= 3;
+      }
+      if (name === 'indices') {
+        if (indices) throw new Error('Geometry has multiple index attributes');
+        indices = attribute;
+      } else {
+        this.attributes[name] = attribute;
+      }
+    }
+
+    if (indices) {
+      if (!(indices.value instanceof Uint16Array || indices.value instanceof Uint32Array)) {
+        throw new Error('Geometry indices must be a Uint16Array or Uint32Array');
+      }
+      indices.size = 1;
+      this.indices = indices;
+      validateIndices(indices, this.attributes);
+    }
+
+    this.vertexCount = props.vertexCount ?? calculateVertexCount(this.attributes, this.indices);
+    if (!Number.isInteger(this.vertexCount) || this.vertexCount < 0) {
+      throw new Error('Geometry vertexCount must be a non-negative integer');
+    }
+  }
+
+  getVertexCount(): number {
+    return this.vertexCount;
+  }
+
+  getAttributes(): GeometryAttributes {
+    return (
+      this.indices ? {indices: this.indices, ...this.attributes} : this.attributes
+    ) as GeometryAttributes;
+  }
+}
+
+function normalizeAttribute(input: GeometryAttributeInput): GeometryAttribute {
+  const attribute = isTypedArray(input) ? {value: input} : {...input};
+  if (!isTypedArray(attribute.value)) {
+    throw new Error('Geometry attributes must contain a typed-array value');
+  }
+  if (attribute.size !== undefined && (!Number.isInteger(attribute.size) || attribute.size < 1)) {
+    throw new Error('Geometry attribute size must be a positive integer');
+  }
+  if (attribute.size && attribute.value.length % attribute.size !== 0) {
+    throw new Error('Geometry attribute length must be divisible by its size');
+  }
+  return attribute;
+}
+
+function isTypedArray(value: unknown): value is TypedArray {
+  return ArrayBuffer.isView(value) && !(value instanceof DataView);
+}
+
+function validateIndices(
+  indices: GeometryAttribute,
+  attributes: Record<string, GeometryAttribute>
+): void {
+  let maximumIndex = -1;
+  for (const index of indices.value) maximumIndex = Math.max(maximumIndex, Number(index));
+  for (const [name, attribute] of Object.entries(attributes)) {
+    if (!attribute.constant && attribute.size) {
+      const attributeVertexCount = attribute.value.length / attribute.size;
+      if (maximumIndex >= attributeVertexCount) {
+        throw new Error(
+          `Geometry index ${maximumIndex} exceeds ${name} vertex count ${attributeVertexCount}`
+        );
+      }
+    }
+  }
+}
+
+function calculateVertexCount(
+  attributes: Record<string, GeometryAttribute>,
+  indices?: GeometryAttribute
+): number {
+  if (indices) return indices.value.length;
+  let count = Infinity;
+  for (const attribute of Object.values(attributes)) {
+    if (!attribute.constant && attribute.size) {
+      count = Math.min(count, attribute.value.length / attribute.size);
+    }
+  }
+  if (!Number.isFinite(count)) throw new Error('Geometry has no countable attributes');
+  return count;
+}