Matrix- & Vektor-Bibliothek

Die Scripting-Engine enthält eine vollständige Lineare-Algebra-Bibliothek im globalen Matrix-Namespace. Alle Typen erweitern Float32Array für Zero-Copy-Interop mit der Bildverarbeitungs-Pipeline.

Basierend auf glMatrix — als objektorientierte API mit verkettbaren Methoden umgeschrieben (statt des ursprünglichen funktionalen Stils).

Visuelle Referenz, live gerendert: Die Grafik oben ist die Ausgabe des Beispiels demo_matrix_toolbox — die Engine dokumentiert sich selbst. Der flache Backing-Array speichert Spalten, nicht Zeilen; Translation steht bei Mat3 auf [6]/[7] und bei Mat4 auf [12]/[13]/[14]. Das Beispiel lässt sich im Playground öffnen, parametrieren und in jeder Skalierung neu rendern.

Vektoren

Vec2 — 2D-Vektor

const a = new Matrix.Vec2(3, 4);
const b = Matrix.Vec2.fromValues(1, 0);

a.add(b);                    // [4, 4]
a.normalize();               // Einheitsvektor
a.dot(b);                    // Skalarprodukt
a.cross(b);                  // Skalar (z-Komponente)
a.distance(b);               // Euklidischer Abstand
a.lerp(b, 0.5);              // Lineare Interpolation
a.rotate(Matrix.Vec2.fromValues(0, 0), Math.PI / 4);  // Um Ursprung rotieren
a.transformMat3(matrix);     // 3x3-Transformation anwenden

Wichtige Methoden: add, subtract, multiply, divide, scale, normalize, dot, cross, lerp, distance, length, angle, rotate, transformMat2, transformMat2d, transformMat3, transformMat4

Vec3 — 3D-Vektor

const v = new Matrix.Vec3(1, 2, 3);
const up = Matrix.Vec3.fromValues(0, 1, 0);

v.cross(up);                 // Kreuzprodukt
v.transformMat4(mvp);        // Model-View-Projection anwenden
v.transformQuat(rotation);   // Quaternion-Rotation anwenden
v.rotateX(origin, Math.PI);  // Um X-Achse rotieren

Vec4 — 4D-Vektor

Gleiche Schnittstelle wie Vec3 mit w-Komponente. Für homogene Koordinaten und Farbwerte.

Matrizen

Mat2 — 2x2-Matrix

const m = new Matrix.Mat2();       // Einheitsmatrix
m.rotate(Math.PI / 6);            // 30° rotieren
m.scale(Matrix.Vec2.fromValues(2, 1));  // X um 2 skalieren

Mat2d — 2x3 Affine Transformation

const m = new Matrix.Mat2d();      // Einheitsmatrix
m.translate(Matrix.Vec2.fromValues(100, 50));
m.rotate(Math.PI / 4);
m.scale(Matrix.Vec2.fromValues(0.5, 0.5));

Kompakte Darstellung affiner 2D-Transformationen [a, b, c, d, tx, ty].

Mat3 — 3x3-Matrix

Das Arbeitstier für 2D-Bildtransformationen, Perspektiv-Mapping und Normalenmatrizen.

const m = new Matrix.Mat3();
m.translate(Matrix.Vec2.fromValues(100, 200));
m.rotate(0.5);
m.scale(Matrix.Vec2.fromValues(2, 2));

// Projektionsmatrix für 2D-Rendering
const proj = new Matrix.Mat3();
proj.projection(800, 600);

// Normalenmatrix aus 4x4 Model-View ableiten
const normal = new Matrix.Mat3();
normal.normalFromMat4(modelView);

// Matrix-Operationen
const det = m.determinant();
m.invert();                  // gibt null zurück wenn singulär
m.transpose();

Mat4 — 4x4-Matrix

Vollständige 3D-Transformationsmatrix mit Kamera- und Projektions-Unterstützung.

