@loaders.gl/tile-converter 5.0.0-alpha.1 → 5.0.0-alpha.11

package/src/v5/mesh-conversion.ts

@@ -0,0 +1,230 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {getSpatialCoordinateFrame} from '@loaders.gl/tiles';
+import type {TilesetSpatialReference} from '@loaders.gl/tiles';
+import type {MeshGeometry} from '@loaders.gl/schema';
+import type {LoadLibraryOptions} from '@loaders.gl/worker-utils';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import type {TileConversionCodec} from '@loaders.gl/tile-converter/v5/core';
+import type {
+  Tiles3DConversionSpatialContext,
+  I3SConversionSpatialContext
+} from '@loaders.gl/tile-converter/v5/core';
+import {encodeMeshTile, validateMeshGeometry} from './mesh.js';
+import type {MeshTileFeatures} from './mesh-features.js';
+import type {MeshTileMaterial} from './mesh.js';
+import {encodeDracoMeshTile} from './mesh-draco.js';
+
+/** Explicitly selected geometry, with positions already in the spatial context's source frame. */
+export interface MeshConversionInput {
+  /** Caller-owned resource identifier, forwarded to the output sink. */
+  readonly id: string;
+  /** Triangle geometry with absolute packed Float32 or Float64 source positions. */
+  readonly mesh: MeshGeometry;
+  /** Original I3S vector basis; overrides the codec default when supplied by a source. */
+  readonly normalReferenceFrame?: 'earth-centered' | 'vertex-reference-frame';
+  /** Optional single material with an embedded base-color image, mapped explicitly by the source adapter. */
+  readonly material?: MeshTileMaterial;
+  /** Explicit feature table and triangle associations, written as structural metadata. */
+  readonly features?: MeshTileFeatures;
+  /** Finite xyz origin in the target frame, subtracted before float32 encoding. */
+  readonly origin: readonly [number, number, number];
+}
+
+/** A completed GLB resource and the metadata needed to place its local geometry. */
+export interface EncodedMeshConversionResource {
+  /** Caller-owned resource identifier. */
+  readonly id: string;
+  /** Self-contained GLB with local positions and transformed normals. */
+  readonly glb: ArrayBuffer;
+  /** Target-frame translation to add to the encoded positions. */
+  readonly origin: readonly [number, number, number];
+  /** Target-frame bounds of the reconstructed encoded vertices, including float32 rounding. */
+  readonly boundingBox: readonly [readonly number[], readonly number[]];
+  /** Bounds of encoded local vertices before adding the origin, without absolute-coordinate cancellation. */
+  readonly localBoundingBox: readonly [readonly number[], readonly number[]];
+  /** Metadata describing the output coordinate operation and height reference. */
+  readonly spatialReference: TilesetSpatialReference;
+  /** Largest measured Euclidean reconstruction error in target coordinate units. */
+  readonly maximumPositionError: number;
+}
+
+/** Spatial policy used by the concrete mesh conversion codec. */
+export interface MeshConversionCodecOptions {
+  /** Shared context that accepts absolute source positions and returns absolute target positions. */
+  readonly spatialContext: Tiles3DConversionSpatialContext | I3SConversionSpatialContext;
+  /** I3S vector frame when using an I3S context; defaults to earth-centered. */
+  readonly normalReferenceFrame?: 'earth-centered' | 'vertex-reference-frame';
+  /** Rebase around the transformed bounds center instead of the resource's explicit origin. */
+  readonly autoOrigin?: boolean;
+  /** Maximum Euclidean reconstruction error per vertex, in target coordinate units. */
+  readonly maxPositionError: number;
+  /** Lossless Draco Edge Breaker is enabled by default; false emits uncompressed GLB geometry. */
+  readonly draco?: boolean;
+  /** Optional local/CDN library locations or injected Draco runtimes for compression and verification. */
+  readonly dracoLibraryOptions?: LoadLibraryOptions;
+}
+
+/**
+ * Creates a concrete mesh codec for `convertTileset`.
+ *
+ * Source adapters must select geometry and apply source placement before supplying absolute
+ * positions and matching normals. This codec applies the supplied spatial context once, rebases
+ * around each input's target origin, and rejects rounding above the explicit error budget.
+ * Lossless Draco Edge Breaker is enabled by default; decoded positions determine output bounds.
+ * Set draco to false for uncompressed geometry. Quantization is not enabled by this profile.
+ * Geographic and unknown output frames are rejected. The returned origin/bounds/reference are
+ * external placement metadata; applications own axis conventions, hierarchy, and packaging.
+ * Input arrays are not mutated. Core input/output byte gates, cancellation, awaited writes, and
+ * destination finalize/abort handling apply when used through `convertTileset`.
+ *
+ * @param options - Resolved spatial context and finite nonnegative target-unit precision budget.
+ * @returns One GLB and matching metadata per input geometry.
+ */
+export function createMeshConversionCodec<TInspection = unknown>(
+  options: MeshConversionCodecOptions
+): TileConversionCodec<TInspection, MeshConversionInput, EncodedMeshConversionResource> {
+  const {spatialContext, maxPositionError, draco = true, dracoLibraryOptions} = options;
+  if (typeof draco !== 'boolean') {
+    throw new TileConversionError('MESH_DRACO_OPTIONS_INVALID', 'draco must be a boolean');
+  }
+  if (!Number.isFinite(maxPositionError) || maxPositionError < 0) {
+    throw new TileConversionError(
+      'MESH_PRECISION_LIMIT_INVALID',
+      'maxPositionError must be finite and nonnegative'
+    );
+  }
+  const spatialReference = spatialContext.spatialReference;
+  const outputCrs = spatialReference.targetCrs || spatialReference.sourceCrs;
+  const outputFrame =
+    spatialReference.status === 'native'
+      ? spatialReference.coordinateFrame
+      : outputCrs
+        ? getSpatialCoordinateFrame(outputCrs)
+        : 'unknown';
+  if (
+    !['native', 'transformed'].includes(spatialReference.status) ||
+    !['projected', 'geocentric', 'local', 'cartesian'].includes(outputFrame)
+  ) {
+    throw new TileConversionError(
+      'MESH_OUTPUT_FRAME_UNSUPPORTED',
+      'Mesh output requires a resolved Cartesian coordinate frame'
+    );
+  }
+  return {
+    /** Prepares and encodes one geometry while honoring cancellation. */
+    async *convert(resource, _inspection, signal) {
+      signal?.throwIfAborted();
+      const geometry = validateMeshGeometry(resource.mesh, true);
+      const sourcePositions = geometry.attributes.POSITION.value;
+      const origin: [number, number, number] = [...resource.origin];
+      if (origin.length !== 3 || origin.some(value => !Number.isFinite(value))) {
+        throw new TileConversionError(
+          'MESH_ORIGIN_INVALID',
+          'Target origin must contain three finite coordinates'
+        );
+      }
+      const transformed =
+        'transformGeometryAsync' in spatialContext
+          ? await spatialContext.transformGeometryAsync(
+              sourcePositions,
+              geometry.attributes.NORMAL?.value,
+              resource.normalReferenceFrame ?? options.normalReferenceFrame
+            )
+          : {
+              positions: spatialContext.transformPositions(sourcePositions),
+              normals: geometry.attributes.NORMAL
+                ? spatialContext.transformNormals(geometry.attributes.NORMAL.value, sourcePositions)
+                : undefined
+            };
+      signal?.throwIfAborted();
+      const targetPositions = transformed.positions;
+      if (
+        targetPositions.length !== sourcePositions.length ||
+        targetPositions.some(value => !Number.isFinite(value))
+      ) {
+        throw new TileConversionError(
+          'MESH_TRANSFORM_INVALID',
+          'Spatial transformation must return one finite xyz position per vertex'
+        );
+      }
+      if (options.autoOrigin) {
+        const minimum = [Infinity, Infinity, Infinity];
+        const maximum = [-Infinity, -Infinity, -Infinity];
+        for (let index = 0; index < targetPositions.length; index++) {
+          const axis = index % 3;
+          minimum[axis] = Math.min(minimum[axis], targetPositions[index]);
+          maximum[axis] = Math.max(maximum[axis], targetPositions[index]);
+        }
+        for (let axis = 0; axis < 3; axis++) origin[axis] = minimum[axis] / 2 + maximum[axis] / 2;
+      }
+      const localPositions = new Float32Array(targetPositions.length);
+      const minimum = [Infinity, Infinity, Infinity];
+      const maximum = [-Infinity, -Infinity, -Infinity];
+      const localMinimum = [Infinity, Infinity, Infinity];
+      const localMaximum = [-Infinity, -Infinity, -Infinity];
+      let maximumPositionError = 0;
+      for (let index = 0; index < targetPositions.length; index += 3) {
+        for (let axis = 0; axis < 3; axis++) {
+          localPositions[index + axis] = targetPositions[index + axis] - origin[axis];
+        }
+        const positionError = Math.hypot(
+          localPositions[index] + origin[0] - targetPositions[index],
+          localPositions[index + 1] + origin[1] - targetPositions[index + 1],
+          localPositions[index + 2] + origin[2] - targetPositions[index + 2]
+        );
+        if (!Number.isFinite(positionError) || positionError > maxPositionError) {
+          throw new TileConversionError(
+            'MESH_POSITION_PRECISION_EXCEEDED',
+            'Float32 mesh positions exceed the configured reconstruction error budget'
+          );
+        }
+        maximumPositionError = Math.max(maximumPositionError, positionError);
+      }
+      geometry.attributes.POSITION = {value: localPositions, size: 3};
+      if (geometry.attributes.NORMAL) {
+        geometry.attributes.NORMAL = {
+          value: transformed.normals!,
+          size: 3
+        };
+      }
+      const appearance = {material: resource.material, features: resource.features};
+      const encoded = draco
+        ? await encodeDracoMeshTile(geometry, appearance, dracoLibraryOptions)
+        : {glb: encodeMeshTile(geometry, appearance), positions: localPositions};
+      signal?.throwIfAborted();
+      for (let index = 0; index < encoded.positions.length; index++) {
+        const axis = index % 3;
+        const position = encoded.positions[index];
+        localMinimum[axis] = Math.min(localMinimum[axis], position);
+        localMaximum[axis] = Math.max(localMaximum[axis], position);
+        minimum[axis] = Math.min(minimum[axis], position + origin[axis]);
+        maximum[axis] = Math.max(maximum[axis], position + origin[axis]);
+      }
+      yield {
+        id: resource.id,
+        glb: encoded.glb,
+        origin,
+        boundingBox: [minimum, maximum],
+        localBoundingBox: [localMinimum, localMaximum],
+        spatialReference,
+        maximumPositionError
+      };
+    },
+    /** Reports position rounding authorized by the configured precision budget. */
+    async validateOutput(resource) {
+      return resource.maximumPositionError > 0
+        ? [
+            {
+              code: 'MESH_POSITION_ROUNDING',
+              message: `Encoded positions have up to ${resource.maximumPositionError} target-unit reconstruction error`,
+              severity: 'info' as const,
+              resourceId: resource.id
+            }
+          ]
+        : [];
+    }
+  };
+}

