SVGFEConvolveMatrixElement.kernelUnitLengthX — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEConvolveMatrixElement.kernelUnitLengthX

Beschreibung

Die Eigenschaft kernelUnitLengthX gehört zur Schnittstelle SVGFEConvolveMatrixElement und bildet den ersten Wert des SVG-Attributs kernelUnitLength auf das DOM ab. Dieses Attribut legt fest, wie groß der Abstand zwischen zwei aufeinanderfolgenden Spalten der Faltungsmatrix in Einheiten des aktuellen Benutzerkoordinatensystems ist (Attribut primitiveUnits am <filter>). Der zweite Wert (Y-Richtung) steht über kernelUnitLengthY zur Verfügung.

Die Eigenschaft selbst ist schreibgeschützt. Sie gibt aber ein SVGAnimatedNumber-Objekt zurück: Über baseVal liest und setzt man den statischen Attributwert, über animVal liest man den aktuell (eventuell per SMIL animierten) Wert.

Wofür braucht man das? Mit kernelUnitLength wird ein Faltungsfilter (Schärfen, Weichzeichnen, Kantenerkennung, Prägen) unabhängig von Auflösung und Zoomfaktor. Ohne das Attribut arbeitet der Filter pixelbasiert, sodass das Ergebnis je nach Bildschirmdichte unterschiedlich aussieht. Per Skript kann man den Wert auslesen, um etwa einen Regler in einem Filter-Editor zu befüllen, oder ihn dynamisch anpassen.

Wird nur ein einziger Wert im Attribut angegeben, gilt er für beide Richtungen; kernelUnitLengthX und kernelUnitLengthY liefern dann denselben Wert. Ist das Attribut gar nicht gesetzt, liefert baseVal in der Praxis 0.

Rückgabewert

Typ

SVGAnimatedNumber

Beschreibung

Ein Objekt mit baseVal (statischer Wert, beschreibbar) und animVal (aktueller, ggf. animierter Wert, nur lesbar) für die X-Komponente von kernelUnitLength.

Beispiele

Wert der X-Komponente auslesen

// Markup:
// <svg width="0" height="0">
//   <filter id="schaerfen">
//     <feConvolveMatrix id="conv" order="3"
//       kernelMatrix="0 -1 0 -1 5 -1 0 -1 0"
//       kernelUnitLength="2 3" />
//   </filter>
// </svg>

const conv = document.getElementById('conv');

console.log(conv.kernelUnitLengthX.baseVal);
console.log(conv.kernelUnitLengthY.baseVal);
console.log(conv.kernelUnitLengthX instanceof SVGAnimatedNumber);

2 3 true

Ein Wert gilt für beide Richtungen

const svgNS = 'http://www.w3.org/2000/svg';
const conv = document.createElementNS(svgNS, 'feConvolveMatrix');
conv.setAttribute('kernelUnitLength', '1.5');

console.log(conv.kernelUnitLengthX.baseVal);
console.log(conv.kernelUnitLengthY.baseVal);

1.5 1.5

Filterstärke per Regler anpassen

// <input type="range" id="regler" min="0.5" max="5" step="0.5" value="1">
const conv = document.querySelector('#schaerfen feConvolveMatrix');
const regler = document.getElementById('regler');

regler.addEventListener('input', () => {
  const wert = Number(regler.value);
  // Robust: Attribut direkt setzen, statt baseVal zu beschreiben
  conv.setAttribute('kernelUnitLength', `${wert} ${wert}`);
  console.log('X-Einheit jetzt:', conv.kernelUnitLengthX.baseVal);
});

X-Einheit jetzt: 2.5 (bei Reglerstellung 2.5)

Fehlendes Attribut erkennen

const conv = document.createElementNS('http://www.w3.org/2000/svg', 'feConvolveMatrix');

const istGesetzt = conv.hasAttribute('kernelUnitLength');
console.log(istGesetzt, conv.kernelUnitLengthX.baseVal);

false 0

// Wichtig · Fallstricke

Nicht direkt zuweisen: conv.kernelUnitLengthX = 3 hat keine Wirkung (schreibgeschützt). Nur kernelUnitLengthX.baseVal lässt sich setzen. Das Verhalten beim Zurückschreiben ins Attribut ist je nach Browser nicht ganz einheitlich, deshalb ist setAttribute('kernelUnitLength', 'x y') die verlässlichere Wahl.
Standardwert: Fehlt das Attribut, liefert baseVal in der Regel 0. Das bedeutet „nicht angegeben“ (pixelbasierte Verarbeitung) und ist keine echte Einheitslänge. Mit hasAttribute() lässt sich das unterscheiden.
Ungültige Werte: Negative Werte oder 0 im Attribut gelten laut Spezifikation als Fehler. Der Filter wird dann so behandelt, als fehle das Attribut.
Rendering-Unterschiede: Die DOM-Eigenschaft gibt es in allen modernen Browsern. Wie kernelUnitLength beim Rendern umgesetzt wird, weicht zwischen den Engines aber teilweise ab (z. B. Firefox gegenüber Chromium). Visuelle Ergebnisse sollte man in mehreren Browsern prüfen.
Einheiten: Der Wert bezieht sich auf das Koordinatensystem aus primitiveUnits. Bei objectBoundingBox sind schon kleine Werte wie 0.01 groß.

Siehe auch

SVGFEConvolveMatrixElement.kernelUnitLengthY SVGFEConvolveMatrixElement SVGFEConvolveMatrixElement.kernelMatrix SVGFEConvolveMatrixElement.orderX SVGAnimatedNumber SVGFEDiffuseLightingElement.kernelUnitLengthX