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

package/src/v5/mesh-source.ts

@@ -3,14 +3,10 @@
 // Copyright (c) vis.gl contributors
 
 import {Matrix4} from '@math.gl/core';
-import type {MeshAttribute} from '@loaders.gl/schema';
-import type {
-  GLTFPostprocessed,
-  GLTFNodePostprocessed,
-  GLTFMeshPrimitivePostprocessed,
-  GLTFMaterialPostprocessed
-} from '@loaders.gl/gltf';
-import type {Tileset3D, TilesetSourceMetadata} from '@loaders.gl/tiles';
+import type {MeshAttribute} from '@loaders.gl/core/schema';
+import type {GLTFWithBuffers, GLTFMeshPrimitive, GLTFMaterial} from '@loaders.gl/gltf';
+import {getGLTFAccessor, getGLTFAccessorValue} from '@loaders.gl/gltf';
+import type {Tileset3D, TilesetSourceMetadata} from '@loaders.gl/tiles-3d';
 import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
 import type {TileConversionSource} from '@loaders.gl/tile-converter/v5/core';
 import {createTilesetConversionSource} from '@loaders.gl/tile-converter/v5/core';
@@ -21,19 +17,22 @@ import {validateMeshGeometry, validateMeshIndices} from './mesh.js';
 import {resolveMeshSourceTexture} from './mesh-source-texture.js';
 import {extractMeshFeatures} from './mesh-source-features.js';
 import type {MeshSourceFeatureOptions} from './mesh-source-features.js';
