ImageData.height — Eigenschaft · JavaScript-Referenz

Signatur

ImageData.height

Beschreibung

ImageData.height gibt als vorzeichenlose Ganzzahl an, wie viele Pixelzeilen ein ImageData-Objekt enthält. Der Wert wird beim Erzeugen festgelegt, zum Beispiel über new ImageData(), CanvasRenderingContext2D.createImageData() oder getImageData(), und lässt sich danach nicht mehr ändern.

Zusammen mit width beschreibt height, wie das flache Array data (Uint8ClampedArray) aufgebaut ist. Jedes Pixel belegt vier aufeinanderfolgende Bytes (R, G, B, A). Deshalb gilt immer data.length === width * height * 4. Das Byte, mit dem das Pixel an der Stelle (x, y) beginnt, liegt bei (y * width + x) * 4.

Gebraucht wird die Eigenschaft vor allem in Schleifen, die Pixel für Pixel filtern (Graustufen, Spiegeln, Weichzeichnen), und beim Anlegen eines gleich großen Ziel-Puffers. height gibt die tatsächliche Größe in Gerätepixeln des Puffers an. Mit der CSS-Höhe des Canvas-Elements hat sie nichts zu tun.

Rückgabewert

Typ

number

Beschreibung

Eine positive Ganzzahl (unsigned long): die Höhe des Bildausschnitts in Pixeln bzw. die Anzahl der Pixelzeilen.

Beispiele

Höhe eines neu erzeugten ImageData-Objekts auslesen

const img = new ImageData(200, 100);
console.log(img.width, img.height);
console.log(img.data.length === img.width * img.height * 4);

200 100 true

Pixelzeilen durchlaufen und einen vertikalen Verlauf zeichnen

const canvas = document.createElement('canvas');
canvas.width = 256;
canvas.height = 128;
document.body.append(canvas);
const ctx = canvas.getContext('2d');

const img = ctx.createImageData(canvas.width, canvas.height);
const { width, height, data } = img;

for (let y = 0; y < height; y++) {
  const shade = Math.round((y / (height - 1)) * 255);
  for (let x = 0; x < width; x++) {
    const i = (y * width + x) * 4;
    data[i] = shade;       // Rot
    data[i + 1] = 0;       // Grün
    data[i + 2] = 255 - shade; // Blau
    data[i + 3] = 255;     // Alpha
  }
}
ctx.putImageData(img, 0, 0);
console.log(`${height} Zeilen gezeichnet`);

128 Zeilen gezeichnet

Bild vertikal spiegeln mit height

const flipVertical = (src) => {
  const { width, height, data } = src;
  const out = new ImageData(width, height);
  const rowBytes = width * 4;
  for (let y = 0; y < height; y++) {
    const from = y * rowBytes;
    const to = (height - 1 - y) * rowBytes;
    out.data.set(data.subarray(from, from + rowBytes), to);
  }
  return out;
};

const src = new ImageData(new Uint8ClampedArray([255,0,0,255, 0,0,255,255]), 1, 2);
const flipped = flipVertical(src);
console.log(flipped.height, Array.from(flipped.data));

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

Schreibversuch wird ignoriert

'use strict';
const img = new ImageData(10, 20);
try {
  img.height = 50;
} catch (e) {
  console.log(e instanceof TypeError);
}
console.log(img.height);

true 20

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an height wird ohne Strict Mode stillschweigend ignoriert, im Strict Mode wirft sie einen TypeError. Wer eine andere Größe braucht, muss ein neues ImageData-Objekt anlegen oder das Bild auf einem Canvas skalieren.
Keine CSS-Größe: getImageData() arbeitet mit den Pixelmaßen des Canvas-Puffers (canvas.height), nicht mit der dargestellten CSS-Höhe. Auf HiDPI-Bildschirmen können beide Werte deutlich voneinander abweichen.
Konstruktor mit Daten: Bei new ImageData(data, width, height) muss data.length genau width * height * 4 betragen, sonst wird ein IndexSizeError geworfen. Lässt man height weg, berechnet der Browser den Wert aus der Länge des Arrays.
Leistung: Lies width, height und data vor großen Schleifen einmal in lokale Variablen ein, statt bei jedem Durchlauf auf die Eigenschaften zuzugreifen.
Kompatibilität: Wird von allen modernen Browsern unterstützt. In Web Workers und mit OffscreenCanvas steht die Eigenschaft ebenfalls zur Verfügung.

Siehe auch

ImageData ImageData.width ImageData.data CanvasRenderingContext2D.getImageData() CanvasRenderingContext2D.putImageData() CanvasRenderingContext2D.createImageData() ImageData.colorSpace