@bitbybit-dev/base 0.20.12 → 0.20.14

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

@@ -14,7 +14,8 @@ export declare class Polyline {
     private readonly geometryHelper;
     constructor(vector: Vector, point: Point, line: Line, geometryHelper: GeometryHelper);
     /**
-     * Gets the length of the polyline
+     * Calculates total length of polyline by summing distances between consecutive points.
+     * Example: points=[[0,0,0], [3,0,0], [3,4,0]] → 3 + 4 = 7
      * @param inputs a polyline
      * @returns length
      * @group get
@@ -23,7 +24,8 @@ export declare class Polyline {
      */
     length(inputs: Inputs.Polyline.PolylineDto): number;
     /**
-     * Gets the number of points in the polyline
+     * Counts number of points in polyline.
+     * Example: polyline with points=[[0,0,0], [1,0,0], [1,1,0]] → 3
      * @param inputs a polyline
      * @returns nr of points
      * @group get
@@ -32,7 +34,8 @@ export declare class Polyline {
      */
     countPoints(inputs: Inputs.Polyline.PolylineDto): number;
     /**
-     * Gets the points of the polyline
+     * Extracts points array from polyline object.
+     * Example: polyline={points:[[0,0,0], [1,0,0]]} → [[0,0,0], [1,0,0]]
      * @param inputs a polyline
      * @returns points
      * @group get
@@ -41,7 +44,8 @@ export declare class Polyline {
      */
     getPoints(inputs: Inputs.Polyline.PolylineDto): Inputs.Base.Point3[];
     /**
-     * Reverse the points of the polyline
+     * Reverses point order of polyline (flips direction).
+     * Example: points=[[0,0,0], [1,0,0], [2,0,0]] → [[2,0,0], [1,0,0], [0,0,0]]
      * @param inputs a polyline
      * @returns reversed polyline
      * @group convert
@@ -50,7 +54,8 @@ export declare class Polyline {
      */
     reverse(inputs: Inputs.Polyline.PolylineDto): Inputs.Polyline.PolylinePropertiesDto;
     /**
-     * Transform the polyline
+     * Applies transformation matrix to all points in polyline (rotates, scales, or translates).
+     * Example: polyline with 4 points, translation [5,0,0] → all points moved +5 in X direction
      * @param inputs a polyline
      * @returns transformed polyline
      * @group transforms
@@ -59,7 +64,8 @@ export declare class Polyline {
      */
     transformPolyline(inputs: Inputs.Polyline.TransformPolylineDto): Inputs.Polyline.PolylinePropertiesDto;
     /**
-     * Create the polyline
+     * Creates a polyline from points array with optional isClosed flag.
+     * Example: points=[[0,0,0], [1,0,0], [1,1,0]], isClosed=true → {points:..., isClosed:true}
      * @param inputs points and info if its closed
      * @returns polyline
      * @group create
@@ -68,7 +74,9 @@ export declare class Polyline {
      */
     create(inputs: Inputs.Polyline.PolylineCreateDto): Inputs.Polyline.PolylinePropertiesDto;
     /**
-     * Create the lines from the polyline
+     * Converts polyline to line segments (each segment as line object with start/end).
+     * Closed polylines include closing segment.
+     * Example: 3 points → 2 or 3 lines (depending on isClosed)
      * @param inputs polyline
      * @returns lines
      * @group convert
@@ -77,7 +85,9 @@ export declare class Polyline {
      */
     polylineToLines(inputs: Inputs.Polyline.PolylineDto): Inputs.Base.Line3[];
     /**
-     * Create the segments from the polyline
+     * Converts polyline to segment arrays (each segment as [point1, point2]).
+     * Closed polylines include closing segment if endpoints differ.
+     * Example: 4 points, closed → 4 segments connecting all points in a loop
      * @param inputs polyline
      * @returns segments
      * @group convert
@@ -86,7 +96,9 @@ export declare class Polyline {
      */
     polylineToSegments(inputs: Inputs.Polyline.PolylineDto): Inputs.Base.Segment3[];
     /**
-     * Finds the points of self intersection of the polyline
+     * Finds points where polyline crosses itself (self-intersection points).
+     * Skips adjacent segments and deduplicates close points.
+     * Example: figure-8 shaped polyline → returns center crossing point
      * @param inputs points of self intersection
      * @returns polyline
      * @group intersections
@@ -95,7 +107,9 @@ export declare class Polyline {
      */
     polylineSelfIntersection(inputs: Inputs.Polyline.PolylineToleranceDto): Inputs.Base.Point3[];
     /**
-     * Finds the intersection points between two polylines
+     * Finds intersection points between two polylines (all segment-segment crossings).
+     * Tests all segment pairs and deduplicates close points.
+     * Example: crossing polylines forming an X → returns center intersection point
      * @param inputs two polylines and tolerance
      * @returns points
      * @group intersection
@@ -104,7 +118,9 @@ export declare class Polyline {
      */
     twoPolylineIntersection(inputs: Inputs.Polyline.TwoPolylinesToleranceDto): Inputs.Base.Point3[];
     /**
-     * Create the polylines from segments that are potentially connected but scrambled randomly
+     * Sorts scrambled segments into connected polylines by matching endpoints.
+     * Uses spatial hashing for efficient connection finding.
+     * Example: 10 random segments that form 2 connected paths → 2 polylines
      * @param inputs segments
      * @returns polylines
      * @group sort

package/lib/api/services/polyline.js

@@ -10,7 +10,8 @@ export class Polyline {
         this.geometryHelper = geometryHelper;
     }
     /**
-     * Gets the length of the polyline
+     * Calculates total length of polyline by summing distances between consecutive points.
+     * Example: points=[[0,0,0], [3,0,0], [3,4,0]] → 3 + 4 = 7
      * @param inputs a polyline
      * @returns length
      * @group get
@@ -27,7 +28,8 @@ export class Polyline {
         return distanceOfPolyline;
     }
     /**
-     * Gets the number of points in the polyline
+     * Counts number of points in polyline.
+     * Example: polyline with points=[[0,0,0], [1,0,0], [1,1,0]] → 3
      * @param inputs a polyline
      * @returns nr of points
      * @group get
@@ -38,7 +40,8 @@ export class Polyline {
         return inputs.polyline.points.length;
     }
     /**
-     * Gets the points of the polyline
+     * Extracts points array from polyline object.
+     * Example: polyline={points:[[0,0,0], [1,0,0]]} → [[0,0,0], [1,0,0]]
      * @param inputs a polyline
      * @returns points
      * @group get
@@ -49,7 +52,8 @@ export class Polyline {
         return inputs.polyline.points;
     }
     /**
-     * Reverse the points of the polyline
+     * Reverses point order of polyline (flips direction).
+     * Example: points=[[0,0,0], [1,0,0], [2,0,0]] → [[2,0,0], [1,0,0], [0,0,0]]
      * @param inputs a polyline
      * @returns reversed polyline
      * @group convert
@@ -60,7 +64,8 @@ export class Polyline {
         return { points: inputs.polyline.points.reverse() };
     }
     /**
-     * Transform the polyline
+     * Applies transformation matrix to all points in polyline (rotates, scales, or translates).
+     * Example: polyline with 4 points, translation [5,0,0] → all points moved +5 in X direction
      * @param inputs a polyline
      * @returns transformed polyline
      * @group transforms
@@ -74,7 +79,8 @@ export class Polyline {
         return { points: transformedControlPoints };
     }
     /**
-     * Create the polyline
+     * Creates a polyline from points array with optional isClosed flag.
+     * Example: points=[[0,0,0], [1,0,0], [1,1,0]], isClosed=true → {points:..., isClosed:true}
      * @param inputs points and info if its closed
      * @returns polyline
      * @group create
@@ -89,7 +95,9 @@ export class Polyline {
         };
     }
     /**
-     * Create the lines from the polyline
+     * Converts polyline to line segments (each segment as line object with start/end).
+     * Closed polylines include closing segment.
+     * Example: 3 points → 2 or 3 lines (depending on isClosed)
      * @param inputs polyline
      * @returns lines
      * @group convert
@@ -104,7 +112,9 @@ export class Polyline {
         }));
     }
     /**
-     * Create the segments from the polyline
+     * Converts polyline to segment arrays (each segment as [point1, point2]).
+     * Closed polylines include closing segment if endpoints differ.
+     * Example: 4 points, closed → 4 segments connecting all points in a loop
      * @param inputs polyline
      * @returns segments
      * @group convert
@@ -132,7 +142,9 @@ export class Polyline {
         return segments;
     }
     /**
-     * Finds the points of self intersection of the polyline
+     * Finds points where polyline crosses itself (self-intersection points).
+     * Skips adjacent segments and deduplicates close points.
+     * Example: figure-8 shaped polyline → returns center crossing point
      * @param inputs points of self intersection
      * @returns polyline
      * @group intersections
@@ -184,7 +196,9 @@ export class Polyline {
         return selfIntersectionPoints;
     }
     /**
-     * Finds the intersection points between two polylines
+     * Finds intersection points between two polylines (all segment-segment crossings).
+     * Tests all segment pairs and deduplicates close points.
+     * Example: crossing polylines forming an X → returns center intersection point
      * @param inputs two polylines and tolerance
      * @returns points
      * @group intersection
@@ -226,7 +240,9 @@ export class Polyline {
         return intersectionPoints;
     }
     /**
-     * Create the polylines from segments that are potentially connected but scrambled randomly
+     * Sorts scrambled segments into connected polylines by matching endpoints.
+     * Uses spatial hashing for efficient connection finding.
+     * Example: 10 random segments that form 2 connected paths → 2 polylines
      * @param inputs segments
      * @returns polylines
      * @group sort

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

@@ -8,7 +8,8 @@ export declare class TextBitByBit {
     private readonly point;
     constructor(point: Point);
     /**
-     * Creates a text
+     * Creates and returns a text string (pass-through for text input).
+     * Example: text='Hello World' → 'Hello World'
      * @param inputs a text
      * @returns text
      * @group create
@@ -17,7 +18,8 @@ export declare class TextBitByBit {
      */
     create(inputs: Inputs.Text.TextDto): string;
     /**
-    * Split the text to multiple pieces by a separator
+    * Splits text into multiple pieces using a separator string.
+    * Example: text='apple,banana,cherry', separator=',' → ['apple', 'banana', 'cherry']
     * @param inputs a text
     * @returns text
     * @group transform
@@ -26,7 +28,8 @@ export declare class TextBitByBit {
     */
     split(inputs: Inputs.Text.TextSplitDto): string[];
     /**
-    * Replace all occurrences of a text by another text
+    * Replaces all occurrences of a search string with a replacement string.
+    * Example: text='hello hello', search='hello', replaceWith='hi' → 'hi hi'
     * @param inputs a text
     * @returns text
     * @group transform
@@ -35,7 +38,8 @@ export declare class TextBitByBit {
     */
     replaceAll(inputs: Inputs.Text.TextReplaceDto): string;
     /**
-    * Join multiple items by a separator into text
+    * Joins multiple items into a single text string using a separator.
+    * Example: list=['apple', 'banana', 'cherry'], separator=', ' → 'apple, banana, cherry'
     * @param inputs a list of items
     * @returns text
     * @group transform
@@ -62,7 +66,8 @@ export declare class TextBitByBit {
     */
     toStringEach<T>(inputs: Inputs.Text.ToStringEachDto<T>): string[];
     /**
-     * Format a text with values
+     * Formats text with placeholder values using {0}, {1}, etc. syntax.
+     * Example: text='Point: ({0}, {1})', values=[10, 5] → 'Point: (10, 5)'
      * @param inputs a text and values
      * @returns formatted text
      * @group transform
@@ -71,7 +76,279 @@ export declare class TextBitByBit {
      */
     format(inputs: Inputs.Text.TextFormatDto): string;
     /**
-     * Creates a vector segments for character and includes width and height information
+     * Checks if text contains a search string.
+     * Example: text='hello world', search='world' → true
+     * @param inputs a text and search string
+     * @returns boolean
+     * @group query
+     * @shortname includes
+     * @drawable false
+     */
+    includes(inputs: Inputs.Text.TextSearchDto): boolean;
+    /**
+     * Checks if text starts with a search string.
+     * Example: text='hello world', search='hello' → true
+     * @param inputs a text and search string
+     * @returns boolean
+     * @group query
+     * @shortname starts with
+     * @drawable false
+     */
+    startsWith(inputs: Inputs.Text.TextSearchDto): boolean;
+    /**
+     * Checks if text ends with a search string.
+     * Example: text='hello world', search='world' → true
+     * @param inputs a text and search string
+     * @returns boolean
+     * @group query
+     * @shortname ends with
+     * @drawable false
+     */
+    endsWith(inputs: Inputs.Text.TextSearchDto): boolean;
+    /**
+     * Returns the index of the first occurrence of a search string.
+     * Example: text='hello world', search='world' → 6
+     * @param inputs a text and search string
+     * @returns index or -1 if not found
+     * @group query
+     * @shortname index of
+     * @drawable false
+     */
+    indexOf(inputs: Inputs.Text.TextSearchDto): number;
+    /**
+     * Returns the index of the last occurrence of a search string.
+     * Example: text='hello world hello', search='hello' → 12
+     * @param inputs a text and search string
+     * @returns index or -1 if not found
+     * @group query
+     * @shortname last index of
+     * @drawable false
+     */
+    lastIndexOf(inputs: Inputs.Text.TextSearchDto): number;
+    /**
+     * Extracts a section of text between two indices.
+     * Example: text='hello world', start=0, end=5 → 'hello'
+     * @param inputs a text, start and end indices
+     * @returns extracted text
+     * @group transform
+     * @shortname substring
+     * @drawable false
+     */
+    substring(inputs: Inputs.Text.TextSubstringDto): string;
+    /**
+     * Extracts a section of text and returns a new string.
+     * Example: text='hello world', start=0, end=5 → 'hello'
+     * @param inputs a text, start and end indices
+     * @returns extracted text
+     * @group transform
+     * @shortname slice
+     * @drawable false
+     */
+    slice(inputs: Inputs.Text.TextSubstringDto): string;
+    /**
+     * Returns the character at the specified index.
+     * Example: text='hello', index=1 → 'e'
+     * @param inputs a text and index
+     * @returns character
+     * @group query
+     * @shortname char at
+     * @drawable false
+     */
+    charAt(inputs: Inputs.Text.TextIndexDto): string;
+    /**
+     * Removes whitespace from both ends of text.
+     * Example: text='  hello  ' → 'hello'
+     * @param inputs a text
+     * @returns trimmed text
+     * @group transform
+     * @shortname trim
+     * @drawable false
+     */
+    trim(inputs: Inputs.Text.TextDto): string;
+    /**
+     * Removes whitespace from the start of text.
+     * Example: text='  hello  ' → 'hello  '
+     * @param inputs a text
+     * @returns trimmed text
+     * @group transform
+     * @shortname trim start
+     * @drawable false
+     */
+    trimStart(inputs: Inputs.Text.TextDto): string;
+    /**
+     * Removes whitespace from the end of text.
+     * Example: text='  hello  ' → '  hello'
+     * @param inputs a text
+     * @returns trimmed text
+     * @group transform
+     * @shortname trim end
+     * @drawable false
+     */
+    trimEnd(inputs: Inputs.Text.TextDto): string;
+    /**
+     * Pads text from the start to reach target length.
+     * Example: text='x', length=3, padString='a' → 'aax'
+     * @param inputs a text, target length and pad string
+     * @returns padded text
+     * @group transform
+     * @shortname pad start
+     * @drawable false
+     */
+    padStart(inputs: Inputs.Text.TextPadDto): string;
+    /**
+     * Pads text from the end to reach target length.
+     * Example: text='x', length=3, padString='a' → 'xaa'
+     * @param inputs a text, target length and pad string
+     * @returns padded text
+     * @group transform
+     * @shortname pad end
+     * @drawable false
+     */
+    padEnd(inputs: Inputs.Text.TextPadDto): string;
+    /**
+     * Converts text to uppercase.
+     * Example: text='hello' → 'HELLO'
+     * @param inputs a text
+     * @returns uppercase text
+     * @group transform
+     * @shortname to upper case
+     * @drawable false
+     */
+    toUpperCase(inputs: Inputs.Text.TextDto): string;
+    /**
+     * Converts text to lowercase.
+     * Example: text='HELLO' → 'hello'
+     * @param inputs a text
+     * @returns lowercase text
+     * @group transform
+     * @shortname to lower case
+     * @drawable false
+     */
+    toLowerCase(inputs: Inputs.Text.TextDto): string;
+    /**
+     * Capitalizes the first character of text.
+     * Example: text='hello world' → 'Hello world'
+     * @param inputs a text
+     * @returns text with first character uppercase
+     * @group transform
+     * @shortname capitalize first
+     * @drawable false
+     */
+    toUpperCaseFirst(inputs: Inputs.Text.TextDto): string;
+    /**
+     * Lowercases the first character of text.
+     * Example: text='Hello World' → 'hello World'
+     * @param inputs a text
+     * @returns text with first character lowercase
+     * @group transform
+     * @shortname uncapitalize first
+     * @drawable false
+     */
+    toLowerCaseFirst(inputs: Inputs.Text.TextDto): string;
+    /**
+     * Repeats text a specified number of times.
+     * Example: text='ha', count=3 → 'hahaha'
+     * @param inputs a text and count
+     * @returns repeated text
+     * @group transform
+     * @shortname repeat
+     * @drawable false
+     */
+    repeat(inputs: Inputs.Text.TextRepeatDto): string;
+    /**
+     * Reverses the characters in text.
+     * Example: text='hello' → 'olleh'
+     * @param inputs a text
+     * @returns reversed text
+     * @group transform
+     * @shortname reverse
+     * @drawable false
+     */
+    reverse(inputs: Inputs.Text.TextDto): string;
+    /**
+     * Returns the length of text.
+     * Example: text='hello' → 5
+     * @param inputs a text
+     * @returns length
+     * @group query
+     * @shortname length
+     * @drawable false
+     */
+    length(inputs: Inputs.Text.TextDto): number;
+    /**
+     * Checks if text is empty or only whitespace.
+     * Example: text='   ' → true
+     * @param inputs a text
+     * @returns boolean
+     * @group query
+     * @shortname is empty
+     * @drawable false
+     */
+    isEmpty(inputs: Inputs.Text.TextDto): boolean;
+    /**
+     * Concatenates multiple text strings.
+     * Example: texts=['hello', ' ', 'world'] → 'hello world'
+     * @param inputs array of texts
+     * @returns concatenated text
+     * @group transform
+     * @shortname concat
+     * @drawable false
+     */
+    concat(inputs: Inputs.Text.TextConcatDto): string;
+    /**
+     * Tests if text matches a regular expression pattern.
+     * Example: text='hello123', pattern='[0-9]+' → true
+     * @param inputs a text and regex pattern
+     * @returns boolean
+     * @group regex
+     * @shortname test regex
+     * @drawable false
+     */
+    regexTest(inputs: Inputs.Text.TextRegexDto): boolean;
+    /**
+     * Matches text against a regular expression and returns matches.
+     * Example: text='hello123world456', pattern='[0-9]+', flags='g' → ['123', '456']
+     * @param inputs a text and regex pattern
+     * @returns array of matches or null
+     * @group regex
+     * @shortname regex match
+     * @drawable false
+     */
+    regexMatch(inputs: Inputs.Text.TextRegexDto): string[] | null;
+    /**
+     * Replaces text matching a regular expression pattern.
+     * Example: text='hello123world456', pattern='[0-9]+', flags='g', replaceWith='X' → 'helloXworldX'
+     * @param inputs a text, regex pattern, and replacement
+     * @returns text with replacements
+     * @group regex
+     * @shortname regex replace
+     * @drawable false
+     */
+    regexReplace(inputs: Inputs.Text.TextRegexReplaceDto): string;
+    /**
+     * Searches text for a regular expression pattern and returns the index.
+     * Example: text='hello123', pattern='[0-9]+' → 5
+     * @param inputs a text and regex pattern
+     * @returns index or -1 if not found
+     * @group regex
+     * @shortname regex search
+     * @drawable false
+     */
+    regexSearch(inputs: Inputs.Text.TextRegexDto): number;
+    /**
+     * Splits text using a regular expression pattern.
+     * Example: text='a1b2c3', pattern='[0-9]+' → ['a', 'b', 'c']
+     * @param inputs a text and regex pattern
+     * @returns array of split strings
+     * @group regex
+     * @shortname regex split
+     * @drawable false
+     */
+    regexSplit(inputs: Inputs.Text.TextRegexDto): string[];
+    /**
+     * Converts a character to vector paths (polylines) with width and height data for rendering.
+     * Uses simplex stroke font to generate 2D line segments representing the character shape.
+     * Example: char='A', height=10 → {width:8, height:10, paths:[[points forming A shape]]}
      * @param inputs a text
      * @returns width, height and segments as json
      * @group vector
@@ -80,7 +357,9 @@ export declare class TextBitByBit {
      */
     vectorChar(inputs: Inputs.Text.VectorCharDto): Models.Text.VectorCharData;
     /**
-     * Creates a vector text lines for a given text and includes width and height information
+     * Converts multi-line text to vector paths (polylines) with alignment and spacing controls.
+     * Supports line breaks, letter spacing, line spacing, horizontal alignment, and origin centering.
+     * Example: text='Hello\nWorld', height=10, align=center → [{line1 chars}, {line2 chars}]
      * @param inputs a text as string
      * @returns segments
      * @group vector