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

package/src/v5/i3s-mesh-source-material.ts

@@ -0,0 +1,157 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {I3STileContent, I3STileHeader} from '@loaders.gl/i3s';
+import type {GLTFMaterialPostprocessed} from '@loaders.gl/gltf';
+import {getBinaryImageMetadata} from '@loaders.gl/images';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import type {MeshTilesetSourceOptions} from './mesh-source.js';
+import {mapMeshSourceMaterial} from './mesh-source.js';
+import type {MeshTileMaterial} from './mesh.js';
+
+/** Maps normalized I3S factors and one encoded base-color PNG/JPEG with explicit wrapping. */
+export async function mapI3SMeshSourceMaterial(
+  content: I3STileContent,
+  header: Partial<I3STileHeader>,
+  readExternalResource: MeshTilesetSourceOptions['readExternalResource'],
+  contentUri: string | undefined,
+  signal?: AbortSignal
+): Promise<MeshTileMaterial | undefined> {
+  const material = Object.fromEntries(
+    Object.entries(content.material || {}).filter(([, value]) => value !== undefined)
+  );
+  const metallicRoughness = material.pbrMetallicRoughness
+    ? Object.fromEntries(
+        Object.entries(material.pbrMetallicRoughness).filter(([, value]) => value !== undefined)
+      )
+    : {};
+  material.pbrMetallicRoughness = metallicRoughness;
+  if (material.cullFace !== undefined && material.cullFace !== 'back') {
+    throw new TileConversionError(
+      'I3S_MESH_SOURCE_MATERIAL_UNSUPPORTED',
+      'Only back-face culling is supported'
+    );
+  }
+  delete material.cullFace;
+  let textureInfo = metallicRoughness.baseColorTexture
+    ? {...(metallicRoughness.baseColorTexture as Record<string, unknown>)}
+    : undefined;
+  const resources = header.textureUrls?.length
+    ? header.textureUrls
+    : header.textureUrl
+      ? [
+          {
+            textureSetDefinitionId: textureInfo?.textureSetDefinitionId ?? 0,
+            textureUrl: header.textureUrl,
+            textureFormat: header.textureFormat || 'jpg'
+          }
+        ]
+      : [];
+  // Legacy singleton textures without a material definition are implicit base-color maps.
+  if (!textureInfo && !header.materialDefinition && resources.length === 1) {
+    textureInfo = {textureSetDefinitionId: resources[0].textureSetDefinitionId};
+  }
+  const encodedTextures = content.textures || {};
+  if (
+    !textureInfo &&
+    (resources.length || content.texture || Object.keys(encodedTextures).length)
+  ) {
+    throw new TileConversionError(
+      'I3S_MESH_SOURCE_TEXTURE_UNSUPPORTED',
+      'Texture resources require a base-color mapping'
+    );
+  }
+  if (textureInfo) {
+    const definitionId = textureInfo.textureSetDefinitionId;
+    const wrappingModes: Record<string, number> = {none: 33071, repeat: 10497, mirror: 33648};
+    if (
+      typeof definitionId !== 'number' ||
+      !Number.isSafeInteger(definitionId) ||
+      definitionId < 0 ||
+      (textureInfo.texCoord !== undefined && textureInfo.texCoord !== 0) ||
+      Object.keys(textureInfo).some(
+        name => !['textureSetDefinitionId', 'texCoord', 'wrapS', 'wrapT', 'texture'].includes(name)
+      ) ||
+      (['wrapS', 'wrapT'] as const).some(
+        name =>
+          textureInfo![name] !== undefined &&
+          (typeof textureInfo![name] !== 'string' ||
+            !Object.hasOwn(wrappingModes, textureInfo![name] as string))
+      ) ||
+      resources.length > 1 ||
+      resources.some(resource => resource.textureSetDefinitionId !== definitionId) ||
+      Object.keys(encodedTextures).some(key => key !== String(definitionId))
+    ) {
+      throw new TileConversionError(
+        'I3S_MESH_SOURCE_TEXTURE_UNSUPPORTED',
+        'Only one base-color texture set on TEXCOORD_0 with qualified wrapping is supported'
+      );
+    }
+    let encoded =
+      encodedTextures[String(definitionId)] ||
+      content.texture ||
+      (textureInfo.texture as {source?: {image?: unknown}} | undefined)?.source?.image;
+    if (!encoded) {
+      if (!resources.length || !readExternalResource) {
+        throw new TileConversionError(
+          'I3S_MESH_SOURCE_TEXTURE_UNSUPPORTED',
+          'Encoded texture bytes or an explicit bounded resource reader are required'
+        );
+      }
+      signal?.throwIfAborted();
+      encoded = await readExternalResource(resources[0].textureUrl, contentUri, signal);
+      signal?.throwIfAborted();
+    }
+    const data = encoded instanceof ArrayBuffer ? new Uint8Array(encoded) : encoded;
+    let image;
+    if (data instanceof Uint8Array) {
+      try {
+        image = getBinaryImageMetadata(new DataView(data.buffer, data.byteOffset, data.byteLength));
+      } catch {
+        /* Reject malformed or compressed image resources below. */
+      }
+    }
+    const declaredFormat = resources[0]?.textureFormat;
+    if (
+      !image ||
+      !['image/png', 'image/jpeg'].includes(image.mimeType) ||
+      (declaredFormat &&
+        (declaredFormat === 'png'
+          ? image.mimeType !== 'image/png'
+          : declaredFormat === 'jpg'
+            ? image.mimeType !== 'image/jpeg'
+            : true))
+    ) {
+      throw new TileConversionError(
+        'I3S_MESH_SOURCE_TEXTURE_UNSUPPORTED',
+        'I3S base-color bytes must have matching PNG/JPEG headers'
+      );
+    }
+    const sampler = Object.fromEntries(
+      ['wrapS', 'wrapT']
+        .filter(name => textureInfo![name] !== undefined)
+        .map(name => [name, wrappingModes[textureInfo![name] as string]])
+    );
+    metallicRoughness.baseColorTexture = {
+      texCoord: 0,
+      texture: {
+        source: {mimeType: image.mimeType, bufferView: {data}},
+        ...(Object.keys(sampler).length ? {sampler} : {})
+      }
+    };
+  }
+  const mapped = await mapMeshSourceMaterial(
+    material as GLTFMaterialPostprocessed,
+    undefined,
+    contentUri,
+    signal
+  );
+  if (mapped?.baseColorTexture && !content.sourceAttributes?.uv0) {
+    throw new TileConversionError(
+      'MESH_TEXCOORD_REQUIRED',
+      'Base-color textures require TEXCOORD_0'
+    );
+  }
+  return mapped;
+}

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

