@thatopen/components 2.4.8 → 2.4.9

package/dist/index.mjs

@@ -5,7 +5,7 @@ var __publicField = (obj, key, value) => {
   return value;
 };
 import * as THREE$1 from "three";
-import { BufferAttribute, Vector3, Vector2, Plane, Line3, Triangle, Sphere, Matrix4, Box3, BackSide, DoubleSide, FrontSide, Mesh, Ray, Raycaster, Quaternion, Object3D, Euler, MeshBasicMaterial, LineBasicMaterial, CylinderGeometry, BoxGeometry, BufferGeometry, Float32BufferAttribute, OctahedronGeometry, Line, SphereGeometry, TorusGeometry, PlaneGeometry } from "three";
+import { BufferAttribute, Vector3, Vector2, Plane, Line3, Triangle, Sphere, Matrix4, Box3, BackSide, DoubleSide, FrontSide, Mesh, Ray, Raycaster, Quaternion, Controls, Euler, Object3D, MeshBasicMaterial, LineBasicMaterial, CylinderGeometry, BoxGeometry, BufferGeometry, Float32BufferAttribute, OctahedronGeometry, Line, SphereGeometry, TorusGeometry, PlaneGeometry } from "three";
 import * as FRAGS from "@thatopen/fragments";
 import { FragmentsGroup, Serializer } from "@thatopen/fragments";
 import * as WEBIFC from "web-ifc";
