@loaders.gl/tile-converter 5.0.0-alpha.8 → 5.0.0-alpha.9

package/dist/v5/mesh-conversion.d.ts

@@ -0,0 +1,55 @@
+import type { TilesetSpatialReference } from '@loaders.gl/tiles';
+import type { MeshGeometry } from '@loaders.gl/schema';
+import type { TileConversionCodec } from './conversion-api.js';
+import type { Tiles3DConversionSpatialContext } from './spatial-conversion.js';
+import type { MeshTileMaterial } from './mesh.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;
+    /** Optional single material with an embedded base-color image, mapped explicitly by the source adapter. */
+    readonly material?: MeshTileMaterial;
+    /** 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;
+    /** Maximum Euclidean reconstruction error per vertex, in target coordinate units. */
+    readonly maxPositionError: number;
+}
+/**
+ * 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.
+ * 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 declare function createMeshConversionCodec<TInspection = unknown>(options: MeshConversionCodecOptions): TileConversionCodec<TInspection, MeshConversionInput, EncodedMeshConversionResource>;

package/dist/v5/mesh-tileset-archive.d.ts

@@ -0,0 +1,16 @@
+import type { BrowserTileConversionFile } from './browser-sink.js';
+/** Output-size budget for a single-mesh 3TZ archive. */
+export interface SingleMeshTilesetArchiveOptions {
+    /** Maximum final archive bytes, including ZIP headers and index; not peak serialization memory. */
+    readonly maxArchiveBytes: number;
+}
+/**
+ * Packages the two unmodified files from a finalized single-mesh sink as a downloadable 3TZ Blob.
+ * The writer checks the complete archive budget before reading either Blob. Applications own
+ * object-URL creation/revocation and download UI. Retained input Blobs and transient ZIP buffers
+ * are additional memory. SLPK requires separately authored I3S scene-layer resources.
+ * @param files - Files returned by a successfully finalized createSingleMeshTilesetSink.
+ * @param options - Required final archive-size budget.
+ * @returns An indexed 3TZ Blob; save with the .3tz extension.
+ */
+export declare function createSingleMeshTilesetArchive(files: readonly BrowserTileConversionFile[], options: SingleMeshTilesetArchiveOptions): Promise<Blob>;

package/dist/v5/mesh-tileset-sink.d.ts

@@ -0,0 +1,31 @@
+import type { TileConversionSink } from './conversion-api.js';
+import type { BrowserTileConversionFile } from './browser-sink.js';
+import type { EncodedMeshConversionResource } from './mesh-conversion.js';
+/** Limits and fidelity policy for one ECEF mesh tileset. */
+export interface SingleMeshTilesetSinkOptions {
+    /** Maximum combined UTF-8 tileset JSON and GLB Blob bytes retained by the sink. */
+    readonly maxTotalBytes: number;
+    /** Explicit geometric error in meters, including source error and position rounding. */
+    readonly geometricError: number;
+}
+/** A single-tile output package retained as two named browser-native Blobs. */
+export interface SingleMeshTilesetSink extends TileConversionSink<EncodedMeshConversionResource> {
+    /** Returns mesh.glb and tileset.json only after successful finalization; empty after abort. */
+    getFiles(): readonly BrowserTileConversionFile[];
+}
+/**
+ * Packages exactly one `createMeshConversionCodec` output as a 3D Tiles 1.1 tileset.
+ *
+ * Requires resolved EPSG:4978 output identified by the compact string, with ellipsoidal heights.
+ * The tile transform cancels the standard glTF y-up to z-up rotation and adds the ECEF origin.
+ * Bounds come from encoded local vertices, avoiding subtraction of large absolute coordinates.
+ * Fixed relative names keep the package deterministic. Save both files together or pass them to
+ * createSingleMeshTilesetArchive for 3TZ packaging. Applications own downloads, workers, and
+ * source-scene extraction.
+ * The byte limit bounds retained Blobs, not peak conversion/serialization memory. Input GLB and
+ * local bounds must be unmodified codec outputs; this sink does not independently validate GLB.
+ *
+ * @param options - Required retained-output budget and geometric error in meters.
+ * @returns A bounded sink that exposes files on finalization and clears them on abort.
+ */
+export declare function createSingleMeshTilesetSink(options: SingleMeshTilesetSinkOptions): SingleMeshTilesetSink;

