Registry / web-framework / canvas-color-tracker

canvas-color-tracker

JSON →
library1.3.2jsnpmunverified

canvas-color-tracker is a utility library (current stable version 1.3.2) designed to facilitate interaction with dynamically rendered objects on an HTML5 canvas, where native object-specific mouse events are not available. It provides a system for tracking canvas elements by assigning each a unique, invisible color key on a 'shadow' or off-screen canvas. Developers render their objects on this shadow canvas with these unique colors, then use `mousemove` events on the main canvas to sample the pixel color under the mouse pointer. This color is then used to look up the associated object in the `canvas-color-tracker` registry. A key feature is its checksum encoding mechanism for color keys, which enhances lookup reliability by accounting for pixel anti-aliasing and color mutations at object boundaries. The library focuses solely on the registry aspect: generating keys, registering objects, and performing lookups. It enables effective object identification and interaction for complex canvas applications, supporting up to approximately 262,000 objects with default settings.

npm install canvas-color-tracker
INSTALL
IMPORT
SIG · CANVAS-COLOR-TRACK
C
canvas-color-tracker
web-frameworkjavascriptv1.3.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ColorTracker
import ColorTracker from 'canvas-color-tracker';
const ColorTracker = require('canvas-color-tracker');
The library primarily uses ESM syntax. For CommonJS environments (Node.js versions < 12 without ESM support), direct `require` might lead to issues or require a bundler. For browser environments, a script tag is also available.
ColorTracker
<script src="//cdn.jsdelivr.net/npm/canvas-color-tracker"></script>
For direct browser usage without a module bundler, the library can be loaded via a script tag, making `ColorTracker` globally available.

Demonstrates how to initialize ColorTracker, register an object with a unique color, draw it on both a main and a hidden shadow canvas, and then look up the object based on a sampled pixel color from the shadow canvas, simulating a hover event.

import ColorTracker from 'canvas-color-tracker'; // Assume a canvas context is available for pixel data const canvas = document.createElement('canvas'); canvas.width = 800; canvas.height = 600; const context = canvas.getContext('2d', { willReadFrequently: true }); const shadowCanvas = document.createElement('canvas'); shadowCanvas.width = canvas.width; shadowCanvas.height = canvas.height; const shadowCtx = shadowCanvas.getContext('2d', { willReadFrequently: true }); // Create a new ColorTracker instance // Default checksum_bits (6) allows ~262k objects. Use `new ColorTracker(4)` for ~1M objects. const myTracker = new ColorTracker(); // Register an object and get its unique color key const myObject = { id: 1, name: 'Red Square', x: 50, y: 50, size: 20 }; const myObjectColor = myTracker.register(myObject); if (myObjectColor) { // Draw the actual object on the main canvas context.fillStyle = 'red'; context.fillRect(myObject.x, myObject.y, myObject.size, myObject.size); // Draw the object with its unique shadow color on the hidden shadow canvas shadowCtx.fillStyle = myObjectColor; shadowCtx.fillRect(myObject.x, myObject.y, myObject.size, myObject.size); } // Simulate a mouse hover event const hoverX = 55; // Inside the red square const hoverY = 55; // Get the pixel color from the shadow canvas at the hover position const pixel = shadowCtx.getImageData(hoverX, hoverY, 1, 1).data; // Returns a Uint8ClampedArray: [r, g, b, a] const hoverColor = [pixel[0], pixel[1], pixel[2]]; // Only RGB is used for lookup // Look up the object using the color data const hoveredObject = myTracker.lookup(hoverColor); if (hoveredObject) { console.log('Hovered over:', hoveredObject.name); // Expected: Hovered over: Red Square } else { console.log('No object found at this position.'); } // Example of registry full scenario (highly simplified, usually needs many registrations) // For demonstration, let's assume we force it to be full or hit null return // myTracker.register(someObject) could return null if capacity exceeded.
Debug
Known issues
gotchaThe `checksum_bits` parameter, configurable during `ColorTracker` instantiation, directly impacts the maximum number of objects the registry can store. Higher `checksum_bits` reduce the chance of anti-aliasing-induced color collisions but decrease the total capacity. The maximum objects are `2^(24 - checksum_bits) - 1`. The default of 6 bits supports approximately 262,000 objects.
fix
Adjust `new ColorTracker(checksum_bits)` based on your application's requirements for object count versus collision robustness. For example, `new ColorTracker(4)` allows ~1 million objects.
affects: >=1.0.0
gotchaThe `register()` method returns `null` if the object registry is full and cannot store any more unique objects. This can lead to silent failures if not handled.
fix
Always check the return value of `myTracker.register(obj)`. If `null` is returned, the object was not added, and you should consider increasing the registry capacity by reducing `checksum_bits` if feasible, or implementing a strategy to manage object registration.
affects: >=1.0.0
gotchaCanvas anti-aliasing on object boundaries can produce blended pixel colors, which might not precisely match the unique color key assigned by the tracker. `canvas-color-tracker` mitigates this with checksum encoding, but extreme anti-aliasing or certain rendering contexts could still lead to lookup failures.
fix
Ensure your shadow canvas rendering is as consistent as possible. If issues persist, consider disabling anti-aliasing for the shadow canvas context if your canvas library supports it, or carefully choosing your `checksum_bits` value. The built-in checksum mechanism is designed to handle common anti-aliasing scenarios.
affects: >=1.0.0
Errors
Common errors & fixes
Object not found for sampled color (or `lookup` returns `null`/`undefined`)
The sampled pixel color from the shadow canvas does not exactly match a registered object's unique key, potentially due to anti-aliasing or an incorrect color format being passed to `lookup`.
fix
Ensure the color passed to `lookup` is either a hex string (e.g., `'#RRGGBB'`) or an `[r, g, b]` array (e.g., `ImageData.data` sliced to the first three values). Verify that your shadow canvas drawing precisely matches the object's registered color. The internal checksum usually handles minor anti-aliasing discrepancies.
`myTracker.register(myObject)` returns `null` instead of a color string.
The internal object registry has reached its maximum capacity, preventing new objects from being added.
fix
Review the number of objects being tracked. If it exceeds approximately 262,000 (default `checksum_bits=6`), you may need to instantiate `ColorTracker` with a lower `checksum_bits` value (e.g., `new ColorTracker(4)` for ~1 million objects), accepting a slightly higher theoretical risk of checksum collisions.
Upgrade
Version history
1.3.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
5 hits · last 30 days
node
4
OpenAI (training)
1
Resources
canvas-color-tracker — npm install canvas-color-tracker · libregistry