package/src/v5/mesh-draco.ts

@@ -0,0 +1,182 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {DracoLoader, encodeDraco, type DracoMesh} from '@loaders.gl/draco';
+import type {GLTFAccessor} from '@loaders.gl/gltf';
+import type {MeshGeometry} from '@loaders.gl/schema';
+import type {LoadLibraryOptions} from '@loaders.gl/worker-utils';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import {
+  createMeshTileScenegraph,
+  finalizeMeshTileScenegraph,
+  type MeshTileOptions,
+  validateMeshGeometry
+} from './mesh.js';
+
+import {prepareMeshFeatureGeometry, encodeMeshFeatures} from './mesh-features.js';
+
+const DRACO_EXTENSION = 'KHR_draco_mesh_compression';
+
+/** Encodes the validated single-mesh profile with lossless Edge Breaker and no raw fallback. */
+export async function encodeDracoMeshTile(
+  geometry: MeshGeometry,
+  options: MeshTileOptions,
+  libraryOptions: LoadLibraryOptions = {}
+): Promise<{glb: ArrayBuffer; positions: Float32Array}> {
+  geometry = prepareMeshFeatureGeometry(validateMeshGeometry(geometry), options.features);
+  // Draco requires explicit faces even when the input triangle list is non-indexed.
+  if (!geometry.indices) {
+    geometry.indices = {
+      size: 1,
+      value: Uint32Array.from(
+        {length: geometry.attributes.POSITION.value.length / 3},
+        (_, index) => index
+      )
+    };
+  }
+  const {modules, useLocalLibraries, CDN: contentDeliveryNetwork} = libraryOptions;
+  const runtimeOptions = {modules, core: {useLocalLibraries, CDN: contentDeliveryNetwork}};
+  const {scenegraph, materialIndex} = createMeshTileScenegraph(options, geometry);
+  const encoded = await encodeDraco(geometry, {
+    ...runtimeOptions,
+    draco: {method: 'MESH_EDGEBREAKER_ENCODING'}
+  });
+  const loaderOptions = {...runtimeOptions, draco: {shape: 'mesh' as const}};
+  const loader = await DracoLoader.preload('', loaderOptions);
+  const decoded = (await loader.parse!(encoded.data, loaderOptions)) as DracoMesh;
+  const positions = decoded.attributes.POSITION.value;
+  if (
+    !(positions instanceof Float32Array) ||
+    positions.length !== encoded.report.pointCount * 3 ||
+    encoded.report.pointCount === 0 ||
+    !decoded.indices ||
+    decoded.indices.value.length !== encoded.report.faceCount * 3 ||
+    encoded.report.faceCount * 3 !==
+      (geometry.indices?.value.length ?? geometry.attributes.POSITION.value.length / 3)
+  ) {
+    throw new TileConversionError(
+      'MESH_DRACO_ENCODING_INVALID',
+      'Draco must preserve the triangle count and emit finite positions'
+    );
+  }
+  // Lossy quantization is deliberately unavailable in this initial profile.
+  const inputPositions = geometry.attributes.POSITION.value;
+  const positionKeys = new Set<string>();
+  for (let index = 0; index < inputPositions.length; index += 3) {
+    positionKeys.add(getPositionKey(inputPositions, index));
+  }
+  for (let index = 0; index < positions.length; index += 3) {
+    if (!positionKeys.has(getPositionKey(positions, index))) {
+      throw new TileConversionError(
+        'MESH_DRACO_POSITION_CHANGED',
+        'Lossless Draco must preserve the encoded Float32 positions'
+      );
+    }
+  }
+  if (JSON.stringify(getMeshTriangles(geometry)) !== JSON.stringify(getMeshTriangles(decoded))) {
+    throw new TileConversionError(
+      'MESH_DRACO_ATTRIBUTE_CHANGED',
+      'Lossless Draco must preserve oriented triangles and every attribute, including feature ownership'
+    );
+  }
+  const bufferView = scenegraph.addBufferView(encoded.data);
+  const attributes: Record<string, number> = {};
+  const attributeIdentifiers: Record<string, number> = {};
+  scenegraph.json.accessors = [];
+  for (const [name, attribute] of Object.entries(geometry.attributes)) {
+    const decodedAttribute = decoded.attributes[name];
+    if (
+      !decodedAttribute ||
+      decodedAttribute.value.length !== encoded.report.pointCount * attribute.size
+    ) {
+      throw new TileConversionError('MESH_DRACO_ENCODING_INVALID', `Draco must preserve ${name}`);
+    }
+    const accessor: GLTFAccessor = {
+      componentType:
+        attribute.value instanceof Uint8Array
+          ? 5121
+          : attribute.value instanceof Uint16Array
+            ? 5123
+            : attribute.value instanceof Uint32Array
+              ? 5125
+              : 5126,
+      count: encoded.report.pointCount,
+      type:
+        attribute.size === 1
+          ? 'SCALAR'
+          : attribute.size === 2
+            ? 'VEC2'
+            : attribute.size === 3
+              ? 'VEC3'
+              : 'VEC4',
+      ...(attribute.normalized ? {normalized: true} : {})
+    };
+    if (name === 'POSITION') {
+      const minimum = [Infinity, Infinity, Infinity];
+      const maximum = [-Infinity, -Infinity, -Infinity];
+      for (let index = 0; index < positions.length; index++) {
+        const axis = index % 3;
+        minimum[axis] = Math.min(minimum[axis], positions[index]);
+        maximum[axis] = Math.max(maximum[axis], positions[index]);
+      }
+      accessor.min = minimum;
+      accessor.max = maximum;
+    }
+    attributes[name] = scenegraph.json.accessors.push(accessor) - 1;
+    attributeIdentifiers[name] = encoded.report.attributes[name].id;
+  }
+  const indices =
+    scenegraph.json.accessors.push({
+      componentType: decoded.indices.value instanceof Uint16Array ? 5123 : 5125,
+      count: encoded.report.faceCount * 3,
+      type: 'SCALAR'
+    }) - 1;
+  scenegraph.json.meshes = [
+    {
+      primitives: [
+        {
+          attributes,
+          indices,
+          mode: 4,
+          ...(materialIndex === undefined ? {} : {material: materialIndex}),
+          extensions: {[DRACO_EXTENSION]: {bufferView, attributes: attributeIdentifiers}}
+        }
+      ]
+    }
+  ];
+  encodeMeshFeatures(scenegraph, 0, options.features);
+  scenegraph.registerRequiredExtension(DRACO_EXTENSION);
+  return {glb: finalizeMeshTileScenegraph(scenegraph, 0), positions};
+}
+
+/** Identifies one exact finite Float32 position independently of Draco vertex ordering. */
+function getPositionKey(positions: ArrayLike<number>, index: number): string {
+  return `${positions[index]},${positions[index + 1]},${positions[index + 2]}`;
+}
+
+/** Compares oriented triangles independently of vertex/face order, retaining every attribute. */
+function getMeshTriangles(mesh: Pick<MeshGeometry, 'attributes' | 'indices'>): string[] {
+  const names = Object.keys(mesh.attributes).sort();
+  const indices = mesh.indices!.value;
+  const triangles: string[] = [];
+  for (let index = 0; index < indices.length; index += 3) {
+    const vertices = [0, 1, 2].map(corner =>
+      names
+        .map(name => {
+          const attribute = mesh.attributes[name];
+          return Array.from(
+            {length: attribute.size},
+            (_, component) => attribute.value[indices[index + corner] * attribute.size + component]
+          ).join(',');
+        })
+        .join('|')
+    );
+    triangles.push(
+      [0, 1, 2]
+        .map(corner => [...vertices.slice(corner), ...vertices.slice(0, corner)].join(';'))
+        .sort()[0]
+    );
+  }
+  return triangles.sort();
+}