package/dist/v5/mesh.d.ts

@@ -0,0 +1,73 @@
+import type { MeshGeometry } from '@loaders.gl/schema';
+/** Explicit glTF wrapping and filtering for the selected base-color image. */
+export interface MeshTileSampler {
+    /** Horizontal wrapping: CLAMP_TO_EDGE, MIRRORED_REPEAT, or REPEAT; omitted values use REPEAT. */
+    readonly wrapS?: 33071 | 33648 | 10497;
+    /** Vertical wrapping: CLAMP_TO_EDGE, MIRRORED_REPEAT, or REPEAT; omitted values use REPEAT. */
+    readonly wrapT?: 33071 | 33648 | 10497;
+    /** Magnification: NEAREST or LINEAR; omission leaves filtering to the renderer. */
+    readonly magFilter?: 9728 | 9729;
+    /** Minification: NEAREST, LINEAR, or a glTF mipmap filter; omission leaves filtering to the renderer. */
+    readonly minFilter?: 9728 | 9729 | 9984 | 9985 | 9986 | 9987;
+}
+/** Selected KHR_texture_transform controls for TEXCOORD_0. */
+export interface MeshTileTextureTransform {
+    /** Finite UV translation; omitted values use [0, 0]. */
+    readonly offset?: readonly [number, number];
+    /** Finite counterclockwise rotation in radians around the UV origin; omission uses 0. */
+    readonly rotation?: number;
+    /** Finite UV scale; zero and negative values are allowed, and omission uses [1, 1]. */
+    readonly scale?: readonly [number, number];
+}
+/** One already encoded base-color image using TEXCOORD_0. */
+export interface MeshTileTexture {
+    /** Encoded PNG/JPEG bytes; a typed array subview selects only its own bytes. */
+    readonly data: Uint8Array;
+    /** Declared image format, checked against the encoded header. */
+    readonly mimeType: 'image/png' | 'image/jpeg';
+    /** Optional wrapping/filtering; omission retains glTF's implicit sampler. */
+    readonly sampler?: MeshTileSampler;
+    /** Optional UV transform, preserved as a required KHR_texture_transform extension. */
+    readonly transform?: MeshTileTextureTransform;
+}
+/** One glTF metallic-roughness material, shared by every triangle in the mesh. */
+export interface MeshTileMaterial {
+    /** Linear RGBA base-color multiplier; components must be finite in [0, 1]. */
+    readonly baseColorFactor?: readonly [number, number, number, number];
+    /** Optional embedded image, multiplied by baseColorFactor and COLOR_0; requires TEXCOORD_0. */
+    readonly baseColorTexture?: MeshTileTexture;
+    /** Metallic weight in [0, 1]; omitted values use the glTF default of 1. */
+    readonly metallicFactor?: number;
+    /** Roughness weight in [0, 1]; omitted values use the glTF default of 1. */
+    readonly roughnessFactor?: number;
+    /** Alpha interpretation; omitted values use OPAQUE. */
+    readonly alphaMode?: 'OPAQUE' | 'MASK' | 'BLEND';
+    /** Finite nonnegative threshold, allowed only with MASK; omitted values use 0.5. */
+    readonly alphaCutoff?: number;
+    /** Whether both sides are rendered; omitted values use false. */
+    readonly doubleSided?: boolean;
+}
+/** Optional appearance for the single-mesh GLB profile. */
+export interface MeshTileOptions {
+    /** Explicitly selected material; other texture maps and material extensions are unsupported. */
+    readonly material?: MeshTileMaterial;
+}
+/**
+ * Encodes one triangle mesh as a self-contained glTF 2.0 GLB resource.
+ *
+ * POSITION and optional NORMAL must contain packed finite Float32 xyz triples. COLOR_0 accepts
+ * packed Float32 linear RGB/RGBA in [0, 1] or normalized Uint8/Uint16 colors per vertex.
+ * Normals must have unit length within 0.0001. TEXCOORD_0 accepts packed finite Float32
+ * or normalized Uint8/Uint16 UV pairs per vertex. Optional indices use packed unsigned
+ * 8-, 16-, or 32-bit values.
+ * Unsupported attributes, layouts, and encoded transforms fail rather than being discarded.
+ * Coordinates are preserved: callers own CRS conversion, local origins, placement, source material mapping,
+ * feature mappings, and tileset packaging. Input arrays are never modified.
+ *
+ * @param mesh - Triangle-list geometry in the caller's selected local coordinate frame.
+ * @param options - Optional single material with an already encoded base-color image.
+ * @returns An embedded-buffer GLB containing one mesh, node, and default scene.
+ */
+export declare function encodeMeshTile(mesh: MeshGeometry, options?: MeshTileOptions): ArrayBuffer;
+/** Validates the shared mesh profile; spatial preparation may retain Float64 positions internally. */
+export declare function validateMeshGeometry(mesh: MeshGeometry, allowFloat64Positions?: boolean): MeshGeometry;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loaders.gl/tile-converter",
-  "version": "5.0.0-alpha.8",
+  "version": "5.0.0-alpha.9",
   "description": "Converter",
   "license": "MIT",
   "type": "module",
