SVGFEConvolveMatrixElement.kernelUnitLengthY — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEConvolveMatrixElement.kernelUnitLengthY

Beschreibung

Die Eigenschaft kernelUnitLengthY gehört zum Interface SVGFEConvolveMatrixElement, das im DOM ein <feConvolveMatrix>-Filterprimitiv darstellt. Sie gibt den vertikalen Anteil des Attributs kernelUnitLength zurück. Dieses Attribut legt fest, wie groß der Abstand zwischen aufeinanderfolgenden Spalten und Zeilen der Faltungsmatrix in Einheiten des aktuellen Koordinatensystems (primitiveUnits) ist.

kernelUnitLength erwartet den Typ <number-optional-number>: Der erste Wert ist die X-Länge (siehe kernelUnitLengthX), der optionale zweite die Y-Länge. Wird nur ein Wert angegeben, gilt er für beide Richtungen, sodass kernelUnitLengthY dann denselben Wert wie kernelUnitLengthX hat.

Die Eigenschaft selbst ist schreibgeschützt, liefert aber ein SVGAnimatedNumber-Objekt. Über baseVal liest du den im Markup gesetzten Wert, über animVal den aktuellen, eventuell durch SMIL-Animation veränderten Wert. Nützlich ist das vor allem, wenn du Filter per Skript untersuchst oder auflösungsunabhängige Faltungseffekte (Schärfen, Prägen, Kantenerkennung) dynamisch anpassen willst.

Rückgabewert

Typ

SVGAnimatedNumber

Beschreibung

Ein Objekt mit baseVal (Wert aus dem Attribut, number) und animVal (aktuell animierter Wert, number, nur lesbar) für die vertikale Kernel-Einheitslänge.

Beispiele

Y-Anteil aus einem zweiteiligen kernelUnitLength lesen

const SVG_NS = 'http://www.w3.org/2000/svg';
const conv = document.createElementNS(SVG_NS, 'feConvolveMatrix');
conv.setAttribute('order', '3');
conv.setAttribute('kernelMatrix', '0 -1 0 -1 5 -1 0 -1 0');
conv.setAttribute('kernelUnitLength', '2 3');

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

2 3

Ein einzelner Wert gilt für beide Achsen

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

const { kernelUnitLengthX: x, kernelUnitLengthY: y } = conv;
console.log(`X: ${x.baseVal}, Y: ${y.baseVal}`);

X: 1.5, Y: 1.5

Filter im Dokument untersuchen und anpassen

// HTML: <svg><filter id="schaerfen"><feConvolveMatrix order="3"
//   kernelMatrix="0 -1 0 -1 5 -1 0 -1 0" kernelUnitLength="1 2"/></filter></svg>
const conv = document.querySelector('#schaerfen feConvolveMatrix');

const beschreibe = (el) => ({
  x: el.kernelUnitLengthX.baseVal,
  y: el.kernelUnitLengthY.baseVal
});

console.log(beschreibe(conv));

// Ändern über das Attribut – die Eigenschaft spiegelt den neuen Wert sofort wider
conv.setAttribute('kernelUnitLength', '1 4');
console.log(conv.kernelUnitLengthY.baseVal);

{ x: 1, y: 2 } 4

// Wichtig · Fallstricke

Die Eigenschaft selbst ist schreibgeschützt: conv.kernelUnitLengthY = 2 hat keine Wirkung (im Strict Mode gibt es einen TypeError). Ändere stattdessen das Attribut per setAttribute('kernelUnitLength', …) oder setze baseVal.
Fehlt das Attribut, soll laut Spezifikation eine Länge von einem Pixel der internen Bitmap verwendet werden. Der im DOM gemeldete baseVal ist dann meist 0. Das ist also kein tatsächlich wirksamer Wert.
Negative Werte oder 0 im Attribut sind ein Fehler. Der Browser ignoriert sie dann und verwendet den Standardwert.
Die Browser setzen kernelUnitLength beim Rendern unterschiedlich um. Manche Engines lesen den Wert zwar im DOM aus, werten ihn aber beim Zeichnen nicht oder nur teilweise aus. Prüfe die visuelle Wirkung daher immer in mehreren Browsern.
Die Elemente müssen im SVG-Namensraum erzeugt werden (createElementNS). Mit document.createElement('feConvolveMatrix') entsteht ein HTMLUnknownElement ohne diese Eigenschaft.

Siehe auch

SVGFEConvolveMatrixElement SVGFEConvolveMatrixElement.kernelUnitLengthX SVGFEConvolveMatrixElement.kernelMatrix SVGFEConvolveMatrixElement.orderX SVGAnimatedNumber