@@ -4002,6 +4002,9 @@ const _plane = new Plane();
 const _closestPoint = new Vector3();
 const _triangle = new Triangle();
 class ConvexHull {
+  /**
+   * Constructs a new convex hull.
+   */
   constructor() {
     this.tolerance = -1;
     this.faces = [];
@@ -4010,16 +4013,29 @@ class ConvexHull {
     this.unassigned = new VertexList();
     this.vertices = [];
   }
+  /**
+   * Computes to convex hull for the given array of points.
+   *
+   * @param {Array<Vector3>} points - The array of points in 3D space.
+   * @return {ConvexHull} A reference to this convex hull.
+   */
   setFromPoints(points) {
     if (points.length >= 4) {
       this.makeEmpty();
       for (let i = 0, l = points.length; i < l; i++) {
         this.vertices.push(new VertexNode(points[i]));
       }
-      this.compute();
+      this._compute();
     }
     return this;
   }
+  /**
+   * Computes the convex hull of the given 3D object (including its descendants),
+   * accounting for the world transforms of both the 3D object and its descendants.
+   *
+   * @param {Object3D} object - The 3D object to compute the convex hull for.
+   * @return {ConvexHull} A reference to this convex hull.
+   */
   setFromObject(object) {
     const points = [];
     object.updateMatrixWorld(true);
@@ -4038,6 +4054,12 @@ class ConvexHull {
     });
     return this.setFromPoints(points);
   }
+  /**
+   * Returns `true` if the given point lies in the convex hull.
+   *
+   * @param {Vector3} point - The point to test.
+   * @return {boolean} Whether the given point lies in the convex hull or not.
+   */
   containsPoint(point) {
     const faces = this.faces;
     for (let i = 0, l = faces.length; i < l; i++) {
@@ -4047,6 +4069,13 @@ class ConvexHull {
     }
     return true;
   }
+  /**
+   * Computes the intersections point of the given ray and this convex hull.
+   *
+   * @param {Ray} ray - The ray to test.
+   * @param {Vector3} target - The target vector that is used to store the method's result.
+   * @return {Vector3|null} The intersection point. Returns `null` if not intersection was detected.
+   */
   intersectRay(ray2, target) {
     const faces = this.faces;
     let tNear = -Infinity;
@@ -4076,16 +4105,35 @@ class ConvexHull {
     }
     return target;
   }
+  /**
+   * Returns `true` if the given ray intersects with this convex hull.
+   *
+   * @param {Ray} ray - The ray to test.
+   * @return {boolean} Whether the given ray intersects with this convex hull or not.
+   */
   intersectsRay(ray2) {
     return this.intersectRay(ray2, _v1$1) !== null;
   }
+  /**
+   * Makes the convex hull empty.
+   *
+   * @return {ConvexHull} A reference to this convex hull.
+   */
   makeEmpty() {
     this.faces = [];
     this.vertices = [];
     return this;
   }
-  // Adds a vertex to the 'assigned' list of vertices and assigns it to the given face
-  addVertexToFace(vertex, face) {
+  // private
+  /**
+   * Adds a vertex to the 'assigned' list of vertices and assigns it to the given face.
+   *
+   * @private
+   * @param {VertexNode} vertex - The vertex to add.
+   * @param {Face} face - The target face.
+   * @return {ConvexHull} A reference to this convex hull.
+   */
+  _addVertexToFace(vertex, face) {
     vertex.face = face;
     if (face.outside === null) {
       this.assigned.append(vertex);
@@ -4095,8 +4143,17 @@ class ConvexHull {
     face.outside = vertex;
     return this;
   }
-  // Removes a vertex from the 'assigned' list of vertices and from the given face
-  removeVertexFromFace(vertex, face) {
+  /**
+   * Removes a vertex from the 'assigned' list of vertices and from the given face.
+   * It also makes sure that the link from 'face' to the first vertex it sees in 'assigned'
+   * is linked correctly after the removal.
+   *
+   * @private
+   * @param {VertexNode} vertex - The vertex to remove.
+   * @param {Face} face - The target face.
+   * @return {ConvexHull} A reference to this convex hull.
+   */
+  _removeVertexFromFace(vertex, face) {
     if (vertex === face.outside) {
       if (vertex.next !== null && vertex.next.face === face) {
         face.outside = vertex.next;
@@ -4107,8 +4164,15 @@ class ConvexHull {
     this.assigned.remove(vertex);
     return this;
   }
-  // Removes all the visible vertices that a given face is able to see which are stored in the 'assigned' vertex list
-  removeAllVerticesFromFace(face) {
+  /**
+   * Removes all the visible vertices that a given face is able to see which are stored in
+   * the 'assigned' vertex list.
+   *
+   * @private
+   * @param {Face} face - The target face.
+   * @return {VertexNode|undefined} A reference to this convex hull.
+   */
+  _removeAllVerticesFromFace(face) {
     if (face.outside !== null) {
       const start = face.outside;
       let end = face.outside;
@@ -4121,9 +4185,20 @@ class ConvexHull {
       return start;
     }
   }
-  // Removes all the visible vertices that 'face' is able to see
-  deleteFaceVertices(face, absorbingFace) {
-    const faceVertices = this.removeAllVerticesFromFace(face);
+  /**
+   * Removes all the visible vertices that `face` is able to see.
+   *
+   * - If `absorbingFace` doesn't exist, then all the removed vertices will be added to the 'unassigned' vertex list.
+   * - If `absorbingFace` exists, then this method will assign all the vertices of 'face' that can see 'absorbingFace'.
+   * - If a vertex cannot see `absorbingFace`, it's added to the 'unassigned' vertex list.
+   *
+   * @private
+   * @param {Face} face - The given face.
+   * @param {Face} [absorbingFace] - An optional face that tries to absorb the vertices of the first face.
+   * @return {ConvexHull} A reference to this convex hull.
+   */
+  _deleteFaceVertices(face, absorbingFace) {
+    const faceVertices = this._removeAllVerticesFromFace(face);
     if (faceVertices !== void 0) {
       if (absorbingFace === void 0) {
         this.unassigned.appendChain(faceVertices);
@@ -4133,7 +4208,7 @@ class ConvexHull {
           const nextVertex = vertex.next;
           const distance = absorbingFace.distanceToPoint(vertex.point);
           if (distance > this.tolerance) {
-            this.addVertexToFace(vertex, absorbingFace);
+            this._addVertexToFace(vertex, absorbingFace);
           } else {
             this.unassigned.append(vertex);
           }
@@ -4143,8 +4218,14 @@ class ConvexHull {
     }
     return this;
   }
-  // Reassigns as many vertices as possible from the unassigned list to the new faces
-  resolveUnassignedPoints(newFaces) {
+  /**
+   * Reassigns as many vertices as possible from the unassigned list to the new faces.
+   *
+   * @private
+   * @param {Array<Face>} newFaces - The new faces.
+   * @return {ConvexHull} A reference to this convex hull.
+   */
+  _resolveUnassignedPoints(newFaces) {
     if (this.unassigned.isEmpty() === false) {
       let vertex = this.unassigned.first();
       do {
@@ -4164,15 +4245,21 @@ class ConvexHull {
           }
         }
         if (maxFace !== null) {
-          this.addVertexToFace(vertex, maxFace);
+          this._addVertexToFace(vertex, maxFace);
         }
         vertex = nextVertex;
       } while (vertex !== null);
     }
     return this;
   }
-  // Computes the extremes of a simplex which will be the initial hull
-  computeExtremes() {
+  /**
+   * Computes the extremes values (min/max vectors) which will be used to
+   * compute the initial hull.
+   *
+   * @private
+   * @return {Object} The extremes.
+   */
+  _computeExtremes() {
     const min = new Vector3();
     const max = new Vector3();
     const minVertices = [];
@@ -4201,11 +4288,16 @@ class ConvexHull {
     this.tolerance = 3 * Number.EPSILON * (Math.max(Math.abs(min.x), Math.abs(max.x)) + Math.max(Math.abs(min.y), Math.abs(max.y)) + Math.max(Math.abs(min.z), Math.abs(max.z)));
     return { min: minVertices, max: maxVertices };
   }
-  // Computes the initial simplex assigning to its faces all the points
-  // that are candidates to form part of the hull
-  computeInitialHull() {
+  /**
+   * Computes the initial simplex assigning to its faces all the points that are
+   * candidates to form part of the hull.
+   *
+   * @private
+   * @return {ConvexHull} A reference to this convex hull.
+   */
+  _computeInitialHull() {
     const vertices = this.vertices;
-    const extremes = this.computeExtremes();
+    const extremes = this._computeExtremes();
     const min = extremes.min;
     const max = extremes.max;
     let maxDistance = 0;
@@ -4288,14 +4380,19 @@ class ConvexHull {
           }
         }
         if (maxFace !== null) {
-          this.addVertexToFace(vertex, maxFace);
+          this._addVertexToFace(vertex, maxFace);
         }
       }
     }
     return this;
   }
-  // Removes inactive faces
-  reindexFaces() {
+  /**
+   * Removes inactive (e.g. deleted) faces from the internal face list.
+   *
+   * @private
+   * @return {ConvexHull} A reference to this convex hull.
+   */
+  _reindexFaces() {
     const activeFaces = [];
     for (let i = 0; i < this.faces.length; i++) {
       const face = this.faces[i];
@@ -4306,8 +4403,17 @@ class ConvexHull {
     this.faces = activeFaces;
     return this;
   }
-  // Finds the next vertex to create faces with the current hull
-  nextVertexToAdd() {
+  /**
+   * Finds the next vertex to create faces with the current hull.
+   *
+   * - Let the initial face be the first face existing in the 'assigned' vertex list.
+   * - If a face doesn't exist then return since there're no vertices left.
+   * - Otherwise for each vertex that face sees find the one furthest away from it.
+   *
+   * @private
+   * @return {?VertexNode} The next vertex to add.
+   */
+  _nextVertexToAdd() {
     if (this.assigned.isEmpty() === false) {
       let eyeVertex, maxDistance = 0;
       const eyeFace = this.assigned.first().face;
@@ -4323,11 +4429,20 @@ class ConvexHull {
       return eyeVertex;
     }
   }
-  // Computes a chain of half edges in CCW order called the 'horizon'.
-  // For an edge to be part of the horizon it must join a face that can see
-  // 'eyePoint' and a face that cannot see 'eyePoint'.
-  computeHorizon(eyePoint, crossEdge, face, horizon) {
-    this.deleteFaceVertices(face);
+  /**
+   * Computes a chain of half edges in CCW order called the 'horizon'. For an edge
+   * to be part of the horizon it must join a face that can see 'eyePoint' and a face
+   * that cannot see 'eyePoint'.
+   *
+   * @private
+   * @param {Vector3} eyePoint - The 3D-coordinates of a point.
+   * @param {HalfEdge} crossEdge - The edge used to jump to the current face.
+   * @param {Face} face - The current face being tested.
+   * @param {Array<HalfEdge>} horizon - The edges that form part of the horizon in CCW order.
+   * @return {ConvexHull} A reference to this convex hull.
+   */
+  _computeHorizon(eyePoint, crossEdge, face, horizon) {
+    this._deleteFaceVertices(face);
     face.mark = Deleted;
     let edge;
     if (crossEdge === null) {
@@ -4340,7 +4455,7 @@ class ConvexHull {
       const oppositeFace = twinEdge.face;
       if (oppositeFace.mark === Visible) {
         if (oppositeFace.distanceToPoint(eyePoint) > this.tolerance) {
-          this.computeHorizon(eyePoint, twinEdge, oppositeFace, horizon);
+          this._computeHorizon(eyePoint, twinEdge, oppositeFace, horizon);
         } else {
           horizon.push(edge);
         }
@@ -4349,22 +4464,38 @@ class ConvexHull {
     } while (edge !== crossEdge);
     return this;
   }
-  // Creates a face with the vertices 'eyeVertex.point', 'horizonEdge.tail' and 'horizonEdge.head' in CCW order
-  addAdjoiningFace(eyeVertex, horizonEdge) {
+  /**
+   * Creates a face with the vertices 'eyeVertex.point', 'horizonEdge.tail' and 'horizonEdge.head'
+   * in CCW order. All the half edges are created in CCW order thus the face is always pointing
+   * outside the hull.
+   *
+   * @private
+   * @param {VertexNode} eyeVertex - The vertex that is added to the hull.
+   * @param {HalfEdge} horizonEdge - A single edge of the horizon.
+   * @return {HalfEdge} The half edge whose vertex is the eyeVertex.
+   */
+  _addAdjoiningFace(eyeVertex, horizonEdge) {
     const face = Face.create(eyeVertex, horizonEdge.tail(), horizonEdge.head());
     this.faces.push(face);
     face.getEdge(-1).setTwin(horizonEdge.twin);
     return face.getEdge(0);
   }
-  //  Adds 'horizon.length' faces to the hull, each face will be linked with the
-  //  horizon opposite face and the face on the left/right
-  addNewFaces(eyeVertex, horizon) {
+  /**
+   * Adds 'horizon.length' faces to the hull, each face will be linked with the horizon
+   * opposite face and the face on the left/right.
+   *
+   * @private
+   * @param {VertexNode} eyeVertex - The vertex that is added to the hull.
+   * @param {Array<HalfEdge>} horizon - The horizon.
+   * @return {ConvexHull} A reference to this convex hull.
+   */
+  _addNewFaces(eyeVertex, horizon) {
     this.newFaces = [];
     let firstSideEdge = null;
     let previousSideEdge = null;
     for (let i = 0; i < horizon.length; i++) {
       const horizonEdge = horizon[i];
-      const sideEdge = this.addAdjoiningFace(eyeVertex, horizonEdge);
+      const sideEdge = this._addAdjoiningFace(eyeVertex, horizonEdge);
       if (firstSideEdge === null) {
         firstSideEdge = sideEdge;
       } else {
@@ -4376,34 +4507,62 @@ class ConvexHull {
     firstSideEdge.next.setTwin(previousSideEdge);
     return this;
   }
-  // Adds a vertex to the hull
-  addVertexToHull(eyeVertex) {
+  /**
+   * Adds a vertex to the hull with the following algorithm:
+   *
+   * - Compute the 'horizon' which is a chain of half edges. For an edge to belong to this group
+   * it must be the edge connecting a face that can see 'eyeVertex' and a face which cannot see 'eyeVertex'.
+   * - All the faces that can see 'eyeVertex' have its visible vertices removed from the assigned vertex list.
+   * - A new set of faces is created with each edge of the 'horizon' and 'eyeVertex'. Each face is connected
+   * with the opposite horizon face and the face on the left/right.
+   * - The vertices removed from all the visible faces are assigned to the new faces if possible.
+   *
+   * @private
+   * @param {VertexNode} eyeVertex - The vertex to add.
+   * @return {ConvexHull} A reference to this convex hull.
+   */
+  _addVertexToHull(eyeVertex) {
     const horizon = [];
     this.unassigned.clear();
-    this.removeVertexFromFace(eyeVertex, eyeVertex.face);
-    this.computeHorizon(eyeVertex.point, null, eyeVertex.face, horizon);
-    this.addNewFaces(eyeVertex, horizon);
-    this.resolveUnassignedPoints(this.newFaces);
+    this._removeVertexFromFace(eyeVertex, eyeVertex.face);
+    this._computeHorizon(eyeVertex.point, null, eyeVertex.face, horizon);
+    this._addNewFaces(eyeVertex, horizon);
+    this._resolveUnassignedPoints(this.newFaces);
     return this;
   }
-  cleanup() {
+  /**
+   * Cleans up internal properties after computing the convex hull.
+   *
+   * @private
+   * @return {ConvexHull} A reference to this convex hull.
+   */
+  _cleanup() {
     this.assigned.clear();
     this.unassigned.clear();
     this.newFaces = [];
     return this;
   }
-  compute() {
+  /**
+   * Starts the execution of the quick hull algorithm.
+   *
+   * @private
+   * @return {ConvexHull} A reference to this convex hull.
+   */
+  _compute() {
     let vertex;
-    this.computeInitialHull();
-    while ((vertex = this.nextVertexToAdd()) !== void 0) {
-      this.addVertexToHull(vertex);
+    this._computeInitialHull();
+    while ((vertex = this._nextVertexToAdd()) !== void 0) {
+      this._addVertexToHull(vertex);
     }
-    this.reindexFaces();
-    this.cleanup();
+    this._reindexFaces();
+    this._cleanup();
     return this;
   }
 }
 class Face {
+  /**
+   * Constructs a new face.
+   */
   constructor() {
     this.normal = new Vector3();
     this.midpoint = new Vector3();
@@ -4413,6 +4572,15 @@ class Face {
     this.mark = Visible;
     this.edge = null;
   }
+  /**
+   * Creates a face from the given vertex nodes.
+   *
+   * @private
+   * @param {VertexNode} a - The first vertex node.
+   * @param {VertexNode} b - The second vertex node.
+   * @param {VertexNode} c - The third vertex node.
+   * @return {Face} The created face.
+   */
   static create(a, b, c) {
     const face = new Face();
     const e0 = new HalfEdge(a, face);
@@ -4424,6 +4592,13 @@ class Face {
     face.edge = e0;
     return face.compute();
   }
+  /**
+   * Returns an edge by the given index.
+   *
+   * @private
+   * @param {number} i - The edge index.
+   * @return {HalfEdge} The edge.
+   */
   getEdge(i) {
     let edge = this.edge;
     while (i > 0) {
@@ -4436,6 +4611,12 @@ class Face {
     }
     return edge;
   }
+  /**
+   * Computes all properties of the face.
+   *
+   * @private
+   * @return {Face} A reference to this face.
+   */
   compute() {
     const a = this.edge.tail();
     const b = this.edge.head();
@@ -4447,11 +4628,24 @@ class Face {
     this.constant = this.normal.dot(this.midpoint);
     return this;
   }
+  /**
+   * Returns the signed distance from a given point to the plane representation of this face.
+   *
+   * @private
+   * @param {Vector3} point - The point to compute the distance to.
+   * @return {number} The distance.
+   */
   distanceToPoint(point) {
     return this.normal.dot(point) - this.constant;
   }
 }
 class HalfEdge {
+  /**
+   * Constructs a new half edge.
+   *
+   * @param {VertexNode} vertex - A reference to its destination vertex.
+   * @param {Face} face - A reference to its face.
+   */
   constructor(vertex, face) {
     this.vertex = vertex;
     this.prev = null;
@@ -4459,12 +4653,30 @@ class HalfEdge {
     this.twin = null;
     this.face = face;
   }
+  /**
+   * Returns the destination vertex.
+   *
+   * @private
+   * @return {VertexNode} The destination vertex.
+   */
   head() {
     return this.vertex;
   }
+  /**
+   * Returns the origin vertex.
+   *
+   * @private
+   * @return {VertexNode} The destination vertex.
+   */
   tail() {
     return this.prev ? this.prev.vertex : null;
   }
+  /**
+   * Returns the Euclidean length (straight-line length) of the edge.
+   *
+   * @private
+   * @return {number} The edge's length.
+   */
   length() {
     const head = this.head();
     const tail = this.tail();
@@ -4473,6 +4685,12 @@ class HalfEdge {
     }
     return -1;
   }
+  /**
+   * Returns the square of the Euclidean length (straight-line length) of the edge.
+   *
+   * @private
+   * @return {number} The square of the edge's length.
+   */
   lengthSquared() {
     const head = this.head();
     const tail = this.tail();
@@ -4481,6 +4699,14 @@ class HalfEdge {
     }
     return -1;
   }
+  /**
+   * Sets the twin edge of this half-edge. It also ensures that the twin reference
+   * of the given half-edge is correctly set.
+   *
+   * @private
+   * @param {HalfEdge} edge - The twin edge to set.
+   * @return {HalfEdge} A reference to this edge.
+   */
   setTwin(edge) {
     this.twin = edge;
     edge.twin = this;
@@ -4488,6 +4714,11 @@ class HalfEdge {
   }
 }
 class VertexNode {
+  /**
+   * Constructs a new vertex node.
+   *
+   * @param {Vector3} point - A point in 3D space.
+   */
   constructor(point) {
     this.point = point;
     this.prev = null;
@@ -4496,21 +4727,49 @@ class VertexNode {
   }
 }
 class VertexList {
+  /**
+   * Constructs a new vertex list.
+   */
   constructor() {
     this.head = null;
     this.tail = null;
   }
+  /**
+   * Returns the head reference.
+   *
+   * @private
+   * @return {VertexNode} The head reference.
+   */
   first() {
     return this.head;
   }
+  /**
+   * Returns the tail reference.
+   *
+   * @private
+   * @return {VertexNode} The tail reference.
+   */
   last() {
     return this.tail;
   }
+  /**
+   * Clears the linked list.
+   *
+   * @private
+   * @return {VertexList} A reference to this vertex list.
+   */
   clear() {
     this.head = this.tail = null;
     return this;
   }
-  // Inserts a vertex before the target vertex
+  /**
+   * Inserts a vertex before a target vertex.
+   *
+   * @private
+   * @param {VertexNode} target - The target.
+   * @param {VertexNode} vertex - The vertex to insert.
+   * @return {VertexList} A reference to this vertex list.
+   */
   insertBefore(target, vertex) {
     vertex.prev = target.prev;
     vertex.next = target;
@@ -4522,7 +4781,14 @@ class VertexList {
     target.prev = vertex;
     return this;
   }
-  // Inserts a vertex after the target vertex
+  /**
+   * Inserts a vertex after a target vertex.
+   *
+   * @private
+   * @param {VertexNode} target - The target.
+   * @param {VertexNode} vertex - The vertex to insert.
+   * @return {VertexList} A reference to this vertex list.
+   */
   insertAfter(target, vertex) {
     vertex.prev = target;
     vertex.next = target.next;
@@ -4534,7 +4800,13 @@ class VertexList {
     target.next = vertex;
     return this;
   }
-  // Appends a vertex to the end of the linked list
+  /**
+   * Appends a vertex to this vertex list.
+   *
+   * @private
+   * @param {VertexNode} vertex - The vertex to append.
+   * @return {VertexList} A reference to this vertex list.
+   */
   append(vertex) {
     if (this.head === null) {
       this.head = vertex;
@@ -4546,7 +4818,13 @@ class VertexList {
     this.tail = vertex;
     return this;
   }
-  // Appends a chain of vertices where 'vertex' is the head.
+  /**
+   * Appends a chain of vertices where the given vertex is the head.
+   *
+   * @private
+   * @param {VertexNode} vertex - The head vertex of a chain of vertices.
+   * @return {VertexList} A reference to this vertex list.
+   */
   appendChain(vertex) {
     if (this.head === null) {
       this.head = vertex;
@@ -4560,7 +4838,13 @@ class VertexList {
     this.tail = vertex;
     return this;
   }
-  // Removes a vertex from the linked list
+  /**
+   * Removes a vertex from the linked list.
+   *
+   * @private
+   * @param {VertexNode} vertex - The vertex to remove.
+   * @return {VertexList} A reference to this vertex list.
+   */
   remove(vertex) {
     if (vertex.prev === null) {
       this.head = vertex.next;
@@ -4574,7 +4858,14 @@ class VertexList {
     }
     return this;
   }
-  // Removes a list of vertices whose 'head' is 'a' and whose 'tail' is b
+  /**
+   * Removes a sublist of vertices from the linked list.
+   *
+   * @private
+   * @param {VertexNode} a - The head of the sublist.
+   * @param {VertexNode} b - The tail of the sublist.
+   * @return {VertexList} A reference to this vertex list.
+   */
   removeSubList(a, b) {
     if (a.prev === null) {
       this.head = b.next;
@@ -4588,6 +4879,12 @@ class VertexList {
     }
     return this;
   }
+  /**
+   * Returns `true` if the linked list is empty.
+   *
+   * @private
+   * @return {boolean} Whether the linked list is empty or not.
+   */
   isEmpty() {
     return this.head === null;
   }
@@ -6293,7 +6590,7 @@ const _Components = class _Components {
 /**
  * The version of the @thatopen/components library.
  */
-__publicField(_Components, "release", "2.4.8");
+__publicField(_Components, "release", "2.4.9");
 let Components = _Components;
 class SimpleWorld extends Base {
   constructor() {
@@ -10789,7 +11086,7 @@ class SimpleGrid {
             
             `,
       extensions: {
-        derivatives: true
+        // derivatives: true,
       }
     });
     this.three = new THREE$1.Mesh(geometry, material);
@@ -10943,26 +11240,26 @@ const _unit = {
   Z: new Vector3(0, 0, 1)
 };
 const _changeEvent = { type: "change" };
-const _mouseDownEvent = { type: "mouseDown" };
+const _mouseDownEvent = { type: "mouseDown", mode: null };
 const _mouseUpEvent = { type: "mouseUp", mode: null };
 const _objectChangeEvent = { type: "objectChange" };
-class TransformControls extends Object3D {
-  constructor(camera, domElement) {
-    super();
-    if (domElement === void 0) {
-      console.warn('THREE.TransformControls: The second parameter "domElement" is now mandatory.');
-      domElement = document;
-    }
-    this.isTransformControls = true;
-    this.visible = false;
-    this.domElement = domElement;
-    this.domElement.style.touchAction = "none";
-    const _gizmo = new TransformControlsGizmo();
-    this._gizmo = _gizmo;
-    this.add(_gizmo);
-    const _plane2 = new TransformControlsPlane();
-    this._plane = _plane2;
-    this.add(_plane2);
+class TransformControls extends Controls {
+  /**
+   * Constructs a new controls instance.
+   *
+   * @param {Camera} camera - The camera of the rendered scene.
+   * @param {?HTMLDOMElement} domElement - The HTML element used for event listeners.
+   */
+  constructor(camera, domElement = null) {
+    super(void 0, domElement);
+    const root = new TransformControlsRoot(this);
+    this._root = root;
+    const gizmo = new TransformControlsGizmo();
+    this._gizmo = gizmo;
+    root.add(gizmo);
+    const plane = new TransformControlsPlane();
+    this._plane = plane;
+    root.add(plane);
     const scope = this;
     function defineProperty(propName2, defaultValue) {
       let propValue = defaultValue;
@@ -10973,16 +11270,16 @@ class TransformControls extends Object3D {
         set: function(value) {
           if (propValue !== value) {
             propValue = value;
-            _plane2[propName2] = value;
-            _gizmo[propName2] = value;
+            plane[propName2] = value;
+            gizmo[propName2] = value;
             scope.dispatchEvent({ type: propName2 + "-changed", value });
             scope.dispatchEvent(_changeEvent);
           }
         }
       });
       scope[propName2] = defaultValue;
-      _plane2[propName2] = defaultValue;
-      _gizmo[propName2] = defaultValue;
+      plane[propName2] = defaultValue;
+      gizmo[propName2] = defaultValue;
     }
     defineProperty("camera", camera);
     defineProperty("object", void 0);
@@ -10998,6 +11295,12 @@ class TransformControls extends Object3D {
     defineProperty("showX", true);
     defineProperty("showY", true);
     defineProperty("showZ", true);
+    defineProperty("minX", -Infinity);
+    defineProperty("maxX", Infinity);
+    defineProperty("minY", -Infinity);
+    defineProperty("maxY", Infinity);
+    defineProperty("minZ", -Infinity);
+    defineProperty("maxZ", Infinity);
     const worldPosition = new Vector3();
     const worldPositionStart = new Vector3();
     const worldQuaternion = new Quaternion();
@@ -11039,36 +11342,38 @@ class TransformControls extends Object3D {
     this._onPointerHover = onPointerHover.bind(this);
     this._onPointerMove = onPointerMove.bind(this);
     this._onPointerUp = onPointerUp.bind(this);
+    if (domElement !== null) {
+      this.connect(domElement);
+    }
+  }
+  connect(element) {
+    super.connect(element);
     this.domElement.addEventListener("pointerdown", this._onPointerDown);
     this.domElement.addEventListener("pointermove", this._onPointerHover);
     this.domElement.addEventListener("pointerup", this._onPointerUp);
+    this.domElement.style.touchAction = "none";
   }
-  // updateMatrixWorld  updates key transformation variables
-  updateMatrixWorld() {
-    if (this.object !== void 0) {
-      this.object.updateMatrixWorld();
-      if (this.object.parent === null) {
-        console.error("TransformControls: The attached 3D object must be a part of the scene graph.");
-      } else {
-        this.object.parent.matrixWorld.decompose(this._parentPosition, this._parentQuaternion, this._parentScale);
-      }
-      this.object.matrixWorld.decompose(this.worldPosition, this.worldQuaternion, this._worldScale);
-      this._parentQuaternionInv.copy(this._parentQuaternion).invert();
-      this._worldQuaternionInv.copy(this.worldQuaternion).invert();
-    }
-    this.camera.updateMatrixWorld();
-    this.camera.matrixWorld.decompose(this.cameraPosition, this.cameraQuaternion, this._cameraScale);
-    if (this.camera.isOrthographicCamera) {
-      this.camera.getWorldDirection(this.eye).negate();
-    } else {
-      this.eye.copy(this.cameraPosition).sub(this.worldPosition).normalize();
-    }
-    super.updateMatrixWorld(this);
+  disconnect() {
+    this.domElement.removeEventListener("pointerdown", this._onPointerDown);
+    this.domElement.removeEventListener("pointermove", this._onPointerHover);
+    this.domElement.removeEventListener("pointermove", this._onPointerMove);
+    this.domElement.removeEventListener("pointerup", this._onPointerUp);
+    this.domElement.style.touchAction = "auto";
+  }
+  /**
+   * Returns the visual representation of the controls. Add the helper to your scene to
+   * visually transform the attached  3D object.
+   *
+   * @return {TransformControlsRoot} The helper.
+   */
+  getHelper() {
+    return this._root;
   }
   pointerHover(pointer) {
     if (this.object === void 0 || this.dragging === true)
       return;
-    _raycaster.setFromCamera(pointer, this.camera);
+    if (pointer !== null)
+      _raycaster.setFromCamera(pointer, this.camera);
     const intersect = intersectObjectWithRay(this._gizmo.picker[this.mode], _raycaster);
     if (intersect) {
       this.axis = intersect.object.name;
@@ -11077,10 +11382,11 @@ class TransformControls extends Object3D {
     }
   }
   pointerDown(pointer) {
-    if (this.object === void 0 || this.dragging === true || pointer.button !== 0)
+    if (this.object === void 0 || this.dragging === true || pointer != null && pointer.button !== 0)
       return;
     if (this.axis !== null) {
-      _raycaster.setFromCamera(pointer, this.camera);
+      if (pointer !== null)
+        _raycaster.setFromCamera(pointer, this.camera);
       const planeIntersect = intersectObjectWithRay(this._plane, _raycaster, true);
       if (planeIntersect) {
         this.object.updateMatrixWorld();
@@ -11106,9 +11412,10 @@ class TransformControls extends Object3D {
     } else if (axis === "E" || axis === "XYZE" || axis === "XYZ") {
       space = "world";
     }
-    if (object === void 0 || axis === null || this.dragging === false || pointer.button !== -1)
+    if (object === void 0 || axis === null || this.dragging === false || pointer !== null && pointer.button !== -1)
       return;
-    _raycaster.setFromCamera(pointer, this.camera);
+    if (pointer !== null)
+      _raycaster.setFromCamera(pointer, this.camera);
     const planeIntersect = intersectObjectWithRay(this._plane, _raycaster, true);
     if (!planeIntersect)
       return;
@@ -11162,6 +11469,9 @@ class TransformControls extends Object3D {
           }
         }
       }
+      object.position.x = Math.max(this.minX, Math.min(this.maxX, object.position.x));
+      object.position.y = Math.max(this.minY, Math.min(this.maxY, object.position.y));
+      object.position.z = Math.max(this.minZ, Math.min(this.maxZ, object.position.z));
     } else if (mode === "scale") {
       if (axis.search("XYZ") !== -1) {
         let d = this.pointEnd.length() / this.pointStart.length();
@@ -11238,7 +11548,7 @@ class TransformControls extends Object3D {
     this.dispatchEvent(_objectChangeEvent);
   }
   pointerUp(pointer) {
-    if (pointer.button !== 0)
+    if (pointer !== null && pointer.button !== 0)
       return;
     if (this.dragging && this.axis !== null) {
       _mouseUpEvent.mode = this.mode;
@@ -11248,30 +11558,34 @@ class TransformControls extends Object3D {
     this.axis = null;
   }
   dispose() {
-    this.domElement.removeEventListener("pointerdown", this._onPointerDown);
-    this.domElement.removeEventListener("pointermove", this._onPointerHover);
-    this.domElement.removeEventListener("pointermove", this._onPointerMove);
-    this.domElement.removeEventListener("pointerup", this._onPointerUp);
-    this.traverse(function(child) {
-      if (child.geometry)
-        child.geometry.dispose();
-      if (child.material)
-        child.material.dispose();
-    });
+    this.disconnect();
+    this._root.dispose();
   }
-  // Set current object
+  /**
+   * Sets the 3D object that should be transformed and ensures the controls UI is visible.
+   *
+   * @param {Object3D} object -  The 3D object that should be transformed.
+   * @return {TransformControls} A reference to this controls.
+   */
   attach(object) {
     this.object = object;
-    this.visible = true;
+    this._root.visible = true;
     return this;
   }
-  // Detach from object
+  /**
+   * Removes the current 3D object from the controls and makes the helper UI invisible.
+   *
+   * @return {TransformControls} A reference to this controls.
+   */
   detach() {
     this.object = void 0;
-    this.visible = false;
     this.axis = null;
+    this._root.visible = false;
     return this;
   }
+  /**
+   * Resets the object's position, rotation and scale to when the current transform began.
+   */
   reset() {
     if (!this.enabled)
       return;
@@ -11284,28 +11598,68 @@ class TransformControls extends Object3D {
       this.pointStart.copy(this.pointEnd);
     }
   }
+  /**
+   * Returns the raycaster that is used for user interaction. This object is shared between all
+   * instances of `TransformControls`.
+   *
+   * @returns {Raycaster} The internal raycaster.
+   */
   getRaycaster() {
     return _raycaster;
   }
-  // TODO: deprecate
+  /**
+   * Returns the transformation mode.
+   *
+   * @returns {'translate'|'rotate'|'scale'} The transformation mode.
+   */
   getMode() {
     return this.mode;
   }
+  /**
+   * Sets the given transformation mode.
+   *
+   * @param {'translate'|'rotate'|'scale'} mode - The transformation mode to set.
+   */
   setMode(mode) {
     this.mode = mode;
   }
+  /**
+   * Sets the translation snap.
+   *
+   * @param {?number} translationSnap - The translation snap to set.
+   */
   setTranslationSnap(translationSnap) {
     this.translationSnap = translationSnap;
   }
+  /**
+   * Sets the rotation snap.
+   *
+   * @param {?number} rotationSnap - The rotation snap to set.
+   */
   setRotationSnap(rotationSnap) {
     this.rotationSnap = rotationSnap;
   }
+  /**
+   * Sets the scale snap.
+   *
+   * @param {?number} scaleSnap - The scale snap to set.
+   */
   setScaleSnap(scaleSnap) {
     this.scaleSnap = scaleSnap;
   }
+  /**
+   * Sets the size of the helper UI.
+   *
+   * @param {number} size - The size to set.
+   */
   setSize(size) {
     this.size = size;
   }
+  /**
+   * Sets the coordinate space in which transformations are applied.
+   *
+   * @param {'world'|'local'} space - The space to set.
+   */
   setSpace(space) {
     this.space = space;
   }
@@ -11381,6 +11735,45 @@ const _unitZ = new Vector3(0, 0, 1);
 const _v1 = new Vector3();
 const _v2 = new Vector3();
 const _v3 = new Vector3();
+class TransformControlsRoot extends Object3D {
+  constructor(controls) {
+    super();
+    this.isTransformControlsRoot = true;
+    this.controls = controls;
+    this.visible = false;
+  }
+  // updateMatrixWorld updates key transformation variables
+  updateMatrixWorld(force) {
+    const controls = this.controls;
+    if (controls.object !== void 0) {
+      controls.object.updateMatrixWorld();
+      if (controls.object.parent === null) {
+        console.error("TransformControls: The attached 3D object must be a part of the scene graph.");
+      } else {
+        controls.object.parent.matrixWorld.decompose(controls._parentPosition, controls._parentQuaternion, controls._parentScale);
+      }
+      controls.object.matrixWorld.decompose(controls.worldPosition, controls.worldQuaternion, controls._worldScale);
+      controls._parentQuaternionInv.copy(controls._parentQuaternion).invert();
+      controls._worldQuaternionInv.copy(controls.worldQuaternion).invert();
+    }
+    controls.camera.updateMatrixWorld();
+    controls.camera.matrixWorld.decompose(controls.cameraPosition, controls.cameraQuaternion, controls._cameraScale);
+    if (controls.camera.isOrthographicCamera) {
+      controls.camera.getWorldDirection(controls.eye).negate();
+    } else {
+      controls.eye.copy(controls.cameraPosition).sub(controls.worldPosition).normalize();
+    }
+    super.updateMatrixWorld(force);
+  }
+  dispose() {
+    this.traverse(function(child) {
+      if (child.geometry)
+        child.geometry.dispose();
+      if (child.material)
+        child.material.dispose();
+    });
+  }
+}
 class TransformControlsGizmo extends Object3D {
   constructor() {
     super();
@@ -12006,7 +12399,7 @@ class SimplePlane {
   /** {@link Hideable.visible } */
   set visible(state) {
     this._visible = state;
-    this._controls.visible = state;
+    this._controls.object.visible = state;
     this._helper.visible = state;
     this.toggleControls(state);
   }
@@ -12073,7 +12466,7 @@ class SimplePlane {
     this._arrowBoundBox.removeFromParent();
     this._arrowBoundBox.geometry.dispose();
     this._planeMesh.geometry.dispose();
-    this._controls.removeFromParent();
+    this._controls.object.removeFromParent();
     this._controls.dispose();
     this.onDisposed.trigger();
     this.onDisposed.reset();
@@ -12109,7 +12502,7 @@ class SimplePlane {
     const container = this.world.renderer.three.domElement;
     const controls = new TransformControls(camera, container);
     this.initializeControls(controls);
-    this.world.scene.three.add(controls);
+    this.world.scene.three.add(controls.object);
     return controls;
   }
   initializeControls(controls) {
@@ -12118,7 +12511,7 @@ class SimplePlane {
     controls.showY = false;
     controls.setSpace("local");
     this.createArrowBoundingBox();
-    controls.children[0].children[0].add(this._arrowBoundBox);
+    controls.object.children[0].children[0].add(this._arrowBoundBox);
   }
   createArrowBoundingBox() {
     this._arrowBoundBox.geometry = new THREE$1.CylinderGeometry(0.18, 0.18, 1.2);