const model = new Matrix.Mat4();
model.translate(Matrix.Vec3.fromValues(0, 1, -5));
model.rotateY(Math.PI / 3);
model.scale(Matrix.Vec3.fromValues(2, 2, 2));

// Perspektivische Projektion
const proj = new Matrix.Mat4();
proj.perspectiveNO(Math.PI / 4, 16 / 9, 0.1, 100);

// Orthographische Projektion
const ortho = new Matrix.Mat4();
ortho.orthoNO(-1, 1, -1, 1, 0.1, 100);

// Kamera
const view = new Matrix.Mat4();
view.lookAt(
  Matrix.Vec3.fromValues(0, 5, 10),   // Auge
  Matrix.Vec3.fromValues(0, 0, 0),    // Zentrum
  Matrix.Vec3.fromValues(0, 1, 0)     // Oben
);

// Zerlegen
const rotation = new Matrix.Quat();
const translation = new Matrix.Vec3();
const scale = new Matrix.Vec3();
model.decompose(rotation, translation, scale);

Projektions-Methoden: perspectiveNO, perspectiveZO, orthoNO, orthoZO, frustum, lookAt Transform-Methoden: translate, rotate, rotateX/Y/Z, scale, fromRotationTranslation, fromRotationTranslationScale

Quaternionen

Quat — Einheits-Quaternion

Repräsentiert Rotationen ohne Gimbal Lock.

const q = new Matrix.Quat();          // Identität [0, 0, 0, 1]

// Aus Achse-Winkel
q.setAxisAngle(Matrix.Vec3.fromValues(0, 1, 0), Math.PI / 2);

// Aus Euler-Winkeln (Grad)
q.fromEuler(45, 0, 90);

// Aus Rotationsmatrix
q.fromMat3(rotMatrix);

// Sphärische Interpolation (sanftes Rotations-Blending)
const a = new Matrix.Quat().fromEuler(0, 0, 0);
const b = new Matrix.Quat().fromEuler(0, 90, 0);
a.slerp(b, 0.5);            // halbe Rotation

// Auf Vektor anwenden
const v = new Matrix.Vec3(1, 0, 0);
v.transformQuat(q);

Quat2 — Duale Quaternion

Repräsentiert starre Transformationen (Rotation + Translation) in einem einzigen 8-Komponenten-Typ.

Homographie — Perspektivisches Bild-Mapping

Die Engine bietet einen eingebauten Homographie-Löser für das Mapping von Bildern auf beliebige Vierecke.

stampAt — High-Level API

// Ein Bild auf 4 Ziel-Ecken platzieren
const canvas = Engine.createImage(800, 600);
const photo = Engine.loadImage("INPUT");

// Definieren wo die Foto-Ecken auf dem Canvas landen
canvas.stampAt(photo, [
  { x: 100, y:  80 },    // oben-links
  { x: 500, y:  60 },    // oben-rechts
  { x: 520, y: 400 },    // unten-rechts
  { x: 120, y: 380 },    // unten-links
], 1.0, BlendMode.Over);

warpPerspective — Low-Level API

// Eigene Homographie-Matrix berechnen
const matrix = computeMyTransform();  // 9-Element-Array, zeilenweise

img.warpPerspective(
  outputWidth, outputHeight,
  matrix,
  Interp.Bilinear     // 0=Nearest, 1=Bilinear, 2=Bicubic
);

Praktisches Beispiel: 3D-Würfel

// Ein Bild auf eine Würfelfläche mappen
const face = photo.clone();
const srcCorners = [
  [0, 0], [photo.width, 0],
  [photo.width, photo.height], [0, photo.height]
];
const dstCorners = [
  [150, 100], [350, 120],
  [340, 350], [160, 330]
];
face.stampAt(photo, dstCorners.map(([x,y]) => ({x, y})));

Siehe demo_cube.js und demo_drum.js in den Beispielen für vollständige 3D-Projektions-Implementierungen mit Lambertian-Shading.