Fix and improve path intersection methods

- Add path.intersectsBeam() method
- Add utils.beamIntersectsLine() method
- Simplify calculation and improve precision on beam intersections
- Document return types properly
- beamIntersectsCurve now uses the proper function from Bezier library instead of emulating it by constructing a huge line
- docs: path.intersect... methods never return false, they simply return an empty array in case of no intersection

packages/core/src/path.mjs

@@ -12,6 +12,8 @@ import {
   round,
   __addNonEnumProp,
   __asNumber,
+  beamIntersectsCurve,
+  beamIntersectsLine,
 } from './utils.mjs'
 
 //////////////////////////////////////////////
@@ -540,6 +542,38 @@ Path.prototype.intersects = function (path) {
   return intersections
 }
 
+/**
+ * Finds intersections between this Path and an endless line (beam) defined by two points
+ *
+ * @param {Point} start - The first point on the beam
+ * @param {Point} end - The second point on the beam
+ * @return {Array} intersections - An array of Point objects where the path intersects the beam
+ */
+Path.prototype.intersectsBeam = function (start, end) {
+  let intersections = []
+  for (let pathA of this.divide()) {
+    if (pathA.ops[1].type === 'line') {
+      __addIntersectionsToArray(
+        beamIntersectsLine(start, end, pathA.ops[0].to, pathA.ops[1].to),
+        intersections
+      )
+    } else if (pathA.ops[1].type === 'curve') {
+      __addIntersectionsToArray(
+        beamIntersectsCurve(
+          start,
+          end,
+          pathA.ops[0].to,
+          pathA.ops[1].cp1,
+          pathA.ops[1].cp2,
+          pathA.ops[1].to
+        ),
+        intersections
+      )
+    }
+  }
+  return intersections
+}
+
 /**
  * Finds intersections between this Path and an X value
  *
@@ -1319,7 +1353,7 @@ export function pathsProxy(paths, log) {
  *
  * @private
  * @param {Array|Object|false} candidates - One Point or an array of Points to check for intersection
- * @param {Path} path - The Path instance to add as intersection if it has coordinates
+ * @param {Path} intersections - The Path instance to add as intersection if it has coordinates
  * @return {Array} intersections - An array of Point objects where the paths intersect
  */
 function __addIntersectionsToArray(candidates, intersections) {

packages/core/src/utils.mjs

@@ -94,32 +94,60 @@ export function beamIntersectsY(from, to, y) {
  * @param {Point} a2 - Point 2 of line A
  * @param {Point} b1 - Point 1 of line B
  * @param {Point} b2 - Point 2 of line B
- * @return {Point} intersections - The Point at the intersection
+ * @return {Point|false} intersections - The Point at the intersection or `false` if the lines are parallel
  */
 export function beamsIntersect(a1, a2, b1, b2) {
-  let slopeA = a1.slope(a2)
-  let slopeB = b1.slope(b2)
-  if (slopeA === slopeB) return false // Parallel lines
+  const intersection = beamIntersection(a1, a2, b1, b2)
+  if (!intersection) return false
+  return intersection.p
+}
 
-  // Check for vertical line A
-  if (Math.round(a1.x * 10000) === Math.round(a2.x * 10000))
-    return new Point(a1.x, slopeB * a1.x + (b1.y - slopeB * b1.x))
-  // Check for vertical line B
-  else if (Math.round(b1.x * 10000) === Math.round(b2.x * 10000))
-    return new Point(b1.x, slopeA * b1.x + (a1.y - slopeA * a1.x))
-  else {
-    // Swap points if line A or B goes from right to left
-    if (a1.x > a2.x) a1 = a2.copy()
-    if (b1.x > b2.x) b1 = b2.copy()
-    // Find y intercept
-    let iA = a1.y - slopeA * a1.x
-    let iB = b1.y - slopeB * b1.x
+/**
+ * Finds the intersection of two endless lines (beams)
+ *
+ * @param {Point} a1 - Point 1 of line A
+ * @param {Point} a2 - Point 2 of line A
+ * @param {Point} b1 - Point 1 of line B
+ * @param {Point} b2 - Point 2 of line B
+ * @return {{p:Point, t: number, u:number}|false} the intersection.
+ * The method will return `false` if the lines are (approximately) parallel or undefined,
+ * e.g., if both points of a line have (approximately) the same coordinate.
+ * Otherwise, p is the point of the intersection,
+ * t and u determine where the intersection lies relative to the points of line A and line B respectively.
+ * 0.0 means the intersection is on the first point, 1.0 on the second point.
+ */
+function beamIntersection(a1, a2, b1, b2) {
+  // Function to compute the cross-product of two vectors
+  function crossProduct(v1, v2) {
+    return v1.x * v2.y - v1.y * v2.x
+  }
 
-    // Find intersection
-    let x = (iB - iA) / (slopeA - slopeB)
-    let y = slopeA * x + iA
+  // Vector from a1 to a2
+  const r = { x: a2.x - a1.x, y: a2.y - a1.y }
+  // Vector from b1 to b2
+  const s = { x: b2.x - b1.x, y: b2.y - b1.y }
 
-    return new Point(x, y)
+  // Vector from a1 to b1
+  const ab = { x: b1.x - a1.x, y: b1.y - a1.y }
+
+  // Compute the cross-product of r and s
+  const rCrossS = crossProduct(r, s)
+
+  // If the cross-product is close to zero, the lines are parallel or nearly parallel
+  const EPSILON = 1e-10 // small threshold to handle numerical stability
+  if (Math.abs(rCrossS) < EPSILON) {
+    return false // The lines are parallel (or almost parallel), or the points had (almost) the same coordinate
+  }
+
+  // Compute the parameters t and u where the beams intersect
+  const t = crossProduct(ab, s) / rCrossS
+  const u = crossProduct(ab, r) / rCrossS
+
+  // Compute the intersection point using a1 + t * r and return result
+  return {
+    p: new Point(a1.x + t * r.x, a1.y + t * r.y),
+    t: t,
+    u: u,
   }
 }
 
@@ -133,12 +161,28 @@ export function beamsIntersect(a1, a2, b1, b2) {
  * @param {Point} cp1 - Control Point at the start of the curve
  * @param {Point} cp2 - Control Point at the end of the curve
  * @param {Point} to - End Point of the curve
- * @return {Array} intersections - An array of Points at the intersections
+ * @return {false|Point|Array} intersections - false if no intersections, else a singular point or an array of Points at the intersections
  */
 export function beamIntersectsCurve(start, end, from, cp1, cp2, to) {
-  let _start = new Point(start.x + (start.x - end.x) * 1000, start.y + (start.y - end.y) * 1000)
-  let _end = new Point(end.x + (end.x - start.x) * 1000, end.y + (end.y - start.y) * 1000)
-  return lineIntersectsCurve(_start, _end, from, cp1, cp2, to)
+  let intersections = []
+  let bz = new Bezier(
+    { x: from.x, y: from.y },
+    { x: cp1.x, y: cp1.y },
+    { x: cp2.x, y: cp2.y },
+    { x: to.x, y: to.y }
+  )
+  let line = {
+    p1: { x: start.x, y: start.y },
+    p2: { x: end.x, y: end.y },
+  }
+  for (let t of Bezier.getUtils().roots(bz.points, line)) {
+    let isect = bz.get(t)
+    intersections.push(new Point(isect.x, isect.y))
+  }
+
+  if (intersections.length === 0) return false
+  else if (intersections.length === 1) return intersections[0]
+  else return intersections
 }
 
 /**
@@ -410,14 +454,29 @@ export function lineIntersectsCircle(c, r, p1, p2, sort = 'x') {
  * @return {Point} intersection - The Point at the intersection
  */
 export function linesIntersect(a1, a2, b1, b2) {
-  let p = beamsIntersect(a1, a2, b1, b2)
-  if (!p) return false
-  let lenA = a1.dist(a2)
-  let lenB = b1.dist(b2)
-  let lenC = a1.dist(p) + p.dist(a2)
-  let lenD = b1.dist(p) + p.dist(b2)
-  if (Math.round(lenA) == Math.round(lenC) && Math.round(lenB) == Math.round(lenD)) return p
-  else return false
+  const intersection = beamIntersection(a1, a2, b1, b2)
+  if (!intersection) return false
+  const EPSILON = 1e-10
+  if (intersection.t < -EPSILON || intersection.t > 1 + EPSILON) return false // outside of line segment A
+  if (intersection.u < -EPSILON || intersection.u > 1 + EPSILON) return false // outside of line segment B
+  return intersection.p
+}
+
+/**
+ * Finds the intersection of a beam and a line segment
+ *
+ * @param {Point} a1 - Point 1 of beam
+ * @param {Point} a2 - Point 2 of beam
+ * @param {Point} b1 - Point 1 of line segment
+ * @param {Point} b2 - Point 2 of line segment
+ * @return {Point} intersection - The Point at the intersection
+ */
+export function beamIntersectsLine(a1, a2, b1, b2) {
+  const intersection = beamIntersection(a1, a2, b1, b2)
+  if (!intersection) return false
+  const EPSILON = 1e-10
+  if (intersection.u < -EPSILON || intersection.u > 1 + EPSILON) return false // outside of line segment
+  return intersection.p
 }
 
 /**
@@ -429,7 +488,7 @@ export function linesIntersect(a1, a2, b1, b2) {
  * @param {Point} cp1 - Control Point at the start of the curve
  * @param {Point} cp2 - Control Point at the end of the curve
  * @param {Point} to - End Point of the curve
- * @return {Array} intersections - An array of Points at the intersections
+ * @return {false|Point|Array} intersections - false if no intersections, else a singular point or an array of Points at the intersections
  */
 export function lineIntersectsCurve(start, end, from, cp1, cp2, to) {
   let intersections = []

packages/core/tests/path.test.mjs

@@ -603,6 +603,17 @@ describe('Path', () => {
     expect(round(intersections[5].y)).to.equal(93.31)
   })
 
+  it('Should find an intersection with a beam', () => {
+    const test = new Path()
+      .move(new Point(300, 400))
+      .line(new Point(300, 380))
+      .curve(new Point(350, 200), new Point(350, 100), new Point(350, 0))
+    let intersectsBeam = test.intersectsBeam(new Point(0, 370), new Point(100, 370))
+    expect(intersectsBeam.length).to.equal(1)
+    expect(round(intersectsBeam[0].x)).to.equal(302.75)
+    expect(round(intersectsBeam[0].y)).to.equal(370)
+  })
+
   it('Should throw an error when running path.intersect on an identical path', () => {
     const test = new Path()
     expect(() => test.intersects(test)).to.throw()

packages/core/tests/utils.test.mjs

@@ -48,6 +48,24 @@ describe('Utils', () => {
     expect(linesIntersect(a, b, c, d)).to.equal(false)
   })
 
+  it('Should detect parallel vertical lines', () => {
+    let a = new Point(10, 20.234)
+    let b = new Point(10, 20)
+    let c = new Point(90, 40)
+    let d = new Point(90, 45.123)
+    expect(beamsIntersect(a, b, c, d)).to.equal(false)
+    expect(linesIntersect(a, b, c, d)).to.equal(false)
+  })
+
+  it('Should detect almost parallel vertical lines', () => {
+    let a = new Point(10, 20.234)
+    let b = new Point(10, 20)
+    let c = new Point(360, 40)
+    let d = new Point(360.00000000000006, 45.123)
+    expect(beamsIntersect(a, b, c, d)).to.equal(false)
+    expect(linesIntersect(a, b, c, d)).to.equal(false)
+  })
+
   it('Should detect vertical lines', () => {
     let a = new Point(10, 20)
     let b = new Point(10, 90)

sites/dev/docs/reference/api/path/intersects/readme.mdx

@@ -17,7 +17,7 @@ for more information.
 ## Signature
 
 ```
-array|false path.intersects(Path path)
+array path.intersects(Path path)
 ```
 
 

sites/dev/docs/reference/api/path/intersectsbeam/readme.mdx

@@ -0,0 +1,56 @@
+---
+title: Path.intersectsBeam()
+---
+
+The `Path.intersectsBeam()` method returns the Point object(s) where the path
+intersects with an endless line (beam).
+
+:::warning
+
+This method can sometimes fail to find intersections in some curves
+due to a limitation in an underlying Bézier library.
+Please see [Bug #3367](https://github.com/freesewing/freesewing/issues/3367)
+for more information.
+
+:::
+
+## Signature
+
+```js
+array path.intersectsBeam(Point a, Point b)
+```
+
+<Example caption="Example of the Path.intersectsBeam() method">
+
+```js
+;({ Point, points, Path, paths, snippets, Snippet, getId, part }) => {
+  points.A = new Point(45, 60)
+  points.B = new Point(10, 30)
+  points.BCp2 = new Point(40, 20)
+  points.C = new Point(90, 30)
+  points.CCp1 = new Point(50, -30)
+
+  points.beamA = new Point(55, 30)
+  points.beamB = new Point(0, 55)
+
+  paths.demo1 = new Path().move(points.A).line(points.B).curve(points.BCp2, points.CCp1, points.C)
+
+  paths.beam = new Path().move(points.beamA).line(points.beamB).addClass('dashed')
+
+  for (let p of paths.demo1.intersectsBeam(points.beamA, points.beamB)) {
+    snippets[getId()] = new Snippet('notch', p)
+  }
+
+  return part
+}
+```
+
+</Example>
+
+## Notes
+
+This method works similar to `path.intersectsX(...)` and `path.intersectsY(...)`,
+but here the intersecting beam doesn't have to be horizontally or vertically.
+
+If you need intersections with a limited line instead of a beam,
+use something like `path.intersects(new Path.move(pointA).line(pointB))` instead.

sites/dev/docs/reference/api/path/intersectsx/readme.mdx

@@ -17,7 +17,7 @@ for more information.
 ## Signature
 
 ```js
-array|false path.intersectsX(float x)
+array path.intersectsX(float x)
 ```
 
 ## Example

sites/dev/docs/reference/api/path/intersectsy/readme.mdx

@@ -17,7 +17,7 @@ for more information.
 ## Signature
 
 ```js
-array|false path.intersectsY(float y)
+array path.intersectsY(float y)
 ```
 
 ## Example

sites/dev/docs/reference/api/utils/beamintersectsline/readme.mdx

@@ -0,0 +1,45 @@
+---
+title: utils.beamIntersectsLine()
+---
+
+The `utils.beamIntersectsLine()` function finds the intersection between an endless
+line (beam) and a (limited) line segment. Returns a [Point](/reference/api/point) object for the
+intersection, or `false` if the beam doesn't intersect the line.
+
+The first two points in the parameter list form the beam, the last two points form the line.
+
+## Signature
+
+```js
+Point | false utils.beamIntersectsLine(
+  Point beamA,
+  Point beamB,
+  Point lineA,
+  Point lineB
+)
+```
+
+## Example
+
+<Example caption="A Utils.beamIntersectsLine() example">
+
+```js
+;({ Point, points, Path, paths, Snippet, snippets, utils, part }) => {
+  points.A = new Point(45, 20)
+  points.B = new Point(60, 15)
+  points.C = new Point(10, 10)
+  points.D = new Point(50, 40)
+
+  paths.AB = new Path().move(points.A).line(points.B).addClass('dotted')
+  paths.CD = new Path().move(points.C).line(points.D)
+
+  snippets.x = new Snippet(
+    'notch',
+    utils.beamIntersectsLine(points.A, points.B, points.C, points.D)
+  )
+
+  return part
+}
+```
+
+</Example>

sites/dev/docs/reference/api/utils/beamsintersect/readme.mdx

@@ -19,7 +19,7 @@ Point | false utils.beamsIntersect(
 
 ## Example
 
-<Example caption="A Utils.beamIntersect() example">
+<Example caption="A Utils.beamsIntersect() example">
 ```js
 ({ Point, points, Path, paths, Snippet, snippets, utils, part }) => {