potree-core 2.0.10 → 2.0.12

package/dist/point-cloud-octree.d.ts

@@ -6,29 +6,99 @@ import { PickParams } from './point-cloud-octree-picker';
 import { PointCloudTree } from './point-cloud-tree';
 import { IPointCloudTreeNode, IPotree, PickPoint, PCOGeometry } from './types';
 export declare class PointCloudOctree extends PointCloudTree {
+    /**
+     * The name of the point cloud octree.
+     */
     potree: IPotree;
+    /**
+     * Indicates whether the point cloud octree has been disposed.
+     *
+     * This is set to true when the octree is disposed, and can be used to check if the octree is still valid.
+     */
     disposed: boolean;
+    /**
+     * The geometry of the point cloud octree.
+     *
+     * This contains the root node and other properties related to the point cloud geometry.
+     */
     pcoGeometry: PCOGeometry;
+    /**
+     * The bounding box of the point cloud octree.
+     *
+     * This is used to define the spatial extent of the point cloud.
+     */
     boundingBox: Box3;
+    /**
+     * The bounding sphere of the point cloud octree.
+     *
+     * This is used for spatial queries and to determine visibility.
+     */
     boundingSphere: Sphere;
-    material: PointCloudMaterial;
+    /**
+     * The position of the point cloud octree in the 3D space.
+     *
+     * This is used to position the octree in the scene.
+     */
     level: number;
+    /**
+     * The maximum level of detail for the point cloud octree.
+     *
+     * This is used to limit the depth of the octree when rendering or processing.
+     */
     maxLevel: number;
     /**
-   * The minimum radius of a node's bounding sphere on the screen in order to be displayed.
-   */
+     * The minimum radius of a node's bounding sphere on the screen in order to be displayed.
+     */
     minNodePixelSize: number;
+    /**
+     * The root node of the point cloud octree.
+     */
     root: IPointCloudTreeNode | null;
+    /**
+     * Bounding box nodes for visualization.
+     */
     boundingBoxNodes: Object3D[];
+    /**
+     * An array of visible nodes in the point cloud octree.
+     *
+     * These nodes are currently visible in the scene and can be rendered.
+     */
     visibleNodes: PointCloudOctreeNode[];
+    /**
+     * An array of visible geometry nodes in the point cloud octree.
+     *
+     * These nodes contain the geometry data for rendering and are currently visible.
+     */
     visibleGeometry: PointCloudOctreeGeometryNode[];
+    /**
+     * The number of visible points in the point cloud octree.
+     *
+     * This is used to keep track of how many points are currently visible in the scene.
+     */
     numVisiblePoints: number;
+    /**
+     * Indicates whether the bounding box should be shown in the scene.
+     *
+     * This can be toggled to visualize the spatial extent of the point cloud octree.
+     */
     showBoundingBox: boolean;
+    private _material;
+    /**
+     * The bounds of the visible area in the point cloud octree.
+     *
+     * This is used to determine which nodes are currently visible based on the camera's frustum.
+     */
     private visibleBounds;
+    /**
+     * The picker used for picking points in the point cloud octree.
+     *
+     * This is used to interact with the point cloud, such as selecting points or querying information.
+     */
     private picker;
     constructor(potree: IPotree, pcoGeometry: PCOGeometry, material?: PointCloudMaterial);
-    private initMaterial;
     dispose(): void;
+    get material(): PointCloudMaterial;
+    set material(material: PointCloudMaterial);
     get pointSizeType(): PointSizeType;
     set pointSizeType(value: PointSizeType);
     toTreeNode(geometryNode: PointCloudOctreeGeometryNode, parent?: PointCloudOctreeNode | null): PointCloudOctreeNode;

package/dist/point-cloud-tree.d.ts

@@ -1,6 +1,17 @@
 import { Object3D } from 'three';
 import { IPointCloudTreeNode } from './types';
+/**
+ * Represents a point cloud tree structure.
+ */
 export declare class PointCloudTree extends Object3D {
+    /**
+     * The root node of the point cloud tree.
+     */
     root: IPointCloudTreeNode | null;
+    /**
+     * Checks if the point cloud tree has been initialized.
+     *
+     * @returns Returns true if the tree has been initialized (i.e., root is not null), false otherwise.
+     */
     initialized(): boolean;
 }

package/dist/potree.d.ts

@@ -1,20 +1,34 @@
-import { Camera, Ray, WebGLRenderer } from 'three';
-import { GetUrlFn } from './loading';
+import { RequestManager } from './loading2/RequestManager';
+import { Camera, Frustum, Ray, Vector2, Vector3, WebGLRenderer } from 'three';
 import { PointCloudOctree } from './point-cloud-octree';
-import { PickParams } from './point-cloud-octree-picker';
+import { PickParams, PointCloudOctreePicker } from './point-cloud-octree-picker';
 import { IPointCloudTreeNode, IPotree, IVisibilityUpdateResult, PickPoint } from './types';
+import { BinaryHeap } from './utils/binary-heap';
 import { LRU } from './utils/lru';
+/**
+ * Represents an item in a processing queue for point cloud operations.
+ *
+ * This class is typically used to manage nodes within a point cloud structure, associating each node with a specific weight and its parent node if applicable.
+ */
 export declare class QueueItem {
     pointCloudIndex: number;
     weight: number;
     node: IPointCloudTreeNode;
     parent?: IPointCloudTreeNode | null;
+    /**
+     * Creates a new QueueItem instance.
+     *
+     * @param pointCloudIndex - The index of the point cloud this item belongs to.
+     * @param weight - The weight or priority associated with this queue item.
+     * @param node - The point cloud tree node represented by this queue item.
+     * @param parent - (Optional) The parent node of the current node, or null if it has no parent.
+     */
     constructor(pointCloudIndex: number, weight: number, node: IPointCloudTreeNode, parent?: IPointCloudTreeNode | null);
 }
 export declare class Potree implements IPotree {
-    private static picker;
-    private _pointBudget;
-    private _rendererSize;
+    static picker: PointCloudOctreePicker | undefined;
+    _pointBudget: number;
+    _rendererSize: Vector2;
     maxNumNodesLoading: number;
     get features(): {
         SHADER_INTERPOLATION: boolean;
@@ -23,7 +37,8 @@ export declare class Potree implements IPotree {
         precision: string;
     };
     lru: LRU;
-    loadPointCloud(url: string, getUrl: GetUrlFn, xhrRequest?: (input: RequestInfo, init?: RequestInit) => Promise<Response>): Promise<PointCloudOctree>;
+    loadPointCloud(url: string, baseUrl: string): Promise<PointCloudOctree>;
+    loadPointCloud(url: string, requestManager: RequestManager): Promise<PointCloudOctree>;
     updatePointClouds(pointClouds: PointCloudOctree[], camera: Camera, renderer: WebGLRenderer): IVisibilityUpdateResult;
     static pick(pointClouds: PointCloudOctree[], renderer: WebGLRenderer, camera: Camera, ray: Ray, params?: Partial<PickParams>): PickPoint | null;
     get pointBudget(): number;
@@ -33,5 +48,9 @@ export declare class Potree implements IPotree {
     private updateChildVisibility;
     private updateBoundingBoxVisibility;
     private shouldClip;
-    private updateVisibilityStructures;
+    updateVisibilityStructures: (pointClouds: PointCloudOctree[], camera: Camera) => {
+        frustums: Frustum[];
+        cameraPositions: Vector3[];
+        priorityQueue: BinaryHeap<QueueItem>;
+    };
 }

package/dist/rendering/edl-pass.d.ts

@@ -0,0 +1,25 @@
+import { Camera, Object3D, WebGLRenderer } from 'three';
+import { PointCloudOctree } from '../point-cloud-octree';
+export type EDLPassParams = {
+    renderer: WebGLRenderer;
+    scene: Object3D;
+    camera: Camera;
+    pointClouds?: PointCloudOctree[];
+    pointCloudLayer?: number;
+};
+export declare class EDLPass {
+    edlStrength: number;
+    radius: number;
+    opacity: number;
+    neighbourCount: number;
+    private rtEDL;
+    private rtTypeChecked;
+    private edlMaterial;
+    private screenPass;
+    private size;
+    constructor();
+    private ensureRenderTargetType;
+    dispose(): void;
+    private resizeToRenderer;
+    render(params: EDLPassParams): void;
+}

package/dist/rendering/potree-renderer.d.ts

@@ -0,0 +1,83 @@
+import { Camera, Object3D, WebGLRenderer } from 'three';
+import { PointCloudOctree } from '../point-cloud-octree';
+import { Potree } from '../potree';
+import { IVisibilityUpdateResult } from '../types';
+/**
+ * Configuration for Eye-Dome Lighting (EDL) rendering.
+ *
+ * Note: EDL is a multi-pass / post-process effect (render default layer 0 (non-pointcloud), render point clouds to an offscreen target,
+ * then composite). Therefore it cannot be expressed as a single `renderer.render(scene, camera)` call.
+ */
+export type PotreeRendererEDLOptions = {
+    enabled: boolean;
+    /** Defaults to 1 so layer 0 can remain reserved for non-pointcloud content in the first pass. */
+    pointCloudLayer?: number;
+    strength?: number;
+    radius?: number;
+    opacity?: number;
+    neighbourCount?: number;
+};
+/**
+ * Options for {@link PotreeRenderer}.
+ *
+ * This is intentionally additive and does not change existing Potree APIs.
+ */
+export type PotreeRendererOptions = {
+    edl?: PotreeRendererEDLOptions;
+};
+/**
+ * Parameters required to render a frame.
+ */
+export type PotreeRendererRenderParams = {
+    renderer: WebGLRenderer;
+    scene: Object3D;
+    camera: Camera;
+    pointClouds?: PointCloudOctree[];
+};
+/**
+ * Thin helper that renders Potree point clouds.
+ *
+ * Why this exists:
+ * - Without EDL, users typically do: `potree.updatePointClouds(...)` then `renderer.render(scene, camera)`.
+ * - With EDL enabled, users previously had to manually:
+ *   1) keep point-cloud objects on a dedicated layer, and
+ *   2) run `EDLPass.render(...)` instead of `renderer.render(...)`.
+ *
+ * `PotreeRenderer` keeps that wiring in one place while preserving backward compatibility.
+ */
+export declare class PotreeRenderer {
+    private edlPass;
+    private edlOptions;
+    private lastPointClouds;
+    private overriddenMaterials;
+    private overriddenLayerMasks;
+    constructor(options?: PotreeRendererOptions);
+    /** Releases internally owned GPU resources (render targets). */
+    dispose(): void;
+    /**
+     * Enables/disables EDL and updates EDL parameters.
+     *
+     * This method is safe to call at runtime (e.g. toggling EDL on/off).
+     */
+    setEDL(options: PotreeRendererEDLOptions): void;
+    private setLayerMaskRecursive;
+    /**
+     * Ensures all point-cloud objects (including newly created child nodes) are on the provided layer.
+      * Side effect: overwrites `Object3D.layers` for the point cloud subtree.
+     *
+     * When EDL is enabled, layer separation is required so we can render:
+     * - non-pointcloud content first (layer 0), then
+     * - point clouds on a dedicated layer into an offscreen target.
+     */
+    syncPointCloudLayers(pointClouds: PointCloudOctree[], layer: number): void;
+    private applyEDLState;
+    /**
+     * Renders a frame.
+     *
+     * - EDL disabled: calls `renderer.render(scene, camera)`.
+     * - EDL enabled: runs the EDL multi-pass pipeline via {@link EDLPass}.
+     */
+    render(params: PotreeRendererRenderParams): void;
+    /** Convenience helper: `updatePointClouds()` followed by {@link render}. */
+    updateAndRender(potree: Potree, pointClouds: PointCloudOctree[], camera: Camera, renderer: WebGLRenderer, scene: Object3D): IVisibilityUpdateResult;
+}

package/dist/rendering/screen-pass.d.ts

@@ -0,0 +1,11 @@
+import { RawShaderMaterial, WebGLRenderer, WebGLRenderTarget } from 'three';
+export declare class ScreenPass {
+    private scene;
+    private camera;
+    private quad;
+    private geometry;
+    private placeholderMaterial;
+    constructor();
+    dispose(): void;
+    render(renderer: WebGLRenderer, material: RawShaderMaterial, target?: WebGLRenderTarget | null): void;
+}

package/dist/type-predicates.d.ts

@@ -1,3 +1,15 @@
 import { PointCloudOctreeGeometryNode } from './point-cloud-octree-geometry-node';
+/**
+ * Checks if the given node is a geometry node.
+ *
+ * @param node - Node to check.
+ * @returns True if the node is a geometry node, false otherwise.
+ */
 export declare function isGeometryNode(node?: any): node is PointCloudOctreeGeometryNode;
+/**
+ * Checks if the given node is a tree node.
+ *
+ * @param node - Node to check.
+ * @returns True if the node is a tree node, false otherwise.
+ */
 export declare function isTreeNode(node?: any): any;

package/dist/types.d.ts

@@ -1,7 +1,7 @@
+import { RequestManager } from './loading2/RequestManager';
 import { OctreeGeometry } from './loading2/OctreeGeometry';
 import { PointCloudOctreeGeometry } from './point-cloud-octree-geometry';
 import { Box3, Camera, Sphere, Vector3, WebGLRenderer } from 'three';
-import { GetUrlFn, XhrRequest } from './loading/types';
 import { PointCloudOctree } from './point-cloud-octree';
 import { LRU } from './utils/lru';
 export interface IPointCloudTreeNode {
@@ -24,6 +24,7 @@ export interface IVisibilityUpdateResult {
     numVisiblePoints: number;
     /**
      * True when a node has been loaded but was not added to the scene yet.
+     *
      * Make sure to call updatePointClouds() again on the next frame.
      */
     exceededMaxLoadsToGPU: boolean;
@@ -40,7 +41,8 @@ export interface IPotree {
     pointBudget: number;
     maxNumNodesLoading: number;
     lru: LRU;
-    loadPointCloud(url: string, getUrl: GetUrlFn, xhrRequest?: XhrRequest): Promise<PointCloudOctree>;
+    loadPointCloud(url: string, baseUrl: string): Promise<PointCloudOctree>;
+    loadPointCloud(url: string, requestManager: RequestManager): Promise<PointCloudOctree>;
     updatePointClouds(pointClouds: PointCloudOctree[], camera: Camera, renderer: WebGLRenderer): IVisibilityUpdateResult;
 }
 export interface PickPoint {

package/dist/utils/binary-heap.d.ts

@@ -0,0 +1,16 @@
+export class BinaryHeap<T> 
+{
+	constructor(scoreFunction: (node: T)=> number);
+
+	push(node: T): void;
+
+	pop(): T | undefined;
+
+	remove(node: T): void;
+
+	size(): number;
+
+	bubbleUp(n: number): void;
+
+	sinkDown(n: number): void;
+}

package/dist/utils/bounds.d.ts

@@ -1,6 +1,17 @@
 import { Box3, Matrix4 } from 'three';
 /**
- * adapted from mhluska at https://github.com/mrdoob/three.js/issues/1561
+ * Computes the transformed bounding box of a given Box3 using a transformation matrix.
+ *
+ * @param box - The original bounding box to transform.
+ * @param transform - The transformation matrix to apply.
+ * @returns A new Box3 that represents the transformed bounding box.
  */
 export declare function computeTransformedBoundingBox(box: Box3, transform: Matrix4): Box3;
+/**
+ * Creates a child AABB (Axis-Aligned Bounding Box) from a parent AABB based on the specified index.
+ *
+ * @param aabb - The parent AABB from which to create the child AABB.
+ * @param index - The index that determines how to split the parent AABB into a child AABB.
+ * @returns New Box3 representing the child AABB.
+ */
 export declare function createChildAABB(aabb: Box3, index: number): Box3;

package/dist/utils/box3-helper.d.ts

@@ -1,12 +1,8 @@
 import { Box3, Color, LineSegments } from 'three';
 /**
+ * Helper class to visualize a Box3 bounding box in 3D space.
  *
- * code adapted from three.js BoxHelper.js
- * https://github.com/mrdoob/three.js/blob/dev/src/helpers/BoxHelper.js
- *
- * @author mrdoob / http://mrdoob.com/
- * @author Mugen87 / http://github.com/Mugen87
- * @author mschuetz / http://potree.org
+ * Code adapted from three.js BoxHelper.js
  */
 export declare class Box3Helper extends LineSegments {
     constructor(box: Box3, color?: Color);

package/dist/utils/lru.d.ts

@@ -11,22 +11,76 @@ export declare class LRUItem {
  */
 export declare class LRU {
     pointBudget: number;
+    /**
+     * The least recently used item.
+     */
     first: LRUItem | null;
+    /**
+     * The most recently used item
+     */
     last: LRUItem | null;
+    /**
+     * The total number of points in the LRU cache.
+     */
     numPoints: number;
+    /**
+     * Items in the LRU cache, indexed by node ID.
+     */
     private items;
+    /**
+     * Creates a new LRU cache with a specified point budget.
+     *
+     * @param pointBudget The maximum number of points that can be stored in the LRU cache.
+     */
     constructor(pointBudget?: number);
     get size(): number;
+    /**
+     * Checks if the LRU cache contains the specified node.
+     *
+     * @param node - The node to check for in the LRU cache.
+     * @returns Returns true if the node is in the cache, false otherwise.
+     */
     has(node: Node): boolean;
     /**
-   * Makes the specified the most recently used item. if the list does not contain node, it will
-   * be added.
-   */
+     * Makes the specified the most recently used item. if the list does not contain node, it will be added.
+     *
+     * @param node - The node to touch, making it the most recently used item in the LRU cache.
+     */
     touch(node: Node): void;
+    /**
+     * Adds a new node to the LRU cache, making it the most recently used item.
+     *
+     * @param node - The node to add to the LRU cache.
+     */
     private addNew;
+    /**
+     * Touches an existing item in the LRU cache, moving it to the end of the list (most recently used).
+     *
+     * @param item - The LRUItem to touch, making it the most recently used item in the cache.
+     */
     private touchExisting;
+    /**
+     * Removes a node from the LRU cache.
+     *
+     * @param node - The node to remove from the LRU cache.
+     */
     remove(node: Node): void;
+    /**
+     * Gets the least recently used item from the LRU cache.
+     *
+     * @returns Returns the least recently used node, or undefined if the cache is empty.
+     */
     getLRUItem(): Node | undefined;
+    /**
+     * Frees up memory by removing the least recently used items until the number of points is below the point budget.
+     *
+     * @returns - Returns nothing.
+     */
     freeMemory(): void;
+    /**
+     * Disposes of a subtree starting from the specified node and removes it from the LRU cache.
+     *
+     * @param node - The root node of the subtree to dispose of.
+     */
     disposeSubtree(node: Node): void;
 }

package/dist/utils/math.d.ts

@@ -1 +1,9 @@
+/**
+ * Clamps a number between a minimum and maximum value.
+ *
+ * @param value - The number to clamp.
+ * @param min - The minimum value the number can be.
+ * @param max - The maximum value the number can be.
+ * @returns Clamped value between min and max.
+ */
 export declare function clamp(value: number, min: number, max: number): number;

package/dist/version.d.ts

@@ -3,7 +3,25 @@ export declare class Version {
     versionMajor: number;
     versionMinor: number;
     constructor(version: string);
+    /**
+     * Checks if this version is newer than the given version.
+     *
+     * @param version - The version to compare against.
+     * @returns True if this version is newer than the given version, false otherwise.
+     */
     newerThan(version: string): boolean;
+    /**
+     * Checks if this version is equal or higher than the given version.
+     *
+     * @param version - The version to compare against.
+     * @returns True if this version is equal or higher than the given version, false otherwise.
+     */
     equalOrHigher(version: string): boolean;
+    /**
+     * Checks if this version is equal or lower than the given version.
+     *
+     * @param version - The version to compare against.
+     * @returns True if this version is equal or lower than the given version, false otherwise.
+     */
     upTo(version: string): boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "potree-core",
-	"version": "2.0.10",
+	"version": "2.0.12",
 	"description": "Potree wrapper for three.js applications",
 	"repository": {
 		"type": "git",
@@ -15,10 +15,10 @@
 		"dev": "webpack --mode development --watch --progress --stats-children",
 		"build": "webpack --mode production --config webpack.prod.js",
 		"start": "npm run build && webpack-dev-server --config webpack.example.js --mode development --progress --port 5200",
-		"docs": "jsdoc -d docs source",
-		"pub": "npm run build && npm publish --access public .",
-		"lint": "eslint source",
-		"lint-fix": "eslint --fix source"
+		"docs": "typedoc source/** --out docs --tsconfig tsconfig.json --theme default --excludeExternals --excludeNotDocumented",
+		"pub": "npm run build && npm run docs && npm publish --access public .",
+		"lint": "eslint ./source",
+		"lint-fix": "eslint --fix ./source"
 	},
 	"keywords": [
 		"three",
@@ -32,7 +32,6 @@
 		"three": ">0.125.0"
 	},
 	"dependencies": {
-		"three": "^0.154.0",
 		"brotli": "1.3.3"
 	},
 	"devDependencies": {
@@ -48,12 +47,14 @@
 		"html-webpack-plugin": "5.5.0",
 		"raw-loader": "4.0.2",
 		"style-loader": "3.3.1",
+		"three": "^0.154.0",
 		"ts-loader": "9.5.1",
+		"typedoc": "0.28.5",
 		"typescript": "5.5.4",
 		"webpack": "5.94.0",
 		"webpack-bundle-analyzer": "4.10.2",
 		"webpack-cli": "5.1.4",
-		"webpack-dev-server": "5.0.4",
+		"webpack-dev-server": "5.2.1",
 		"worker-loader": "3.0.8"
 	}
 }