Images & Pixel Manipulation

Technical Deep Dive & Specifications

The Three drawImage Overloads

// 1. DIRECT BLIT (3 Parameters)
ctx.drawImage(imageSource, dx, dy);

// 2. SCALE / STRETCH (5 Parameters)
ctx.drawImage(imageSource, dx, dy, dWidth, dHeight);

// 3. SOURCE SLICE & DESTINATION SCALE (9 Parameters - The "Sprite Sheet" Overload)
ctx.drawImage(imageSource, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight);

SOURCE IMAGE (Sprite Sheet):                      DESTINATION CANVAS:
+-------------------------------+                 +-------------------------------+
| (sx, sy)                      |                 |                               |
|   +-----------+               |                 | (dx, dy)                      |
|   | sWidth    |               |                 |   +-----------------------+   |
|   |  CROP     | sHeight       |    =======>     |   | dWidth                |   |
|   |  WINDOW   |               |                 |   |  SCALED               |   |
|   +-----------+               |                 |   |  RENDER               |   |
|                               |                 |   |                       |   |
+-------------------------------+                 |   +-----------------------+   |
                                                  +-------------------------------+

• sx, sy, sWidth, sHeight: The crop bounding box inside the source image.
• dx, dy, dWidth, dHeight: The destination bounding box on the canvas.

The ImageData Structure & Uint8ClampedArray

When you call const imgData = ctx.getImageData(sx, sy, sw, sh), the browser returns an ImageData object:

• imgData.width: Number of horizontal pixels in the slice.
• imgData.height: Number of vertical pixels in the slice.
• imgData.data: A one-dimensional typed array (Uint8ClampedArray) containing raw RGBA color values.

The Flat Byte Array Memory Layout

Every pixel occupies 4 contiguous array indices ($0\text{–}255$):

Index:    0    1    2    3    4    5    6    7    8    9   10   11
Value:  [ R0,  G0,  B0,  A0,  R1,  G1,  B1,  A1,  R2,  G2,  B2,  A2 ... ]
         |--- Pixel (0,0) ---| |--- Pixel (1,0) ---| |--- Pixel (2,0) ---|

Total array length $= \text{width} \times \text{height} \times 4\text{ bytes}$.

Coordinate Index Formula

To locate the starting Red index for a pixel at Cartesian coordinate $(x, y)$:

const index = (y * width + x) * 4;
const red   = data[index];
const green = data[index + 1];
const blue  = data[index + 2];
const alpha = data[index + 3];

Image Filter Mathematics

for (let i = 0; i < data.length; i += 4) {
  const r = data[i];
  const g = data[i + 1];
  const b = data[i + 2];

  // 1. Grayscale (ITU-R BT.601 Human Luminosity Perception Formula)
  const gray = 0.299 * r + 0.587 * g + 0.114 * b;
  data[i] = gray;     // R
  data[i + 1] = gray; // G
  data[i + 2] = gray; // B

  // 2. Color Inversion
  // data[i]     = 255 - r;
  // data[i + 1] = 255 - g;
  // data[i + 2] = 255 - b;

  // 3. Binary Threshold (High-Contrast Monochrome)
  // const v = (gray >= 128) ? 255 : 0;
  // data[i] = data[i+1] = data[i+2] = v;
}

The CORS Tainted Canvas Security Policy

If you draw an image hosted on an external domain (e.g. https://cdn.example.com/avatar.png) onto your canvas without CORS approval:

1. The canvas is permanently marked as Tainted.
2. The browser permits visual rendering, BUT...
3. Calling ctx.getImageData(), canvas.toDataURL(), or canvas.toBlob() throws an immediate fatal exception:
   DOMException: Failed to execute 'getImageData' on 'CanvasRenderingContext2D': The canvas has been tainted by cross-origin data.

External Origin (No CORS) ---> <img> ---> Canvas ---> ctx.getImageData() ---> 🚨 FATAL SecurityError!

How to Enable Cross-Origin Pixel Access:

1. Ensure the remote server sends Access-Control-Allow-Origin: * headers.
2. Set img.crossOrigin = 'anonymous' in JavaScript before setting img.src:

const img = new Image();
img.crossOrigin = 'anonymous'; // Request CORS headers
img.onload = () => {
  ctx.drawImage(img, 0, 0);
  const data = ctx.getImageData(0, 0, canvas.width, canvas.height); // Safe!
};
img.src = 'https://cors-enabled-cdn.com/photo.jpg';

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Line 46 (getContext('2d', { willReadFrequently: true })): Tells the browser's graphics engine to retain the backing store in CPU system memory, ensuring high-speed getImageData and putImageData throughput without GPU bus synchronization penalties.
• Lines 50–72 (generateSourcePattern): Constructs an in-memory graphic using linear gradients and geometric shapes so the demo can run immediately without relying on external network images.
• Lines 78–79 (originalImageData = ctx.getImageData(...)): Reads the full $550 \times 340 \times 4 = 748,000\text{ bytes}$ into memory as our unmodified reference baseline.
• Lines 86–90 (new ImageData(...)): Clones the Uint8ClampedArray memory buffer so filter operations are non-destructive and can be re-run on demand.
• Lines 93–115: High-speed loop advancing by $4$ bytes per step (i += 4), executing pixel-level RGB transformations in under $3\text{ milliseconds}$.
• Line 118 (ctx.putImageData(imgData, 0, 0)): Directly commits the modified pixel buffer back to the canvas surface.

Expected Browser Render Output

+-------------------------------------------------------------+
| [Original]  [Grayscale]  [Invert]  [Threshold]  [Sepia]     |
|                                                             |
| +---------------------------------------------------------+ |
| | (Vibrant Multi-Color Gradient / Monochrome Pixel Surface) | |
| |       ( O )  ( O )  ( O )  ( O )  ( O )                 | |
| |            Real-Time Pixel Shaders in JS                | |
| +---------------------------------------------------------+ |
+-------------------------------------------------------------+