Add JSDoc for three/plugins

Author: gkjohnson

src/three/plugins/CesiumIonAuthPlugin.js

@@ -2,6 +2,18 @@ import { CesiumIonAuthPlugin as CesiumIonAuthPluginImpl } from '3d-tiles-rendere
 import { TMSTilesPlugin } from './images/EPSGTilesPlugin.js';
 import { QuantizedMeshPlugin } from './QuantizedMeshPlugin.js';
 
+/**
+ * Plugin for authenticating requests to Cesium Ion. Handles token refresh, asset
+ * endpoint resolution, and attribution collection. Auto-registration of terrain and
+ * imagery plugins via `assetTypeHandler` is deprecated — provide a custom handler
+ * instead.
+ * @param {Object} [options]
+ * @param {string} [options.apiToken] Cesium Ion API token.
+ * @param {string|null} [options.assetId=null] Cesium Ion asset ID, or `null` when using an explicit root URL.
+ * @param {boolean} [options.autoRefreshToken=false] Automatically refresh the token on 4xx errors.
+ * @param {boolean} [options.useRecommendedSettings=true] Apply recommended renderer settings for Cesium Ion assets.
+ * @param {Function} [options.assetTypeHandler] Callback `(type, tiles, asset)` invoked for non-3DTILES asset types.
+ */
 export class CesiumIonAuthPlugin extends CesiumIonAuthPluginImpl {
 
 	constructor( options = {} ) {

src/three/plugins/DebugTilesPlugin.js

@@ -59,6 +59,25 @@ const ColorModes = Object.freeze( {
 	LOAD_ORDER,
 } );
 
+/**
+ * Plugin that adds visual debugging aids to a `TilesRenderer`: bounding-volume
+ * helpers (box, sphere, region), tile color modes based on depth/error/distance/load
+ * order, and an unlit rendering mode. Color modes are available via the static
+ * `ColorModes` property.
+ * @param {Object} [options]
+ * @param {boolean} [options.displayBoxBounds=false] Show OBB bounding-box helpers.
+ * @param {boolean} [options.displaySphereBounds=false] Show bounding-sphere helpers.
+ * @param {boolean} [options.displayRegionBounds=false] Show bounding-region helpers.
+ * @param {boolean} [options.displayParentBounds=false] Also show ancestor bounding volumes for visible tiles.
+ * @param {number} [options.colorMode=ColorModes.NONE] Initial tile color mode.
+ * @param {number} [options.boundsColorMode=ColorModes.NONE] Color mode applied to bounding-volume helpers.
+ * @param {number} [options.maxDebugDepth=-1] Maximum tree depth for depth-based coloring (`-1` = auto).
+ * @param {number} [options.maxDebugDistance=-1] Maximum distance for distance-based coloring (`-1` = auto).
+ * @param {number} [options.maxDebugError=-1] Maximum error for error-based coloring (`-1` = auto).
+ * @param {Function|null} [options.customColorCallback=null] Callback `( tile, mesh )` used when `colorMode` is `CUSTOM_COLOR`.
+ * @param {boolean} [options.unlit=false] Replace tile materials with unlit `MeshBasicMaterial`.
+ * @param {boolean} [options.enabled=true] Whether the plugin is active on init.
+ */
 export class DebugTilesPlugin {
 
 	static get ColorModes() {
@@ -232,6 +251,12 @@ export class DebugTilesPlugin {
 		this.customColorCallback = options.customColorCallback;
 		this.unlit = options.unlit;
 
+		/**
+		 * Maps a normalized [0, 1] value to a `Color` for debug visualizations. Defaults to
+		 * a black-to-white gradient. Replace with a custom function to use a different color
+		 * ramp.
+		 * @type {( val: number, target: Color ) => void}
+		 */
 		this.getDebugColor = ( value, target ) => {
 
 			target.setRGB( value, value, value );

src/three/plugins/GLTFExtensionsPlugin.js

@@ -3,6 +3,19 @@ import { GLTFStructuralMetadataExtension } from './gltf/GLTFStructuralMetadataEx
 import { GLTFMeshFeaturesExtension } from './gltf/GLTFMeshFeaturesExtension.js';
 import { GLTFCesiumRTCExtension } from './gltf/GLTFCesiumRTCExtension.js';
 
+/**
+ * Plugin for automatically adding common extensions and loaders for 3D Tiles to the
+ * `GLTFLoader` used for parsing tile geometry. A `DRACOLoader` can be provided to
+ * support loading Draco-compressed point cloud files.
+ * @param {Object} [options]
+ * @param {boolean} [options.metadata=true] Enable the `EXT_structural_metadata` and `EXT_mesh_features` extensions.
+ * @param {boolean} [options.rtc=true] Enable the `CESIUM_RTC` extension.
+ * @param {Array} [options.plugins=[]] Additional GLTF loader plugins to pass to `GLTFLoader.register`.
+ * @param {Object} [options.dracoLoader=null] A `DRACOLoader` instance for Draco-compressed geometry.
+ * @param {Object} [options.ktxLoader=null] A `KTX2Loader` instance for KTX2-compressed textures.
+ * @param {Object} [options.meshoptDecoder=null] A `MeshoptDecoder` for Meshopt-compressed meshes.
+ * @param {boolean} [options.autoDispose=true] Automatically dispose the DRACO and KTX loaders on `dispose()`.
+ */
 export class GLTFExtensionsPlugin {
 
 	constructor( options ) {

src/three/plugins/LoadRegionPlugin.js

@@ -1,6 +1,12 @@
 import { Ray, Sphere } from 'three';
 import { OBB } from '3d-tiles-renderer/three';
 
+/**
+ * Plugin that restricts tile loading and traversal to one or more geometric regions
+ * (`SphereRegion`, `RayRegion`, `OBBRegion`). Only tiles that intersect an active
+ * region are loaded and refined. Regions marked as masks additionally prevent tiles
+ * outside them from loading.
+ */
 export class LoadRegionPlugin {
 
 	constructor() {
@@ -111,6 +117,14 @@ export class LoadRegionPlugin {
 }
 
 // Definitions of predefined regions
+
+/**
+ * Abstract base class for `LoadRegionPlugin` regions. Subclass and override
+ * `intersectsTile` to define custom load regions.
+ * @param {Object} [options]
+ * @param {number} [options.errorTarget=10] Geometric error target used when this region controls refinement.
+ * @param {boolean} [options.mask=false] When `true`, tiles outside this region are suppressed (mask mode).
+ */
 export class BaseRegion {
 
 	constructor( options = {} ) {
@@ -152,6 +166,13 @@ export class BaseRegion {
 
 }
 
+/**
+ * A spherical load region. Only tiles that intersect `sphere` are loaded.
+ * @param {Object} [options]
+ * @param {Sphere} [options.sphere] The sphere volume; defaults to an empty sphere at the origin.
+ * @param {number} [options.errorTarget=10] Geometric error target for tiles inside the region.
+ * @param {boolean} [options.mask=false] Mask mode — suppresses tiles outside this region.
+ */
 export class SphereRegion extends BaseRegion {
 
 	constructor( options = {} ) {
@@ -181,6 +202,13 @@ export class SphereRegion extends BaseRegion {
 
 }
 
+/**
+ * A ray-based load region. Only tiles that intersect `ray` are loaded.
+ * @param {Object} [options]
+ * @param {Ray} [options.ray] The ray; defaults to a ray at the origin pointing in +Z.
+ * @param {number} [options.errorTarget=10] Geometric error target for tiles inside the region.
+ * @param {boolean} [options.mask=false] Mask mode — suppresses tiles outside this region.
+ */
 export class RayRegion extends BaseRegion {
 
 	constructor( options = {} ) {
@@ -210,6 +238,13 @@ export class RayRegion extends BaseRegion {
 
 }
 
+/**
+ * An oriented bounding-box load region. Only tiles that intersect `obb` are loaded.
+ * @param {Object} [options]
+ * @param {OBB} [options.obb] The oriented bounding box; defaults to an empty OBB at the origin.
+ * @param {number} [options.errorTarget=10] Geometric error target for tiles inside the region.
+ * @param {boolean} [options.mask=false] Mask mode — suppresses tiles outside this region.
+ */
 export class OBBRegion extends BaseRegion {
 
 	constructor( options = {} ) {

src/three/plugins/QuantizedMeshPlugin.js

@@ -77,6 +77,17 @@ function getContentUrl( x, y, level, version, layer ) {
 
 }
 
+/**
+ * Plugin that adds support for the Cesium quantized-mesh terrain format. Fetches the
+ * `layer.json` descriptor from the tileset root and dynamically generates 3D Tiles
+ * tile content from quantized-mesh buffers.
+ * @param {Object} [options]
+ * @param {boolean} [options.useRecommendedSettings=true] Apply recommended error and fetch settings for terrain.
+ * @param {number|null} [options.skirtLength=null] Override skirt length in metres; defaults to tile geometric error.
+ * @param {boolean} [options.smoothSkirtNormals=true] Blend skirt normals with tile surface for smoother edges.
+ * @param {boolean} [options.generateNormals=true] Compute vertex normals for the terrain mesh.
+ * @param {boolean} [options.solid=false] Generate a solid closed mesh (adds a bottom cap).
+ */
 export class QuantizedMeshPlugin {
 
 	constructor( options = {} ) {

src/three/plugins/ReorientationPlugin.js

@@ -2,6 +2,23 @@ import { Sphere } from 'three';
 import { OBJECT_FRAME } from '3d-tiles-renderer/three';
 
 const sphere = /* @__PURE__ */ new Sphere();
+
+/**
+ * Plugin for automatically re-orienting and re-centering the tileset to make it visible
+ * near the origin and facing the right direction. If `lat`/`lon` are provided the
+ * tileset is placed at that geographic location; otherwise the plugin tries to determine
+ * if the tileset is on the globe surface and estimates the coordinates. If no coordinates
+ * can be determined the tileset is oriented so the given `up` axis aligns to three.js' +Y.
+ * @param {Object} [options]
+ * @param {number|null} [options.lat=null] Latitude in radians of the surface point to orient to (requires `lon`).
+ * @param {number|null} [options.lon=null] Longitude in radians of the surface point to orient to (requires `lat`).
+ * @param {number} [options.height=0] Height in metres above the ellipsoid surface.
+ * @param {string} [options.up='+z'] Axis to orient toward three.js +Y when no lat/lon is available. Valid values are `±x`, `±y`, `±z`.
+ * @param {boolean} [options.recenter=true] Whether to reposition the tileset to the origin.
+ * @param {number} [options.azimuth=0] Azimuth rotation in radians.
+ * @param {number} [options.elevation=0] Elevation rotation in radians.
+ * @param {number} [options.roll=0] Roll rotation in radians.
+ */
 export class ReorientationPlugin {
 
 	constructor( options ) {
@@ -118,6 +135,16 @@ export class ReorientationPlugin {
 
 	}
 
+	/**
+	 * Centers the tileset such that the given coordinates are positioned at the origin
+	 * with X facing west and Z facing north.
+	 * @param {number} lat Latitude in radians.
+	 * @param {number} lon Longitude in radians.
+	 * @param {number} [height=0] Height in metres above the ellipsoid surface.
+	 * @param {number} [azimuth=0] Azimuth rotation in radians.
+	 * @param {number} [elevation=0] Elevation rotation in radians.
+	 * @param {number} [roll=0] Roll rotation in radians.
+	 */
 	transformLatLonHeightToOrigin( lat, lon, height = 0, azimuth = 0, elevation = 0, roll = 0 ) {
 
 		const { group, ellipsoid } = this.tiles;

src/three/plugins/TileCompressionPlugin.js

@@ -103,6 +103,22 @@ function compressPositionAttribute( mesh, arrayType = Int16Array ) {
 
 }
 
+/**
+ * Plugin that processes tile geometry buffer attributes into smaller data types on load
+ * and disables texture mipmaps to save memory. Can reduce geometry memory footprint by
+ * more than half and texture memory by around a third. Note that the default attribute
+ * size when compression is enabled is fairly aggressive and may cause visual artifacts.
+ * @param {Object} [options]
+ * @param {boolean} [options.generateNormals=false] Generate vertex normals if absent.
+ * @param {boolean} [options.disableMipmaps=true] Disable mipmap generation on tile textures.
+ * @param {boolean} [options.compressIndex=true] Compress index buffers to the smallest fitting integer type.
+ * @param {boolean} [options.compressNormals=false] Compress normal attributes.
+ * @param {boolean} [options.compressUvs=false] Compress UV attributes.
+ * @param {boolean} [options.compressPosition=false] Compress position attributes.
+ * @param {TypedArrayConstructor} [options.uvType=Int8Array] Target type for UV compression.
+ * @param {TypedArrayConstructor} [options.normalType=Int8Array] Target type for normal compression.
+ * @param {TypedArrayConstructor} [options.positionType=Int16Array] Target type for position compression.
+ */
 export class TileCompressionPlugin {
 
 	constructor( options ) {

src/three/plugins/TileFlatteningPlugin.js

@@ -35,6 +35,11 @@ function calculateSphere( object, target ) {
 
 }
 
+/**
+ * Plugin that flattens tile geometry vertices onto the surface of one or more mesh
+ * "shapes", useful for placing flat terrain overlays or cutting roads into terrain.
+ * Shapes are added via `addShape()` and removed via `deleteShape()` or `clearShapes()`.
+ */
 export class TileFlatteningPlugin {
 
 	constructor() {
@@ -230,12 +235,25 @@ export class TileFlatteningPlugin {
 	}
 
 	// API for updating and shapes to flatten the vertices
+	/**
+	 * Returns whether the given object has already been added as a shape.
+	 * @param {Object3D} mesh
+	 * @returns {boolean}
+	 */
 	hasShape( mesh ) {
 
 		return this.shapes.has( mesh );
 
 	}
 
+	/**
+	 * Adds the given mesh as a flattening shape. All coordinates must be in the tileset's local
+	 * frame. Throws if the shape has already been added.
+	 * @param {Object3D} mesh The shape mesh to flatten tile vertices onto.
+	 * @param {Vector3} [direction] Direction to cast rays when flattening (default downward along -Z).
+	 * @param {Object} [options]
+	 * @param {number} [options.threshold=Infinity] Maximum distance from the shape surface within which vertices are flattened. `Infinity` always flattens; `0` never flattens.
+	 */
 	addShape( mesh, direction = new Vector3( 0, 0, - 1 ), options = {} ) {
 
 		if ( this.hasShape( mesh ) ) {
@@ -289,6 +307,11 @@ export class TileFlatteningPlugin {
 
 	}
 
+	/**
+	 * Notifies the plugin that a shape's geometry or transform has changed and tile
+	 * flattening needs to be regenerated.
+	 * @param {Object3D} mesh
+	 */
 	updateShape( mesh ) {
 
 		if ( ! this.hasShape( mesh ) ) {
@@ -307,13 +330,21 @@ export class TileFlatteningPlugin {
 
 	}
 
+	/**
+	 * Removes the given shape and triggers tile regeneration.
+	 * @param {Object3D} mesh
+	 * @returns {boolean} `true` if the shape was found and removed.
+	 */
 	deleteShape( mesh ) {
 
 		this.needsUpdate = true;
 		return this.shapes.delete( mesh );
 
 	}
 
+	/**
+	 * Removes all shapes and resets flattened tiles to their original positions.
+	 */
 	clearShapes() {
 
 		if ( this.shapes.size === 0 ) {

src/three/plugins/UnloadTilesPlugin.js

@@ -4,6 +4,16 @@ import { LRUCache } from '3d-tiles-renderer/core';
 
 // TODO:
 // - abstract the "tile visible" callback so fade tiles can call it when tiles are _actually_ marked as non-visible
+
+/**
+ * Plugin that unloads geometry, textures, and materials of any given tile when its
+ * visibility changes to non-visible, freeing GPU memory. The model data still exists on
+ * the CPU until it is completely removed from the cache, allowing it to be re-uploaded
+ * without re-fetching.
+ * @param {Object} [options]
+ * @param {number} [options.delay=0] Milliseconds to wait after a tile is hidden before freeing its GPU data. Useful to avoid thrashing when the camera is moving.
+ * @param {number} [options.bytesTarget=0] Target GPU byte budget to unload down to. `0` means unload with no budget limit.
+ */
 export class UnloadTilesPlugin {
 
 	set delay( v ) {
@@ -30,6 +40,12 @@ export class UnloadTilesPlugin {
 
 	}
 
+	/**
+	 * The number of bytes currently uploaded to the GPU for rendering. Compare to
+	 * `lruCache.cachedBytes` which reports all downloaded bytes including those not
+	 * yet on the GPU.
+	 * @type {number}
+	 */
 	get estimatedGpuBytes() {
 
 		return this.lruCache.cachedBytes;

src/three/plugins/UpdateOnChangePlugin.js

@@ -1,6 +1,12 @@
 import { Matrix4 } from 'three';
 
 const _matrix = /* @__PURE__ */ new Matrix4();
+
+/**
+ * Plugin that skips `TilesRenderer.update()` calls when nothing has changed — no camera
+ * movement, no new tiles loaded, and no explicit `needsUpdate` flag set. Useful for
+ * event-driven renderers that only render on demand.
+ */
 export class UpdateOnChangePlugin {
 
 	constructor() {