@loaders.gl/i3s 4.0.0-alpha.16 → 4.0.0-alpha.18

package/src/types.ts

@@ -1,17 +1,28 @@
 import type {Matrix4, Quaternion, Vector3} from '@math.gl/core';
 import type {TypedArray, MeshAttribute, TextureLevel} from '@loaders.gl/schema';
-import {Tile3D, Tileset3D} from '@loaders.gl/tiles';
+import {TILESET_TYPE, TILE_REFINEMENT, TILE_TYPE, Tile3D, Tileset3D} from '@loaders.gl/tiles';
+import I3SNodePagesTiles from './lib/helpers/i3s-nodepages-tiles';
 
 export type COLOR = [number, number, number, number];
 
 /**
- * spec - https://github.com/Esri/i3s-spec/blob/master/docs/1.8/3DSceneLayer.cmn.md
+ * Extension of SceneLayer3D JSON with postprocessed loader data
  */
-// TODO Replace "[key: string]: any" with actual defenition
 export interface I3STilesetHeader extends SceneLayer3D {
   /** Not in spec, but is necessary for woking */
   url?: string;
-  [key: string]: any;
+  /** Base path that non-absolute paths in tileset are relative to. */
+  basePath?: string;
+  /** root node metadata */
+  root: I3STileHeader;
+  /** instance of the NodePages to tiles loader */
+  nodePagesTile?: I3SNodePagesTiles;
+  /** Type of the tileset */
+  type: TILESET_TYPE.I3S;
+  /** LOD metric type per I3S spec*/
+  lodMetricType?: string;
+  /** LOD metric value */
+  lodMetricValue?: number;
 }
 /** https://github.com/Esri/i3s-spec/blob/master/docs/1.8/nodePage.cmn.md */
 export type NodePage = {
@@ -57,20 +68,62 @@ type meshAttribute = {
   resource: number;
 };
 
+/**
+ * Texture format
+ * @see https://github.com/Esri/i3s-spec/blob/master/docs/1.7/textureSetDefinitionFormat.cmn.md
+ */
 export type I3STextureFormat = 'jpg' | 'png' | 'ktx-etc2' | 'dds' | 'ktx2';
 
-// TODO Replace "[key: string]: any" with actual defenition
-export type I3STileHeader = {
-  isDracoGeometry: boolean;
-  textureUrl?: string;
-  url?: string;
-  textureFormat?: I3STextureFormat;
-  textureLoaderOptions?: any;
-  materialDefinition?: I3SMaterialDefinition;
+/** Postprocessed I3S Node */
+export type I3STileHeader = I3SMinimalNodeData & {
+  /** MBS per I3S spec */
   mbs: Mbs;
-  obb?: Obb;
+  /** Material definition from the layer metadata per I3S spec */
+  materialDefinition?: I3SMaterialDefinition;
+  /** Bounding volume converted to 3DTiles format. It is generic for `tile` module */
+  boundingVolume: {box?: number[]; sphere?: number[]};
+  /** LOD metric selected for usage */
+  lodMetricType?: string;
+  /** LOD metric value */
+  lodMetricValue?: number;
+  /** Tile content type */
+  type: TILE_TYPE.MESH;
+  /** Tile refinement type. I3S supports only `REPLACE` */
+  refine: TILE_REFINEMENT.REPLACE;
+};
+
+/**
+ * Minimal I3S node data is needed for loading
+ * These data can come from 3DNodeIndexDocument (I3S spec) or from `I3SNodePagesTiles` instance
+ * @see https://github.com/Esri/i3s-spec/blob/master/docs/1.7/3DNodeIndexDocument.cmn.md
+ */
+export type I3SMinimalNodeData = {
+  /** Node ID */
+  id: string;
+  /** Node base path */
+  url?: string;
+  /** LOD selection metrics  */
   lodSelection?: LodSelection[];
-  [key: string]: any;
+  // OBB per I3S spec
+  obb?: Obb;
+  /** MBS per I3S spec */
+  mbs?: Mbs;
+  /** Geometry content URL */
+  contentUrl?: string;
+  /** Texture image URL */
+  textureUrl?: string;
+  /** Feature attributes URLs */
+  attributeUrls?: string[];
+  /** Material definition from I3S layer metadata */
+  materialDefinition?: I3SMaterialDefinition;
+  /** Texture format per I3S spec */
+  textureFormat: I3STextureFormat;
+  /** Loader options for texture loader. The loader might be `CompressedTextureLoader` for `dds`, BasisLoader for `ktx2` or ImageLoader for `jpg`and `png` */
+  textureLoaderOptions?: {[key: string]: any};
+  /** Child Nodes references  */
+  children: NodeReference[];
+  /** Is the node has Draco compressed geometry */
+  isDracoGeometry: boolean;
 };
 
 export type I3SParseOptions = {
@@ -96,13 +149,20 @@ export type I3SParseOptions = {
    * Supported coordinate systems: METER_OFFSETS, LNGLAT_OFFSETS
    */
   coordinateSystem?: number;
+  /** Options to colorize 3DObjects by attribute value */
   colorsByAttribute?: {
+    /** Feature attribute name */
     attributeName: string;
+    /** Minimum attribute value */
     minValue: number;
+    /** Maximum attribute value */
     maxValue: number;
+    /** Minimum color. 3DObject will be colorized with gradient from `minColor to `maxColor` */
     minColor: COLOR;
+    /** Maximum color. 3DObject will be colorized with gradient from `minColor to `maxColor` */
     maxColor: COLOR;
-    mode: string;
+    /** Colorization mode. `replace` - replace vertex colors with a new colors, `multiply` - multiply vertex colors with new colors */
+    mode: 'multiply' | 'replace';
   };
 
   /** @deprecated */
@@ -157,12 +217,20 @@ export type BoundingVolumes = {
   obb: Obb;
 };
 
+/**
+ * Oriented bounding box per I3S spec
+ * @see https://github.com/Esri/i3s-spec/blob/master/docs/1.7/obb.cmn.md
+ */
 export type Obb = {
   center: number[] | Vector3;
   halfSize: number[] | Vector3;
   quaternion: number[] | Quaternion;
 };
 
+/**
+ * Minimum bounding sphere per I3S spec
+ * @see https://github.com/Esri/i3s-spec/blob/master/docs/1.7/3DNodeIndexDocument.cmn.md#properties
+ */
 export type Mbs = [number, number, number, number];
 
 /** SceneLayer3D based on I3S specification - https://github.com/Esri/i3s-spec/blob/master/docs/1.8/3DSceneLayer.cmn.md */
@@ -370,36 +438,32 @@ export type Node3DIndexDocument = {
 };
 
 /**
- * Minimal I3S node data is needed for loading
+ * LOD selection metrics per I3S spec
+ * @see https://github.com/Esri/i3s-spec/blob/master/docs/1.7/lodSelection.cmn.md
  */
-export type I3SMinimalNodeData = {
-  id: string;
-  url?: string;
-  transform?: number[];
-  lodSelection?: LodSelection[];
-  obb?: Obb;
-  mbs?: Mbs;
-  contentUrl?: string;
-  textureUrl?: string;
-  attributeUrls?: string[];
-  materialDefinition?: I3SMaterialDefinition;
-  textureFormat?: I3STextureFormat;
-  textureLoaderOptions?: {[key: string]: any};
-  children?: NodeReference[];
-  isDracoGeometry: boolean;
-};
-
 export type LodSelection = {
+  /**  */
   metricType?: string;
   maxError: number;
 };
 
+/**
+ * Node reference per I3S spec
+ * @see https://github.com/Esri/i3s-spec/blob/master/docs/1.7/nodeReference.cmn.md
+ */
 export type NodeReference = {
+  /** Tree Key ID of the referenced node represented as string. */
   id: string;
+  /** Version (store update session ID) of the referenced node. */
   version?: string;
+  /** An array of four doubles, corresponding to x, y, z and radius of the minimum bounding sphere of a node. */
   mbs?: Mbs;
+  /** Describes oriented bounding box. */
   obb?: Obb;
+  /** Number of values per element. */
   href?: string;
+  /** Number of features in the referenced node and its descendants, down to the leaf nodes. */
+  featureCount?: number;
 };
 
 export type Resource = {
@@ -789,7 +853,7 @@ type TextureSetDefinition = {
 
 /** Spec - https://github.com/Esri/i3s-spec/blob/master/docs/1.8/geometryDefinition.cmn.md */
 type GeometryDefinition = {
-  topology: 'triangle' | string;
+  topology?: 'triangle';
   geometryBuffers: GeometryBuffer[];
 };
 /** Spec - https://github.com/Esri/i3s-spec/blob/master/docs/1.8/geometryBuffer.cmn.md */
@@ -805,7 +869,7 @@ type GeometryBuffer = {
   compressedAttributes?: {encoding: string; attributes: string[]};
 };
 
-type GeometryBufferItem = {type: string; component: number; encoding?: string; binding: string};
+type GeometryBufferItem = {type: string; component: number; encoding?: string; binding?: string};
 
 type AttributeValue = {valueType: string; encoding?: string; valuesPerElement?: number};