Merge pull request #225 from matterport/tileset-types

[types] - more complete types for the 3d-tiles spec tiles

README.md

@@ -400,7 +400,7 @@ Sets `box` to the axis aligned root bounding box of the tile set in the [group](
 ### .getOrientedBounds
 
 ```js
-getOrientedBounds( box : Box3, boxTransform : Matrix4) : boolean;
+getOrientedBounds( box : Box3, boxTransform : Matrix4 ) : boolean;
 ```
 
 Sets `box` and `boxTransform` to the bounds and matrix that describe the oriented bounding box that encapsulates the root of the tile set. Returns `false` if the tile root was not loaded.
@@ -457,7 +457,7 @@ Fires the callback for every loaded scene in the hierarchy with the associatd ti
 ### .onLoadTileSet
 
 ```js
-onLoadTileSet = null : ( tileSet : Object ) => void
+onLoadTileSet = null : ( tileSet : Tileset ) => void
 ```
 
 Callback that is called whenever a tile set is loaded.
@@ -465,7 +465,7 @@ Callback that is called whenever a tile set is loaded.
 ### .onLoadModel
 
 ```js
-onLoadModel = null : ( scene : Object3D, tile : object ) => void
+onLoadModel = null : ( scene : Object3D, tile : Tile ) => void
 ```
 
 Callback that is called every time a model is loaded. This can be used in conjunction with [.forEachLoadedModel](#forEachLoadedModel) to set the material of all load and still yet to load meshes in the tile set.
@@ -473,7 +473,7 @@ Callback that is called every time a model is loaded. This can be used in conjun
 ### .onDisposeModel
 
 ```js
-onDisposeModel = null : ( scene : Object3D, tile : object ) => void
+onDisposeModel = null : ( scene : Object3D, tile : Tile ) => void
 ```
 
 Callback that is called every time a model is disposed of. This should be used in conjunction with [.onLoadModel](#onLoadModel) to dispose of any custom materials created for a tile. Note that the textures, materials, and geometries that a tile loaded in with are all automatically disposed of even if they have been removed from the tile meshes.

package-lock.json

@@ -4161,6 +4161,11 @@
       "integrity": "sha512-l42BggppR6zLmpfU6fq9HEa2oGPEI8yrSPL3GITjfRInppYFahObbIQOQK3UGxEnyQpltZLaPe75046NOZQikw==",
       "dev": true
     },
+    "@types/three": {
+      "version": "0.134.0",
+      "resolved": "https://registry.npmjs.org/@types/three/-/three-0.134.0.tgz",
+      "integrity": "sha512-4YB+99Rgqq27EjiYTItEoZtdjLnTh8W9LxowgpC9eWsjaQJIL4Kn/ZcUKAnW3gB/jS4hqGN8iqmid+RcUZDzpA=="
+    },
     "@types/yargs": {
       "version": "15.0.13",
       "resolved": "https://registry.npmjs.org/@types/yargs/-/yargs-15.0.13.tgz",
@@ -13438,9 +13443,9 @@
       "dev": true
     },
     "three": {
-      "version": "0.126.0",
-      "resolved": "https://registry.npmjs.org/three/-/three-0.126.0.tgz",
-      "integrity": "sha512-/MecvboUefStCkUfXLImoJxthN+FoLPcEP7pz1r1Dd9i8BPGGuj+S1sOPRvW4Z+ViZjP2oWWm1inNC/MT52ybA==",
+      "version": "0.134.0",
+      "resolved": "https://registry.npmjs.org/three/-/three-0.134.0.tgz",
+      "integrity": "sha512-LbBerg7GaSPjYtTOnu41AMp7tV6efUNR3p4Wk5NzkSsNTBuA5mDGOfwwZL1jhhVMLx9V20HolIUo0+U3AXehbg==",
       "dev": true
     },
     "throat": {

package.json

@@ -40,6 +40,7 @@
   "devDependencies": {
     "@babel/core": "^7.13.8",
     "@babel/preset-env": "^7.13.8",
+    "@types/three": ">=0.128.0",
     "babel-jest": "^25.5.1",
     "concurrently": "^5.3.0",
     "eslint": "^6.8.0",
@@ -49,7 +50,7 @@
     "jest-cli": "^25.5.4",
     "parcel-bundler": "^1.12.4",
     "static-server": "^2.2.1",
-    "three": ">=0.126.0",
+    "three": ">=0.128.0",
     "typescript": "^3.9.9"
   },
   "peerDependencies": {

src/base/Tile.d.ts

@@ -0,0 +1,50 @@
+import { TileBase } from './TileBase';
+
+/**
+ * Documented 3d-tile state managed by the TilesRenderer* / used/usable in priority / traverseFunctions!
+ */
+export interface Tile extends TileBase {
+
+	parent: Tile;
+
+	/**
+	 * Hierarchy Depth from the TileGroup
+	 */
+	__depth : number;
+	/**
+	 * The screen space error for this tile
+	 */
+	__error : number;
+	/**
+	 * How far is this tiles bounds from the nearest active Camera.
+	 * Expected to be filled in during calculateError implementations.
+	 */
+	__distanceFromCamera : number;
+	/**
+	 * This tile is currently active if:
+	 *  1: Tile content is loaded and ready to be made visible if needed
+	 */
+	__active : boolean;
+	/**
+	 * This tile is currently visible if:
+	 *  1: Tile content is loaded
+	 *  2: Tile is within a camera frustum
+	 *  3: Tile meets the SSE requirements
+	 */
+	__visible : boolean;
+	/**
+	 * Whether or not the tile was visited during the last update run.
+	 */
+	__used : boolean;
+
+	/**
+	 * Whether or not the tile was within the frustum on the last update run.
+	 */
+	__inFrustum : boolean;
+
+	/**
+	 * TODO: Document this if it is useful enough to be the default property in the LRU sorting.
+	 */
+	__depthFromRenderedParent : number;
+
+}

src/base/TileBase.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 3d-tiles Tile object per spec:
+ * (incomplete, expanding as features become supported by this package.)
+ *
+ * See spec for full schema: https://github.com/CesiumGS/3d-tiles/blob/master/specification/schema/tile.schema.json
+ */
+export interface TileBase {
+
+	boundingVolume: {
+
+		/**
+		 * An array of 12 numbers that define an oriented bounding box. The first three elements define the x, y, and z
+		 * values for the center of the box. The next three elements (with indices 3, 4, and 5) define the x axis
+		 * direction and half-length. The next three elements (indices 6, 7, and 8) define the y axis direction and
+		 * half-length. The last three elements (indices 9, 10, and 11) define the z axis direction and half-length.
+		 */
+		box?: number[];
+
+		/**
+		 * An array of four numbers that define a bounding sphere. The first three elements define the x, y, and z
+		 * values for the center of the sphere. The last element (with index 3) defines the radius in meters.
+		 */
+		sphere?: number[];
+
+	};
+
+	/**
+	 * The error, in meters, introduced if this tileset is not rendered. At runtime, the geometric error is used to compute screen space error (SSE), i.e., the error measured in pixels.
+	 */
+	geometricError: number;
+
+	// optional properties
+
+	children?: TileBase[];
+
+	content?: {
+
+		uri: string;
+
+		/**
+		 * Dictionary object with content specific extension objects.
+		 */
+		extensions?: Record<string, any>;
+
+		extras?: Record<string, any>;
+
+		// Non standard, noted here as it exists in the code in this package to support old pre-1.0 tilesets
+		url?: string;
+
+	};
+
+
+	/**
+	 * Dictionary object with tile specific extension objects.
+	 */
+	extensions?: Record<string, any>;
+
+	extras?: Record<string, any>;
+
+	refine?: 'REPLACE' | 'ADD';
+
+}

src/base/TileInternal.d.ts

@@ -0,0 +1,35 @@
+import { Tile } from './Tile';
+
+/**
+ * Internal state used/set by the package.
+ */
+
+export interface TileInternal extends Tile {
+
+	// tile description
+	__externalTileSet: boolean;
+	__contentEmpty: boolean;
+	__isLeaf: boolean;
+
+	// resource tracking
+	__usedLastFrame: boolean;
+	__used: boolean;
+
+	// Visibility tracking
+	__allChildrenLoaded: boolean;
+	__childrenWereVisible: boolean;
+	__inFrustum: boolean;
+	__wasSetVisible: boolean;
+
+	// download state tracking
+	/**
+	 * This tile is currently active if:
+	 *  1: Tile content is loaded and ready to be made visible if needed
+	 */
+	__active: boolean;
+	__loadIndex: number;
+	__loadAbort: AbortController | null;
+	__loadingState: number;
+	__wasSetActive: boolean;
+
+}

src/base/TilesRendererBase.d.ts

@@ -30,48 +30,3 @@ export class TilesRendererBase {
 	dispose() : void;
 
 }
-
-/** Documented 3d-tile state managed by the TilesRenderer* / traverseFunctions! */
-export interface Tile {
-
-	/**
-	 * Hierarchy Depth from the TileGroup
-	 */
-	__depth : Number;
-	/**
-	 * The screen space error for this tile
-	 */
-	__error : Number;
-	/**
-	 * How far is this tiles bounds from the nearest active Camera.
-	 * Expected to be filled in during calculateError implementations.
-	 */
-	__distanceFromCamera : Number;
-	/**
-	 * This tile is currently active if:
-	 *  1: Tile content is loaded and ready to be made visible if needed
-	 */
-	__active : Boolean;
-	/**
-	 * This tile is currently visible if:
-	 *  1: Tile content is loaded
-	 *  2: Tile is within a camera frustum
-	 *  3: Tile meets the SSE requirements
-	 */
-	__visible : Boolean;
-	/**
-	 * Whether or not the tile was visited during the last update run.
-	 */
-	__used : Boolean;
-
-	/**
-	 * Whether or not the tile was within the frustum on the last update run.
-	 */
-	__inFrustum : Boolean;
-
-	/**
-	 * TODO: Document this if it is useful enough to be the default property in the LRU sorting.
-	 */
-	__depthFromRenderedParent : Number;
-
-}

src/base/Tileset.d.ts

@@ -0,0 +1,66 @@
+import { TileBase } from './TileBase';
+
+/**
+ * A 3d-tiles tileset.
+ *
+ * Schema, see: https://github.com/CesiumGS/3d-tiles/blob/main/specification/schema/tileset.schema.json
+ */
+export interface Tileset {
+
+	/**
+	 * Metadata about the entire tileset.
+	 */
+	asset: {
+
+		/**
+		 * 3d-tiles version
+		 */
+		version: string,
+
+		/**
+		 * Application specific version
+		 */
+		tilesetVersion?: string,
+
+		/**
+		 * Dictionary object with extension-specific objects.
+		 */
+		extensions? : Record<string, any>,
+
+	};
+
+	/**
+	 * The error, in meters, introduced if this tileset is not rendered. At runtime, the geometric error is used to compute screen space error (SSE), i.e., the error measured in pixels.
+	 */
+	geometricError: Number;
+
+	/**
+	 * The root tile.
+	 */
+	root: TileBase;
+
+	// optional properties
+
+	/**
+	 * Names of 3D Tiles extensions used somewhere in this tileset.
+	 */
+	extensionsUsed?: string[];
+
+	/**
+	 * Names of 3D Tiles extensions required to properly load this tileset.
+	 */
+	extensionsRequired?: string[];
+
+	/**
+	 * A dictionary object of metadata about per-feature properties.
+	 */
+	properties?: Record<string, any>;
+
+	/**
+	 * Dictionary object with extension-specific objects.
+	 */
+	extensions? : Record<string, any>;
+
+	extras? : Record<string, any>;
+
+}

src/index.d.ts

@@ -10,12 +10,16 @@ import {
 	RANDOM_COLOR,
 } from './three/DebugTilesRenderer';
 import { TilesRenderer } from './three/TilesRenderer';
+import { TilesGroup } from './three/TilesGroup';
 import { B3DMLoader } from './three/B3DMLoader';
 import { I3DMLoader } from './three/I3DMLoader';
 import { PNTSLoader } from './three/PNTSLoader';
 import { CMPTLoader } from './three/CMPTLoader';
 
 import { TilesRendererBase } from './base/TilesRendererBase';
+import { Tile } from './base/Tile';
+import { TileBase } from './base/TileBase';
+import { Tileset } from './base/Tileset';
 import { B3DMLoaderBase } from './base/B3DMLoaderBase';
 import { I3DMLoaderBase } from './base/I3DMLoaderBase';
 import { PNTSLoaderBase } from './base/PNTSLoaderBase';
@@ -29,7 +33,11 @@ export {
 	TilesRenderer,
 	B3DMLoader,
 
+	Tile,
+	TileBase,
+	Tileset,
 	TilesRendererBase,
+	TilesGroup,
 	B3DMLoaderBase,
 
 	LRUCache,

src/three/TilesRenderer.d.ts

@@ -1,4 +1,6 @@
 import { Box3, Camera, Vector2, Matrix4, WebGLRenderer, Object3D, LoadingManager } from 'three';
+import { Tile } from '../base/Tile';
+import { Tileset } from '../base/Tileset';
 import { TilesRendererBase } from '../base/TilesRendererBase';
 import { TilesGroup } from './TilesGroup';
 
@@ -23,10 +25,11 @@ export class TilesRenderer extends TilesRendererBase {
 	setResolution( camera : Camera, resolution : Vector2 ) : Boolean;
 	setResolutionFromRenderer( camera : Camera, renderer : WebGLRenderer ) : Boolean;
 
-	forEachLoadedModel( callback : ( scene : Object3D, tile : object ) => void ) : void;
+	forEachLoadedModel( callback : ( scene : Object3D, tile : Tile ) => void ) : void;
+
+	onLoadTileSet : ( ( tileSet : Tileset ) => void ) | null;
+	onLoadModel : ( ( scene : Object3D, tile : Tile ) => void ) | null;
+	onDisposeModel : ( ( scene : Object3D, tile : Tile ) => void ) | null;
 
-	onLoadTileSet : ( ( tileSet : object ) => void ) | null;
-	onLoadModel : ( ( scene : Object3D, tile : object ) => void ) | null;
-	onDisposeModel : ( ( scene : Object3D, tile : object ) => void ) | null;
 
 }