@@ -0,0 +1,227 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {I3STileContent, I3SMeshFeatures} from '@loaders.gl/i3s';
+import type {
+  Tileset3D,
+  TilesetSourceMetadata,
+  TilesetContentTraversalItem
+} from '@loaders.gl/tiles';
+import {
+  TileConversionError,
+  createTilesetConversionSource
+} from '@loaders.gl/tile-converter/v5/core';
+import type {
+  TileConversionSource,
+  TilesetConversionSourceOptions
+} from '@loaders.gl/tile-converter/v5/core';
+import type {MeshSourceResource} from './mesh-source.js';
+import type {MeshTilesetSourceOptions} from './mesh-source.js';
+import {mapI3SMeshSourceMaterial} from './i3s-mesh-source-material.js';
+import {extractI3SMeshFeatures} from './i3s-mesh-source-features.js';
+import type {I3SMeshSourceFeatureOptions} from './i3s-mesh-source-features.js';
+import {validateMeshGeometry} from './mesh.js';
+export type {I3SMeshSourceFeatureOptions} from './i3s-mesh-source-features.js';
+
+/** Selected I3S triangle, encoded base-color appearance and explicit-schema feature profile. */
+export interface I3SMeshTilesetSourceOptions extends TilesetConversionSourceOptions {
+  /** Read scalar/string attribute resources with an explicit schema and geometry OID mapping. */
+  readonly features?: I3SMeshSourceFeatureOptions;
+  /** Application-owned bounded reader, including archive resolution, authentication and decompression. */
+  readonly readExternalResource?: MeshTilesetSourceOptions['readExternalResource'];
+  /** Custom alternative to features, for source semantics outside the scalar resource profile. */
+  readonly getFeatures?: (
+    content: I3STileContent,
+    item: TilesetContentTraversalItem,
+    metadata: TilesetSourceMetadata,
+    signal?: AbortSignal
+  ) => I3SMeshFeatures | Promise<I3SMeshFeatures>;
+}
+
+/**
+ * Reads original absolute I3S positions through camera-independent traversal.
+ * Use a dedicated runtime with i3s.geometryMode='source'. The shared I3S spatial codec owns
+ * units, elevation and reprojection; this source never consumes renderer placement matrices.
+ * Pair the GLB codec with autoOrigin=true, or select an explicit target origin on the resources.
+ * Positions/normals/TEXCOORD_0, basic PBR factors and one encoded PNG/JPEG base-color texture
+ * are supported. Vertex colors, UV regions, additional attributes and segmentation fail explicitly.
+ * Features require an explicit schema/resource reader or a custom Arrow mapper.
+ * Unsafe decoded numeric geometry identifiers are rejected; exact property IDs use bigint.
+ * @param tileset - Dedicated I3S runtime using source-coordinate content decoding.
+ * @param options - Feature mapping and lifetime policy for content loaded during traversal.
+ * @returns A portable source of one absolute mesh per I3S node content.
+ */
+export function createI3SMeshTilesetConversionSource(
+  tileset: Tileset3D,
+  options: I3SMeshTilesetSourceOptions = {}
+): TileConversionSource<TilesetSourceMetadata, MeshSourceResource> {
+  const source = createTilesetConversionSource(tileset, options);
+  return {
+    /** Validates the layer profile and explicit source decode policy before reading. */
+    async inspect(signal) {
+      if (options.features && options.getFeatures) {
+        throw new TileConversionError(
+          'I3S_MESH_SOURCE_FEATURE_MAPPING_REQUIRED',
+          'Choose explicit resource features or a custom getFeatures mapper, not both'
+        );
+      }
+      const metadata = await source.inspect(signal);
+      if (
+        metadata.type !== 'I3S' ||
+        !['3DObject', 'IntegratedMesh'].includes(metadata.tileset.layerType) ||
+        tileset.options.i3s?.geometryMode !== 'source'
+      ) {
+        throw new TileConversionError(
+          'I3S_MESH_SOURCE_PROFILE_UNSUPPORTED',
+          'I3S mesh extraction requires a 3DObject/IntegratedMesh runtime with geometryMode=source'
+        );
+      }
+      if (!metadata.spatialReference?.sourceCrs) {
+        throw new TileConversionError(
+          'I3S_MESH_SOURCE_REFERENCE_REQUIRED',
+          'I3S conversion requires an explicit source CRS'
+        );
+      }
+      return metadata;
+    },
+    /** Converts each supported content entry before shared traversal releases its buffers. */
+    async *read(metadata, signal) {
+      for await (const item of source.read(metadata, signal)) {
+        for (const entry of item.contents) {
+          signal?.throwIfAborted();
+          const content = entry.payload as I3STileContent;
+          const attributes = content?.sourceAttributes;
+          if (
+            content?.geometryMode !== 'source' ||
+            content.topology !== 'triangle-list' ||
+            !attributes ||
+            !(attributes.position?.value instanceof Float64Array) ||
+            content.spatialReference?.status !== 'native' ||
+            (
+              [
+                'sourceCrs',
+                'verticalCrs',
+                'axisOrder',
+                'units',
+                'verticalUnitScale',
+                'heightReference',
+                'elevationMode',
+                'elevationOffset',
+                'elevationUnitScale',
+                'coordinateEpoch'
+              ] as const
+            ).some(
+              field =>
+                JSON.stringify(content.spatialReference?.[field]) !==
+                JSON.stringify(metadata.spatialReference?.[field])
+            )
+          ) {
+            throw new TileConversionError(
+              'I3S_MESH_SOURCE_GEOMETRY_UNSUPPORTED',
+              'I3S extraction requires original source-frame Float64 triangle geometry'
+            );
+          }
+          if (
+            !['earth-centered', 'vertex-reference-frame'].includes(
+              content.normalReferenceFrame || ''
+            ) ||
+            content.normalReferenceFrame !==
+              (metadata.tileset.store?.normalReferenceFrame || 'earth-centered')
+          ) {
+            throw new TileConversionError(
+              'I3S_MESH_SOURCE_NORMAL_FRAME_UNSUPPORTED',
+              'Unknown I3S vector basis'
+            );
+          }
+          if (
+            content.meshSegmentation ||
+            Object.entries(attributes).some(
+              ([name, value]) =>
+                value && !['position', 'normal', 'uv0', 'id', 'faceRange'].includes(name)
+            )
+          ) {
+            throw new TileConversionError(
+              'I3S_MESH_SOURCE_ATTRIBUTE_UNSUPPORTED',
+              'Only positions, normals, TEXCOORD_0 and explicitly mapped feature associations are supported'
+            );
+          }
+          const hasFeatures =
+            content.featureIds.length > 0 ||
+            metadata.tileset.fields?.length ||
+            metadata.tileset.attributeStorageInfo?.length;
+          if (Array.from(content.featureIds).some(value => !Number.isSafeInteger(value))) {
+            throw new TileConversionError(
+              'I3S_MESH_SOURCE_FEATURE_ID_UNSUPPORTED',
+              'Decoded numeric feature IDs must be exact safe integers'
+            );
+          }
+          if (hasFeatures && !options.getFeatures && !options.features) {
+            throw new TileConversionError(
+              'I3S_MESH_SOURCE_FEATURE_MAPPING_REQUIRED',
+              'I3S feature data requires explicit resource features or a custom Arrow mapper'
+            );
+          }
+          const mesh = validateMeshGeometry(
+            {
+              mode: 4,
+              topology: 'triangle-list',
+              attributes: {
+                POSITION: attributes.position,
+                ...(attributes.normal ? {NORMAL: attributes.normal} : {}),
+                ...(attributes.uv0 ? {TEXCOORD_0: attributes.uv0} : {})
+              },
+              ...(content.indices ? {indices: {value: content.indices, size: 1}} : {})
+            },
+            true
+          );
+          if (mesh.attributes.POSITION.value.length / 3 !== content.vertexCount) {
+            throw new TileConversionError(
+              'I3S_MESH_SOURCE_COUNT_INVALID',
+              'I3S vertexCount must match the decoded geometry'
+            );
+          }
+          const features = options.getFeatures
+            ? await options.getFeatures(content, item, metadata, signal)
+            : options.features
+              ? await extractI3SMeshFeatures(
+                  content,
+                  item,
+                  metadata,
+                  options.features,
+                  options.readExternalResource,
+                  entry.uri,
+                  signal
+                )
+              : undefined;
+          signal?.throwIfAborted();
+          if (hasFeatures && !features) {
+            throw new TileConversionError(
+              'I3S_MESH_SOURCE_FEATURE_MAPPING_REQUIRED',
+              'The feature mapper must return all declared feature data'
+            );
+          }
+          const mappedMaterial = await mapI3SMeshSourceMaterial(
+            content,
+            item.tile.header,
+            options.readExternalResource,
+            entry.uri,
+            signal
+          );
+          signal?.throwIfAborted();
+          yield {
+            id: `${item.tile.id}/${entry.index}`,
+            origin: [0, 0, 0],
+            mesh,
+            normalReferenceFrame:
+              content.normalReferenceFrame === 'vertex-reference-frame'
+                ? 'vertex-reference-frame'
+                : 'earth-centered',
+            features,
+            material: mappedMaterial
+          };
+        }
+      }
+    }
+  };
+}

