SVGFEConvolveMatrixElement.kernelMatrix — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEConvolveMatrixElement.kernelMatrix

Beschreibung

Die Eigenschaft kernelMatrix des Interfaces SVGFEConvolveMatrixElement gibt das Attribut kernelMatrix eines <feConvolveMatrix>-Filterelements wieder. Diese Zahlenliste enthält die Gewichte der Faltungsmatrix (des „Kernels“), mit der jedes Pixel aus seinen Nachbarpixeln neu berechnet wird. So entstehen Effekte wie Schärfen, Weichzeichnen, Kantenerkennung oder Prägung (Emboss).

Der Rückgabewert ist ein SVGAnimatedNumberList-Objekt. Über baseVal erhältst du eine veränderbare SVGNumberList mit den im Attribut angegebenen Werten, über animVal den aktuell (gegebenenfalls durch SMIL-Animation) wirksamen, nur lesbaren Wert. Die Einträge werden zeilenweise gelesen: Die ersten orderX Werte bilden die erste Zeile der Matrix, die nächsten orderX Werte die zweite usw.

Einsetzen lässt sich die Eigenschaft, wenn du einen Filter zur Laufzeit auslesen oder dynamisch anpassen willst, zum Beispiel um die Stärke eines Schärfefilters per Schieberegler zu steuern. Änderungen an baseVal wirken sich direkt auf das Attribut im DOM und damit auf das Rendering aus.

Rückgabewert

Typ

SVGAnimatedNumberList

Beschreibung

Ein Objekt mit den Eigenschaften baseVal (veränderbare SVGNumberList) und animVal (nur lesbare SVGNumberList des aktuell wirksamen Werts). Die Eigenschaft selbst ist nur lesbar.

Beispiele

Kernel-Werte auslesen

// <svg><filter id="sharpen"><feConvolveMatrix id="conv" order="3"
//   kernelMatrix="0 -1 0 -1 5 -1 0 -1 0"/></filter></svg>
const conv = document.getElementById('conv');
const list = conv.kernelMatrix.baseVal;

const werte = [];
for (let i = 0; i < list.numberOfItems; i++) {
  werte.push(list.getItem(i).value);
}
console.log(list.numberOfItems);
console.log(werte.join(' '));

9 0 -1 0 -1 5 -1 0 -1 0

Matrix über die SVGNumberList ersetzen

const conv = document.getElementById('conv');
const svg = conv.ownerSVGElement;
const list = conv.kernelMatrix.baseVal;

// Weichzeichner: 3×3-Box-Blur
const boxBlur = [1, 1, 1, 1, 1, 1, 1, 1, 1];

list.clear();
for (const v of boxBlur) {
  const num = svg.createSVGNumber();
  num.value = v;
  list.appendItem(num);
}

console.log(conv.getAttribute('kernelMatrix'));

1 1 1 1 1 1 1 1 1

Schärfe per Schieberegler steuern

// <input type="range" id="staerke" min="0" max="3" step="0.1" value="1">
const conv = document.getElementById('conv');
const slider = document.getElementById('staerke');

const setzeSchaerfe = (s) => {
  const list = conv.kernelMatrix.baseVal;
  // Nachbarn: -s, Mitte: 1 + 4s  (Summe bleibt 1)
  const kernel = [0, -s, 0, -s, 1 + 4 * s, -s, 0, -s, 0];
  kernel.forEach((v, i) => {
    list.getItem(i).value = v;
  });
};

slider.addEventListener('input', () => setzeSchaerfe(Number(slider.value)));
setzeSchaerfe(1);
console.log(conv.kernelMatrix.baseVal.getItem(4).value);

5

// Wichtig · Fallstricke

Nur lesbar: conv.kernelMatrix = … hat keine Wirkung (im Strict Mode TypeError). Ändere stattdessen kernelMatrix.baseVal oder nutze setAttribute('kernelMatrix', '…').
Anzahl muss passen: Die Liste muss genau orderX × orderY Einträge enthalten. Stimmt die Anzahl nicht, wird der Filter laut Spezifikation als Durchreich-Filter behandelt oder (in älteren Implementierungen) gar nicht gerendert – ohne Fehlermeldung in der Konsole.
Normierung: Wenn divisor fehlt, wird die Summe der Kernel-Werte als Teiler verwendet (bei Summe 0 wird 1 genommen). Wer kernelMatrix dynamisch ändert, sollte divisor und bias im Blick behalten, sonst wird das Bild unerwartet hell oder dunkel.
animVal: Viele Browser geben für animVal dieselben Werte wie für baseVal zurück; SMIL-Animationen von kernelMatrix werden uneinheitlich unterstützt.
Performance: Große Kernel (z. B. 7×7 und größer) sind rechenintensiv, besonders bei Animationen oder großen Flächen.

Siehe auch

SVGFEConvolveMatrixElement SVGFEConvolveMatrixElement.orderX SVGFEConvolveMatrixElement.orderY SVGFEConvolveMatrixElement.divisor SVGFEConvolveMatrixElement.bias SVGAnimatedNumberList SVGNumberList