@bitbybit-dev/base 0.20.13 → 0.21.0

package/lib/api/services/point.d.ts

@@ -16,7 +16,8 @@ export declare class Point {
     private readonly lists;
     constructor(geometryHelper: GeometryHelper, transforms: Transforms, vector: Vector, lists: Lists);
     /**
-     * Transforms the single point
+     * Applies transformation matrix to a single point (rotates, scales, or translates).
+     * Example: point=[0,0,0] with translation [5,5,0] → [5,5,0]
      * @param inputs Contains a point and the transformations to apply
      * @returns Transformed point
      * @group transforms
@@ -25,7 +26,8 @@ export declare class Point {
      */
     transformPoint(inputs: Inputs.Point.TransformPointDto): Inputs.Base.Point3;
     /**
-     * Transforms multiple points
+     * Applies same transformation matrix to multiple points (batch transform).
+     * Example: 5 points with rotation 90° → all 5 points rotated together
      * @param inputs Contains points and the transformations to apply
      * @returns Transformed points
      * @group transforms
@@ -34,7 +36,9 @@ export declare class Point {
      */
     transformPoints(inputs: Inputs.Point.TransformPointsDto): Inputs.Base.Point3[];
     /**
-     * Transforms multiple points by multiple transformations
+     * Applies different transformation matrices to corresponding points (one transform per point).
+     * Arrays must have equal length.
+     * Example: 3 points with 3 different translations → each point moved independently
      * @param inputs Contains points and the transformations to apply
      * @returns Transformed points
      * @group transforms
@@ -43,7 +47,8 @@ export declare class Point {
      */
     transformsForPoints(inputs: Inputs.Point.TransformsForPointsDto): Inputs.Base.Point3[];
     /**
-     * Translate multiple points
+     * Moves multiple points by a translation vector (same offset for all points).
+     * Example: points=[[0,0,0], [1,0,0]], translation=[5,5,0] → [[5,5,0], [6,5,0]]
      * @param inputs Contains points and the translation vector
      * @returns Translated points
      * @group transforms
@@ -52,7 +57,9 @@ export declare class Point {
      */
     translatePoints(inputs: Inputs.Point.TranslatePointsDto): Inputs.Base.Point3[];
     /**
-     * Translate multiple points
+     * Moves multiple points by corresponding translation vectors (one vector per point).
+     * Arrays must have equal length.
+     * Example: 3 points with 3 different vectors → each point moved by its corresponding vector
      * @param inputs Contains points and the translation vector
      * @returns Translated points
      * @group transforms
@@ -61,7 +68,8 @@ export declare class Point {
      */
     translatePointsWithVectors(inputs: Inputs.Point.TranslatePointsWithVectorsDto): Inputs.Base.Point3[];
     /**
-     * Translate multiple points by x, y, z values provided
+     * Moves multiple points by separate X, Y, Z values (convenience method for translation).
+     * Example: points=[[0,0,0]], x=10, y=5, z=0 → [[10,5,0]]
      * @param inputs Contains points and the translation in x y and z
      * @returns Translated points
      * @group transforms
@@ -70,7 +78,8 @@ export declare class Point {
      */
     translateXYZPoints(inputs: Inputs.Point.TranslateXYZPointsDto): Inputs.Base.Point3[];
     /**
-     * Scale multiple points by providing center point and x, y, z scale factors
+     * Scales multiple points around a center point with different factors per axis.
+     * Example: points=[[10,0,0]], center=[5,0,0], scaleXyz=[2,1,1] → [[15,0,0]] (doubles X distance from center)
      * @param inputs Contains points, center point and scale factors
      * @returns Scaled points
      * @group transforms
@@ -79,7 +88,8 @@ export declare class Point {
      */
     scalePointsCenterXYZ(inputs: Inputs.Point.ScalePointsCenterXYZDto): Inputs.Base.Point3[];
     /**
-     * Stretch multiple points by providing center point, direction and uniform scale factor
+     * Stretches multiple points along a direction from a center point (directional scaling).
+     * Example: points=[[10,0,0]], center=[0,0,0], direction=[1,0,0], scale=2 → [[20,0,0]]
      * @param inputs Contains points, center point, direction and scale factor
      * @returns Stretched points
      * @group transforms
@@ -88,7 +98,8 @@ export declare class Point {
      */
     stretchPointsDirFromCenter(inputs: Inputs.Point.StretchPointsDirFromCenterDto): Inputs.Base.Point3[];
     /**
-     * Rotate multiple points by providing center point, axis and degrees of rotation
+     * Rotates multiple points around a center point along a custom axis.
+     * Example: points=[[10,0,0]], center=[0,0,0], axis=[0,1,0], angle=90° → [[0,0,-10]]
      * @param inputs Contains points, axis, center point and angle of rotation
      * @returns Rotated points
      * @group transforms
@@ -97,7 +108,8 @@ export declare class Point {
      */
     rotatePointsCenterAxis(inputs: Inputs.Point.RotatePointsCenterAxisDto): Inputs.Base.Point3[];
     /**
-     * Gets a bounding box of the points
+     * Calculates axis-aligned bounding box containing all points (min, max, center, width, height, length).
+     * Example: points=[[0,0,0], [10,5,3]] → {min:[0,0,0], max:[10,5,3], center:[5,2.5,1.5], width:10, height:5, length:3}
      * @param inputs Points
      * @returns Bounding box of points
      * @group extract
@@ -106,7 +118,8 @@ export declare class Point {
      */
     boundingBoxOfPoints(inputs: Inputs.Point.PointsDto): Inputs.Base.BoundingBox;
     /**
-     * Measures the closest distance between a point and a collection of points
+     * Calculates distance to the nearest point in a collection.
+     * Example: point=[0,0,0], points=[[5,0,0], [10,0,0], [3,0,0]] → 3 (distance to [3,0,0])
      * @param inputs Point from which to measure and points to measure the distance against
      * @returns Distance to closest point
      * @group extract
@@ -115,7 +128,8 @@ export declare class Point {
      */
     closestPointFromPointsDistance(inputs: Inputs.Point.ClosestPointFromPointsDto): number;
     /**
-     * Finds the closest point index between a point and a collection of points. Caution, index is not 0 based, it starts with 1.
+     * Finds array index of the nearest point in a collection (1-based index, not 0-based).
+     * Example: point=[0,0,0], points=[[5,0,0], [10,0,0], [3,0,0]] → 3 (index of [3,0,0])
      * @param inputs Point from which to find the index in a collection of points
      * @returns Closest point index
      * @group extract
@@ -124,7 +138,8 @@ export declare class Point {
      */
     closestPointFromPointsIndex(inputs: Inputs.Point.ClosestPointFromPointsDto): number;
     /**
-     * Finds the closest point in a collection
+     * Finds the nearest point in a collection to a reference point.
+     * Example: point=[0,0,0], points=[[5,0,0], [10,0,0], [3,0,0]] → [3,0,0]
      * @param inputs Point and points collection to find the closest point in
      * @returns Closest point
      * @group extract
@@ -133,7 +148,8 @@ export declare class Point {
      */
     closestPointFromPoints(inputs: Inputs.Point.ClosestPointFromPointsDto): Inputs.Base.Point3;
     /**
-     * Finds the distance between two points
+     * Calculates Euclidean distance between two points.
+     * Example: start=[0,0,0], end=[3,4,0] → 5 (using Pythagorean theorem: √(3²+4²))
      * @param inputs Coordinates of start and end points
      * @returns Distance
      * @group measure
@@ -142,7 +158,8 @@ export declare class Point {
      */
     distance(inputs: Inputs.Point.StartEndPointsDto): number;
     /**
-     * Finds the distances between the start point and multiple end points
+     * Calculates distances from a start point to multiple end points.
+     * Example: start=[0,0,0], endPoints=[[3,0,0], [0,4,0], [5,0,0]] → [3, 4, 5]
      * @param inputs Coordinates of start and end points
      * @returns Distances
      * @group measure
@@ -151,7 +168,8 @@ export declare class Point {
      */
     distancesToPoints(inputs: Inputs.Point.StartEndPointsListDto): number[];
     /**
-     * Multiply point by a specified amount
+     * Duplicates a point N times (creates array with N copies of the same point).
+     * Example: point=[5,5,0], amountOfPoints=3 → [[5,5,0], [5,5,0], [5,5,0]]
      * @param inputs The point to be multiplied and the amount of points to create
      * @returns Distance
      * @group transforms
@@ -160,7 +178,8 @@ export declare class Point {
      */
     multiplyPoint(inputs: Inputs.Point.MultiplyPointDto): Inputs.Base.Point3[];
     /**
-     * Get x coordinate of the point
+     * Extracts X coordinate from a point.
+     * Example: point=[5,10,3] → 5
      * @param inputs The point
      * @returns X coordinate
      * @group get
@@ -169,7 +188,8 @@ export declare class Point {
      */
     getX(inputs: Inputs.Point.PointDto): number;
     /**
-     * Get y coordinate of the point
+     * Extracts Y coordinate from a point.
+     * Example: point=[5,10,3] → 10
      * @param inputs The point
      * @returns Y coordinate
      * @group get
@@ -178,7 +198,8 @@ export declare class Point {
      */
     getY(inputs: Inputs.Point.PointDto): number;
     /**
-     * Get z coordinate of the point
+     * Extracts Z coordinate from a point.
+     * Example: point=[5,10,3] → 3
      * @param inputs The point
      * @returns Z coordinate
      * @group get
@@ -187,7 +208,8 @@ export declare class Point {
      */
     getZ(inputs: Inputs.Point.PointDto): number;
     /**
-     * Get average point of points
+     * Calculates centroid (average position) of multiple points.
+     * Example: points=[[0,0,0], [10,0,0], [10,10,0]] → [6.67,3.33,0]
      * @param inputs The points
      * @returns point
      * @group extract
@@ -196,7 +218,8 @@ export declare class Point {
      */
     averagePoint(inputs: Inputs.Point.PointsDto): Inputs.Base.Point3;
     /**
-     * Creates the xyz point
+     * Creates a 3D point from X, Y, Z coordinates.
+     * Example: x=10, y=5, z=3 → [10,5,3]
      * @param inputs xyz information
      * @returns point 3d
      * @group create
@@ -205,7 +228,8 @@ export declare class Point {
      */
     pointXYZ(inputs: Inputs.Point.PointXYZDto): Inputs.Base.Point3;
     /**
-     * Creates the xy point
+     * Creates a 2D point from X, Y coordinates.
+     * Example: x=10, y=5 → [10,5]
      * @param inputs xy information
      * @returns point 3d
      * @group create
@@ -214,7 +238,9 @@ export declare class Point {
      */
     pointXY(inputs: Inputs.Point.PointXYDto): Inputs.Base.Point2;
     /**
-     * Creates the spiral out of multiple points
+     * Creates logarithmic spiral points using golden angle or custom widening factor.
+     * Generates natural spiral patterns common in nature (sunflower, nautilus shell).
+     * Example: numberPoints=100, radius=10, phi=1.618 → 100 points forming outward spiral
      * @param inputs Spiral information
      * @returns Specified number of points in the array along the spiral
      * @group create
@@ -223,8 +249,9 @@ export declare class Point {
      */
     spiral(inputs: Inputs.Point.SpiralDto): Inputs.Base.Point3[];
     /**
-     * Creates a flat point grid on XY plane. This grid contains center points for hexagons of the given radius.
-     * Be aware that we control only the nr of hexagons to be made and not the length and width of the grid.
+     * Creates hexagonal grid center points on XY plane (honeycomb pattern).
+     * Grid size controlled by number of hexagons, not width/height.
+     * Example: radiusHexagon=1, nrHexagonsX=3, nrHexagonsY=3 → 9 hex centers in grid pattern
      * @param inputs Information about hexagon and the grid
      * @returns Points in the array on the grid
      * @group create
@@ -233,9 +260,9 @@ export declare class Point {
      */
     hexGrid(inputs: Inputs.Point.HexGridCentersDto): Inputs.Base.Point3[];
     /**
-     * Creates a pointy-top or flat-top hexagon grid, scaling hexagons to fit specified dimensions exactly.
-     * Returns both center points and the vertices of each (potentially scaled) hexagon.
-     * Hexagons are ordered column-first, then row-first.
+     * Creates hexagonal grid scaled to fit within specified width/height bounds (auto-calculates hex size).
+     * Returns center points and hex vertices. Supports pointy-top or flat-top orientation.
+     * Example: width=10, height=10, nrHexagonsInHeight=3 → hex grid filling 10×10 area with 3 rows
      * @param inputs Information about the desired grid dimensions and hexagon counts.
      * @returns An object containing the array of center points and an array of hexagon vertex arrays.
      * @group create
@@ -291,7 +318,8 @@ export declare class Point {
      */
     safestPointsMaxFilletHalfLine(inputs: Inputs.Point.PointsMaxFilletsHalfLineDto): number;
     /**
-     * Removes consecutive duplicates from the point array with tolerance
+     * Removes consecutive duplicate points from array within tolerance.
+     * Example: [[0,0,0], [0,0,0], [1,0,0], [1,0,0], [2,0,0]] → [[0,0,0], [1,0,0], [2,0,0]]
      * @param inputs points, tolerance and check first and last
      * @returns Points in the array without consecutive duplicates
      * @group clean
@@ -300,7 +328,8 @@ export declare class Point {
      */
     removeConsecutiveDuplicates(inputs: Inputs.Point.RemoveConsecutiveDuplicatesDto): Inputs.Base.Point3[];
     /**
-     * Creates a normal vector from 3 points
+     * Calculates normal vector from three points using cross product (perpendicular to plane).
+     * Example: p1=[0,0,0], p2=[1,0,0], p3=[0,1,0] → [0,0,1] (pointing up from XY plane)
      * @param inputs Three points and the reverse normal flag
      * @returns Normal vector
      * @group create
@@ -310,7 +339,8 @@ export declare class Point {
     normalFromThreePoints(inputs: Inputs.Point.ThreePointsNormalDto): Inputs.Base.Vector3;
     private closestPointFromPointData;
     /**
-     * Checks if two points are almost equal
+     * Checks if two points are approximately equal within tolerance (distance-based comparison).
+     * Example: point1=[1.0000001, 2.0, 3.0], point2=[1.0, 2.0, 3.0], tolerance=1e-6 → true
      * @param inputs Two points and the tolerance
      * @returns true if the points are almost equal
      * @group measure
@@ -319,7 +349,8 @@ export declare class Point {
      */
     twoPointsAlmostEqual(inputs: Inputs.Point.TwoPointsToleranceDto): boolean;
     /**
-     * Sorts points lexicographically (X, then Y, then Z)
+     * Sorts points lexicographically (by X, then Y, then Z coordinates).
+     * Example: [[5,0,0], [1,0,0], [3,0,0]] → [[1,0,0], [3,0,0], [5,0,0]]
      * @param inputs points
      * @returns sorted points
      * @group sort

package/lib/api/services/point.js

@@ -11,7 +11,8 @@ export class Point {
         this.lists = lists;
     }
     /**
-     * Transforms the single point
+     * Applies transformation matrix to a single point (rotates, scales, or translates).
+     * Example: point=[0,0,0] with translation [5,5,0] → [5,5,0]
      * @param inputs Contains a point and the transformations to apply
      * @returns Transformed point
      * @group transforms
@@ -25,7 +26,8 @@ export class Point {
         return transformedControlPoints[0];
     }
     /**
-     * Transforms multiple points
+     * Applies same transformation matrix to multiple points (batch transform).
+     * Example: 5 points with rotation 90° → all 5 points rotated together
      * @param inputs Contains points and the transformations to apply
      * @returns Transformed points
      * @group transforms
@@ -36,7 +38,9 @@ export class Point {
         return this.geometryHelper.transformControlPoints(inputs.transformation, inputs.points);
     }
     /**
-     * Transforms multiple points by multiple transformations
+     * Applies different transformation matrices to corresponding points (one transform per point).
+     * Arrays must have equal length.
+     * Example: 3 points with 3 different translations → each point moved independently
      * @param inputs Contains points and the transformations to apply
      * @returns Transformed points
      * @group transforms
@@ -52,7 +56,8 @@ export class Point {
         });
     }
     /**
-     * Translate multiple points
+     * Moves multiple points by a translation vector (same offset for all points).
+     * Example: points=[[0,0,0], [1,0,0]], translation=[5,5,0] → [[5,5,0], [6,5,0]]
      * @param inputs Contains points and the translation vector
      * @returns Translated points
      * @group transforms
@@ -64,7 +69,9 @@ export class Point {
         return this.geometryHelper.transformControlPoints(translationTransform, inputs.points);
     }
     /**
-     * Translate multiple points
+     * Moves multiple points by corresponding translation vectors (one vector per point).
+     * Arrays must have equal length.
+     * Example: 3 points with 3 different vectors → each point moved by its corresponding vector
      * @param inputs Contains points and the translation vector
      * @returns Translated points
      * @group transforms
@@ -81,7 +88,8 @@ export class Point {
         });
     }
     /**
-     * Translate multiple points by x, y, z values provided
+     * Moves multiple points by separate X, Y, Z values (convenience method for translation).
+     * Example: points=[[0,0,0]], x=10, y=5, z=0 → [[10,5,0]]
      * @param inputs Contains points and the translation in x y and z
      * @returns Translated points
      * @group transforms
@@ -93,7 +101,8 @@ export class Point {
         return this.geometryHelper.transformControlPoints(translationTransform, inputs.points);
     }
     /**
-     * Scale multiple points by providing center point and x, y, z scale factors
+     * Scales multiple points around a center point with different factors per axis.
+     * Example: points=[[10,0,0]], center=[5,0,0], scaleXyz=[2,1,1] → [[15,0,0]] (doubles X distance from center)
      * @param inputs Contains points, center point and scale factors
      * @returns Scaled points
      * @group transforms
@@ -105,7 +114,8 @@ export class Point {
         return this.geometryHelper.transformControlPoints(scaleTransforms, inputs.points);
     }
     /**
-     * Stretch multiple points by providing center point, direction and uniform scale factor
+     * Stretches multiple points along a direction from a center point (directional scaling).
+     * Example: points=[[10,0,0]], center=[0,0,0], direction=[1,0,0], scale=2 → [[20,0,0]]
      * @param inputs Contains points, center point, direction and scale factor
      * @returns Stretched points
      * @group transforms
@@ -117,7 +127,8 @@ export class Point {
         return this.geometryHelper.transformControlPoints(stretchTransforms, inputs.points);
     }
     /**
-     * Rotate multiple points by providing center point, axis and degrees of rotation
+     * Rotates multiple points around a center point along a custom axis.
+     * Example: points=[[10,0,0]], center=[0,0,0], axis=[0,1,0], angle=90° → [[0,0,-10]]
      * @param inputs Contains points, axis, center point and angle of rotation
      * @returns Rotated points
      * @group transforms
@@ -129,7 +140,8 @@ export class Point {
         return this.geometryHelper.transformControlPoints(rotationTransforms, inputs.points);
     }
     /**
-     * Gets a bounding box of the points
+     * Calculates axis-aligned bounding box containing all points (min, max, center, width, height, length).
+     * Example: points=[[0,0,0], [10,5,3]] → {min:[0,0,0], max:[10,5,3], center:[5,2.5,1.5], width:10, height:5, length:3}
      * @param inputs Points
      * @returns Bounding box of points
      * @group extract
@@ -165,7 +177,8 @@ export class Point {
         };
     }
     /**
-     * Measures the closest distance between a point and a collection of points
+     * Calculates distance to the nearest point in a collection.
+     * Example: point=[0,0,0], points=[[5,0,0], [10,0,0], [3,0,0]] → 3 (distance to [3,0,0])
      * @param inputs Point from which to measure and points to measure the distance against
      * @returns Distance to closest point
      * @group extract
@@ -176,7 +189,8 @@ export class Point {
         return this.closestPointFromPointData(inputs).distance;
     }
     /**
-     * Finds the closest point index between a point and a collection of points. Caution, index is not 0 based, it starts with 1.
+     * Finds array index of the nearest point in a collection (1-based index, not 0-based).
+     * Example: point=[0,0,0], points=[[5,0,0], [10,0,0], [3,0,0]] → 3 (index of [3,0,0])
      * @param inputs Point from which to find the index in a collection of points
      * @returns Closest point index
      * @group extract
@@ -187,7 +201,8 @@ export class Point {
         return this.closestPointFromPointData(inputs).index;
     }
     /**
-     * Finds the closest point in a collection
+     * Finds the nearest point in a collection to a reference point.
+     * Example: point=[0,0,0], points=[[5,0,0], [10,0,0], [3,0,0]] → [3,0,0]
      * @param inputs Point and points collection to find the closest point in
      * @returns Closest point
      * @group extract
@@ -198,7 +213,8 @@ export class Point {
         return this.closestPointFromPointData(inputs).point;
     }
     /**
-     * Finds the distance between two points
+     * Calculates Euclidean distance between two points.
+     * Example: start=[0,0,0], end=[3,4,0] → 5 (using Pythagorean theorem: √(3²+4²))
      * @param inputs Coordinates of start and end points
      * @returns Distance
      * @group measure
@@ -212,7 +228,8 @@ export class Point {
         return Math.sqrt(x * x + y * y + z * z);
     }
     /**
-     * Finds the distances between the start point and multiple end points
+     * Calculates distances from a start point to multiple end points.
+     * Example: start=[0,0,0], endPoints=[[3,0,0], [0,4,0], [5,0,0]] → [3, 4, 5]
      * @param inputs Coordinates of start and end points
      * @returns Distances
      * @group measure
@@ -225,7 +242,8 @@ export class Point {
         });
     }
     /**
-     * Multiply point by a specified amount
+     * Duplicates a point N times (creates array with N copies of the same point).
+     * Example: point=[5,5,0], amountOfPoints=3 → [[5,5,0], [5,5,0], [5,5,0]]
      * @param inputs The point to be multiplied and the amount of points to create
      * @returns Distance
      * @group transforms
@@ -240,7 +258,8 @@ export class Point {
         return points;
     }
     /**
-     * Get x coordinate of the point
+     * Extracts X coordinate from a point.
+     * Example: point=[5,10,3] → 5
      * @param inputs The point
      * @returns X coordinate
      * @group get
@@ -251,7 +270,8 @@ export class Point {
         return inputs.point[0];
     }
     /**
-     * Get y coordinate of the point
+     * Extracts Y coordinate from a point.
+     * Example: point=[5,10,3] → 10
      * @param inputs The point
      * @returns Y coordinate
      * @group get
@@ -262,7 +282,8 @@ export class Point {
         return inputs.point[1];
     }
     /**
-     * Get z coordinate of the point
+     * Extracts Z coordinate from a point.
+     * Example: point=[5,10,3] → 3
      * @param inputs The point
      * @returns Z coordinate
      * @group get
@@ -273,7 +294,8 @@ export class Point {
         return inputs.point[2];
     }
     /**
-     * Get average point of points
+     * Calculates centroid (average position) of multiple points.
+     * Example: points=[[0,0,0], [10,0,0], [10,10,0]] → [6.67,3.33,0]
      * @param inputs The points
      * @returns point
      * @group extract
@@ -296,7 +318,8 @@ export class Point {
         ];
     }
     /**
-     * Creates the xyz point
+     * Creates a 3D point from X, Y, Z coordinates.
+     * Example: x=10, y=5, z=3 → [10,5,3]
      * @param inputs xyz information
      * @returns point 3d
      * @group create
@@ -307,7 +330,8 @@ export class Point {
         return [inputs.x, inputs.y, inputs.z];
     }
     /**
-     * Creates the xy point
+     * Creates a 2D point from X, Y coordinates.
+     * Example: x=10, y=5 → [10,5]
      * @param inputs xy information
      * @returns point 3d
      * @group create
@@ -318,7 +342,9 @@ export class Point {
         return [inputs.x, inputs.y];
     }
     /**
-     * Creates the spiral out of multiple points
+     * Creates logarithmic spiral points using golden angle or custom widening factor.
+     * Generates natural spiral patterns common in nature (sunflower, nautilus shell).
+     * Example: numberPoints=100, radius=10, phi=1.618 → 100 points forming outward spiral
      * @param inputs Spiral information
      * @returns Specified number of points in the array along the spiral
      * @group create
@@ -339,8 +365,9 @@ export class Point {
         return spiral;
     }
     /**
-     * Creates a flat point grid on XY plane. This grid contains center points for hexagons of the given radius.
-     * Be aware that we control only the nr of hexagons to be made and not the length and width of the grid.
+     * Creates hexagonal grid center points on XY plane (honeycomb pattern).
+     * Grid size controlled by number of hexagons, not width/height.
+     * Example: radiusHexagon=1, nrHexagonsX=3, nrHexagonsY=3 → 9 hex centers in grid pattern
      * @param inputs Information about hexagon and the grid
      * @returns Points in the array on the grid
      * @group create
@@ -373,9 +400,9 @@ export class Point {
         return points;
     }
     /**
-     * Creates a pointy-top or flat-top hexagon grid, scaling hexagons to fit specified dimensions exactly.
-     * Returns both center points and the vertices of each (potentially scaled) hexagon.
-     * Hexagons are ordered column-first, then row-first.
+     * Creates hexagonal grid scaled to fit within specified width/height bounds (auto-calculates hex size).
+     * Returns center points and hex vertices. Supports pointy-top or flat-top orientation.
+     * Example: width=10, height=10, nrHexagonsInHeight=3 → hex grid filling 10×10 area with 3 rows
      * @param inputs Information about the desired grid dimensions and hexagon counts.
      * @returns An object containing the array of center points and an array of hexagon vertex arrays.
      * @group create
@@ -846,7 +873,8 @@ export class Point {
         return Math.max(0, safestRadius);
     }
     /**
-     * Removes consecutive duplicates from the point array with tolerance
+     * Removes consecutive duplicate points from array within tolerance.
+     * Example: [[0,0,0], [0,0,0], [1,0,0], [1,0,0], [2,0,0]] → [[0,0,0], [1,0,0], [2,0,0]]
      * @param inputs points, tolerance and check first and last
      * @returns Points in the array without consecutive duplicates
      * @group clean
@@ -857,7 +885,8 @@ export class Point {
         return this.geometryHelper.removeConsecutivePointDuplicates(inputs.points, inputs.checkFirstAndLast, inputs.tolerance);
     }
     /**
-     * Creates a normal vector from 3 points
+     * Calculates normal vector from three points using cross product (perpendicular to plane).
+     * Example: p1=[0,0,0], p2=[1,0,0], p3=[0,1,0] → [0,0,1] (pointing up from XY plane)
      * @param inputs Three points and the reverse normal flag
      * @returns Normal vector
      * @group create
@@ -913,7 +942,8 @@ export class Point {
         return { index: closestPointIndex + 1, distance, point };
     }
     /**
-     * Checks if two points are almost equal
+     * Checks if two points are approximately equal within tolerance (distance-based comparison).
+     * Example: point1=[1.0000001, 2.0, 3.0], point2=[1.0, 2.0, 3.0], tolerance=1e-6 → true
      * @param inputs Two points and the tolerance
      * @returns true if the points are almost equal
      * @group measure
@@ -927,7 +957,8 @@ export class Point {
         return dist < inputs.tolerance;
     }
     /**
-     * Sorts points lexicographically (X, then Y, then Z)
+     * Sorts points lexicographically (by X, then Y, then Z coordinates).
+     * Example: [[5,0,0], [1,0,0], [3,0,0]] → [[1,0,0], [3,0,0], [5,0,0]]
      * @param inputs points
      * @returns sorted points
      * @group sort