plotboilerplate 1.18.0 → 1.19.0

package/src/ts/PlotBoilerplate.ts

@@ -75,7 +75,9 @@
  * @modified 2021-04-25 Extending `remove` to accept arrays of drawables.
  * @modified 2021-11-16 Adding the `PBText` drawable.
  * @modified 2022-08-01 Added `title` to the params.
- * @version  1.15.1
+ * @modified 2022-10-25 Added the `origin` to the default draw config.
+ * @modified 2022-11-06 Adding an XML declaration to the SVG export routine.
+ * @version  1.16.0
  *
  * @file PlotBoilerplate
  * @fileoverview The main class.
@@ -270,7 +272,7 @@ export class PlotBoilerplate {
    * @memberof PlotBoilerplate
    * @instance
    */
-  selectPolygon: Polygon;
+  selectPolygon: Polygon | null;
 
   /**
    * @member {Array<IDraggable>}
@@ -532,6 +534,9 @@ export class PlotBoilerplate {
         lineWidth: 1,
         fill: true,
         anchor: true
+      },
+      origin: {
+        color: "#000000"
       }
     }; // END drawConfig
 
@@ -554,14 +559,16 @@ export class PlotBoilerplate {
         this.config.enableGL = false;
       }
       if (this.config.enableGL) {
-        const ctx: WebGLRenderingContext = this.canvas.getContext("webgl"); // webgl-experimental?
+        // Override the case 'null' here. If GL is not supported, well then nothing works.
+        const ctx: WebGLRenderingContext = this.canvas.getContext("webgl") as WebGLRenderingContext; // webgl-experimental?
         this.draw = new drawutilsgl(ctx, false);
         // PROBLEM: same instance of fill and draw when using WebGL.
         //          Shader program cannot be duplicated on the same context.
         this.fill = (this.draw as drawutilsgl).copyInstance(true);
         console.warn("Initialized with experimental mode enableGL=true. Note that this is not yet fully implemented.");
       } else {
-        const ctx: CanvasRenderingContext2D = this.canvas.getContext("2d");
+        // Override the case 'null' here. If context creation is not supported, well then nothing works.
+        const ctx: CanvasRenderingContext2D = this.canvas.getContext("2d") as CanvasRenderingContext2D;
         this.draw = new drawutils(ctx, false);
         this.fill = new drawutils(ctx, true);
       }
@@ -599,8 +606,8 @@ export class PlotBoilerplate {
     if (config.title) {
       this.eventCatcher.setAttribute("title", config.title);
     }
-    this.draw.scale.set(this.config.scaleX, this.config.scaleY);
-    this.fill.scale.set(this.config.scaleX, this.config.scaleY);
+    this.draw.scale.set(this.config.scaleX ?? 1.0, this.config.scaleY);
+    this.fill.scale.set(this.config.scaleX ?? 1.0, this.config.scaleY);
     this.vertices = [];
     this.selectPolygon = null;
     this.draggedElements = [];
@@ -655,9 +662,13 @@ export class PlotBoilerplate {
 
     tosvgDraw.beginDrawCycle(0);
     tosvgFill.beginDrawCycle(0);
-    if (pb.config.preClear) pb.config.preClear();
-    tosvgDraw.clear(pb.config.backgroundColor);
-    if (pb.config.preDraw) pb.config.preDraw(tosvgDraw, tosvgFill);
+    if (pb.config.preClear) {
+      pb.config.preClear();
+    }
+    tosvgDraw.clear(pb.config.backgroundColor || "white");
+    if (pb.config.preDraw) {
+      pb.config.preDraw(tosvgDraw, tosvgFill);
+    }
     pb.drawAll(0, tosvgDraw, tosvgFill);
     pb.drawVertices(0, tosvgDraw);
     if (pb.config.postDraw) pb.config.postDraw(tosvgDraw, tosvgFill);
@@ -669,7 +680,8 @@ export class PlotBoilerplate {
     var serializer = new XMLSerializer();
     var svgCode = serializer.serializeToString(svgNode);
 
-    var blob = new Blob([svgCode], { type: "image/svg;charset=utf-8" });
+    // Add: '<?xml version="1.0" encoding="utf-8"?>\n' ?
+    var blob = new Blob(['<?xml version="1.0" encoding="utf-8"?>\n' + svgCode], { type: "image/svg;charset=utf-8" });
     // See documentation for FileSaver.js for usage.
     //    https://github.com/eligrey/FileSaver.js
     if (typeof globalThis["saveAs"] !== "function")
@@ -751,9 +763,9 @@ export class PlotBoilerplate {
    **/
   private updateCSSscale() {
     if (this.config.cssUniformScale) {
-      PlotBoilerplate.utils.setCSSscale(this.canvas, this.config.cssScaleX, this.config.cssScaleX);
+      PlotBoilerplate.utils.setCSSscale(this.canvas, this.config.cssScaleX ?? 1.0, this.config.cssScaleX ?? 1.0);
     } else {
-      PlotBoilerplate.utils.setCSSscale(this.canvas, this.config.cssScaleX, this.config.cssScaleY);
+      PlotBoilerplate.utils.setCSSscale(this.canvas, this.config.cssScaleX ?? 1.0, this.config.cssScaleY ?? 1.0);
     }
   }
 
@@ -1011,7 +1023,7 @@ export class PlotBoilerplate {
   getVertexNear(pixelPosition: XYCoords, pixelTolerance: number): Vertex | undefined {
     var p: IDraggable | undefined = this.locatePointNear(
       this.transformMousePosition(pixelPosition.x, pixelPosition.y),
-      pixelTolerance / Math.min(this.config.cssScaleX, this.config.cssScaleY)
+      pixelTolerance / Math.min(this.config.cssScaleX ?? 1.0, this.config.cssScaleY ?? 1.0)
     );
     if (p && p.typeName == "vertex") {
       return this.vertices[p.vindex];
@@ -1095,7 +1107,7 @@ export class PlotBoilerplate {
   drawOrigin(draw: DrawLib<any>) {
     // Add a crosshair to mark the origin
     draw.setCurrentId("origin");
-    draw.crosshair({ x: 0, y: 0 }, 10, "#000000");
+    draw.crosshair({ x: 0, y: 0 }, 10, this.drawConfig.origin.color);
   }
 
   /**
@@ -1360,10 +1372,10 @@ export class PlotBoilerplate {
     } else {
       console.error("Cannot draw object. Unknown class.");
     }
-    draw.setCurrentClassName(null);
-    draw.setCurrentId(null);
-    fill.setCurrentClassName(null);
-    fill.setCurrentId(null);
+    draw.setCurrentClassName(undefined);
+    draw.setCurrentId(undefined);
+    fill.setCurrentClassName(undefined);
+    fill.setCurrentId(undefined);
   }
 
   /**
@@ -1473,7 +1485,7 @@ export class PlotBoilerplate {
    **/
   clear() {
     // Note that elements might have an alpha channel. Clear the scene first.
-    this.draw.clear(this.config.backgroundColor);
+    this.draw.clear(this.config.backgroundColor || "white");
   }
 
   /**
@@ -1505,7 +1517,10 @@ export class PlotBoilerplate {
   viewport(): Bounds {
     return new Bounds(
       this.transformMousePosition(0, 0),
-      this.transformMousePosition(this.canvasSize.width * this.config.cssScaleX, this.canvasSize.height * this.config.cssScaleY)
+      this.transformMousePosition(
+        this.canvasSize.width * (this.config.cssScaleX ?? 1.0),
+        this.canvasSize.height * (this.config.cssScaleY ?? 1.0)
+      )
     );
   }
 
@@ -1569,8 +1584,8 @@ export class PlotBoilerplate {
   resizeCanvas() {
     const _self: PlotBoilerplate = this;
     const _setSize = (w: number, h: number) => {
-      w *= _self.config.canvasWidthFactor;
-      h *= _self.config.canvasHeightFactor;
+      w *= _self.config.canvasWidthFactor ?? 1.0;
+      h *= _self.config.canvasHeightFactor ?? 1.0;
       _self.canvasSize.width = w;
       _self.canvasSize.height = h;
       if (_self.canvas instanceof HTMLCanvasElement) {
@@ -1597,8 +1612,8 @@ export class PlotBoilerplate {
       var width: number = globalThis.innerWidth || document.documentElement.clientWidth || document.body.clientWidth;
       var height: number = globalThis.innerHeight || document.documentElement.clientHeight || document.body.clientHeight;
       _self.canvas.style.position = "absolute";
-      _self.canvas.style.width = _self.config.canvasWidthFactor * width + "px";
-      _self.canvas.style.height = _self.config.canvasWidthFactor * height + "px";
+      _self.canvas.style.width = (_self.config.canvasWidthFactor ?? 1.0) * width + "px";
+      _self.canvas.style.height = (_self.config.canvasWidthFactor ?? 1.0) * height + "px";
       _self.canvas.style.top = "0px";
       _self.canvas.style.left = "0px";
       _setSize(width, height);
@@ -1606,15 +1621,15 @@ export class PlotBoilerplate {
       // Set editor size
       _self.canvas.style.position = "absolute";
       const space: XYDimension = this.getAvailableContainerSpace();
-      _self.canvas.style.width = _self.config.canvasWidthFactor * space.width + "px";
-      _self.canvas.style.height = _self.config.canvasHeightFactor * space.height + "px";
-      _self.canvas.style.top = null;
-      _self.canvas.style.left = null;
+      _self.canvas.style.width = (_self.config.canvasWidthFactor ?? 1.0) * space.width + "px";
+      _self.canvas.style.height = (_self.config.canvasHeightFactor ?? 1.0) * space.height + "px";
+      _self.canvas.style.top = "";
+      _self.canvas.style.left = "";
       _setSize(space.width, space.height);
     } else {
-      _self.canvas.style.width = null;
-      _self.canvas.style.height = null;
-      _setSize(_self.config.defaultCanvasWidth, _self.config.defaultCanvasHeight);
+      _self.canvas.style.width = "";
+      _self.canvas.style.height = "";
+      _setSize(_self.config.defaultCanvasWidth ?? 1024, _self.config.defaultCanvasHeight ?? 768);
     }
 
     if (_self.config.redrawOnResize) _self.redraw();
@@ -2269,7 +2284,7 @@ export class PlotBoilerplate {
        * @param {function} fallback - A default value if the key does not exist.
        * @return {function}
        **/
-      func: (obj: any, key: string, fallback: (...args: any[]) => any) => {
+      func: (obj: any, key: string, fallback: ((...args: any[]) => any) | null) => {
         if (!obj.hasOwnProperty(key)) return fallback;
         if (typeof obj[key] !== "function") return fallback;
         return obj[key];

package/src/ts/Polygon.ts

@@ -99,7 +99,7 @@ export class Polygon implements SVGSerializable {
     this.uid = UIDGenerator.next();
     if (typeof vertices == "undefined") vertices = [];
     this.vertices = vertices;
-    this.isOpen = isOpen;
+    this.isOpen = isOpen || false;
   }
 
   /**

package/src/ts/Vector.ts

@@ -11,7 +11,8 @@
  * @modified 2021-01-20 Added UID.
  * @modified 2022-02-02 Added the `destroy` method.
  * @modified 2022-02-02 Cleared the `Vector.toSVGString` function (deprecated). Use `drawutilssvg` instead.
- * @version  1.4.0
+ * @modified 2022-10-25 Added the `getOrthogonal` method.
+ * @version  1.5.0
  *
  * @file Vector
  * @public
@@ -65,7 +66,7 @@ export class Vector extends VertTuple<Vector> implements SVGSerializable {
   }
 
   /**
-   * The inverse of a vector is a vector witht the same magnitude but oppose direction.
+   * The inverse of a vector is a vector with the same magnitude but oppose direction.
    *
    * Please not that the origin of this vector changes here: a->b becomes b->a.
    *
@@ -116,6 +117,25 @@ export class Vector extends VertTuple<Vector> implements SVGSerializable {
     return new Vertex(this.a.x + a * (this.b.x - this.a.x), this.a.y + a * (this.b.y - this.a.y));
   }
 
+  /**
+   * Get the orthogonal "vector" of this vector (rotated by 90° clockwise).
+   *
+   * @name getOrthogonal
+   * @method getOrthogonal
+   * @return {Vector} A new vector with the same length that stands on this vector's point a.
+   * @instance
+   * @memberof Vector
+   **/
+  getOrthogonal(): Vector {
+    // Orthogonal of vector (0,0)->(x,y) is (0,0)->(-y,x)
+    const linePoint = this.a.clone();
+    const startPoint = this.b.clone().sub(this.a);
+    const tmp = startPoint.x;
+    startPoint.x = -startPoint.y;
+    startPoint.y = tmp;
+    return new Vector(linePoint, startPoint.add(this.a));
+  }
+
   static utils = {
     /**
      * Generate a four-point arrow head, starting at the vector end minus the
@@ -143,8 +163,8 @@ export class Vector extends VertTuple<Vector> implements SVGSerializable {
      * @param {number} scaleY  - the vertical scaling during draw.
      **/
     buildArrowHead: (zA: Vertex, zB: Vertex, headlen: number, scaleX: number, scaleY: number) => {
-      var angle = Math.atan2((zB.y - zA.y) * scaleY, (zB.x - zA.x) * scaleX);
-      var vertices = [];
+      const angle = Math.atan2((zB.y - zA.y) * scaleY, (zB.x - zA.x) * scaleX);
+      const vertices: Array<Vertex> = [];
       vertices.push(new Vertex(zB.x * scaleX - headlen * Math.cos(angle), zB.y * scaleY - headlen * Math.sin(angle)));
       vertices.push(
         new Vertex(

package/src/ts/interfaces/additionals.ts

@@ -0,0 +1,105 @@
+/**
+ * @date 2022-10-17
+ */
+import { Vertex } from "../Vertex";
+
+/**
+ * A common interface for different kinds of path segments.
+ */
+export interface PathSegment {
+  /**
+   * Get the start point of this path segment.
+   *
+   * @method getStartPoint
+   * @memberof PathSegment
+   * @return {Vertex} The start point of this path segment.
+   */
+  getStartPoint(): Vertex;
+
+  /**
+   * Get the end point of this path segment.
+   *
+   * @method getEndPoint
+   * @memberof PathSegment
+   * @return {Vertex} The end point of this path segment.
+   */
+  getEndPoint(): Vertex;
+
+  /**
+   * Get the tangent's end point at the start point of this segment.
+   *
+   * @method getStartTangent
+   * @memberof PathSegment
+   * @return {Vertex} The end point of the starting point's tangent.
+   */
+  getStartTangent(): Vertex;
+
+  /**
+   * Get the tangent's end point at the end point of this segment.
+   *
+   * @method getEndTangent
+   * @memberof PathSegment
+   * @return {Vertex} The end point of the ending point's tangent.
+   */
+  getEndTangent(): Vertex;
+
+  /**
+   * Create a deep clone of this path segment.
+   *
+   * @method clone
+   * @memberof PathSegment
+   * @return {PathSegment} A deep clone/copy of this path segment.
+   */
+  clone: () => PathSegment;
+
+  /**
+   * Revserse this path segment (in-place) and return this same instance (useful for chaining).
+   * The new path segment has start and end point swapped.
+   *
+   * @method reverse
+   * @memberof PathSegment
+   * @return {PathSegment} This path segment instance (for chaining).
+   */
+  reverse: () => PathSegment;
+}
+
+/**
+ * A common interface for general path representations.
+ */
+export interface Path extends PathSegment {
+  /**
+   * Get the number of segments in this path.
+   *
+   * @method getSegmentCount
+   * @memberof Path
+   * @return {number} The number (integer) of path segments.
+   */
+  getSegmentCount: () => number;
+
+  /**
+   * Get the path segment at the given index.
+   *
+   * @method getSegmentAt
+   * @memberof Path
+   * @return {PathSegment} The paths segment at the given index.
+   */
+  getSegmentAt: (index: number) => PathSegment;
+
+  /**
+   * Create a deep clone of this path.
+   *
+   * @method clone
+   * @memberof Path
+   * @return {Path} A deep clone/copy of this path.
+   */
+  clone: () => Path;
+
+  /**
+   * Reverse this path (swap start and end and thus – the direction) in-place.
+   *
+   * @method revert
+   * @memberof Path
+   * @return {PathSegment} This path instance.
+   */
+  reverse: () => Path;
+}

package/src/ts/interfaces/core.ts

@@ -15,6 +15,7 @@
  * @modified 2021-06-21 Added `IBounds.getCenter()`.
  * @modified 2021-11-16 Added `text` options to the `DrawConfig`.
  * @modified 2022-08-01 Added `title` param to the `PBParams` interface.
+ * @modified 2022-10-25 Added `origin` param to the `DrawConfig` interface.
  **/
 
 import { Vertex } from "../Vertex";
@@ -199,6 +200,7 @@ export interface DrawConfig {
     fill?: boolean;
     anchor?: boolean;
   };
+  origin: { color: string };
 }
 
 /** This is a fix for the problem, that the constructor's "name" attribute is not

package/src/ts/interfaces/index.ts

@@ -1,3 +1,4 @@
 export * from "./core";
 export * from "./DrawLib";
 export * from "./externals";
+export * from "./additionals";

package/src/ts/utils/algorithms/arrayShuffle.ts

@@ -0,0 +1,11 @@
+/**
+ * Randomize a given array in-place.
+ *
+ * @author Ikaros Kappler
+ * @date 2022-10-09
+ * @version 1.0.0
+ **/
+
+export const arrayShuffle = (arr: Array<any>): void => {
+  arr.sort(() => Math.random() - 0.5);
+};

package/src/ts/utils/algorithms/detectPaths.ts

@@ -0,0 +1,195 @@
+/**
+ * A function to detect connected paths on the plane given by a random set of segments.
+ *
+ * Note that is algorithm operates IN PLACE and will ALTER your INPUT array.
+ *
+ * @author  Ikaros Kappler
+ * @version 1.0.0
+ * @date    2022-10-17
+ */
+
+import { Path, PathSegment } from "../../interfaces";
+import { GenericPath } from "../datastructures/GenericPath";
+
+/**
+ * An interface/datascructure for keeping track of visited path segments.
+ */
+interface Visitation {
+  visited: boolean;
+  hasPredecessor: boolean;
+  hasSuccessor: boolean;
+}
+
+/**
+ * A private helper function that initializes the visitation tracking and reverses
+ * dangling path ends to connect them with preceding paths.
+ *
+ * Note that this function alters those dangling path segments IN PLACE!
+ *
+ * @param segments
+ * @param epsilon
+ * @returns
+ */
+const initVisitationArray = (segments: Array<PathSegment>, epsilon: number): Array<Visitation> => {
+  const result: Array<Visitation> = []; // { visited: false, hasPredecessor: false }
+  for (var i = 0; i < segments.length; i++) {
+    result.push({ visited: false, hasPredecessor: false, hasSuccessor: false });
+    for (var j = 0; j < segments.length; j++) {
+      if (i === j) {
+        continue;
+      }
+      if (
+        segments[i].getStartPoint().distance(segments[j].getEndPoint()) < epsilon ||
+        segments[i].getStartPoint().distance(segments[j].getStartPoint()) < epsilon
+      ) {
+        result[i].hasPredecessor = true;
+      }
+      if (
+        segments[i].getEndPoint().distance(segments[j].getEndPoint()) < epsilon ||
+        segments[i].getEndPoint().distance(segments[j].getStartPoint()) < epsilon
+      ) {
+        result[i].hasSuccessor = true;
+      }
+    }
+  }
+  // After first initialization make sure that no loose path ends are dangling around
+  // if the affected path segment has a predecessor (but nu successor).
+  //
+  // Revert those segments. This makes the actual detection algorithm much easier.
+  for (var i = 0; i < segments.length; i++) {
+    if (!result[i].hasSuccessor && result[i].hasPredecessor) {
+      segments[i] = segments[i].reverse();
+      result[i].hasPredecessor = false;
+      result[i].hasSuccessor = true;
+    }
+  }
+  return result;
+};
+
+/**
+ * Find the next unvisited path segment (private helper function).
+ *
+ * There is a special order: starting path segments (those without any predecessor)
+ * will be preferred. If no more open paths are available (no starting path segments),
+ * then no more unvisited paths are available or all remaining paths are loops (without
+ * determined start/end).
+ *
+ * Doing this keeps us from the need to run a final loop to connect detected sub paths.
+ *
+ * @param {Array<PathSegment>} segments - The path segments to search in.
+ * @param { Array<Visitation>} isSegmentVisited
+ * @returns {number} The index of the next unvisited path segment or -1 if no more are available.
+ */
+const locateUnvisitedSegment = (segments: Array<PathSegment>, isSegmentVisited: Array<Visitation>): number => {
+  // First run: detect beginnings
+  for (var i = 0; i < segments.length; i++) {
+    if (!isSegmentVisited[i].hasPredecessor && !isSegmentVisited[i].visited) {
+      return i;
+    }
+  }
+  // Second run: if no beginnings exist -> use inner path segment
+  for (var i = 0; i < segments.length; i++) {
+    if (!isSegmentVisited[i].visited) {
+      return i;
+    }
+  }
+  return -1;
+};
+
+/**
+ * Get the next adjacent path segment to the given (current) segment. This is a private
+ * helper function.
+ *
+ * Note that the function will revert the adjacent path segment if required, so the next
+ * starting point 'equals' the current ending point.
+ *
+ * The visitation tracker will be updated if the adjacent segment was found.
+ *
+ * @param {Array<PathSegment>} segments - The total set of available path segments (visited and invisited).
+ * @param {Array<Visitation>} isSegmentVisited - A tracker of visited path segments so far.
+ * @param {PathSegment} currentSegment - The current path segment to find the adjacent segment for.
+ * @param {number} epsilon - The epsilon to use to detect 'equal' start/end points. Must be >= 0.
+ * @returns {PathSegment | null} The next adjacent path segment of null if no such exists.
+ */
+const getAdjacentSegment = (
+  segments: Array<PathSegment>,
+  isSegmentVisited: Array<Visitation>,
+  currentSegment: PathSegment,
+  epsilon: number
+): PathSegment | null => {
+  for (var j = 0; j < segments.length; j++) {
+    if (isSegmentVisited[j].visited) {
+      continue;
+    }
+    var nextSegment = segments[j];
+    // [start]---[end] [start]---[end]
+    if (currentSegment.getEndPoint().distance(nextSegment.getStartPoint()) < epsilon) {
+      isSegmentVisited[j].visited = true;
+      return nextSegment;
+    }
+    // [start]---[end] [end]---[start]
+    else if (currentSegment.getEndPoint().distance(nextSegment.getEndPoint()) < epsilon) {
+      isSegmentVisited[j].visited = true;
+      return nextSegment.reverse();
+    }
+  }
+  return null;
+};
+
+/**
+ * A private helper function to find the adjacent full path for the given path segment,
+ * considering the current path segment is a starting segment (or one inside a loop).
+ *
+ * @param {Array<PathSegment>} segments - The total set of available path segments.
+ * @param { Array<Visitation>} isSegmentVisited - A tracker to determine which segments have already been visited.
+ * @param {number} currentSegmentIndex - The index of the current segments to find the containing path for.
+ * @param {number} epsilon - The epsilon to use to determine 'equal' path points. Must be >= 0.
+ * @returns {GenericPath} The dected path which consists at least of the current path segment.
+ */
+const detectAdjacentPath = (
+  segments: Array<PathSegment>,
+  isSegmentVisited: Array<Visitation>,
+  currentSegmentIndex: number,
+  epsilon: number
+): GenericPath => {
+  var currentSegment: PathSegment | null = segments[currentSegmentIndex];
+  isSegmentVisited[currentSegmentIndex].visited = true;
+  const path = new GenericPath(currentSegment); // { segments: [currentSegment], reverse };
+
+  var i: number = 0;
+  // A safety break if something goes wrong
+  while (i < segments.length && currentSegment) {
+    currentSegment = getAdjacentSegment(segments, isSegmentVisited, currentSegment, epsilon);
+    if (currentSegment) {
+      path.segments.push(currentSegment);
+    }
+    i++;
+  }
+  return path;
+};
+
+/**
+ * Run a path detection on the given set of path segments.
+ *
+ * Note that the array and some path segments may be altered (like reversal) IN PLACE.
+ *
+ * @param {Array<PathSegment>} segments - The total set (array) of available path segments.
+ * @param {number=1.0} epsilon - (optional) An epsilon to use to tell if two plane points should be considered 'equal'.
+ * @returns {Array<GenericPath>} An array containing all detected path (consisting of adjacent path segments of the original set).
+ */
+export const detectPaths = (segments: Array<PathSegment>, epsilon?: number): Array<Path> => {
+  const eps = typeof epsilon === "undefined" || epsilon < 0 ? 1.0 : epsilon;
+  const isSegmentVisited: Array<Visitation> = initVisitationArray(segments, eps);
+  const resultPaths: Array<GenericPath> = [];
+  var nextSegmentIndex: number = -1;
+  var i = 0;
+  while ((nextSegmentIndex = locateUnvisitedSegment(segments, isSegmentVisited)) !== -1 && i < segments.length) {
+    isSegmentVisited[nextSegmentIndex].visited = true;
+    // A safety break (to avoid infinited loops during development).
+    i++;
+    const path = detectAdjacentPath(segments, isSegmentVisited, nextSegmentIndex, eps);
+    i += path.getSegmentCount() - 1;
+    resultPaths.push(path);
+  }
+  return resultPaths;
+};