CanvasRenderingContext2D.getImageData() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.getImageData(sx, sy, sw, sh, settings)

Beschreibung

getImageData() kopiert die Pixel eines rechteckigen Ausschnitts der Leinwand in ein neues ImageData-Objekt. Dessen Eigenschaft data ist ein Uint8ClampedArray, in dem jeder Pixel mit vier aufeinanderfolgenden Bytes steht (Rot, Grün, Blau, Alpha, jeweils 0–255). Das Array hat also die Länge breite * höhe * 4.

Typische Einsatzzwecke sind Bildfilter (Graustufen, Invertieren, Helligkeit), Farbwähler (Pipette), Kollisionserkennung auf Pixelebene, Bildanalyse oder das Weiterverarbeiten von Webcam-Bildern. Die geänderten Daten schreibt man anschließend mit putImageData() zurück auf die Leinwand.

Die Koordinaten beziehen sich auf den Pixelraum der Leinwand (Attribute width/height), nicht auf die CSS-Größe, und werden von der aktuellen Transformationsmatrix nicht beeinflusst. Bereiche außerhalb der Leinwand werden als transparentes Schwarz (0, 0, 0, 0) geliefert. Negative Werte für sw oder sh sind erlaubt und spiegeln das Rechteck nach links bzw. oben.

Parameter

Name	Typ	Default	Beschreibung
$sx Pflicht	number		x-Koordinate der linken oberen Ecke des auszulesenden Rechtecks.
$sy Pflicht	number		y-Koordinate der linken oberen Ecke des auszulesenden Rechtecks.
$sw Pflicht	number		Breite des Rechtecks in Pixeln. Negative Werte lesen nach links. `0` löst einen `IndexSizeError` aus.
$sh Pflicht	number		Höhe des Rechtecks in Pixeln. Negative Werte lesen nach oben. `0` löst einen `IndexSizeError` aus.
$settings	{ colorSpace?: 'srgb' \| 'display-p3' }	Farbraum des Kontexts	Optionales Objekt; `colorSpace` legt den Farbraum der zurückgegebenen Daten fest.

Rückgabewert

Typ

ImageData

Beschreibung

Ein neues ImageData-Objekt mit width, height, colorSpace und data (Uint8ClampedArray mit RGBA-Werten). Es handelt sich um eine Kopie – Änderungen wirken sich erst nach putImageData() auf die Leinwand aus.

Beispiele

Farbe eines einzelnen Pixels auslesen (Pipette)

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

ctx.fillStyle = 'rgb(255, 128, 0)';
ctx.fillRect(0, 0, 50, 50);

const [r, g, b, a] = ctx.getImageData(10, 10, 1, 1).data;
console.log(`rgba(${r}, ${g}, ${b}, ${a / 255})`);

rgba(255, 128, 0, 1)

Graustufen-Filter auf die ganze Leinwand anwenden

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d', { willReadFrequently: true });

const toGrayscale = () => {
  const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
  const { data } = imageData;

  for (let i = 0; i < data.length; i += 4) {
    // Gewichtete Luminanz nach ITU-R BT.601
    const gray = 0.299 * data[i] + 0.587 * data[i + 1] + 0.114 * data[i + 2];
    data[i] = data[i + 1] = data[i + 2] = gray;
  }

  ctx.putImageData(imageData, 0, 0);
};

const img = new Image();
img.src = '/bilder/foto.jpg'; // gleiche Herkunft, sonst SecurityError
img.addEventListener('load', () => {
  canvas.width = img.naturalWidth;
  canvas.height = img.naturalHeight;
  ctx.drawImage(img, 0, 0);
  toGrayscale();
});

Farbe unter dem Mauszeiger anzeigen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d', { willReadFrequently: true });

canvas.addEventListener('mousemove', (event) => {
  const rect = canvas.getBoundingClientRect();
  // CSS-Koordinaten in Leinwand-Pixel umrechnen
  const x = Math.floor((event.clientX - rect.left) * (canvas.width / rect.width));
  const y = Math.floor((event.clientY - rect.top) * (canvas.height / rect.height));

  const [r, g, b] = ctx.getImageData(x, y, 1, 1).data;
  const hex = '#' + [r, g, b].map((v) => v.toString(16).padStart(2, '0')).join('');
  console.log(`(${x}|${y}) → ${hex}`);
});

(120|45) → #ff8000

Fehlerbehandlung bei fremden (tainted) Bildern

const readPixels = (ctx, w, h) => {
  try {
    return ctx.getImageData(0, 0, w, h);
  } catch (err) {
    if (err.name === 'SecurityError') {
      console.warn('Leinwand ist durch ein Cross-Origin-Bild verunreinigt.');
      return null;
    }
    throw err;
  }
};

const img = new Image();
img.crossOrigin = 'anonymous'; // Server muss CORS-Header senden
img.src = 'https://example.com/bild.png';

// Wichtig · Fallstricke

Sicherheit / CORS: Wurde ein Bild, Video oder eine andere Quelle fremder Herkunft ohne gültige CORS-Freigabe gezeichnet, gilt die Leinwand als „tainted“. getImageData() wirft dann einen SecurityError. Abhilfe: img.crossOrigin = 'anonymous' setzen und der Server muss Access-Control-Allow-Origin senden.
Fehler: sw oder sh gleich 0 ergibt einen IndexSizeError. Sehr große Bereiche können wegen Speichermangel scheitern.
Performance: Jeder Aufruf kopiert Daten, häufig aus dem GPU-Speicher zurück. Wer oft liest, sollte den Kontext mit getContext('2d', { willReadFrequently: true }) erzeugen und lieber einmal einen großen Bereich statt vieler Einzelpixel lesen.
Vormultipliziertes Alpha: Browser speichern intern oft vormultipliziert. Halbtransparente Pixel können nach putImageData() und erneutem getImageData() leicht abweichende Farbwerte liefern.
Koordinaten: Transformationen (translate, scale) und devicePixelRatio-Skalierung werden nicht berücksichtigt; es zählen die tatsächlichen Leinwand-Pixel.
Kompatibilität: Die Grundfunktion wird von allen Browsern unterstützt, auch in OffscreenCanvasRenderingContext2D (Web Worker). Der settings-Parameter mit colorSpace steht nur in neueren Browsern zur Verfügung.

Siehe auch

CanvasRenderingContext2D.putImageData() CanvasRenderingContext2D.createImageData() ImageData CanvasRenderingContext2D.drawImage() Uint8ClampedArray HTMLCanvasElement.getContext() CanvasRenderingContext2D