SVGFEConvolveMatrixElement.divisor — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEConvolveMatrixElement.divisor

Beschreibung

Die Eigenschaft divisor der Schnittstelle SVGFEConvolveMatrixElement spiegelt das Attribut divisor des SVG-Filterprimitivs <feConvolveMatrix> wider. Sie gibt ein SVGAnimatedNumber-Objekt zurück. Über dessen baseVal lesen oder setzen Sie den Grundwert, über animVal lesen Sie den aktuellen, möglicherweise per SMIL animierten Wert.

Bei einer Faltung (Convolution) wird jedes Pixel mit den Werten der Kernmatrix (kernelMatrix) gewichtet und aufsummiert. Das Ergebnis wird anschließend durch divisor geteilt. Damit normalisieren Sie das Ergebnis: Ist der Divisor gleich der Summe aller Matrixwerte, bleibt die Gesamthelligkeit des Bildes erhalten. Ein kleinerer Divisor hellt das Bild auf, ein größerer dunkelt es ab.

Ohne das Attribut gilt laut Spezifikation als Standardwert die Summe aller Werte der Kernmatrix. Ist diese Summe 0, wird 1 verwendet. Die Eigenschaft ist nützlich, wenn Sie Filter wie Weichzeichnen, Schärfen oder Kantenerkennung per JavaScript dynamisch anpassen wollen, etwa über einen Schieberegler.

Rückgabewert

Typ

SVGAnimatedNumber

Beschreibung

Objekt mit baseVal (Grundwert, beschreibbar, Typ number) und animVal (aktueller animierter Wert, nur lesbar).

Beispiele

Divisor eines vorhandenen Filters auslesen

// HTML:
// <svg width="0" height="0">
//   <filter id="blur">
//     <feConvolveMatrix id="conv" order="3"
//       kernelMatrix="1 1 1 1 1 1 1 1 1" divisor="9" />
//   </filter>
// </svg>

const conv = document.getElementById('conv');
console.log(conv.divisor instanceof SVGAnimatedNumber);
console.log(conv.divisor.baseVal);
console.log(conv.divisor.animVal);

true 9 9

Helligkeit per Schieberegler anpassen

// <input type="range" id="helligkeit" min="1" max="20" value="9">
const conv = document.getElementById('conv');
const slider = document.getElementById('helligkeit');

slider.addEventListener('input', () => {
  // Kleinerer Divisor = helleres Ergebnis
  conv.divisor.baseVal = Number(slider.value);
  console.log('Neuer Divisor:', conv.getAttribute('divisor'));
});

Neuer Divisor: 5 (z. B. nach Verschieben auf 5)

Schärfefilter dynamisch erzeugen und normalisieren

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(SVG_NS, 'svg');
const filter = document.createElementNS(SVG_NS, 'filter');
filter.id = 'schaerfen';

const conv = document.createElementNS(SVG_NS, 'feConvolveMatrix');
const kernel = [0, -1, 0, -1, 5, -1, 0, -1, 0];
conv.setAttribute('order', '3');
conv.setAttribute('kernelMatrix', kernel.join(' '));

// Divisor = Summe der Matrix, damit die Helligkeit erhalten bleibt
const summe = kernel.reduce((a, b) => a + b, 0) || 1;
conv.divisor.baseVal = summe;

filter.append(conv);
svg.append(filter);
document.body.append(svg);
document.querySelector('img').style.filter = 'url(#schaerfen)';

console.log(conv.divisor.baseVal);

1

// Wichtig · Fallstricke

Nur lesbar: Die Eigenschaft selbst können Sie nicht neu zuweisen (el.divisor = 5 hat keine Wirkung). Ändern Sie stattdessen el.divisor.baseVal oder rufen Sie setAttribute('divisor', …) auf.
Divisor 0: Laut Spezifikation ist der Wert 0 ein Fehler. Browser verwenden dann den Standardwert (Summe der Matrix bzw. 1).
Fehlendes Attribut: Ist divisor nicht gesetzt, liefert baseVal je nach Browser nicht zwingend die berechnete Matrixsumme. Wenn Sie sich auf einen Wert verlassen müssen, setzen Sie das Attribut ausdrücklich.
animVal ist schreibgeschützt. Schreibversuche werden ignoriert oder lösen im strikten Modus einen Fehler aus.
Faltungsfilter mit großen Matrizen (order > 3) sind rechenintensiv. Häufige Änderungen, etwa bei jedem input-Ereignis, können auf großen Flächen ruckeln.
Kompatibilität: Die Eigenschaft wird in allen modernen Browsern unterstützt (Chrome, Firefox, Safari, Edge).

Siehe auch

SVGFEConvolveMatrixElement SVGFEConvolveMatrixElement.kernelMatrix SVGFEConvolveMatrixElement.bias SVGAnimatedNumber Element.setAttribute()