Canvas Color-Based Object Tracking Utility

Common errors

• Object not found for sampled color (or `lookup` returns `null`/`undefined`)

  cause 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.

  cause 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.

Warnings

• gotcha The `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.
• gotcha The `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.
• gotcha Canvas 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.

Install

• npm install canvas-color-tracker npm
• yarn add canvas-color-tracker yarn
• pnpm add canvas-color-tracker pnpm

Imports

• ColorTracker
  wrong:

  const ColorTracker = require('canvas-color-tracker');

  correct:

  import ColorTracker from '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.

Quickstart

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.