Merge pull request #801 from jonobr1/306-hit-testing

Feature Added: Renderer Agnostic Hit Testing

Author: jonobr1

build/two.js

@@ -85,4 +85,4 @@
       }
     ]
   }
-}
+}

build/two.min.js

@@ -1,6 +1,7 @@
 import { Events } from './events.js';
 import { _ } from './utils/underscore.js';
 import { getEffectFromObject } from './utils/shape.js';
+import { boundsContains } from './utils/hit-test.js';
 
 import { Shape } from './shape.js';
 import { Children } from './children.js';
@@ -23,6 +24,22 @@ import { Sprite } from './effects/sprite.js';
 const min = Math.min,
   max = Math.max;
 
+const cache = {
+  getShapesAtPoint: {
+    results: [],
+    hitOptions: {},
+    context: {
+      x: 0,
+      y: 0,
+      visibleOnly: true,
+      results: null,
+    },
+    single: [],
+    output: [],
+    empty: [],
+  },
+};
+
 /**
  * @name Two.Group
  * @class
@@ -362,6 +379,111 @@ export class Group extends Shape {
     }
   }
 
+  static IsVisible = function (element, visibleOnly) {
+    if (!visibleOnly) {
+      return true;
+    }
+
+    let current = element;
+    while (current) {
+      if (typeof current.visible === 'boolean' && !current.visible) {
+        return false;
+      }
+      if (typeof current.opacity === 'number' && current.opacity <= 0) {
+        return false;
+      }
+      current = current.parent;
+    }
+
+    return true;
+  };
+
+  static VisitForHitTest = function (
+    group,
+    context,
+    includeGroups,
+    filter,
+    hitOptions,
+    tolerance,
+    stopOnFirst
+  ) {
+    const children = group && group.children;
+    if (!children) {
+      return false;
+    }
+
+    const results = context.results;
+    for (let i = children.length - 1; i >= 0; i--) {
+      const child = children[i];
+
+      if (!child) {
+        continue;
+      }
+
+      if (!Group.IsVisible(child, context.visibleOnly)) {
+        continue;
+      }
+
+      const rect =
+        typeof child.getBoundingClientRect === 'function'
+          ? child.getBoundingClientRect()
+          : null;
+
+      if (rect && !boundsContains(rect, context.x, context.y, tolerance)) {
+        continue;
+      }
+
+      if (child instanceof Group) {
+        if (
+          includeGroups &&
+          (!filter || filter(child)) &&
+          typeof child.contains === 'function' &&
+          child.contains(context.x, context.y, hitOptions)
+        ) {
+          results.push(child);
+          if (stopOnFirst) {
+            return true;
+          }
+        }
+        if (
+          Group.VisitForHitTest(
+            child,
+            context,
+            includeGroups,
+            filter,
+            hitOptions,
+            tolerance,
+            stopOnFirst
+          )
+        ) {
+          return true;
+        }
+        continue;
+      }
+
+      if (!(child instanceof Shape)) {
+        continue;
+      }
+
+      if (filter && !filter(child)) {
+        continue;
+      }
+
+      if (typeof child.contains !== 'function') {
+        continue;
+      }
+
+      if (child.contains(context.x, context.y, hitOptions)) {
+        results.push(child);
+        if (stopOnFirst) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  };
+
   /**
    * @name Two.Group#copy
    * @function
@@ -487,6 +609,70 @@ export class Group extends Shape {
     return this;
   }
 
+  getShapesAtPoint(x, y, options) {
+    const opts = options || {};
+    const { results, hitOptions, context, single, empty } =
+      cache.getShapesAtPoint;
+
+    results.length = 0;
+
+    const mode = opts.mode === 'deepest' || opts.deepest ? 'deepest' : 'all';
+    const visibleOnly = opts.visibleOnly !== false;
+    const includeGroups = !!opts.includeGroups;
+    const filter = typeof opts.filter === 'function' ? opts.filter : null;
+    const tolerance = typeof opts.tolerance === 'number' ? opts.tolerance : 0;
+
+    if (typeof opts.precision === 'number') {
+      hitOptions.precision = opts.precision;
+    } else {
+      delete hitOptions.precision;
+    }
+    if (typeof opts.fill !== 'undefined') {
+      hitOptions.fill = opts.fill;
+    } else {
+      delete hitOptions.fill;
+    }
+    if (typeof opts.stroke !== 'undefined') {
+      hitOptions.stroke = opts.stroke;
+    } else {
+      delete hitOptions.stroke;
+    }
+    hitOptions.tolerance = tolerance;
+    hitOptions.ignoreVisibility = !visibleOnly;
+
+    const stopOnFirst = mode === 'deepest';
+    context.x = x;
+    context.y = y;
+    context.visibleOnly = visibleOnly;
+    context.results = results;
+
+    Group.VisitForHitTest(
+      this,
+      context,
+      includeGroups,
+      filter,
+      hitOptions,
+      tolerance,
+      stopOnFirst
+    );
+
+    if (stopOnFirst) {
+      if (results.length > 0) {
+        const first = results[0];
+        results.length = 0;
+        single[0] = first;
+        single.length = 1;
+        return single;
+      }
+      empty.length = 0;
+      return empty;
+    }
+
+    const hits = results.slice();
+    results.length = 0;
+    return hits;
+  }
+
   /**
    * @name Two.Group#corner
    * @function

build/two.module.js

@@ -19,11 +19,19 @@ import { Shape } from './shape.js';
 import { Events } from './events.js';
 import { Vector } from './vector.js';
 import { Anchor } from './anchor.js';
+import { Matrix } from './matrix.js';
 
 import { Gradient } from './effects/gradient.js';
 import { LinearGradient } from './effects/linear-gradient.js';
 import { RadialGradient } from './effects/radial-gradient.js';
 import { Texture } from './effects/texture.js';
+import {
+  buildPathHitParts,
+  pointInPolygons,
+  distanceToSegments,
+  hasVisibleFill,
+  hasVisibleStroke,
+} from './utils/hit-test.js';
 
 // Constants
 
@@ -33,6 +41,7 @@ const min = Math.min,
   floor = Math.floor;
 
 const vector = new Vector();
+const hitTestMatrix = new Matrix();
 
 /**
  * @name Two.Path
@@ -815,6 +824,81 @@ export class Path extends Shape {
     };
   }
 
+  contains(x, y, options) {
+    const opts = options || {};
+    const ignoreVisibility = opts.ignoreVisibility === true;
+
+    if (!ignoreVisibility && this.visible === false) {
+      return false;
+    }
+
+    if (!ignoreVisibility && typeof this.opacity === 'number' && this.opacity <= 0) {
+      return false;
+    }
+
+    const tolerance =
+      typeof opts.tolerance === 'number' ? opts.tolerance : 0;
+
+    this._update(true);
+
+    const rect = this.getBoundingClientRect();
+
+    if (
+      !rect ||
+      x < rect.left - tolerance ||
+      x > rect.right + tolerance ||
+      y < rect.top - tolerance ||
+      y > rect.bottom + tolerance
+    ) {
+      return false;
+    }
+
+    const matrix = this.worldMatrix;
+    const inverse = matrix && matrix.inverse(hitTestMatrix);
+
+    if (!inverse) {
+      return super.contains(x, y, opts);
+    }
+
+    const [localX, localY] = inverse.multiply(x, y, 1);
+    const precision =
+      typeof opts.precision === 'number' && !Number.isNaN(opts.precision)
+        ? Math.max(1, Math.floor(opts.precision))
+        : 8;
+
+    const fillTest = hasVisibleFill(this, opts.fill);
+    const strokeTest = hasVisibleStroke(this, opts.stroke);
+
+    const { polygons, segments } = buildPathHitParts(this, precision);
+
+    if (fillTest && polygons.length > 0) {
+      if (pointInPolygons(polygons, localX, localY)) {
+        return true;
+      }
+    }
+
+    if (strokeTest && segments.length > 0) {
+      const linewidth =
+        typeof this.linewidth === 'number' ? this.linewidth : 0;
+      if (linewidth > 0) {
+        const distance = distanceToSegments(segments, localX, localY);
+        if (distance <= linewidth / 2 + tolerance) {
+          return true;
+        }
+      }
+    }
+
+    if (!fillTest && !strokeTest) {
+      return super.contains(x, y, opts);
+    }
+
+    if (fillTest && polygons.length === 0) {
+      return super.contains(x, y, opts);
+    }
+
+    return false;
+  }
+
   /**
    * @name Two.Path#getPointAt
    * @function

package.json

@@ -213,6 +213,55 @@ export class Shape extends Element {
     return this;
   }
 
+  /**
+   * @name Two.Shape#contains
+   * @function
+   * @param {Number} x - x coordinate to hit test against
+   * @param {Number} y - y coordinate to hit test against
+   * @param {Object} [options] - Optional options object
+   * @param {Boolean} [options.ignoreVisibility] - If `true`, hit test against `shape.visible = false` shapes
+   * @param {Number} [options.tolerance] - Padding to hit test against in pixels
+   * @description Remove self from the scene / parent.
+   */
+  contains(x, y, options) {
+    const opts = options || {};
+    const ignoreVisibility = opts.ignoreVisibility === true;
+
+    if (!ignoreVisibility && 'visible' in this && this.visible === false) {
+      return false;
+    }
+
+    if (
+      !ignoreVisibility &&
+      'opacity' in this &&
+      typeof this.opacity === 'number' &&
+      this.opacity <= 0
+    ) {
+      return false;
+    }
+
+    if (typeof this.getBoundingClientRect !== 'function') {
+      return false;
+    }
+
+    const tolerance = typeof opts.tolerance === 'number' ? opts.tolerance : 0;
+
+    this._update(true);
+
+    const rect = this.getBoundingClientRect();
+
+    if (!rect) {
+      return false;
+    }
+
+    return (
+      x >= rect.left - tolerance &&
+      x <= rect.right + tolerance &&
+      y >= rect.top - tolerance &&
+      y <= rect.bottom + tolerance
+    );
+  }
+
   /**
    * @name Two.Shape#copy
    * @function