-import type {I3SMeshFeatures} from '@loaders.gl/i3s';
+import type {MeshSourceSchemaOptions} from './mesh-source-schema.js';
+import type {I3SMeshFeatures} from '@loaders.gl/tiles-3d/i3s';
 export type {MeshSourceFeatureOptions} from './mesh-source-features.js';
 
 /** Source mesh with optional explicit-schema feature data and triangle association. */
 export interface MeshSourceResource extends MeshConversionInput {
   /** Arrow features associated with the selected primitive; IDs are distinct from table row indices. */
   readonly features?: I3SMeshFeatures;
+  /** Original I3S layer semantics, retained for destination policy and diagnostics. */
+  readonly sourceLayerType?: '3DObject' | 'IntegratedMesh';
 }
 
 /** Narrow source profile and content lifetime controls. */
 export interface MeshTilesetSourceOptions extends TilesetConversionSourceOptions {
-  /** Required when the source has batch/structural metadata; no schema is inferred. */
-  readonly features?: MeshSourceFeatureOptions;
+  /** Required for feature-bearing content; omit schema only to map an inline structural metadata class. */
+  readonly features?: MeshSourceFeatureOptions | MeshSourceSchemaOptions;
   /** Explicit bounded reader for external encoded images, relative to the content URI. */
   readonly readExternalResource?: (
     uri: string,
@@ -47,7 +46,7 @@ export interface MeshTilesetSourceOptions extends TilesetConversionSourceOptions
  * optional buffer-view or base64 data-URI PNG/JPEG images, TEXCOORD_0, glTF sampling and
  * KHR_texture_transform controls on TEXCOORD_0. Decode content with
  * `gltf.excludeExtensions: {KHR_texture_transform: false}` to retain authored UVs/transforms.
- * Triangle strips are expanded with alternating winding; the glTF loader already expands fans.
+ * Triangle strips are expanded with alternating winding; fans are expanded explicitly at the mesh boundary.
  * Shared traversal retains placement identity and unloads content according to the supplied policy.
  * The adapter applies node transforms, glTF up-axis correction, RTC translation, and tile placement
  * once, retaining Float64 absolute positions and inverse-transpose unit normals. Animation, skins,
@@ -117,7 +116,7 @@ export function createMeshTilesetConversionSource(
               'Content metadata requires a separate mapping'
             );
           const payload = content.payload as {
-            gltf?: GLTFPostprocessed;
+            gltf?: GLTFWithBuffers;
             gltfUpAxis?: string;
             rtcCenter?: number[];
             type?: string;
@@ -134,7 +133,8 @@ export function createMeshTilesetConversionSource(
               'Mesh extraction requires decoded GLB/glTF or B3DM content'
             );
           }
-          const gltf = payload.gltf;
+          const gltfWithBuffers = payload.gltf;
+          const gltf = gltfWithBuffers.json;
           if (
             gltf.animations?.length ||
             gltf.skins?.length ||
@@ -151,7 +151,9 @@ export function createMeshTilesetConversionSource(
           if (!['X', 'Y', 'Z'].includes(axis))
             throw new TileConversionError('MESH_SOURCE_AXIS_UNSUPPORTED', 'Unknown glTF up axis');
           const placement = new Matrix4(item.tile.computedTransform);
-          const rtc = payload.rtcCenter || gltf.extensions?.CESIUM_RTC?.center;
+          const rtc =
+            payload.rtcCenter ||
+            (gltf.extensions?.CESIUM_RTC as {center?: number[]} | undefined)?.center;
           if (rtc) {
             if (rtc.length !== 3 || rtc.some((value: number) => !Number.isFinite(value)))
               throw new TileConversionError(
@@ -165,15 +167,21 @@ export function createMeshTilesetConversionSource(
           if (axis === 'X')
             placement.multiplyRight(new Matrix4([0, 0, 1, 0, 0, 1, 0, 0, -1, 0, 0, 0, 0, 0, 0, 1]));
           const roots =
-            gltf.scene?.nodes || (gltf.scenes?.length === 1 ? gltf.scenes[0].nodes : undefined);
+            (gltf.scene !== undefined ? gltf.scenes?.[gltf.scene]?.nodes : undefined) ||
+            (gltf.scenes?.length === 1 ? gltf.scenes[0].nodes : undefined);
           if (!roots?.length)
             throw new TileConversionError(
               'MESH_SOURCE_SCENE_UNSUPPORTED',
               'A default scene or exactly one scene is required'
             );
           let primitiveIndex = 0;
-          for (const selected of traverseMeshNodes(roots, placement)) {
+          const primitives = traverseMeshNodes(gltfWithBuffers, roots, placement);
+          let current = primitives.next();
+          while (!current.done) {
+            const selected = current.value;
+            const next = primitives.next();
             const resource = await extractPrimitive(
+              gltfWithBuffers,
               selected.primitive,
               selected.transform,
               `${item.tile.id}/${content.index}/${primitiveIndex++}`,
@@ -182,13 +190,18 @@ export function createMeshTilesetConversionSource(
               signal
             );
             const features = extractMeshFeatures(
-              gltf,
+              gltfWithBuffers,
               selected.primitive,
               payload,
               resource.mesh,
               options.features
             );
-            yield {...resource, features};
+            yield {
+              ...resource,
+              features,
+              contentPrimitive: {index: primitiveIndex - 1, last: Boolean(next.done)}
+            };
+            current = next;
           }
           if (!primitiveIndex)
             throw new TileConversionError(
@@ -201,16 +214,19 @@ export function createMeshTilesetConversionSource(
   };
 }
 
-/** Walks scene placements without deduplicating a shared mesh or mutating postprocessed nodes. */
+/** Walks scene placements without deduplicating a shared mesh or mutating source nodes. */
 function* traverseMeshNodes(
-  nodes: readonly GLTFNodePostprocessed[],
+  gltf: GLTFWithBuffers,
+  nodes: readonly number[],
   parent: Matrix4,
-  ancestors = new Set<GLTFNodePostprocessed>()
-): Generator<{primitive: GLTFMeshPrimitivePostprocessed; transform: Matrix4}> {
-  for (const node of nodes) {
+  ancestors = new Set<number>()
+): Generator<{primitive: GLTFMeshPrimitive; transform: Matrix4}> {
+  for (const nodeIndex of nodes) {
+    const node = gltf.json.nodes![nodeIndex];
     if (
-      ancestors.has(node) ||
-      node.skin ||
+      !node ||
+      ancestors.has(nodeIndex) ||
+      node.skin !== undefined ||
       node.weights ||
       Object.keys(node.extensions || {}).length
     )
@@ -226,21 +242,28 @@ function* traverseMeshNodes(
             .multiplyRight(new Matrix4().fromQuaternion(node.rotation || [0, 0, 0, 1]))
             .scale(node.scale || [1, 1, 1])
     );
-    if (node.mesh) {
-      if (node.mesh.weights || Object.keys(node.mesh.extensions || {}).length)
+    if (node.mesh !== undefined) {
+      const mesh = gltf.json.meshes![node.mesh];
+      if (mesh.weights || Object.keys(mesh.extensions || {}).length)
         throw new TileConversionError(
           'MESH_SOURCE_NODE_UNSUPPORTED',
           'Morph weights and mesh extensions are unsupported'
         );
-      for (const primitive of node.mesh.primitives) yield {primitive, transform};
+      for (const primitive of mesh.primitives) yield {primitive, transform};
     }
-    yield* traverseMeshNodes(node.children || [], transform, new Set([...ancestors, node]));
+    yield* traverseMeshNodes(
+      gltf,
+      node.children || [],
+      transform,
+      new Set([...ancestors, nodeIndex])
+    );
   }
 }
 
 /** Copies one packed primitive, places it once, and derives a useful ECEF local origin. */
 async function extractPrimitive(
-  primitive: GLTFMeshPrimitivePostprocessed,
+  gltf: GLTFWithBuffers,
+  primitive: GLTFMeshPrimitive,
   transform: Matrix4,
   id: string,
   readExternalResource: MeshTilesetSourceOptions['readExternalResource'],
@@ -268,7 +291,8 @@ async function extractPrimitive(
       'Mesh placement requires a finite invertible affine transform with positive determinant'
     );
   const attributes: Record<string, MeshAttribute> = {};
-  for (const [name, accessor] of Object.entries(primitive.attributes)) {
+  for (const [name, reference] of Object.entries(primitive.attributes)) {
+    const accessor = getGLTFAccessor(gltf, reference);
     if (name === '_BATCHID' || /^_FEATURE_ID_\d+$/.test(name)) continue;
     if (!['POSITION', 'NORMAL', 'COLOR_0', 'TEXCOORD_0'].includes(name))
       throw new TileConversionError(
@@ -276,17 +300,17 @@ async function extractPrimitive(
         `Unsupported mesh attribute ${name}`
       );
     attributes[name] = {
-      value: accessor.value as MeshAttribute['value'],
-      size: accessor.components,
+      value: getGLTFAccessorValue(gltf, reference) as MeshAttribute['value'],
+      size: accessor.type === 'SCALAR' ? 1 : Number(accessor.type.slice(3)),
       ...(accessor.normalized ? {normalized: true} : {})
     };
   }
   const mesh = validateMeshGeometry(
     {
       topology: 'triangle-list',
-      mode: primitive.mode === 5 ? 4 : (primitive.mode ?? 4),
+      mode: [5, 6].includes(primitive.mode ?? 4) ? 4 : (primitive.mode ?? 4),
       attributes,
-      indices: createTriangleIndices(primitive, (attributes.POSITION?.value.length ?? 0) / 3)
+      indices: createTriangleIndices(gltf, primitive, (attributes.POSITION?.value.length ?? 0) / 3)
     },
     true
   );
@@ -324,20 +348,22 @@ async function extractPrimitive(
     mesh,
     origin: minimum.map((value, axis) => value / 2 + maximum[axis] / 2) as [number, number, number],
     material: await mapMeshSourceMaterial(
-      primitive.material,
+      primitive.material === undefined ? undefined : gltf.json.materials?.[primitive.material],
       readExternalResource,
       contentUri,
-      signal
+      signal,
+      gltf
     )
   };
 }
 
 /** Maps supported PBR controls and an embedded base-color image, rejecting unmapped semantics. */
 export async function mapMeshSourceMaterial(
-  material: GLTFMaterialPostprocessed | undefined,
+  material: GLTFMaterial | undefined,
   readExternalResource: MeshTilesetSourceOptions['readExternalResource'],
   contentUri: string | undefined,
-  signal?: AbortSignal
+  signal: AbortSignal | undefined,
+  gltf: GLTFWithBuffers
 ): Promise<MeshTileMaterial | undefined> {
   if (!material) return undefined;
   const pbr = material.pbrMetallicRoughness;
@@ -372,6 +398,7 @@ export async function mapMeshSourceMaterial(
     ...('baseColorTexture' in (pbr || {})
       ? {
           baseColorTexture: await resolveMeshSourceTexture(
+            gltf,
             pbr!.baseColorTexture,
             readExternalResource,
             contentUri,
@@ -389,17 +416,20 @@ export async function mapMeshSourceMaterial(
 
 /** Expands a strip without changing vertex storage, feature IDs, source indices, or parity. */
 function createTriangleIndices(
-  primitive: GLTFMeshPrimitivePostprocessed,
+  gltf: GLTFWithBuffers,
+  primitive: GLTFMeshPrimitive,
   vertexCount: number
 ): MeshAttribute | undefined {
-  const attribute = primitive.indices
+  const accessor =
+    primitive.indices === undefined ? undefined : getGLTFAccessor(gltf, primitive.indices);
+  const attribute = accessor
     ? {
-        value: primitive.indices.value as MeshAttribute['value'],
-        size: primitive.indices.components,
-        normalized: primitive.indices.normalized
+        value: getGLTFAccessorValue(gltf, accessor) as MeshAttribute['value'],
+        size: 1,
+        normalized: accessor.normalized
       }
     : undefined;
-  if (primitive.mode !== 5) return attribute;
+  if (primitive.mode !== 5 && primitive.mode !== 6) return attribute;
   const sourceIndices = validateMeshIndices(attribute, vertexCount, 5);
   const indexCount = sourceIndices?.length ?? vertexCount;
   if (!Number.isSafeInteger(indexCount) || indexCount < 3) {
@@ -412,9 +442,10 @@ function createTriangleIndices(
   const indices = new IndexArray((indexCount - 2) * 3);
   for (let triangle = 0; triangle < indexCount - 2; triangle++) {
     // Match the glTF strip equation, including degenerate connectors; they advance parity too.
-    const second = triangle + 1 + (triangle % 2);
-    const third = triangle + 2 - (triangle % 2);
-    indices[triangle * 3] = sourceIndices?.[triangle] ?? triangle;
+    const second = primitive.mode === 6 ? triangle + 1 : triangle + 1 + (triangle % 2);
+    const third = primitive.mode === 6 ? triangle + 2 : triangle + 2 - (triangle % 2);
+    const first = primitive.mode === 6 ? 0 : triangle;
+    indices[triangle * 3] = sourceIndices?.[first] ?? first;
     indices[triangle * 3 + 1] = sourceIndices?.[second] ?? second;
     indices[triangle * 3 + 2] = sourceIndices?.[third] ?? third;
   }

package/src/v5/mesh-tileset-archive.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {Tiles3DArchiveWriter} from '@loaders.gl/3d-tiles/3d-tiles-archive-writer';
+import {Tiles3DArchiveWriter} from '@loaders.gl/tiles-3d/3d-tiles/3d-tiles-archive-writer';
 import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
 import type {BrowserTileConversionFile} from '@loaders.gl/tile-converter/v5/core';
 

package/src/v5/mesh-tileset-sink.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {Tiles3DTilesetJSON, Tiles3DTileJSON} from '@loaders.gl/3d-tiles';
+import type {Tiles3DTilesetJSON, Tiles3DTileJSON} from '@loaders.gl/tiles-3d/3d-tiles';
 import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
 import type {TileConversionSink} from '@loaders.gl/tile-converter/v5/core';
 import {createBoundedMemoryTileConversionSink} from '@loaders.gl/tile-converter/v5/core';
@@ -96,7 +96,7 @@ export function createSingleMeshTilesetSink(
 }
 
 /** Builds placement and local bounds for a trusted single-mesh codec output. */
-function createMeshTileset(
+export function createMeshTileset(
   resource: EncodedMeshConversionResource,
   geometricError: number
 ): Omit<Tiles3DTilesetJSON, 'root'> & {root: Omit<Tiles3DTileJSON, 'children'>} {

package/src/v5/mesh.ts

@@ -4,7 +4,7 @@
 
 import {GLTFScenegraph, GLTFWriter} from '@loaders.gl/gltf';
 import {getBinaryImageMetadata} from '@loaders.gl/images';
-import type {MeshAttribute, MeshGeometry} from '@loaders.gl/schema';
+import type {MeshAttribute, MeshGeometry} from '@loaders.gl/core/schema';
 import {
   prepareMeshFeatureGeometry,
   encodeMeshFeatures,

package/src/v5/node-cli.ts

@@ -0,0 +1,201 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {parseArgs} from 'node:util';
+import {readFeatureSchema} from './node-feature-schema.js';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import {createNodeTilesetConversionSource, NODE_TILESET_LIMITS} from './node-source.js';
+import type {NodeTileConversionOutputFormat} from './node-conversion.js';
+
+/** Text destinations supplied by the process wrapper or a hermetic caller. */
+export interface TileConverterCLIOutput {
+  /** Writes a complete JSON result or help text. */
+  readonly stdout: (text: string) => void;
+  /** Writes a JSON error without contaminating stdout. */
+  readonly stderr: (text: string) => void;
+}
+
+/** Usage for bounded metadata inspection and selected static mesh conversion. */
+const HELP = `Usage: tile-converter-v5 inspect|convert|validate <input path or URL> [options]
+
+  --input-format 3d-tiles|3tz|i3s|slpk  Explicit input format (default: 3d-tiles)
+  --geometric-error N        Required source error in meters for I3S to 3D Tiles
+  --integrated-mesh-policy as-3d-object  Authorize I3S layer-type change
+  --preserve-hierarchy        Retain a complete explicit 3D Tiles tree (3D Tiles/3TZ only)
+  --feature-schema PATH       Local JSON feature class/schema mapping (at most 64 KiB)
+  --resource ID               Selected content placement; repeat for multiple selections
+  --output-format 3d-tiles|3tz|slpk  Target profile (default: 3tz)
+  --output PATH               New destination (required for convert, forbidden for validate)
+  --max-input-bytes N          Lower the 16 MiB input/read budget
+  --max-resources N            Lower the 1,000 content-declaration limit
+  --max-documents N            Lower the 32 metadata-document limit
+  --max-output-bytes N         Lower the 32 MiB output/archive budget
+  --profile                   Include elapsed conversion stage timings in JSON
+  --help                      Show this help
+
+Inspect reads metadata only, following declared .json external tilesets.
+Convert/validate require explicit selections; I3S uses declared CRS and shared spatial preparation.
+Validate decodes, converts and packages the selected target profile without writing files.
+Output defaults to a partial flat mesh collection. --preserve-hierarchy requires every declared content.
+Remote archives require HTTP 206 ranges and a stable ETag or Last-Modified validator.
+I3S inspect lists leaf nodes; feature-bearing conversion requires --feature-schema.
+Hierarchy mode supports at most 32 document placements, 256 tiles and 64 total mesh primitive placements, including ordered 1.1 contents arrays.
+`;
+
+/** Runs a bounded v5 operation, returning an exit code after source/output cleanup. */
+export async function runTileConverterCLI(
+  argumentsList: string[],
+  output: TileConverterCLIOutput,
+  signal?: AbortSignal
+): Promise<number> {
+  try {
+    const {values, positionals} = parseArgs({
+      args: argumentsList,
+      allowPositionals: true,
+      options: {
+        help: {type: 'boolean'},
+        profile: {type: 'boolean'},
+        'preserve-hierarchy': {type: 'boolean'},
+        'input-format': {type: 'string', default: '3d-tiles'},
+        'max-input-bytes': {type: 'string', default: String(NODE_TILESET_LIMITS.maxInputBytes)},
+        'max-resources': {type: 'string', default: String(NODE_TILESET_LIMITS.maxInputResources)},
+        'max-documents': {type: 'string', default: String(NODE_TILESET_LIMITS.maxTilesetDocuments)},
+        'max-output-bytes': {type: 'string', default: String(32 * 1024 * 1024)},
+        'output-format': {type: 'string', default: '3tz'},
+        output: {type: 'string'},
+        resource: {type: 'string', multiple: true},
+        'feature-schema': {type: 'string'},
+        'geometric-error': {type: 'string'},
+        'integrated-mesh-policy': {type: 'string'}
+      }
+    });
+    if (values.help || !argumentsList.length) {
+      output.stdout(HELP);
+      return 0;
+    }
+    if (
+      positionals.length !== 2 ||
+      !['inspect', 'convert', 'validate'].includes(positionals[0]) ||
+      !['3d-tiles', '3tz', 'i3s', 'slpk'].includes(values['input-format'])
+    )
+      throw new TileConversionError(
+        'CLI_USAGE_ERROR',
+        'Use inspect, convert or validate with one input and --input-format 3d-tiles, 3tz, i3s or slpk'
+      );
+    const format = values['input-format'] as '3d-tiles' | '3tz' | 'i3s' | 'slpk';
+    const operation = positionals[0];
+    const sourceOptions = {
+      input: positionals[1],
+      format,
+      signal,
+      maxInputBytes: parseLimit(values['max-input-bytes']),
+      maxInputResources: parseLimit(values['max-resources']),
+      maxTilesetDocuments: parseLimit(values['max-documents']),
+      inspectNestedTilesets: true
+    };
+    if (operation !== 'inspect') {
+      if (
+        !values.resource?.length ||
+        !['3d-tiles', '3tz', 'slpk'].includes(values['output-format']) ||
+        (operation === 'convert' ? !values.output : values.output !== undefined)
+      )
+        throw new TileConversionError(
+          'CLI_USAGE_ERROR',
+          'Convert/validate require --resource selections and a supported --output-format; only convert requires --output'
+        );
+      if (
+        values['integrated-mesh-policy'] !== undefined &&
+        values['integrated-mesh-policy'] !== 'as-3d-object'
+      )
+        throw new TileConversionError(
+          'CLI_USAGE_ERROR',
+          'Use --integrated-mesh-policy as-3d-object'
+        );
+      const features =
+        values['feature-schema'] === undefined
+          ? undefined
+          : await readFeatureSchema(
+              values['feature-schema'],
+              format === 'i3s' || format === 'slpk',
+              signal
+            );
+      const {convertNodeTileset} = await import('./node-conversion.js');
+      const report = await convertNodeTileset({
+        ...sourceOptions,
+        ...features,
+        resourceIds: values.resource,
+        profile: values.profile,
+        preserveHierarchy: values['preserve-hierarchy'],
+        outputFormat: values['output-format'] as NodeTileConversionOutputFormat,
+        output: values.output,
+        maxOutputBytes: parseLimit(values['max-output-bytes']),
+        geometricError:
+          values['geometric-error'] === undefined
+            ? undefined
+            : parseGeometricError(values['geometric-error']),
+        integratedMeshPolicy: values['integrated-mesh-policy'] as 'as-3d-object' | undefined
+      });
+      output.stdout(
+        `${JSON.stringify({operation, input: positionals[1], inputFormat: format, outputFormat: values['output-format'], ...(values.output ? {output: values.output} : {}), report}, null, 2)}\n`
+      );
+      return 0;
+    }
+    if (
+      values.profile !== undefined ||
+      values['feature-schema'] !== undefined ||
+      values['preserve-hierarchy'] !== undefined ||
+      values['geometric-error'] !== undefined ||
+      values['integrated-mesh-policy'] !== undefined ||
+      values.resource ||
+      values.output ||
+      values['output-format'] !== '3tz' ||
+      values['max-output-bytes'] !== String(32 * 1024 * 1024)
+    )
+      throw new TileConversionError(
+        'CLI_USAGE_ERROR',
+        'Inspect does not accept conversion/output options'
+      );
+    const source =
+      format === 'i3s' || format === 'slpk'
+        ? await (await import('./node-i3s-source.js')).createNodeI3SConversionSource({
+            ...sourceOptions,
+            format
+          })
+        : await createNodeTilesetConversionSource({...sourceOptions, format});
+    const inspection = await source.inspect(signal).finally(() => source.close());
+    output.stdout(
+      `${JSON.stringify({operation: 'inspect', input: positionals[1], inputFormat: format, ...inspection}, null, 2)}\n`
+    );
+    return 0;
+  } catch (error) {
+    output.stderr(
+      `${JSON.stringify({
+        code: error instanceof Error && 'code' in error ? error.code : 'CONVERSION_FAILED',
+        message: error instanceof Error ? error.message : String(error),
+        diagnostics: error instanceof TileConversionError ? error.diagnostics : []
+      })}\n`
+    );
+    return 1;
+  }
+}
+
+/** Parses a positive decimal byte/count limit without accepting fractional or infinite values. */
+function parseLimit(value: string): number {
+  if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value)))
+    throw new TileConversionError(
+      'CLI_USAGE_ERROR',
+      'Limits must be positive safe decimal integers'
+    );
+  return Number(value);
+}
+
+/** Parses an explicit metric source error without inferring I3S screen-size semantics. */
+function parseGeometricError(value: string): number {
+  if (!/^(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(value) || !Number.isFinite(Number(value)))
+    throw new TileConversionError(
+      'CLI_USAGE_ERROR',
+      'Geometric error must be a finite nonnegative number in meters'
+    );
+  return Number(value);
+}