asciify-engine 1.0.45 → 1.0.46

package/README.md

@@ -131,6 +131,47 @@ All conversion and render functions accept an `AsciiOptions` object. Spread `DEF
 | `hoverEffect` | `string` | `'none'` | Interactive effect driven by cursor position. See hover effects below. |
 | `hoverStrength` | `number` | `0.8` | Effect intensity (0–1). |
 | `hoverRadius` | `number` | `0.3` | Effect radius relative to canvas size (0–1). |
+| `chromaKey` | `{r,g,b} \| string \| null` | `null` | Remove a background colour (green/blue screen). Keyed pixels become transparent spaces. Accepts `{r,g,b}`, any CSS colour string, or `null` to disable. |
+| `chromaKeyTolerance` | `number` | `60` | Euclidean RGB distance threshold for chroma-key detection. `0` = exact match, higher = more pixels removed (max useful ~100). |
+
+### Chroma Key (Green/Blue Screen)
+
+Remove a solid background colour from any source — images, GIFs, or video — so the canvas background shows through keyed pixels.
+
+```ts
+import { asciify, DEFAULT_OPTIONS } from 'asciify-engine';
+
+// Green screen
+asciify(img, canvas, {
+  options: {
+    ...DEFAULT_OPTIONS,
+    chromaKey: '#00ff00',       // CSS colour string — hex, rgb(), named all work
+    chromaKeyTolerance: 60,     // tune to your footage (0 = exact, ~80 = loose)
+    colorMode: 'fullcolor',
+  },
+});
+
+// Blue screen
+asciify(img, canvas, {
+  options: { ...DEFAULT_OPTIONS, chromaKey: 'blue', chromaKeyTolerance: 70 },
+});
+
+// Custom RGB key
+asciify(img, canvas, {
+  options: { ...DEFAULT_OPTIONS, chromaKey: { r: 0, g: 180, b: 90 }, chromaKeyTolerance: 50 },
+});
+
+// Live video with green screen
+asciifyVideo('/footage.mp4', canvas, {
+  fitTo: '#container',
+  options: { ...DEFAULT_OPTIONS, chromaKey: '#00b140', chromaKeyTolerance: 65, colorMode: 'fullcolor' },
+});
+```
+
+**Tolerance guide:**
+- `40–60` — tight key, natural green screen under good lighting
+- `60–80` — broader key, wrinkled fabric or uneven lighting
+- `80–120` — aggressive; expect some spill into the subject
 
 ### Color Modes
 

package/dist/index.cjs

@@ -119,7 +119,9 @@ var DEFAULT_OPTIONS = {
   hoverEffect: "spotlight",
   hoverColor: "#ffffff",
   artStyle: "classic",
-  customText: ""
+  customText: "",
+  chromaKey: null,
+  chromaKeyTolerance: 60
 };
 var HOVER_PRESETS = {
   none: {
@@ -258,6 +260,17 @@ function getCellColorRGB(cell, colorMode, acR, acG, acB) {
   }
   return _colorRGB;
 }
+function parseChromaKeyColor(color) {
+  if (typeof color !== "string") return color;
+  const canvas = document.createElement("canvas");
+  canvas.width = 1;
+  canvas.height = 1;
+  const ctx = canvas.getContext("2d");
+  ctx.fillStyle = color;
+  ctx.fillRect(0, 0, 1, 1);
+  const d = ctx.getImageData(0, 0, 1, 1).data;
+  return { r: d[0], g: d[1], b: d[2] };
+}
 
 // src/core/animation.ts
 function smoothstep(t) {
@@ -635,6 +648,12 @@ function imageToAsciiFrame(source, options, targetWidth, targetHeight) {
     normRange = hi > lo ? hi - lo : 255;
   }
   const frame = [];
+  let ckRGB = null;
+  let ckTolSq = 0;
+  if (options.chromaKey != null) {
+    ckRGB = parseChromaKeyColor(options.chromaKey);
+    ckTolSq = (options.chromaKeyTolerance ?? 60) ** 2;
+  }
   for (let y = 0; y < rows; y++) {
     const row = [];
     for (let x = 0; x < cols; x++) {
@@ -643,6 +662,15 @@ function imageToAsciiFrame(source, options, targetWidth, targetHeight) {
       const g = pixels[i + 1];
       const b = pixels[i + 2];
       const a = pixels[i + 3];
+      if (ckRGB !== null) {
+        const dr = r - ckRGB.r;
+        const dg = g - ckRGB.g;
+        const db = b - ckRGB.b;
+        if (dr * dr + dg * dg + db * db <= ckTolSq) {
+          row.push({ char: " ", r: 0, g: 0, b: 0, a: 0 });
+          continue;
+        }
+      }
       const rawLum = 0.299 * r + 0.587 * g + 0.114 * b;
       const lum = options.normalize ? (rawLum - normMin) / normRange * 255 : rawLum;
       const adjustedLum = adjustLuminance(lum, options.brightness, options.contrast);