A utility to track objects on a canvas by unique px color.
When using HTML5 canvas to render elements, we don't have the convenience of readily available mouseover events per object, which makes interaction difficult.
canvas-color-tracker provides a system for keeping track of objects in your canvas by indexing them by a unique color, which can be retrieved by determining the 1px color that is directly under the mouse pointer.
This is generally done using a spare/shadow canvas which is not attached to the DOM, but is synchronyzed in terms of object positions with the main canvas. On this shadow canvas we render the objects filled with artificial unique colors that are keys to the object's data, so that by attaching mousemove events to the whole canvas we can determine which objects are being hovered on.
canvas-color-tracker is just the registry part of this process, which generates unique color keys per object and supports addition and retrieval of objects. It also includes a mechanism for validating the color keys using checksum encoding. This is necessary because of pixel antialiasing/smoothing on the boundary of canvas objects, leading into new color mutations which invalidate the object color key lookup.
Check out the canvas examples:
- 100 objects [source]
- 10k objects [source]
- 1M objects!! [source] (please wait until render finishes)
import ColorTracker from 'canvas-color-tracker';
or
const ColorTracker = require('canvas-color-tracker');
or even
<script src="//unpkg.com/canvas-color-tracker"></script>
then
const myTracker = new ColorTracker();
const myObject = { ... };
const myObjectColor = myTracker.register(myObject);
(...)
const hoverColor = context.getImageData(x, y, 1, 1).data;
const hoverObject = myTracker.lookup(hoverColor);
new ColorTracker()
Creates a new object registry with a capacity of 2^24 objects.
Probability of collisions at canvas drawn edges increases to certainty when the registry reaches capacity. This is due to browser anti-aliasing blending colors. The probability is something like N / 2^24 of an edge pixel colliding, where N is the size of the registry.
register(object)
Adds an object to the registry, and returns a unique color (hex string) that can be used to retrieve the object in the future. Object can be of any type, even primitive values. The color returned encodes the checksum, and will be checked for validity at retrieval time. In case the registry is full and has reached its limit of objects, a value of null is returned, indicating that the object was not stored.
lookup(string or [r, g, b])
Retrieve an object from the registry by its unique color key. The color should be passed either as a plain string such as #23a69c, or an array of 3 octet numbers indicating the color's r, g, b encoding. This array is the same format as returned by the canvas context getImageData method. If the color passes the checksum verification and has a registered object in the registry, it is returned. Otherwise the method returns null.