@@ -63,27 +63,27 @@
     "copy-certificates": "cp -R src/v4/i3s-server/certs dist/i3s-server"
   },
   "dependencies": {
-    "@loaders.gl/3d-tiles": "5.0.0-alpha.8",
-    "@loaders.gl/compression": "5.0.0-alpha.8",
-    "@loaders.gl/crypto": "5.0.0-alpha.8",
-    "@loaders.gl/draco": "5.0.0-alpha.8",
-    "@loaders.gl/gltf": "5.0.0-alpha.8",
-    "@loaders.gl/i3s": "5.0.0-alpha.8",
-    "@loaders.gl/images": "5.0.0-alpha.8",
-    "@loaders.gl/loader-utils": "5.0.0-alpha.8",
-    "@loaders.gl/polyfills": "5.0.0-alpha.8",
-    "@loaders.gl/schema": "5.0.0-alpha.8",
-    "@loaders.gl/schema-utils": "5.0.0-alpha.8",
-    "@loaders.gl/textures": "5.0.0-alpha.8",
-    "@loaders.gl/tiles": "5.0.0-alpha.8",
-    "@loaders.gl/worker-utils": "5.0.0-alpha.8",
-    "@loaders.gl/zip": "5.0.0-alpha.8",
-    "@math.gl/core": "5.0.0-alpha.11",
-    "@math.gl/crs": "5.0.0-alpha.11",
-    "@math.gl/culling": "5.0.0-alpha.11",
-    "@math.gl/geoid": "5.0.0-alpha.11",
-    "@math.gl/geometry-utils": "5.0.0-alpha.11",
-    "@math.gl/geospatial": "5.0.0-alpha.11",
+    "@loaders.gl/3d-tiles": "5.0.0-alpha.9",
+    "@loaders.gl/compression": "5.0.0-alpha.9",
+    "@loaders.gl/crypto": "5.0.0-alpha.9",
+    "@loaders.gl/draco": "5.0.0-alpha.9",
+    "@loaders.gl/gltf": "5.0.0-alpha.9",
+    "@loaders.gl/i3s": "5.0.0-alpha.9",
+    "@loaders.gl/images": "5.0.0-alpha.9",
+    "@loaders.gl/loader-utils": "5.0.0-alpha.9",
+    "@loaders.gl/polyfills": "5.0.0-alpha.9",
+    "@loaders.gl/schema": "5.0.0-alpha.9",
+    "@loaders.gl/schema-utils": "5.0.0-alpha.9",
+    "@loaders.gl/textures": "5.0.0-alpha.9",
+    "@loaders.gl/tiles": "5.0.0-alpha.9",
+    "@loaders.gl/worker-utils": "5.0.0-alpha.9",
+    "@loaders.gl/zip": "5.0.0-alpha.9",
+    "@math.gl/core": "5.0.0-alpha.12",
+    "@math.gl/crs": "5.0.0-alpha.12",
+    "@math.gl/culling": "5.0.0-alpha.12",
+    "@math.gl/geoid": "5.0.0-alpha.12",
+    "@math.gl/geometry-utils": "5.0.0-alpha.12",
+    "@math.gl/geospatial": "5.0.0-alpha.12",
     "ajv": "^8.12.0",
     "archiver": "^5.0.0",
     "cors": "^2.8.5",
@@ -108,5 +108,5 @@
   "peerDependencies": {
     "@loaders.gl/core": "~5.0.0-alpha.0"
   },
-  "gitHead": "bdc4536ea5b7d074ea362e372704cbdb180126cc"
+  "gitHead": "c3be3766791d30e79a9aa1d9b326962f264cbbe7"
 }

