ImageData.pixelFormat — Eigenschaft · JavaScript-Referenz

Signatur

ImageData.pixelFormat

Beschreibung

Die Eigenschaft pixelFormat gibt an, wie die Pixelwerte im Array ImageData.data gespeichert sind. Sie ist schreibgeschützt und wird einmalig beim Erzeugen des Objekts festgelegt: über das Einstellungsobjekt des Konstruktors new ImageData(…, { pixelFormat }) oder über die Optionen von CanvasRenderingContext2D.getImageData() bzw. createImageData().

Mögliche Werte:

"rgba-unorm8" – Standard. Vier Kanäle (R, G, B, A) mit je 8 Bit ohne Vorzeichen, normiert auf 0–255. data ist ein Uint8ClampedArray.
"rgba-float16" – Vier Kanäle als 16-Bit-Gleitkommazahlen, üblicherweise im Bereich 0.0–1.0 (bei Wide-Gamut/HDR auch darüber hinaus). data ist ein Float16Array.

Nützlich ist die Eigenschaft vor allem in generischem Code, der ImageData-Objekte unbekannter Herkunft verarbeitet: Anhand von pixelFormat entscheidet man, ob Werte als Ganzzahlen (0–255) oder als Gleitkommazahlen (0.0–1.0) interpretiert werden müssen. Das Float16-Format ist für HDR-Inhalte, hohe Farbtiefe und verlustärmere Bildverarbeitung gedacht, typischerweise zusammen mit colorSpace: "display-p3".

Rückgabewert

Typ

"rgba-unorm8" | "rgba-float16"

Beschreibung

Ein String mit dem Pixelformat. Fehlt die Eigenschaft (ältere Browser), liefert der Zugriff undefined; die Daten sind dann immer im Format "rgba-unorm8".

Beispiele

Standardformat eines ImageData-Objekts auslesen

const img = new ImageData(2, 2);
console.log(img.pixelFormat);
console.log(img.data.constructor.name);

rgba-unorm8 Uint8ClampedArray

Float16-ImageData mit Feature-Erkennung erzeugen

const supportsFloat16 = typeof Float16Array !== 'undefined' && 'pixelFormat' in ImageData.prototype;

if (supportsFloat16) {
  const img = new ImageData(4, 4, { pixelFormat: 'rgba-float16', colorSpace: 'display-p3' });
  console.log(img.pixelFormat, img.colorSpace);
  console.log(img.data instanceof Float16Array);
} else {
  console.log('Float16-ImageData wird nicht unterstützt');
}

rgba-float16 display-p3 true

Pixel formatunabhängig in 0–255 umrechnen

// Liefert den ersten Pixel immer als 8-Bit-Werte, egal welches Format vorliegt
const firstPixelAs8Bit = (imageData) => {
  const [r, g, b, a] = imageData.data;
  if (imageData.pixelFormat === 'rgba-float16') {
    const to8 = (v) => Math.round(Math.min(Math.max(v, 0), 1) * 255);
    return [to8(r), to8(g), to8(b), to8(a)];
  }
  return [r, g, b, a];
};

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

const data = ctx.getImageData(0, 0, 1, 1);
console.log(data.pixelFormat ?? 'rgba-unorm8', firstPixelAs8Bit(data));

rgba-unorm8 [255, 128, 0, 255]

Float16-Daten aus einem Canvas lesen

const canvas = new OffscreenCanvas(1, 1);
const ctx = canvas.getContext('2d');
ctx.fillStyle = 'white';
ctx.fillRect(0, 0, 1, 1);

try {
  const hdr = ctx.getImageData(0, 0, 1, 1, { pixelFormat: 'rgba-float16' });
  console.log(hdr.pixelFormat, Array.from(hdr.data));
} catch (err) {
  console.log('Nicht unterstützt:', err.name);
}

rgba-float16 [1, 1, 1, 1]

// Wichtig · Fallstricke

Experimentell: pixelFormat und das Format "rgba-float16" gibt es bisher nur in neueren Chromium-Versionen. Andere Browser kennen die Eigenschaft nicht, der Zugriff liefert dort undefined. Deshalb immer mit 'pixelFormat' in ImageData.prototype und typeof Float16Array prüfen.
Schreibgeschützt: Eine Zuweisung wie img.pixelFormat = 'rgba-float16' hat keine Wirkung (im Strict Mode gibt es einen TypeError). Wer das Format wechseln will, muss ein neues ImageData-Objekt erzeugen und die Werte selbst umrechnen.
Typ des Arrays muss passen: Übergibt man dem Konstruktor ein Datenarray, muss sein Typ zum Format passen: Uint8ClampedArray für "rgba-unorm8", Float16Array für "rgba-float16". Sonst wird eine Ausnahme ausgelöst.
Wertebereich: Float16-Werte sind nicht auf 0–1 begrenzt. Code, der blind mit 0–255 rechnet, liefert bei Float16-Daten falsche Ergebnisse.
Speicher: Float16 braucht pro Pixel doppelt so viel Speicher (8 statt 4 Byte). Bei großen Bildern macht sich das bemerkbar.

Siehe auch

ImageData.colorSpace ImageData.height ImageData.data ImageData.width AudioData.format