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

package/src/v5/mesh-source-features.ts

@@ -7,6 +7,8 @@ import type {GLTFPostprocessed, GLTFMeshPrimitivePostprocessed} from '@loaders.g
 import type {I3SMeshFeatures} from '@loaders.gl/i3s';
 import {convertFeatureAttributesToArrowBatches} from './feature-arrow.js';
 import type {FeatureArrowBatchOptions} from './feature-arrow.js';
+import {createMeshSourceFeatureOptions} from './mesh-source-schema.js';
+import type {MeshSourceSchemaOptions} from './mesh-source-schema.js';
 import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
 
 /** Explicit source feature mapping; target type changes must be authorized separately. */
@@ -29,7 +31,7 @@ export function extractMeshFeatures(
     featureTableJson?: Record<string, unknown>;
   },
   mesh: MeshGeometry,
-  options?: MeshSourceFeatureOptions
+  options?: MeshSourceFeatureOptions | MeshSourceSchemaOptions
 ): I3SMeshFeatures | undefined {
   const declarations = primitive.extensions?.EXT_mesh_features?.featureIds;
   const metadata = gltf.extensions?.EXT_structural_metadata;
@@ -51,13 +53,14 @@ export function extractMeshFeatures(
   if (!options)
     throw new TileConversionError(
       'MESH_FEATURE_SCHEMA_REQUIRED',
-      'Feature extraction requires an explicit Arrow schema and class mapping'
+      'Feature extraction requires a class selection and a declared Arrow or inline source schema'
     );
   if (!options.metadataClass)
     throw new TileConversionError(
       'MESH_FEATURE_CLASS_REQUIRED',
       'Feature metadata class must be explicit'
     );
+  const mapping = 'schema' in options ? options : createMeshSourceFeatureOptions(gltf, options);
   let count: number;
   let attribute = legacy;
   let properties: Record<string, ArrayLike<unknown>>;
@@ -94,6 +97,17 @@ export function extractMeshFeatures(
         'Feature class and declared table counts must agree'
       );
     count = table.count;
+    // Qualified mesh writers require every feature row to own geometry. Check before defaults allocate.
+    if (
+      !Number.isSafeInteger(count) ||
+      count <= 0 ||
+      count > mesh.attributes.POSITION.value.length / 3
+    ) {
+      throw new TileConversionError(
+        'MESH_FEATURE_IDS_INVALID',
+        'Feature row count exceeds the available mesh vertices'
+      );
+    }
     properties = {};
     const classProperties = metadata.schema?.classes?.[table.class]?.properties;
     if (!classProperties)
@@ -110,6 +124,7 @@ export function extractMeshFeatures(
       string,
       {
         type: string;
+        required?: boolean;
         componentType?: string;
         array?: boolean;
         noData?: unknown;
@@ -141,18 +156,35 @@ export function extractMeshFeatures(
           `Property ${name} requires a separately qualified semantic mapping`
         );
       const data = column?.data;
-      if (data === undefined && property.default === undefined)
+      if (
+        (column !== undefined && (data === undefined || data === null)) ||
+        (data === undefined && property.required === true)
+      )
         throw new TileConversionError(
           'MESH_FEATURE_PROPERTY_UNAVAILABLE',
           `Property ${name} has not been decoded`
         );
-      const decoded = data ?? Array.from({length: count}, () => property.default);
+      const integer64 = ['INT64', 'UINT64'].includes(property.componentType || '');
+      if (
+        integer64 &&
+        property.default !== undefined &&
+        (typeof property.default !== 'number' || !Number.isSafeInteger(property.default))
+      ) {
+        throw new TileConversionError(
+          'MESH_FEATURE_PROPERTY_UNSUPPORTED',
+          `Property ${name} requires an exact 64-bit default`
+        );
+      }
+      const defaultValue =
+        integer64 && property.default !== undefined
+          ? BigInt(property.default as number)
+          : (property.default ?? null);
+      const decoded = data ?? Array.from({length: count}, () => defaultValue);
       if (property.noData === undefined || data === undefined) {
         properties[name] = decoded;
         continue;
       }
       const sentinel = property.noData;
-      const integer64 = ['INT64', 'UINT64'].includes(property.componentType || '');
       if (
         (property.type === 'STRING'
           ? typeof sentinel !== 'string'
@@ -169,7 +201,7 @@ export function extractMeshFeatures(
         );
       const comparable = integer64 ? BigInt(sentinel as number) : sentinel;
       properties[name] = Array.from(decoded as ArrayLike<unknown>, value =>
-        value === comparable ? (property.default ?? null) : value
+        value === comparable ? defaultValue : value
       );
     }
   } else {
@@ -237,7 +269,7 @@ export function extractMeshFeatures(
           .map(([name, values]) => [name, values[index]])
       )
     })),
-    options
+    mapping
   );
   const indices = mesh.indices?.value;
   const triangleFeatureIndices = new Uint32Array((indices?.length ?? vertexCount) / 3);

package/src/v5/mesh-source-schema.ts

@@ -0,0 +1,134 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GLTFPostprocessed, GLTF_EXT_structural_metadata_ClassProperty} from '@loaders.gl/gltf';
+import type {DataType, Field} from '@loaders.gl/schema';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import type {MeshSourceFeatureOptions} from './mesh-source-features.js';
+
+/** Class and identifier selection for a mapping derived from an inline glTF schema. */
+export type MeshSourceSchemaOptions = Omit<MeshSourceFeatureOptions, 'schema' | 'rawMetadataField'>;
+
+/** Declared scalar storage widths; no property values participate in type selection. */
+const SCALAR_TYPES: Readonly<Record<string, DataType>> = {
+  INT8: 'int8',
+  UINT8: 'uint8',
+  INT16: 'int16',
+  UINT16: 'uint16',
+  INT32: 'int32',
+  UINT32: 'uint32',
+  INT64: 'int64',
+  UINT64: 'uint64',
+  FLOAT32: 'float32',
+  FLOAT64: 'float64'
+};
+
+/**
+ * Builds an explicit Arrow mapping from one inline structural-metadata class and property table.
+ * Scalar widths, strings and optional/default/noData declarations are retained. The caller selects
+ * the class and stable identifier property; otherwise identifiers are uint32 table row indices.
+ * Arrays, enums, vectors, transformed numeric properties and external schemas fail explicitly.
+ * This does not authorize destination type changes or loss of source class semantics.
+ */
+export function createMeshSourceFeatureOptions(
+  gltf: GLTFPostprocessed,
+  options: MeshSourceSchemaOptions
+): MeshSourceFeatureOptions {
+  const metadata = gltf.extensions?.EXT_structural_metadata;
+  const table = metadata?.propertyTables?.[0];
+  const properties = metadata?.schema?.classes?.[options.metadataClass]?.properties;
+  if (
+    !options.metadataClass ||
+    metadata?.propertyTables?.length !== 1 ||
+    table?.class !== options.metadataClass ||
+    !properties ||
+    !Number.isSafeInteger(table.count) ||
+    table.count < 1 ||
+    table.count > 0xffffffff ||
+    metadata.propertyTextures?.length ||
+    metadata.propertyAttributes?.length
+  ) {
+    throw new TileConversionError(
+      'MESH_FEATURE_SCHEMA_REQUIRED',
+      'Schema mapping requires one inline class, one matching property table and a positive uint32 row count'
+    );
+  }
+  if (Object.keys(table.properties || {}).some(name => !Object.hasOwn(properties, name))) {
+    throw new TileConversionError(
+      'MESH_FEATURE_PROPERTY_UNMAPPED',
+      'Property table columns must be declared in the selected class'
+    );
+  }
+  const fields: Field[] = Object.entries(properties).map(([name, property]) => {
+    const declaration = property as GLTF_EXT_structural_metadata_ClassProperty;
+    const column = table.properties?.[name];
+    if (
+      declaration.array ||
+      !['SCALAR', 'STRING'].includes(declaration.type) ||
+      declaration.normalized ||
+      declaration.offset !== undefined ||
+      declaration.scale !== undefined ||
+      column?.offset !== undefined ||
+      column?.scale !== undefined ||
+      (declaration.required &&
+        (declaration.noData !== undefined || declaration.default !== undefined))
+    ) {
+      throw new TileConversionError(
+        'MESH_FEATURE_PROPERTY_UNSUPPORTED',
+        `Property ${name} requires an explicit separately qualified mapping`
+      );
+    }
+    const type =
+      declaration.type === 'STRING'
+        ? 'utf8'
+        : Object.hasOwn(SCALAR_TYPES, declaration.componentType || '')
+          ? SCALAR_TYPES[declaration.componentType!]
+          : undefined;
+    if (!type) {
+      throw new TileConversionError(
+        'MESH_FEATURE_PROPERTY_UNSUPPORTED',
+        `Property ${name} has no supported declared scalar width`
+      );
+    }
+    return {
+      name,
+      type,
+      nullable: declaration.required !== true,
+      metadata: {'loaders.gl:structural-property': JSON.stringify(declaration)}
+    };
+  });
+  const identifierName = options.featureIdField || 'feature_id';
+  const sourceIdentifier = options.sourceFeatureIdProperty;
+  const sourceField = sourceIdentifier
+    ? fields.find(field => field.name === sourceIdentifier)
+    : undefined;
+  if (
+    (sourceIdentifier && !sourceField) ||
+    fields.some(field => field.name === identifierName && field !== sourceField) ||
+    (sourceField &&
+      !['utf8', 'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'int64', 'uint64'].includes(
+        String(sourceField.type)
+      ))
+  ) {
+    throw new TileConversionError(
+      'MESH_FEATURE_ID_PROPERTY_REQUIRED',
+      'Select a declared string/integer identifier and a distinct output identifier name'
+    );
+  }
+  return {
+    ...options,
+    schema: {
+      fields: [
+        {
+          ...sourceField,
+          name: identifierName,
+          type: sourceField?.type || 'uint32',
+          nullable: false
+        },
+        ...fields.filter(field => field !== sourceField)
+      ],
+      metadata: {'loaders.gl:source-schema': JSON.stringify(metadata.schema)}
+    }
+  };
+}

package/src/v5/mesh-source.ts

@@ -21,6 +21,7 @@ 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 {MeshSourceSchemaOptions} from './mesh-source-schema.js';
 import type {I3SMeshFeatures} from '@loaders.gl/i3s';
 export type {MeshSourceFeatureOptions} from './mesh-source-features.js';
 
@@ -28,12 +29,14 @@ export type {MeshSourceFeatureOptions} from './mesh-source-features.js';
 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,
@@ -172,7 +175,11 @@ export function createMeshTilesetConversionSource(
               'A default scene or exactly one scene is required'
             );
           let primitiveIndex = 0;
-          for (const selected of traverseMeshNodes(roots, placement)) {
+          const primitives = traverseMeshNodes(roots, placement);
+          let current = primitives.next();
+          while (!current.done) {
+            const selected = current.value;
+            const next = primitives.next();
             const resource = await extractPrimitive(
               selected.primitive,
               selected.transform,
@@ -188,7 +195,12 @@ export function createMeshTilesetConversionSource(
               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(

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

@@ -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/node-cli.ts

@@ -0,0 +1,197 @@
+// 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
+  --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'},
+        '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,
+        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['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);
+}