package/src/v5/index.ts

@@ -0,0 +1,131 @@
+export {
+  convertTileset,
+  inspectTileset,
+  TileConversionError,
+  validateTileset
+} from '@loaders.gl/tile-converter/v5/core';
+export type {
+  ConvertTilesetOptions,
+  TileConversionCodec,
+  TileConversionDiagnostic,
+  TileConversionProgress,
+  TileConversionReport,
+  TileConversionSink,
+  TileConversionSource,
+  TileValidationReport,
+  ValidateTilesetOptions
+} from '@loaders.gl/tile-converter/v5/core';
+export {createTilesetConversionSource} from '@loaders.gl/tile-converter/v5/core';
+export type {TilesetConversionSourceOptions} from '@loaders.gl/tile-converter/v5/core';
+export {
+  createI3SConversionSpatialContext,
+  createTiles3DConversionSpatialContext
+} from '@loaders.gl/tile-converter/v5/core';
+export type {
+  I3SConversionSpatialContext,
+  Tiles3DConversionSpatialContext
+} from '@loaders.gl/tile-converter/v5/core';
+export {convertFeatureAttributesToArrowBatches} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  FeatureArrowBatchOptions,
+  TileFeatureAttributes
+} from '@loaders.gl/tile-converter/v5/adapters';
+export {
+  encodePointCloudTile,
+  encodePointCloudTileWithMetadata
+} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  EncodePointCloudTileOptions,
+  EncodedPointCloudTile
+} from '@loaders.gl/tile-converter/v5/adapters';
+export {traversePointCloudSource} from '@loaders.gl/tile-converter/v5/core';
+export type {
+  PointCloudSourceTile,
+  TraversePointCloudSourceOptions
+} from '@loaders.gl/tile-converter/v5/core';
+export {
+  encodePointCloudSource,
+  encodePointCloudSourceTile
+} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  EncodedPointCloudSourceTile,
+  EncodePointCloudSourceOptions
+} from '@loaders.gl/tile-converter/v5/adapters';
+export {convertPointCloudSource} from '@loaders.gl/tile-converter/v5/adapters';
+export type {ConvertPointCloudSourceOptions} from '@loaders.gl/tile-converter/v5/adapters';
+export {createManifestBackedTileConversionSink} from '@loaders.gl/tile-converter/v5/core';
+export type {
+  ManifestBackedTileConversionSinkOptions,
+  TileResourceManifest,
+  TileResourceManifestEntry,
+  TileResourceManifestStore
+} from '@loaders.gl/tile-converter/v5/core';
+export {encodeMeshTile} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  MeshTileMaterial,
+  MeshTileOptions,
+  MeshTileTexture,
+  MeshTileSampler,
+  MeshTileTextureTransform
+} from '@loaders.gl/tile-converter/v5/adapters';
+export {createMeshConversionCodec} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  MeshConversionInput,
+  EncodedMeshConversionResource,
+  MeshConversionCodecOptions
+} from '@loaders.gl/tile-converter/v5/adapters';
+export {createSingleMeshTilesetSink} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  SingleMeshTilesetSink,
+  SingleMeshTilesetSinkOptions
+} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {
+  createTileConversionArchive,
+  encodeTileConversionArchiveInBatches
+} from '@loaders.gl/tile-converter/v5/adapters';
+export type {TileConversionArchiveOptions} from '@loaders.gl/tile-converter/v5/adapters';
+export {createSingleMeshTilesetArchive} from '@loaders.gl/tile-converter/v5/adapters';
+export type {SingleMeshTilesetArchiveOptions} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {createMeshTilesetConversionSource} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  MeshSourceResource,
+  MeshTilesetSourceOptions,
+  MeshSourceFeatureOptions
+} from '@loaders.gl/tile-converter/v5/adapters';
+export {
+  createI3SMeshConversionCodec,
+  createSingleMeshI3SSink
+} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  I3SMeshConversionResource,
+  I3SMeshConversionCodecOptions,
+  SingleMeshI3SSink
+} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {
+  createI3SMeshSink,
+  createTileConversionResourceFetcher
+} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  I3SMeshSink,
+  I3SMeshSinkOptions,
+  TileConversionResourceFetcherOptions,
+  MeshTileFeatures
+} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {createPointCloudTilesetSink} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  PointCloudTilesetSink,
+  PointCloudTilesetSinkOptions
+} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {transformPointCloudSourceTile} from '@loaders.gl/tile-converter/v5/adapters';
+export type {PointCloudSpatialOptions} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {createI3SMeshTilesetConversionSource} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  I3SMeshTilesetSourceOptions,
+  I3SMeshSourceFeatureOptions
+} from '@loaders.gl/tile-converter/v5/adapters';