ImageData.width — Eigenschaft · JavaScript-Referenz

Signatur

ImageData.width

Beschreibung

ImageData.width ist eine schreibgeschützte Eigenschaft vom Typ unsigned long. Sie gibt an, wie viele Pixel jede Zeile der Bilddaten enthält. Festgelegt wird der Wert beim Erzeugen des Objekts, zum Beispiel über new ImageData(width, height), CanvasRenderingContext2D.createImageData() oder CanvasRenderingContext2D.getImageData().

Am meisten braucht man die Eigenschaft, um in ImageData.data gezielt einzelne Pixel anzusprechen. Das Array data ist ein eindimensionales Uint8ClampedArray mit vier Bytes pro Pixel (Rot, Grün, Blau, Alpha). Den Index eines Pixels an der Position (x, y) berechnet man mit (y * width + x) * 4.

Zusammen mit ImageData.height gilt immer: data.length === width * height * 4. Damit ist width die verlässliche Grundlage für Schleifen über Zeilen und Spalten, für Filter, Faltungen (z. B. Weichzeichner) und für das Umrechnen zwischen Canvas-Koordinaten und Array-Indizes.

Rückgabewert

Typ

number

Beschreibung

Eine positive Ganzzahl (unsigned long): die Breite der Bilddaten in Pixeln.

Beispiele

Breite eines neu erzeugten ImageData-Objekts auslesen

const imageData = new ImageData(200, 100);
console.log(imageData.width);  // Pixel pro Zeile
console.log(imageData.height);
console.log(imageData.data.length); // width * height * 4

200 100 80000

Einzelnes Pixel über width adressieren

const canvas = document.createElement('canvas');
canvas.width = 50;
canvas.height = 50;
const ctx = canvas.getContext('2d');
ctx.fillStyle = 'rgb(255, 0, 0)';
ctx.fillRect(0, 0, 50, 50);

const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);

const getPixel = (img, x, y) => {
  const i = (y * img.width + x) * 4;
  const [r, g, b, a] = img.data.slice(i, i + 4);
  return { r, g, b, a };
};

console.log(getPixel(imageData, 10, 20));

{ r: 255, g: 0, b: 0, a: 255 }

Horizontaler Farbverlauf zeilen- und spaltenweise

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const img = ctx.createImageData(256, 64);
const { width, height, data } = img;

for (let y = 0; y < height; y++) {
  for (let x = 0; x < width; x++) {
    const i = (y * width + x) * 4;
    data[i] = x;                              // Rot steigt nach rechts an
    data[i + 1] = 0;
    data[i + 2] = Math.round(255 - x);        // Blau fällt ab
    data[i + 3] = 255;                        // voll deckend
  }
}

ctx.putImageData(img, 0, 0);
console.log(`Verlauf mit ${width} Pixel Breite gezeichnet`);

Verlauf mit 256 Pixel Breite gezeichnet

Bild horizontal spiegeln

const mirror = (img) => {
  const { width, height, data } = img;
  const out = new ImageData(width, height);
  for (let y = 0; y < height; y++) {
    for (let x = 0; x < width; x++) {
      const src = (y * width + x) * 4;
      const dst = (y * width + (width - 1 - x)) * 4;
      out.data.set(data.subarray(src, src + 4), dst);
    }
  }
  return out;
};

const original = new ImageData(new Uint8ClampedArray([255,0,0,255, 0,0,255,255]), 2, 1);
console.log(Array.from(mirror(original).data));

[0, 0, 255, 255, 255, 0, 0, 255]

// Wichtig · Fallstricke

Schreibgeschützt: Wenn man imageData.width = 300 zuweist, passiert nichts. Im Strict Mode wird ein TypeError geworfen. Für eine andere Größe muss man ein neues ImageData-Objekt anlegen.
Nicht gleich der Canvas-Breite: width ist die Breite des ausgelesenen Bereichs, nicht die des Canvas. Nach getImageData(10, 10, 30, 30) ist width gleich 30. Deshalb bei Indexrechnungen immer img.width verwenden, nicht canvas.width.
CSS-Größe und HiDPI: Die Pixelbreite richtet sich nach dem Zeichenpuffer (canvas.width), nicht nach der im CSS dargestellten Größe. Auf Bildschirmen mit hoher Pixeldichte (devicePixelRatio) können die beiden stark voneinander abweichen.
Beim Konstruktor new ImageData(data, width) muss data.length ein Vielfaches von 4 * width sein. Sonst wird eine IndexSizeError-DOMException geworfen. Ein Wert von 0 für die Breite ist ebenfalls nicht erlaubt.
Die Eigenschaft wird von allen modernen Browsern unterstützt und ist auch in Web Workern verfügbar (z. B. mit OffscreenCanvas).

Siehe auch

ImageCapture.track ImageData.data ImageData.height ImageData.colorSpace ImageData.pixelFormat