package/src/v5/browser-sink.ts

@@ -27,7 +27,7 @@ export interface BrowserTileConversionFile {
 
 /** Memory limit for a browser conversion sink. */
 export interface BoundedMemoryTileConversionSinkOptions {
-  /** Maximum combined Blob size retained by this sink, in bytes. */
+  /** Maximum combined Blob size retained by this sink, captured at creation, in bytes. */
   readonly maxTotalBytes: number;
 }
 
@@ -50,7 +50,8 @@ export interface BoundedMemoryTileConversionSink
 export function createBoundedMemoryTileConversionSink(
   options: BoundedMemoryTileConversionSinkOptions
 ): BoundedMemoryTileConversionSink {
-  if (!Number.isSafeInteger(options.maxTotalBytes) || options.maxTotalBytes < 0) {
+  const {maxTotalBytes} = options;
+  if (!Number.isSafeInteger(maxTotalBytes) || maxTotalBytes < 0) {
     throw new TileConversionError(
       'INVALID_OUTPUT_MEMORY_LIMIT',
       'The browser output memory limit must be a non-negative safe integer'
@@ -85,10 +86,10 @@ export function createBoundedMemoryTileConversionSink(
       }
 
       const byteLength = resource.parts.reduce((total, part) => total + measureBlobPart(part), 0);
-      if (!Number.isSafeInteger(byteLength) || totalBytes + byteLength > options.maxTotalBytes) {
+      if (!Number.isSafeInteger(byteLength) || totalBytes + byteLength > maxTotalBytes) {
         throw new TileConversionError(
           'OUTPUT_MEMORY_LIMIT_EXCEEDED',
-          `Browser output exceeds the configured ${options.maxTotalBytes} byte memory limit`
+          `Browser output exceeds the configured ${maxTotalBytes} byte memory limit`
         );
       }
 

package/src/v5/browser.ts

@@ -52,3 +52,26 @@ export type {
   BrowserTilesetConversionSourceOptions,
   BrowserTilesetResourceDescriptor
 } from './browser-tileset-source.js';
+export {encodeMeshTile} from './mesh.js';
+export type {
+  MeshTileMaterial,
+  MeshTileOptions,
+  MeshTileTexture,
+  MeshTileSampler,
+  MeshTileTextureTransform
+} from './mesh.js';
+export {createMeshConversionCodec} from './mesh-conversion.js';
+export type {
+  MeshConversionInput,
+  EncodedMeshConversionResource,
+  MeshConversionCodecOptions
+} from './mesh-conversion.js';
+export {createTiles3DConversionSpatialContext} from './spatial-conversion.js';
+export type {Tiles3DConversionSpatialContext} from './spatial-conversion.js';
+export {createSingleMeshTilesetSink} from './mesh-tileset-sink.js';
+export type {SingleMeshTilesetSink, SingleMeshTilesetSinkOptions} from './mesh-tileset-sink.js';
+
+export {createTileConversionArchive} from './conversion-archive.js';
+export type {TileConversionArchiveOptions} from './conversion-archive.js';
+export {createSingleMeshTilesetArchive} from './mesh-tileset-archive.js';
+export type {SingleMeshTilesetArchiveOptions} from './mesh-tileset-archive.js';

package/src/v5/conversion-archive.ts

@@ -0,0 +1,51 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Tiles3DArchiveWriter} from '@loaders.gl/3d-tiles/3d-tiles-archive-writer';
+import {SLPKWriter} from '@loaders.gl/i3s/i3s-slpk-writer';
+import {TileConversionError} from './conversion-api.js';
+import type {BrowserTileConversionFile} from './browser-sink.js';
+
+/** Output profile and required budget for packaging finalized conversion resources. */
+export interface TileConversionArchiveOptions {
+  /** Archive format; resources must already use the selected format's layout and encoding. */
+  readonly format: '3tz' | 'slpk';
+  /** Maximum final archive bytes, including headers/index; not peak serialization memory. */
+  readonly maxArchiveBytes: number;
+}
+
+/**
+ * Packages finalized, already-authored resources as a bounded 3TZ or SLPK Blob.
+ * 3TZ requires tileset.json; SLPK requires 3dSceneLayer.json.gz and precompressed I3S resources.
+ * Selecting an archive format does not convert geometry, metadata, or coordinate systems.
+ * Applications own input qualification, object URLs, and downloads. Inputs must remain unchanged.
+ * @param files - Unmodified files from a successfully finalized browser sink.
+ * @param options - Archive format and complete output-size budget.
+ * @returns Archive Blob to save using the selected .3tz or .slpk extension.
+ */
+export async function createTileConversionArchive(
+  files: readonly BrowserTileConversionFile[],
+  options: TileConversionArchiveOptions
+): Promise<Blob> {
+  const {format, maxArchiveBytes} = options;
+  if (!Number.isSafeInteger(maxArchiveBytes) || maxArchiveBytes < 0) {
+    throw new TileConversionError(
+      'INVALID_ARCHIVE_BYTE_LIMIT',
+      'Archive byte limit must be a non-negative safe integer'
+    );
+  }
+  if (format !== '3tz' && format !== 'slpk') {
+    throw new TileConversionError('INVALID_ARCHIVE_FORMAT', 'Expected 3tz or slpk archive format');
+  }
+  const resources = Object.fromEntries(files.map(file => [file.resourceId, file.blob]));
+  if (Object.keys(resources).length !== files.length) {
+    throw new TileConversionError(
+      'DUPLICATE_ARCHIVE_RESOURCE',
+      'Archive resource identifiers must be unique'
+    );
+  }
+  const writer = format === '3tz' ? Tiles3DArchiveWriter : SLPKWriter;
+  const archive = await writer.encode(resources, {[format]: {maxArchiveBytes}});
+  return new Blob([archive], {type: writer.mimeTypes[0]});
+}

package/src/v5/index.ts

@@ -45,3 +45,24 @@ export type {
   TileResourceManifestEntry,
   TileResourceManifestStore
 } from './resource-manifest.js';
+export {encodeMeshTile} from './mesh.js';
+export type {
+  MeshTileMaterial,
+  MeshTileOptions,
+  MeshTileTexture,
+  MeshTileSampler,
+  MeshTileTextureTransform
+} from './mesh.js';
+export {createMeshConversionCodec} from './mesh-conversion.js';
+export type {
+  MeshConversionInput,
+  EncodedMeshConversionResource,
+  MeshConversionCodecOptions
+} from './mesh-conversion.js';
+export {createSingleMeshTilesetSink} from './mesh-tileset-sink.js';
+export type {SingleMeshTilesetSink, SingleMeshTilesetSinkOptions} from './mesh-tileset-sink.js';
+
+export {createTileConversionArchive} from './conversion-archive.js';
+export type {TileConversionArchiveOptions} from './conversion-archive.js';
+export {createSingleMeshTilesetArchive} from './mesh-tileset-archive.js';
+export type {SingleMeshTilesetArchiveOptions} from './mesh-tileset-archive.js';

package/src/v5/mesh-conversion.ts

@@ -0,0 +1,177 @@
+// 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 {TileConversionError} from './conversion-api.js';
+import type {TileConversionCodec} from './conversion-api.js';
+import type {Tiles3DConversionSpatialContext} from './spatial-conversion.js';
+import {encodeMeshTile, validateMeshGeometry} from './mesh.js';
+import type {MeshTileMaterial} from './mesh.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;
+  /** Optional single material with an embedded base-color image, mapped explicitly by the source adapter. */
+  readonly material?: MeshTileMaterial;
+  /** 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;
+  /** Maximum Euclidean reconstruction error per vertex, in target coordinate units. */
+  readonly maxPositionError: number;
+}
+
+/**
+ * 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.
+ * 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} = options;
+  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 targetPositions = spatialContext.transformPositions(sourcePositions);
+      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'
+        );
+      }
+      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];
+          localMinimum[axis] = Math.min(localMinimum[axis], localPositions[index + axis]);
+          localMaximum[axis] = Math.max(localMaximum[axis], localPositions[index + axis]);
+          const reconstructed = localPositions[index + axis] + origin[axis];
+          minimum[axis] = Math.min(minimum[axis], reconstructed);
+          maximum[axis] = Math.max(maximum[axis], reconstructed);
+        }
+        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: spatialContext.transformNormals(geometry.attributes.NORMAL.value, sourcePositions),
+          size: 3
+        };
+      }
+      const glb = encodeMeshTile(geometry, {material: resource.material});
+      signal?.throwIfAborted();
+      yield {
+        id: resource.id,
+        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-tileset-archive.ts

@@ -0,0 +1,48 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Tiles3DArchiveWriter} from '@loaders.gl/3d-tiles/3d-tiles-archive-writer';
+import {TileConversionError} from './conversion-api.js';
+import type {BrowserTileConversionFile} from './browser-sink.js';
+
+/** Output-size budget for a single-mesh 3TZ archive. */
+export interface SingleMeshTilesetArchiveOptions {
+  /** Maximum final archive bytes, including ZIP headers and index; not peak serialization memory. */
+  readonly maxArchiveBytes: number;
+}
+
+/**
+ * Packages the two unmodified files from a finalized single-mesh sink as a downloadable 3TZ Blob.
+ * The writer checks the complete archive budget before reading either Blob. Applications own
+ * object-URL creation/revocation and download UI. Retained input Blobs and transient ZIP buffers
+ * are additional memory. SLPK requires separately authored I3S scene-layer resources.
+ * @param files - Files returned by a successfully finalized createSingleMeshTilesetSink.
+ * @param options - Required final archive-size budget.
+ * @returns An indexed 3TZ Blob; save with the .3tz extension.
+ */
+export async function createSingleMeshTilesetArchive(
+  files: readonly BrowserTileConversionFile[],
+  options: SingleMeshTilesetArchiveOptions
+): Promise<Blob> {
+  const {maxArchiveBytes} = options;
+  if (!Number.isSafeInteger(maxArchiveBytes) || maxArchiveBytes < 0) {
+    throw new TileConversionError(
+      'INVALID_ARCHIVE_BYTE_LIMIT',
+      'Archive byte limit must be a non-negative safe integer'
+    );
+  }
+  if (
+    files.length !== 2 ||
+    !files.some(file => file.resourceId === 'mesh.glb') ||
+    !files.some(file => file.resourceId === 'tileset.json')
+  ) {
+    throw new TileConversionError(
+      'INVALID_SINGLE_MESH_ARCHIVE',
+      'Expected mesh.glb and tileset.json from a finalized single-mesh sink'
+    );
+  }
+  const resources = Object.fromEntries(files.map(file => [file.resourceId, file.blob]));
+  const archive = await Tiles3DArchiveWriter.encode(resources, {'3tz': {maxArchiveBytes}});
+  return new Blob([archive], {type: Tiles3DArchiveWriter.mimeTypes[0]});
+}