@bitbybit-dev/base 0.20.13 → 0.21.0

package/lib/api/services/geometry-helper.js

@@ -1,11 +1,20 @@
 export class GeometryHelper {
     constructor() {
+        /**
+         * Calculates the nesting depth of an array recursively.
+         * Example: [1,2,3] → 1, [[1,2],[3,4]] → 2, [[[1]]] → 3
+         */
         this.getArrayDepth = (value) => {
             return Array.isArray(value) ?
                 1 + Math.max(...value.map(this.getArrayDepth)) :
                 0;
         };
     }
+    /**
+     * Applies one or more 4×4 transformation matrices to a list of points sequentially.
+     * Each transformation is applied in order (composition of transformations).
+     * Example: points=[[0,0,0], [1,0,0]] with translation [5,0,0] → [[5,0,0], [6,0,0]]
+     */
     transformControlPoints(transformation, transformedControlPoints) {
         const transformationArrays = this.getFlatTransformations(transformation);
         transformationArrays.forEach(transform => {
@@ -13,6 +22,11 @@ export class GeometryHelper {
         });
         return transformedControlPoints;
     }
+    /**
+     * Flattens nested transformation arrays into a single-level array of transformation matrices.
+     * Handles both 2D arrays (single transform list) and 3D arrays (nested transform lists).
+     * Example: [[[matrix1, matrix2]], [[matrix3]]] → [matrix1, matrix2, matrix3]
+     */
     getFlatTransformations(transformation) {
         let transformationArrays = [];
         if (this.getArrayDepth(transformation) === 3) {
@@ -25,9 +39,17 @@ export class GeometryHelper {
         }
         return transformationArrays;
     }
+    /**
+     * Applies a single 4×4 transformation matrix (as flat 16-element array) to multiple points.
+     * Example: points=[[0,0,0], [1,0,0]] with translation matrix → transformed points
+     */
     transformPointsByMatrixArray(points, transform) {
         return this.transformPointsCoordinates(points, transform);
     }
+    /**
+     * Transforms multiple points using a transformation matrix (maps each point through the matrix).
+     * Example: points=[[1,0,0], [0,1,0]] with 90° rotation → [[0,1,0], [-1,0,0]]
+     */
     transformPointsCoordinates(points, transform) {
         const transformedPoints = [];
         for (const pt of points) {
@@ -36,7 +58,11 @@ export class GeometryHelper {
         }
         return transformedPoints;
     }
-    // Algorithm works with arbitrary length numeric vectors. This algorithm is more costly for longer arrays of vectors
+    /**
+     * Removes all duplicate vectors from a list (works with arbitrary-length numeric vectors).
+     * Compares vectors using tolerance for floating-point equality.
+     * Example: [[1,2], [3,4], [1,2], [5,6]] with tolerance=1e-7 → [[1,2], [3,4], [5,6]]
+     */
     removeAllDuplicateVectors(vectors, tolerance = 1e-7) {
         const cleanVectors = [];
         vectors.forEach(vector => {
@@ -47,7 +73,11 @@ export class GeometryHelper {
         });
         return cleanVectors;
     }
-    // Algorithm works with arbitrary length numeric vectors. 
+    /**
+     * Removes consecutive duplicate vectors from a list (keeps only first occurrence in each sequence).
+     * Optionally checks and removes duplicate if first and last vectors match.
+     * Example: [[1,2], [1,2], [3,4], [3,4], [5,6]] → [[1,2], [3,4], [5,6]]
+     */
     removeConsecutiveVectorDuplicates(vectors, checkFirstAndLast = true, tolerance = 1e-7) {
         const vectorsRemaining = [];
         if (vectors.length > 1) {
@@ -74,6 +104,11 @@ export class GeometryHelper {
         }
         return vectorsRemaining;
     }
+    /**
+     * Compares two vectors for approximate equality using tolerance (element-wise comparison).
+     * Returns false if vectors have different lengths.
+     * Example: [1.0000001, 2.0], [1.0, 2.0] with tolerance=1e-6 → true
+     */
     vectorsTheSame(vec1, vec2, tolerance) {
         let result = false;
         if (vec1.length !== vec2.length) {
@@ -90,10 +125,19 @@ export class GeometryHelper {
         }
         return result;
     }
+    /**
+     * Checks if two numbers are approximately equal within a tolerance.
+     * Example: 1.0000001, 1.0 with tolerance=1e-6 → true, 1.001, 1.0 with tolerance=1e-6 → false
+     */
     approxEq(num1, num2, tolerance) {
         const res = Math.abs(num1 - num2) < tolerance;
         return res;
     }
+    /**
+     * Removes consecutive duplicate points from a list (specialized for 3D/2D points).
+     * Optionally checks and removes duplicate if first and last points match (for closed loops).
+     * Example: [[0,0,0], [0,0,0], [1,0,0], [1,0,0]] → [[0,0,0], [1,0,0]]
+     */
     removeConsecutivePointDuplicates(points, checkFirstAndLast = true, tolerance = 1e-7) {
         const pointsRemaining = [];
         if (points.length > 1) {
@@ -120,6 +164,10 @@ export class GeometryHelper {
         }
         return pointsRemaining;
     }
+    /**
+     * Checks if two points are approximately equal using tolerance (supports 2D and 3D points).
+     * Example: [1.0000001, 2.0, 3.0], [1.0, 2.0, 3.0] with tolerance=1e-6 → true
+     */
     arePointsTheSame(pointA, pointB, tolerance) {
         let result = false;
         if (pointA.length === 2 && pointB.length === 2) {

package/lib/api/services/helpers/dxf/dxf.d.ts

@@ -2,7 +2,8 @@ import * as Inputs from "../../../inputs";
 export declare class Dxf {
     private dxfGenerator;
     /**
-     * Creates a line segment for DXF paths
+     * Creates a line segment definition for DXF export (pass-through for validation).
+     * Example: start=[0,0], end=[10,5] → DXF line segment from origin to [10,5]
      * @param inputs Line segment definition
      * @returns Line segment DTO
      * @group dxf
@@ -11,7 +12,8 @@ export declare class Dxf {
      */
     lineSegment(inputs: Inputs.IO.DxfLineSegmentDto): Inputs.IO.DxfLineSegmentDto;
     /**
-     * Creates an arc segment for DXF paths
+     * Creates an arc segment definition for DXF export (curved path between two points).
+     * Example: center=[5,5], radius=5, startAngle=0°, endAngle=90° → quarter circle arc
      * @param inputs Arc segment definition
      * @returns Arc segment DTO
      * @group dxf
@@ -20,7 +22,8 @@ export declare class Dxf {
      */
     arcSegment(inputs: Inputs.IO.DxfArcSegmentDto): Inputs.IO.DxfArcSegmentDto;
     /**
-     * Creates a circle segment for DXF paths
+     * Creates a circle segment definition for DXF export (closed circular path).
+     * Example: center=[10,10], radius=5 → full circle with diameter 10 centered at [10,10]
      * @param inputs Circle segment definition
      * @returns Circle segment DTO
      * @group dxf
@@ -29,7 +32,8 @@ export declare class Dxf {
      */
     circleSegment(inputs: Inputs.IO.DxfCircleSegmentDto): Inputs.IO.DxfCircleSegmentDto;
     /**
-     * Creates a polyline segment for DXF paths
+     * Creates a polyline segment definition for DXF export (connected line segments through points).
+     * Example: points=[[0,0], [5,0], [5,5], [0,5]] → rectangular polyline path
      * @param inputs Polyline segment definition
      * @returns Polyline segment DTO
      * @group dxf
@@ -38,7 +42,8 @@ export declare class Dxf {
      */
     polylineSegment(inputs: Inputs.IO.DxfPolylineSegmentDto): Inputs.IO.DxfPolylineSegmentDto;
     /**
-     * Creates a spline segment for DXF paths
+     * Creates a spline segment definition for DXF export (smooth curve through control points).
+     * Example: controlPoints=[[0,0], [5,10], [10,0]] → smooth curved path through points
      * @param inputs Spline segment definition
      * @returns Spline segment DTO
      * @group dxf
@@ -47,7 +52,9 @@ export declare class Dxf {
      */
     splineSegment(inputs: Inputs.IO.DxfSplineSegmentDto): Inputs.IO.DxfSplineSegmentDto;
     /**
-     * Creates a path from segments
+     * Creates a path from multiple segments (combines lines, arcs, circles, polylines, splines).
+     * Similar to OCCT wires - segments are connected to form a continuous or multi-part path.
+     * Example: segments=[lineSegment, arcSegment, polylineSegment] → combined path entity
      * @param inputs Path definition with segments
      * @returns Path DTO
      * @group dxf
@@ -56,7 +63,9 @@ export declare class Dxf {
      */
     path(inputs: Inputs.IO.DxfPathDto): Inputs.IO.DxfPathDto;
     /**
-     * Creates a paths part with layer and color
+     * Creates a paths part with layer and color assignment for DXF organization.
+     * Groups multiple paths into a single layer with consistent styling.
+     * Example: paths=[path1, path2], layer="Outlines", color=red → grouped geometry
      * @param inputs Paths part definition
      * @returns Paths part DTO
      * @group dxf
@@ -65,8 +74,9 @@ export declare class Dxf {
      */
     pathsPart(inputs: Inputs.IO.DxfPathsPartDto): Inputs.IO.DxfPathsPartDto;
     /**
-     * DXF generator that supports lines, arcs, circles, polylines, and splines organized in paths.
-     * Paths can combine multiple segment types similar to OCCT wires.
+     * Generates a complete DXF file from paths parts (exports 2D CAD drawing format).
+     * Supports lines, arcs, circles, polylines, and splines organized in layered paths.
+     * Example: model with 3 parts on different layers → valid DXF file string for CAD software
      * @param inputs DXF model definition
      * @returns DXF file content as string
      * @group dxf

package/lib/api/services/helpers/dxf/dxf.js

@@ -4,7 +4,8 @@ export class Dxf {
         this.dxfGenerator = new DxfGenerator();
     }
     /**
-     * Creates a line segment for DXF paths
+     * Creates a line segment definition for DXF export (pass-through for validation).
+     * Example: start=[0,0], end=[10,5] → DXF line segment from origin to [10,5]
      * @param inputs Line segment definition
      * @returns Line segment DTO
      * @group dxf
@@ -15,7 +16,8 @@ export class Dxf {
         return inputs;
     }
     /**
-     * Creates an arc segment for DXF paths
+     * Creates an arc segment definition for DXF export (curved path between two points).
+     * Example: center=[5,5], radius=5, startAngle=0°, endAngle=90° → quarter circle arc
      * @param inputs Arc segment definition
      * @returns Arc segment DTO
      * @group dxf
@@ -26,7 +28,8 @@ export class Dxf {
         return inputs;
     }
     /**
-     * Creates a circle segment for DXF paths
+     * Creates a circle segment definition for DXF export (closed circular path).
+     * Example: center=[10,10], radius=5 → full circle with diameter 10 centered at [10,10]
      * @param inputs Circle segment definition
      * @returns Circle segment DTO
      * @group dxf
@@ -37,7 +40,8 @@ export class Dxf {
         return inputs;
     }
     /**
-     * Creates a polyline segment for DXF paths
+     * Creates a polyline segment definition for DXF export (connected line segments through points).
+     * Example: points=[[0,0], [5,0], [5,5], [0,5]] → rectangular polyline path
      * @param inputs Polyline segment definition
      * @returns Polyline segment DTO
      * @group dxf
@@ -48,7 +52,8 @@ export class Dxf {
         return inputs;
     }
     /**
-     * Creates a spline segment for DXF paths
+     * Creates a spline segment definition for DXF export (smooth curve through control points).
+     * Example: controlPoints=[[0,0], [5,10], [10,0]] → smooth curved path through points
      * @param inputs Spline segment definition
      * @returns Spline segment DTO
      * @group dxf
@@ -59,7 +64,9 @@ export class Dxf {
         return inputs;
     }
     /**
-     * Creates a path from segments
+     * Creates a path from multiple segments (combines lines, arcs, circles, polylines, splines).
+     * Similar to OCCT wires - segments are connected to form a continuous or multi-part path.
+     * Example: segments=[lineSegment, arcSegment, polylineSegment] → combined path entity
      * @param inputs Path definition with segments
      * @returns Path DTO
      * @group dxf
@@ -70,7 +77,9 @@ export class Dxf {
         return inputs;
     }
     /**
-     * Creates a paths part with layer and color
+     * Creates a paths part with layer and color assignment for DXF organization.
+     * Groups multiple paths into a single layer with consistent styling.
+     * Example: paths=[path1, path2], layer="Outlines", color=red → grouped geometry
      * @param inputs Paths part definition
      * @returns Paths part DTO
      * @group dxf
@@ -81,8 +90,9 @@ export class Dxf {
         return inputs;
     }
     /**
-     * DXF generator that supports lines, arcs, circles, polylines, and splines organized in paths.
-     * Paths can combine multiple segment types similar to OCCT wires.
+     * Generates a complete DXF file from paths parts (exports 2D CAD drawing format).
+     * Supports lines, arcs, circles, polylines, and splines organized in layered paths.
+     * Example: model with 3 parts on different layers → valid DXF file string for CAD software
      * @param inputs DXF model definition
      * @returns DXF file content as string
      * @group dxf

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

@@ -12,7 +12,8 @@ export declare class Line {
     private readonly geometryHelper;
     constructor(vector: Vector, point: Point, geometryHelper: GeometryHelper);
     /**
-     * Gets the start point of the line
+     * Extracts start point from a line.
+     * Example: line={start:[0,0,0], end:[10,5,0]} → [0,0,0]
      * @param inputs a line
      * @returns start point
      * @group get
@@ -21,7 +22,8 @@ export declare class Line {
      */
     getStartPoint(inputs: Inputs.Line.LineDto): Inputs.Base.Point3;
     /**
-     * Gets the end point of the line
+     * Extracts end point from a line.
+     * Example: line={start:[0,0,0], end:[10,5,0]} → [10,5,0]
      * @param inputs a line
      * @returns end point
      * @group get
@@ -30,7 +32,8 @@ export declare class Line {
      */
     getEndPoint(inputs: Inputs.Line.LineDto): Inputs.Base.Point3;
     /**
-     * Gets the length of the line
+     * Calculates length (distance) of a line segment.
+     * Example: line={start:[0,0,0], end:[3,4,0]} → 5 (using Pythagorean theorem)
      * @param inputs a line
      * @returns line length
      * @group get
@@ -39,7 +42,8 @@ export declare class Line {
      */
     length(inputs: Inputs.Line.LineDto): number;
     /**
-     * Reverse the endpoints of the line
+     * Reverses line direction by swapping start and end points.
+     * Example: line={start:[0,0,0], end:[10,5,0]} → {start:[10,5,0], end:[0,0,0]}
      * @param inputs a line
      * @returns reversed line
      * @group operations
@@ -48,7 +52,8 @@ export declare class Line {
      */
     reverse(inputs: Inputs.Line.LineDto): Inputs.Base.Line3;
     /**
-     * Transform the line
+     * Applies transformation matrix to line (rotates, scales, or translates both endpoints).
+     * Example: line={start:[0,0,0], end:[10,0,0]} with translation [5,5,0] → {start:[5,5,0], end:[15,5,0]}
      * @param inputs a line
      * @returns transformed line
      * @group transforms
@@ -57,7 +62,8 @@ export declare class Line {
      */
     transformLine(inputs: Inputs.Line.TransformLineDto): Inputs.Base.Line3;
     /**
-     * Transforms the lines with multiple transform for each line
+     * Applies multiple transformations to multiple lines (one transform per line).
+     * Example: 3 lines with 3 different translation matrices → each line moved independently
      * @param inputs lines
      * @returns transformed lines
      * @group transforms
@@ -66,7 +72,8 @@ export declare class Line {
      */
     transformsForLines(inputs: Inputs.Line.TransformsLinesDto): Inputs.Base.Line3[];
     /**
-     * Create the line
+     * Creates a line from two points (line object with start and end properties).
+     * Example: start=[0,0,0], end=[10,5,0] → {start:[0,0,0], end:[10,5,0]}
      * @param inputs start and end points of the line
      * @returns line
      * @group create
@@ -75,7 +82,8 @@ export declare class Line {
      */
     create(inputs: Inputs.Line.LinePointsDto): Inputs.Base.Line3;
     /**
-     * Create the segment
+     * Creates a segment from two points (array format: [start, end]).
+     * Example: start=[0,0,0], end=[10,5,0] → [[0,0,0], [10,5,0]]
      * @param inputs start and end points of the segment
      * @returns segment
      * @group create
@@ -84,7 +92,8 @@ export declare class Line {
      */
     createSegment(inputs: Inputs.Line.LinePointsDto): Inputs.Base.Segment3;
     /**
-     * Gets the point on the line segment at a given param
+     * Calculates point at parameter t along line segment (0=start, 1=end, linear interpolation).
+     * Example: line={start:[0,0,0], end:[10,0,0]}, param=0.5 → [5,0,0] (midpoint)
      * @param inputs line
      * @returns point on line
      * @group get
@@ -93,7 +102,8 @@ export declare class Line {
      */
     getPointOnLine(inputs: Inputs.Line.PointOnLineDto): Inputs.Base.Point3;
     /**
-     * Create the lines segments between all of the points in a list
+     * Creates line segments connecting consecutive points in a list (forms a polyline path).
+     * Example: points=[[0,0,0], [5,0,0], [5,5,0]] → 2 lines: [0→5] and [5→5,5]
      * @param inputs points
      * @returns lines
      * @group create
@@ -102,7 +112,9 @@ export declare class Line {
      */
     linesBetweenPoints(inputs: Inputs.Line.PointsLinesDto): Inputs.Base.Line3[];
     /**
-     * Create the lines between start and end points
+     * Creates lines by pairing corresponding start and end points from two arrays.
+     * Filters out zero-length lines.
+     * Example: starts=[[0,0,0], [5,0,0]], ends=[[0,5,0], [5,5,0]] → 2 lines connecting paired points
      * @param inputs start points and end points
      * @returns lines
      * @group create
@@ -111,7 +123,8 @@ export declare class Line {
      */
     linesBetweenStartAndEndPoints(inputs: Inputs.Line.LineStartEndPointsDto): Inputs.Base.Line3[];
     /**
-     * Convert the line to segment
+     * Converts line object to segment array format.
+     * Example: {start:[0,0,0], end:[10,5,0]} → [[0,0,0], [10,5,0]]
      * @param inputs line
      * @returns segment
      * @group convert
@@ -120,7 +133,8 @@ export declare class Line {
      */
     lineToSegment(inputs: Inputs.Line.LineDto): Inputs.Base.Segment3;
     /**
-     * Converts the lines to segments
+     * Converts multiple line objects to segment array format (batch conversion).
+     * Example: 3 line objects → 3 segment arrays [[start1, end1], [start2, end2], ...]
      * @param inputs lines
      * @returns segments
      * @group convert
@@ -129,7 +143,8 @@ export declare class Line {
      */
     linesToSegments(inputs: Inputs.Line.LinesDto): Inputs.Base.Segment3[];
     /**
-     * Converts the segment to line
+     * Converts segment array to line object format.
+     * Example: [[0,0,0], [10,5,0]] → {start:[0,0,0], end:[10,5,0]}
      * @param inputs segment
      * @returns line
      * @group convert
@@ -138,7 +153,8 @@ export declare class Line {
      */
     segmentToLine(inputs: Inputs.Line.SegmentDto): Inputs.Base.Line3;
     /**
-     * Converts the segments to lines
+     * Converts multiple segment arrays to line object format (batch conversion).
+     * Example: 3 segment arrays → 3 line objects with start/end properties
      * @param inputs segments
      * @returns lines
      * @group convert
@@ -147,7 +163,9 @@ export declare class Line {
      */
     segmentsToLines(inputs: Inputs.Line.SegmentsDto): Inputs.Base.Line3[];
     /**
-     * If two lines intersect return the intersection point
+     * Calculates intersection point of two lines (or segments if checkSegmentsOnly=true).
+     * Returns undefined if lines are parallel, skew, or segments don't overlap.
+     * Example: line1={start:[0,0,0], end:[10,0,0]}, line2={start:[5,-5,0], end:[5,5,0]} → [5,0,0]
      * @param inputs line1 and line2
      * @returns intersection point or undefined if no intersection
      * @group intersection

package/lib/api/services/line.js

@@ -9,7 +9,8 @@ export class Line {
         this.geometryHelper = geometryHelper;
     }
     /**
-     * Gets the start point of the line
+     * Extracts start point from a line.
+     * Example: line={start:[0,0,0], end:[10,5,0]} → [0,0,0]
      * @param inputs a line
      * @returns start point
      * @group get
@@ -20,7 +21,8 @@ export class Line {
         return inputs.line.start;
     }
     /**
-     * Gets the end point of the line
+     * Extracts end point from a line.
+     * Example: line={start:[0,0,0], end:[10,5,0]} → [10,5,0]
      * @param inputs a line
      * @returns end point
      * @group get
@@ -31,7 +33,8 @@ export class Line {
         return inputs.line.end;
     }
     /**
-     * Gets the length of the line
+     * Calculates length (distance) of a line segment.
+     * Example: line={start:[0,0,0], end:[3,4,0]} → 5 (using Pythagorean theorem)
      * @param inputs a line
      * @returns line length
      * @group get
@@ -42,7 +45,8 @@ export class Line {
         return this.point.distance({ startPoint: inputs.line.start, endPoint: inputs.line.end });
     }
     /**
-     * Reverse the endpoints of the line
+     * Reverses line direction by swapping start and end points.
+     * Example: line={start:[0,0,0], end:[10,5,0]} → {start:[10,5,0], end:[0,0,0]}
      * @param inputs a line
      * @returns reversed line
      * @group operations
@@ -53,7 +57,8 @@ export class Line {
         return { start: inputs.line.end, end: inputs.line.start };
     }
     /**
-     * Transform the line
+     * Applies transformation matrix to line (rotates, scales, or translates both endpoints).
+     * Example: line={start:[0,0,0], end:[10,0,0]} with translation [5,5,0] → {start:[5,5,0], end:[15,5,0]}
      * @param inputs a line
      * @returns transformed line
      * @group transforms
@@ -70,7 +75,8 @@ export class Line {
         };
     }
     /**
-     * Transforms the lines with multiple transform for each line
+     * Applies multiple transformations to multiple lines (one transform per line).
+     * Example: 3 lines with 3 different translation matrices → each line moved independently
      * @param inputs lines
      * @returns transformed lines
      * @group transforms
@@ -89,7 +95,8 @@ export class Line {
         });
     }
     /**
-     * Create the line
+     * Creates a line from two points (line object with start and end properties).
+     * Example: start=[0,0,0], end=[10,5,0] → {start:[0,0,0], end:[10,5,0]}
      * @param inputs start and end points of the line
      * @returns line
      * @group create
@@ -103,7 +110,8 @@ export class Line {
         };
     }
     /**
-     * Create the segment
+     * Creates a segment from two points (array format: [start, end]).
+     * Example: start=[0,0,0], end=[10,5,0] → [[0,0,0], [10,5,0]]
      * @param inputs start and end points of the segment
      * @returns segment
      * @group create
@@ -117,7 +125,8 @@ export class Line {
         ];
     }
     /**
-     * Gets the point on the line segment at a given param
+     * Calculates point at parameter t along line segment (0=start, 1=end, linear interpolation).
+     * Example: line={start:[0,0,0], end:[10,0,0]}, param=0.5 → [5,0,0] (midpoint)
      * @param inputs line
      * @returns point on line
      * @group get
@@ -135,7 +144,8 @@ export class Line {
         return point;
     }
     /**
-     * Create the lines segments between all of the points in a list
+     * Creates line segments connecting consecutive points in a list (forms a polyline path).
+     * Example: points=[[0,0,0], [5,0,0], [5,5,0]] → 2 lines: [0→5] and [5→5,5]
      * @param inputs points
      * @returns lines
      * @group create
@@ -152,7 +162,9 @@ export class Line {
         return lines;
     }
     /**
-     * Create the lines between start and end points
+     * Creates lines by pairing corresponding start and end points from two arrays.
+     * Filters out zero-length lines.
+     * Example: starts=[[0,0,0], [5,0,0]], ends=[[0,5,0], [5,5,0]] → 2 lines connecting paired points
      * @param inputs start points and end points
      * @returns lines
      * @group create
@@ -165,7 +177,8 @@ export class Line {
             .filter(line => this.point.distance({ startPoint: line.start, endPoint: line.end }) !== 0);
     }
     /**
-     * Convert the line to segment
+     * Converts line object to segment array format.
+     * Example: {start:[0,0,0], end:[10,5,0]} → [[0,0,0], [10,5,0]]
      * @param inputs line
      * @returns segment
      * @group convert
@@ -176,7 +189,8 @@ export class Line {
         return [inputs.line.start, inputs.line.end];
     }
     /**
-     * Converts the lines to segments
+     * Converts multiple line objects to segment array format (batch conversion).
+     * Example: 3 line objects → 3 segment arrays [[start1, end1], [start2, end2], ...]
      * @param inputs lines
      * @returns segments
      * @group convert
@@ -187,7 +201,8 @@ export class Line {
         return inputs.lines.map(line => [line.start, line.end]);
     }
     /**
-     * Converts the segment to line
+     * Converts segment array to line object format.
+     * Example: [[0,0,0], [10,5,0]] → {start:[0,0,0], end:[10,5,0]}
      * @param inputs segment
      * @returns line
      * @group convert
@@ -198,7 +213,8 @@ export class Line {
         return { start: inputs.segment[0], end: inputs.segment[1] };
     }
     /**
-     * Converts the segments to lines
+     * Converts multiple segment arrays to line object format (batch conversion).
+     * Example: 3 segment arrays → 3 line objects with start/end properties
      * @param inputs segments
      * @returns lines
      * @group convert
@@ -209,7 +225,9 @@ export class Line {
         return inputs.segments.map(segment => ({ start: segment[0], end: segment[1] }));
     }
     /**
-     * If two lines intersect return the intersection point
+     * Calculates intersection point of two lines (or segments if checkSegmentsOnly=true).
+     * Returns undefined if lines are parallel, skew, or segments don't overlap.
+     * Example: line1={start:[0,0,0], end:[10,0,0]}, line2={start:[5,-5,0], end:[5,5,0]} → [5,0,0]
      * @param inputs line1 and line2
      * @returns intersection point or undefined if no intersection
      * @group intersection