feat: add approximate elements in bbox detection (#6727)

Co-authored-by: dwelle <luzar.david@gmail.com>

src/packages/bbox.ts

@@ -0,0 +1,65 @@
+import { Bounds } from "../element/bounds";
+import { Point } from "../types";
+
+export type LineSegment = [Point, Point];
+
+export function getBBox(line: LineSegment): Bounds {
+  return [
+    Math.min(line[0][0], line[1][0]),
+    Math.min(line[0][1], line[1][1]),
+    Math.max(line[0][0], line[1][0]),
+    Math.max(line[0][1], line[1][1]),
+  ];
+}
+
+export function crossProduct(a: Point, b: Point) {
+  return a[0] * b[1] - b[0] * a[1];
+}
+
+export function doBBoxesIntersect(a: Bounds, b: Bounds) {
+  return a[0] <= b[2] && a[2] >= b[0] && a[1] <= b[3] && a[3] >= b[1];
+}
+
+export function translate(a: Point, b: Point): Point {
+  return [a[0] - b[0], a[1] - b[1]];
+}
+
+const EPSILON = 0.000001;
+
+export function isPointOnLine(l: LineSegment, p: Point) {
+  const p1 = translate(l[1], l[0]);
+  const p2 = translate(p, l[0]);
+
+  const r = crossProduct(p1, p2);
+
+  return Math.abs(r) < EPSILON;
+}
+
+export function isPointRightOfLine(l: LineSegment, p: Point) {
+  const p1 = translate(l[1], l[0]);
+  const p2 = translate(p, l[0]);
+
+  return crossProduct(p1, p2) < 0;
+}
+
+export function isLineSegmentTouchingOrCrossingLine(
+  a: LineSegment,
+  b: LineSegment,
+) {
+  return (
+    isPointOnLine(a, b[0]) ||
+    isPointOnLine(a, b[1]) ||
+    (isPointRightOfLine(a, b[0])
+      ? !isPointRightOfLine(a, b[1])
+      : isPointRightOfLine(a, b[1]))
+  );
+}
+
+// https://martin-thoma.com/how-to-check-if-two-line-segments-intersect/
+export function doLineSegmentsIntersect(a: LineSegment, b: LineSegment) {
+  return (
+    doBBoxesIntersect(getBBox(a), getBBox(b)) &&
+    isLineSegmentTouchingOrCrossingLine(a, b) &&
+    isLineSegmentTouchingOrCrossingLine(b, a)
+  );
+}

src/packages/excalidraw/CHANGELOG.md

@@ -15,8 +15,8 @@ Please add the latest change on the top under the correct section.
 
 ### Features
 
+- Export `elementsOverlappingBBox`, `isElementInsideBBox`, `elementPartiallyOverlapsWithOrContainsBBox` helpers for filtering/checking if elements within bounds. [#6727](https://github.com/excalidraw/excalidraw/pull/6727)
 - Regenerate ids by default when using transform api and also update bindings by 0.5px to avoid possible overlapping [#7195](https://github.com/excalidraw/excalidraw/pull/7195)
-
 - Add `selected` prop for `MainMenu.Item` and `MainMenu.ItemCustom` components to indicate active state. [#7078](https://github.com/excalidraw/excalidraw/pull/7078)
 
 ## 0.16.1 (2023-09-21)

src/packages/excalidraw/index.tsx

@@ -254,3 +254,9 @@ export { DefaultSidebar } from "../../components/DefaultSidebar";
 
 export { normalizeLink } from "../../data/url";
 export { convertToExcalidrawElements } from "../../data/transform";
+
+export {
+  elementsOverlappingBBox,
+  isElementInsideBBox,
+  elementPartiallyOverlapsWithOrContainsBBox,
+} from "../withinBounds";

src/packages/utils.ts

@@ -229,6 +229,12 @@ export const exportToClipboard = async (
   }
 };
 
+export * from "./bbox";
+export {
+  elementsOverlappingBBox,
+  isElementInsideBBox,
+  elementPartiallyOverlapsWithOrContainsBBox,
+} from "./withinBounds";
 export { serializeAsJSON, serializeLibraryAsJSON } from "../data/json";
 export {
   loadFromBlob,

src/packages/withinBounds.test.ts

@@ -0,0 +1,262 @@
+import { Bounds } from "../element/bounds";
+import { API } from "../tests/helpers/api";
+import {
+  elementPartiallyOverlapsWithOrContainsBBox,
+  elementsOverlappingBBox,
+  isElementInsideBBox,
+} from "./withinBounds";
+
+const makeElement = (x: number, y: number, width: number, height: number) =>
+  API.createElement({
+    type: "rectangle",
+    x,
+    y,
+    width,
+    height,
+  });
+
+const makeBBox = (
+  minX: number,
+  minY: number,
+  maxX: number,
+  maxY: number,
+): Bounds => [minX, minY, maxX, maxY];
+
+describe("isElementInsideBBox()", () => {
+  it("should return true if element is fully inside", () => {
+    const bbox = makeBBox(0, 0, 100, 100);
+
+    // bbox contains element
+    expect(isElementInsideBBox(makeElement(0, 0, 100, 100), bbox)).toBe(true);
+    expect(isElementInsideBBox(makeElement(10, 10, 90, 90), bbox)).toBe(true);
+  });
+
+  it("should return false if element is only partially overlapping", () => {
+    const bbox = makeBBox(0, 0, 100, 100);
+
+    // element contains bbox
+    expect(isElementInsideBBox(makeElement(-10, -10, 110, 110), bbox)).toBe(
+      false,
+    );
+
+    // element overlaps bbox from top-left
+    expect(isElementInsideBBox(makeElement(-10, -10, 100, 100), bbox)).toBe(
+      false,
+    );
+    // element overlaps bbox from top-right
+    expect(isElementInsideBBox(makeElement(90, -10, 100, 100), bbox)).toBe(
+      false,
+    );
+    // element overlaps bbox from bottom-left
+    expect(isElementInsideBBox(makeElement(-10, 90, 100, 100), bbox)).toBe(
+      false,
+    );
+    // element overlaps bbox from bottom-right
+    expect(isElementInsideBBox(makeElement(90, 90, 100, 100), bbox)).toBe(
+      false,
+    );
+  });
+
+  it("should return false if element outside", () => {
+    const bbox = makeBBox(0, 0, 100, 100);
+
+    // outside diagonally
+    expect(isElementInsideBBox(makeElement(110, 110, 100, 100), bbox)).toBe(
+      false,
+    );
+
+    // outside on the left
+    expect(isElementInsideBBox(makeElement(-110, 10, 50, 50), bbox)).toBe(
+      false,
+    );
+    // outside on the right
+    expect(isElementInsideBBox(makeElement(110, 10, 50, 50), bbox)).toBe(false);
+    // outside on the top
+    expect(isElementInsideBBox(makeElement(10, -110, 50, 50), bbox)).toBe(
+      false,
+    );
+    // outside on the bottom
+    expect(isElementInsideBBox(makeElement(10, 110, 50, 50), bbox)).toBe(false);
+  });
+
+  it("should return true if bbox contains element and flag enabled", () => {
+    const bbox = makeBBox(0, 0, 100, 100);
+
+    // element contains bbox
+    expect(
+      isElementInsideBBox(makeElement(-10, -10, 110, 110), bbox, true),
+    ).toBe(true);
+
+    // bbox contains element
+    expect(isElementInsideBBox(makeElement(0, 0, 100, 100), bbox)).toBe(true);
+    expect(isElementInsideBBox(makeElement(10, 10, 90, 90), bbox)).toBe(true);
+  });
+});
+
+describe("elementPartiallyOverlapsWithOrContainsBBox()", () => {
+  it("should return true if element overlaps, is inside, or contains", () => {
+    const bbox = makeBBox(0, 0, 100, 100);
+
+    // bbox contains element
+    expect(
+      elementPartiallyOverlapsWithOrContainsBBox(
+        makeElement(0, 0, 100, 100),
+        bbox,
+      ),
+    ).toBe(true);
+    expect(
+      elementPartiallyOverlapsWithOrContainsBBox(
+        makeElement(10, 10, 90, 90),
+        bbox,
+      ),
+    ).toBe(true);
+
+    // element contains bbox
+    expect(
+      elementPartiallyOverlapsWithOrContainsBBox(
+        makeElement(-10, -10, 110, 110),
+        bbox,
+      ),
+    ).toBe(true);
+
+    // element overlaps bbox from top-left
+    expect(
+      elementPartiallyOverlapsWithOrContainsBBox(
+        makeElement(-10, -10, 100, 100),
+        bbox,
+      ),
+    ).toBe(true);
+    // element overlaps bbox from top-right
+    expect(
+      elementPartiallyOverlapsWithOrContainsBBox(
+        makeElement(90, -10, 100, 100),
+        bbox,
+      ),
+    ).toBe(true);
+    // element overlaps bbox from bottom-left
+    expect(
+      elementPartiallyOverlapsWithOrContainsBBox(
+        makeElement(-10, 90, 100, 100),
+        bbox,
+      ),
+    ).toBe(true);
+    // element overlaps bbox from bottom-right
+    expect(
+      elementPartiallyOverlapsWithOrContainsBBox(
+        makeElement(90, 90, 100, 100),
+        bbox,
+      ),
+    ).toBe(true);
+  });
+
+  it("should return false if element does not overlap", () => {
+    const bbox = makeBBox(0, 0, 100, 100);
+
+    // outside diagonally
+    expect(
+      elementPartiallyOverlapsWithOrContainsBBox(
+        makeElement(110, 110, 100, 100),
+        bbox,
+      ),
+    ).toBe(false);
+
+    // outside on the left
+    expect(
+      elementPartiallyOverlapsWithOrContainsBBox(
+        makeElement(-110, 10, 50, 50),
+        bbox,
+      ),
+    ).toBe(false);
+    // outside on the right
+    expect(
+      elementPartiallyOverlapsWithOrContainsBBox(
+        makeElement(110, 10, 50, 50),
+        bbox,
+      ),
+    ).toBe(false);
+    // outside on the top
+    expect(
+      elementPartiallyOverlapsWithOrContainsBBox(
+        makeElement(10, -110, 50, 50),
+        bbox,
+      ),
+    ).toBe(false);
+    // outside on the bottom
+    expect(
+      elementPartiallyOverlapsWithOrContainsBBox(
+        makeElement(10, 110, 50, 50),
+        bbox,
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("elementsOverlappingBBox()", () => {
+  it("should return elements that overlap bbox", () => {
+    const bbox = makeBBox(0, 0, 100, 100);
+
+    const rectOutside = makeElement(110, 110, 100, 100);
+    const rectInside = makeElement(10, 10, 90, 90);
+    const rectContainingBBox = makeElement(-10, -10, 110, 110);
+    const rectOverlappingTopLeft = makeElement(-10, -10, 50, 50);
+
+    expect(
+      elementsOverlappingBBox({
+        bounds: bbox,
+        type: "overlap",
+        elements: [
+          rectOutside,
+          rectInside,
+          rectContainingBBox,
+          rectOverlappingTopLeft,
+        ],
+      }),
+    ).toEqual([rectInside, rectContainingBBox, rectOverlappingTopLeft]);
+  });
+
+  it("should return elements inside/containing bbox", () => {
+    const bbox = makeBBox(0, 0, 100, 100);
+
+    const rectOutside = makeElement(110, 110, 100, 100);
+    const rectInside = makeElement(10, 10, 90, 90);
+    const rectContainingBBox = makeElement(-10, -10, 110, 110);
+    const rectOverlappingTopLeft = makeElement(-10, -10, 50, 50);
+
+    expect(
+      elementsOverlappingBBox({
+        bounds: bbox,
+        type: "contain",
+        elements: [
+          rectOutside,
+          rectInside,
+          rectContainingBBox,
+          rectOverlappingTopLeft,
+        ],
+      }),
+    ).toEqual([rectInside, rectContainingBBox]);
+  });
+
+  it("should return elements inside bbox", () => {
+    const bbox = makeBBox(0, 0, 100, 100);
+
+    const rectOutside = makeElement(110, 110, 100, 100);
+    const rectInside = makeElement(10, 10, 90, 90);
+    const rectContainingBBox = makeElement(-10, -10, 110, 110);
+    const rectOverlappingTopLeft = makeElement(-10, -10, 50, 50);
+
+    expect(
+      elementsOverlappingBBox({
+        bounds: bbox,
+        type: "inside",
+        elements: [
+          rectOutside,
+          rectInside,
+          rectContainingBBox,
+          rectOverlappingTopLeft,
+        ],
+      }),
+    ).toEqual([rectInside]);
+  });
+
+  // TODO test linear, freedraw, and diamond element types (+rotated)
+});

src/packages/withinBounds.ts

@@ -0,0 +1,206 @@
+import type {
+  ExcalidrawElement,
+  ExcalidrawFreeDrawElement,
+  ExcalidrawLinearElement,
+  NonDeletedExcalidrawElement,
+} from "../element/types";
+import {
+  isArrowElement,
+  isFreeDrawElement,
+  isLinearElement,
+  isTextElement,
+} from "../element/typeChecks";
+import { isValueInRange, rotatePoint } from "../math";
+import type { Point } from "../types";
+import { Bounds } from "../element/bounds";
+
+type Element = NonDeletedExcalidrawElement;
+type Elements = readonly NonDeletedExcalidrawElement[];
+
+type Points = readonly Point[];
+
+/** @returns vertices relative to element's top-left [0,0] position  */
+const getNonLinearElementRelativePoints = (
+  element: Exclude<
+    Element,
+    ExcalidrawLinearElement | ExcalidrawFreeDrawElement
+  >,
+): [TopLeft: Point, TopRight: Point, BottomRight: Point, BottomLeft: Point] => {
+  if (element.type === "diamond") {
+    return [
+      [element.width / 2, 0],
+      [element.width, element.height / 2],
+      [element.width / 2, element.height],
+      [0, element.height / 2],
+    ];
+  }
+  return [
+    [0, 0],
+    [0 + element.width, 0],
+    [0 + element.width, element.height],
+    [0, element.height],
+  ];
+};
+
+/** @returns vertices relative to element's top-left [0,0] position  */
+const getElementRelativePoints = (element: ExcalidrawElement): Points => {
+  if (isLinearElement(element) || isFreeDrawElement(element)) {
+    return element.points;
+  }
+  return getNonLinearElementRelativePoints(element);
+};
+
+const getMinMaxPoints = (points: Points) => {
+  const ret = points.reduce(
+    (limits, [x, y]) => {
+      limits.minY = Math.min(limits.minY, y);
+      limits.minX = Math.min(limits.minX, x);
+
+      limits.maxX = Math.max(limits.maxX, x);
+      limits.maxY = Math.max(limits.maxY, y);
+
+      return limits;
+    },
+    {
+      minX: Infinity,
+      minY: Infinity,
+      maxX: -Infinity,
+      maxY: -Infinity,
+      cx: 0,
+      cy: 0,
+    },
+  );
+
+  ret.cx = (ret.maxX + ret.minX) / 2;
+  ret.cy = (ret.maxY + ret.minY) / 2;
+
+  return ret;
+};
+
+const getRotatedBBox = (element: Element): Bounds => {
+  const points = getElementRelativePoints(element);
+
+  const { cx, cy } = getMinMaxPoints(points);
+  const centerPoint: Point = [cx, cy];
+
+  const rotatedPoints = points.map((point) =>
+    rotatePoint([point[0], point[1]], centerPoint, element.angle),
+  );
+  const { minX, minY, maxX, maxY } = getMinMaxPoints(rotatedPoints);
+
+  return [
+    minX + element.x,
+    minY + element.y,
+    maxX + element.x,
+    maxY + element.y,
+  ];
+};
+
+export const isElementInsideBBox = (
+  element: Element,
+  bbox: Bounds,
+  eitherDirection = false,
+): boolean => {
+  const elementBBox = getRotatedBBox(element);
+
+  const elementInsideBbox =
+    bbox[0] <= elementBBox[0] &&
+    bbox[2] >= elementBBox[2] &&
+    bbox[1] <= elementBBox[1] &&
+    bbox[3] >= elementBBox[3];
+
+  if (!eitherDirection) {
+    return elementInsideBbox;
+  }
+
+  if (elementInsideBbox) {
+    return true;
+  }
+
+  return (
+    elementBBox[0] <= bbox[0] &&
+    elementBBox[2] >= bbox[2] &&
+    elementBBox[1] <= bbox[1] &&
+    elementBBox[3] >= bbox[3]
+  );
+};
+
+export const elementPartiallyOverlapsWithOrContainsBBox = (
+  element: Element,
+  bbox: Bounds,
+): boolean => {
+  const elementBBox = getRotatedBBox(element);
+
+  return (
+    (isValueInRange(elementBBox[0], bbox[0], bbox[2]) ||
+      isValueInRange(bbox[0], elementBBox[0], elementBBox[2])) &&
+    (isValueInRange(elementBBox[1], bbox[1], bbox[3]) ||
+      isValueInRange(bbox[1], elementBBox[1], elementBBox[3]))
+  );
+};
+
+export const elementsOverlappingBBox = ({
+  elements,
+  bounds,
+  type,
+  errorMargin = 0,
+}: {
+  elements: Elements;
+  bounds: Bounds;
+  /** safety offset. Defaults to 0. */
+  errorMargin?: number;
+  /**
+   * - overlap: elements overlapping or inside bounds
+   * - contain: elements inside bounds or bounds inside elements
+   * - inside: elements inside bounds
+   **/
+  type: "overlap" | "contain" | "inside";
+}) => {
+  const adjustedBBox: Bounds = [
+    bounds[0] - errorMargin,
+    bounds[1] - errorMargin,
+    bounds[2] + errorMargin,
+    bounds[3] + errorMargin,
+  ];
+
+  const includedElementSet = new Set<string>();
+
+  for (const element of elements) {
+    if (includedElementSet.has(element.id)) {
+      continue;
+    }
+
+    const isOverlaping =
+      type === "overlap"
+        ? elementPartiallyOverlapsWithOrContainsBBox(element, adjustedBBox)
+        : type === "inside"
+        ? isElementInsideBBox(element, adjustedBBox)
+        : isElementInsideBBox(element, adjustedBBox, true);
+
+    if (isOverlaping) {
+      includedElementSet.add(element.id);
+
+      if (element.boundElements) {
+        for (const boundElement of element.boundElements) {
+          includedElementSet.add(boundElement.id);
+        }
+      }
+
+      if (isTextElement(element) && element.containerId) {
+        includedElementSet.add(element.containerId);
+      }
+
+      if (isArrowElement(element)) {
+        if (element.startBinding) {
+          includedElementSet.add(element.startBinding.elementId);
+        }
+
+        if (element.endBinding) {
+          includedElementSet.add(element.endBinding?.elementId);
+        }
+      }
+    }
+  }
+
+  return elements.filter((element) => includedElementSet.has(element.id));
+};