Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
/*
* Die Rahmung, gerechnet statt betrachtet.
*
* Der Befund, aus dem diese Datei kommt, war ein Bild: ein Walk aus vier
* Symbolen stand als Briefmarke in einem leeren Panel, weil die Wolken-Rahmung
* der Uebernahme eine Untergrenze von 300 Einheiten hat. Was ein Test hier
* beweisen kann und ein Screenshot nicht, ist die Umkehrung: bei der
* gerechneten Entfernung fuellt das Rechteck das Bild bis auf den Rand, und
* zwar unabhaengig davon, wie gross es ist.
*/
import { describe, expect, it } from 'vitest';
import {
FLAT_MIN_ZOOM,
FRAME_MARGIN,
FRAME_MIN_DISTANCE,
containShift,
fitCamera,
flatBounds,
frameDistance,
frameFill,
orthographicZoom,
principalFrame,
} from './camera-frame';
import type { Vector3Like } from './camera-frame';
const FOV = 50;
describe('frameDistance', () => {
it('rahmt ein hohes Rechteck ueber die Hoehe', () => {
const box = { centerX: 0, centerY: 0, width: 100, height: 400 };
const distance = frameDistance(box, FOV, 1.3);
const fill = frameFill(box, distance, FOV, 1.3);
expect(fill.vertical).toBeCloseTo(1 / FRAME_MARGIN, 5);
expect(fill.horizontal).toBeLessThan(fill.vertical);
});
it('rahmt ein breites Rechteck ueber die Breite', () => {
const box = { centerX: 0, centerY: 0, width: 900, height: 100 };
const distance = frameDistance(box, FOV, 1.3);
const fill = frameFill(box, distance, FOV, 1.3);
expect(fill.horizontal).toBeCloseTo(1 / FRAME_MARGIN, 5);
expect(fill.vertical).toBeLessThan(fill.horizontal);
});
it('faehrt fuer ein kleines Bild naeher heran, statt auf einer Untergrenze zu bleiben', () => {
const small = frameDistance({ centerX: 0, centerY: 0, width: 170, height: 150 }, FOV, 1.3);
const large = frameDistance({ centerX: 0, centerY: 0, width: 260, height: 420 }, FOV, 1.3);
expect(small).toBeLessThan(large);
// Genau das war der Befund: die Uebernahme haelt hier 300 Einheiten
// Abstand, egal wie klein das Bild ist.
expect(small).toBeLessThan(300);
});
it('fuellt das Bild in beiden Groessen gleich gut', () => {
for (const box of [
{ centerX: 45, centerY: 0, width: 174, height: 210 },
{ centerX: 90, centerY: 0, width: 264, height: 470 },
]) {
const distance = frameDistance(box, FOV, 1.3);
const fill = frameFill(box, distance, FOV, 1.3);
expect(Math.max(fill.vertical, fill.horizontal)).toBeCloseTo(1 / FRAME_MARGIN, 5);
}
});
it('braucht bei einem breiteren Panel weniger Abstand fuer dieselbe Breite', () => {
const box = { centerX: 0, centerY: 0, width: 600, height: 100 };
expect(frameDistance(box, FOV, 2)).toBeLessThan(frameDistance(box, FOV, 1));
});
it('antwortet auf unsinnige Eingaben mit der Untergrenze statt mit NaN', () => {
const box = { centerX: 0, centerY: 0, width: 0, height: 0 };
expect(frameDistance(box, FOV, 1.3)).toBe(FRAME_MIN_DISTANCE);
expect(frameDistance(box, Number.NaN, Number.NaN)).toBe(FRAME_MIN_DISTANCE);
expect(frameDistance({ centerX: 0, centerY: 0, width: -5, height: -5 }, FOV, 0))
.toBe(FRAME_MIN_DISTANCE);
});
});
/*
* Die zweite Rahmung (W10): die flache Ansicht.
*
* Sie hat mit der ersten nichts gemein ausser dem Rand. Eine orthografische
* Kamera hat keinen Ausschnittkegel, also gibt es hier keine Trigonometrie und
* keine Entfernung: der Ausschnitt ist Pixel je Welteinheit, und mehr nicht.
*/
describe('die flache Ansicht', () => {
const NODES = [
{ x: -100, y: -50 },
{ x: 100, y: 50 },
{ x: 0, y: 0 },
];
it('umschliesst die Punkte in der Ebene und laesst z fallen', () => {
expect(flatBounds(NODES)).toEqual({ centerX: 0, centerY: 0, width: 200, height: 100 });
});
it('rechnet den Mittelpunkt und nicht den Schwerpunkt', () => {
// Drei Punkte links und einer rechts: der Schwerpunkt laege links, das
// umschliessende Rechteck liegt in der Mitte. Gerahmt wird das Bild und
// nicht die Dichte.
expect(flatBounds([{ x: 0, y: 0 }, { x: 1, y: 0 }, { x: 2, y: 0 }, { x: 100, y: 0 }]).centerX)
.toBe(50);
});
it('uebergeht Punkte, die keine Zahlen tragen', () => {
expect(flatBounds([{ x: 0, y: 0 }, { x: Number.NaN, y: 10 }, { x: 10, y: 10 }]))
.toEqual({ centerX: 5, centerY: 5, width: 10, height: 10 });
});
it('ergibt ohne Punkte ein Rechteck ohne Ausdehnung', () => {
expect(flatBounds([])).toEqual({ centerX: 0, centerY: 0, width: 0, height: 0 });
expect(flatBounds([{ x: Number.NaN, y: Number.NaN }]).width).toBe(0);
});
it('nimmt den Zoom der engeren Richtung, damit beide hineinpassen', () => {
const box = { centerX: 0, centerY: 0, width: 200, height: 100 };
// 800 / (200 * 1.12) = 3.571, 400 / (100 * 1.12) = 3.571: hier gleich.
expect(orthographicZoom(box, 800, 400)).toBeCloseTo(800 / (200 * FRAME_MARGIN), 5);
// Ein schmaleres Fenster: die Breite entscheidet.
expect(orthographicZoom(box, 400, 400)).toBeCloseTo(400 / (200 * FRAME_MARGIN), 5);
// Ein niedrigeres Fenster: die Hoehe entscheidet.
expect(orthographicZoom(box, 800, 200)).toBeCloseTo(200 / (100 * FRAME_MARGIN), 5);
});
it('laesst den Rand des Rahmens stehen', () => {
const box = { centerX: 0, centerY: 0, width: 200, height: 100 };
const zoom = orthographicZoom(box, 800, 400);
// Bei diesem Zoom nimmt das Rechteck genau den Bruchteil 1/Rand des
// Bildes ein, also bleibt ringsum Platz.
expect((box.width * zoom) / 800).toBeCloseTo(1 / FRAME_MARGIN, 5);
});
it('antwortet auf unsinnige Eingaben mit der Untergrenze statt mit NaN', () => {
const box = { centerX: 0, centerY: 0, width: 200, height: 100 };
expect(orthographicZoom(box, 0, 400)).toBe(FLAT_MIN_ZOOM);
expect(orthographicZoom(box, 800, 0)).toBe(FLAT_MIN_ZOOM);
expect(orthographicZoom({ centerX: 0, centerY: 0, width: 0, height: 0 }, 800, 400))
.toBe(FLAT_MIN_ZOOM);
expect(orthographicZoom(box, Number.NaN, Number.NaN)).toBe(FLAT_MIN_ZOOM);
});
});
/*
* Die Ausrichtung (W10b, AC5).
*
* Der Befund, aus dem dieser Teil kommt, war wieder ein Bild: "mich nervt, dass
* die Galaxy manchmal einfach flach ist" (Nutzer, 2026-08-30). Eine Wolke, die
* in einer Richtung duenn ist, zeigt einer Kamera in genau dieser Richtung einen
* Strich. Was ein Test hier beweisen kann und ein Screenshot nicht, ist die
* Umkehrung fuer JEDEN Punkt: bei der gerechneten Lage liegt keiner ausserhalb
* des Bildes, und zwar unabhaengig davon, wie die Wolke im Raum liegt und wie
* viele Punkte sie hat.
*/
/** Die Bildkoordinaten eines Punktes, gerechnet wie eine perspektivische Kamera. */
function project(
point: Vector3Like,
fit: { eye: Vector3Like; center: Vector3Like; up: Vector3Like; normal: Vector3Like },
fovDegrees: number,
aspect: number,
): { x: number; y: number; z: number } {
const sub = (a: Vector3Like, b: Vector3Like): Vector3Like =>
({ x: a.x - b.x, y: a.y - b.y, z: a.z - b.z });
const dot = (a: Vector3Like, b: Vector3Like): number => a.x * b.x + a.y * b.y + a.z * b.z;
const cross = (a: Vector3Like, b: Vector3Like): Vector3Like => ({
x: a.y * b.z - a.z * b.y,
y: a.z * b.x - a.x * b.z,
z: a.x * b.y - a.y * b.x,
});
// Dieselbe Basis, die three aus lookAt baut: z zurueck zur Kamera, x =
// up x z, y = z x x.
const zAxis = fit.normal;
const xAxis = cross(fit.up, zAxis);
const yAxis = cross(zAxis, xAxis);
const d = sub(point, fit.eye);
const depth = -dot(d, zAxis);
const half = Math.tan((fovDegrees * Math.PI) / 360);
return {
x: dot(d, xAxis) / (depth * half * aspect),
y: dot(d, yAxis) / (depth * half),
z: depth,
};
}
/** Eine Wolke mit vorgegebener Ausdehnung, gedreht, deterministisch erzeugt. */
function cloud(count: number, extents: [number, number, number], seed = 7): Vector3Like[] {
let state = seed;
const random = (): number => {
state = (state * 1103515245 + 12345) % 2147483648;
return state / 2147483648;
};
// Eine feste Drehung um alle drei Achsen: die Wolke soll NICHT achsenparallel
// liegen, sonst faende die Rechnung ihre Achsen zufaellig richtig.
const angle = 0.6;
const c = Math.cos(angle);
const s = Math.sin(angle);
const points: Vector3Like[] = [];
for (let i = 0; i < count; i += 1) {
const a = (random() - 0.5) * extents[0];
const b = (random() - 0.5) * extents[1];
const g = (random() - 0.5) * extents[2];
// um z, dann um x
const x1 = a * c - b * s;
const y1 = a * s + b * c;
const z1 = g;
points.push({ x: x1, y: y1 * c - z1 * s, z: y1 * s + z1 * c });
}
return points;
}
describe('principalFrame', () => {
it('findet die weiteste und die duennste Richtung einer gedrehten Wolke', () => {
const frame = principalFrame(cloud(2000, [1200, 600, 80]));
expect(frame.counted).toBe(2000);
expect(frame.extents[0]).toBeGreaterThan(frame.extents[1]);
expect(frame.extents[1]).toBeGreaterThan(frame.extents[2]);
// Die Groessenordnungen der Ausdehnungen, nicht ihre exakten Werte: eine
// Zufallswolke fuellt ihren Kasten nicht bis auf den letzten Punkt.
expect(frame.extents[0]).toBeGreaterThan(1000);
expect(frame.extents[2]).toBeLessThan(200);
});
it('steht senkrecht aufeinander und ist rechtshaendig', () => {
const { axes } = principalFrame(cloud(500, [900, 400, 120], 13));
const dot = (a: Vector3Like, b: Vector3Like): number => a.x * b.x + a.y * b.y + a.z * b.z;
expect(dot(axes[0], axes[1])).toBeCloseTo(0, 6);
expect(dot(axes[0], axes[2])).toBeCloseTo(0, 6);
expect(dot(axes[1], axes[2])).toBeCloseTo(0, 6);
const cross = {
x: axes[0].y * axes[1].z - axes[0].z * axes[1].y,
y: axes[0].z * axes[1].x - axes[0].x * axes[1].z,
z: axes[0].x * axes[1].y - axes[0].y * axes[1].x,
};
expect(dot(cross, axes[2])).toBeCloseTo(1, 6);
});
it('gibt fuer dieselbe Wolke zweimal dasselbe Dreibein', () => {
const points = cloud(300, [500, 300, 90], 3);
expect(principalFrame(points)).toEqual(principalFrame([...points]));
});
it('laesst eine flache Zeichnung flach: die duennste Achse ist z', () => {
const flat = [
{ x: 0, y: 0, z: 0 },
{ x: 120, y: 36, z: 0 },
{ x: 240, y: -36, z: 0 },
{ x: 120, y: -72, z: 0 },
];
const frame = principalFrame(flat);
expect(frame.extents[2]).toBeCloseTo(0, 9);
expect(Math.abs(frame.axes[2].z)).toBeCloseTo(1, 9);
});
it('antwortet auf nichts mit den Weltachsen statt mit NaN', () => {
const empty = principalFrame([]);
expect(empty.counted).toBe(0);
expect(empty.extents).toEqual([0, 0, 0]);
expect(empty.axes[2]).toEqual({ x: 0, y: 0, z: 1 });
expect(principalFrame([{ x: Number.NaN, y: 0, z: 0 }]).counted).toBe(0);
});
});
describe('fitCamera', () => {
const ASPECT = 1.42;
/** Die Zusicherung aus AC5, ueber jeden einzelnen Punkt. */
const everyPointInside = (points: Vector3Like[], aspect = ASPECT): number => {
const fit = fitCamera(points, FOV, aspect);
expect(fit).not.toBeNull();
let worst = 1;
for (const point of points) {
const seen = project(point, fit!, FOV, aspect);
expect(seen.z).toBeGreaterThan(0);
expect(Math.abs(seen.x)).toBeLessThanOrEqual(1);
expect(Math.abs(seen.y)).toBeLessThanOrEqual(1);
worst = Math.min(worst, 1 - Math.max(Math.abs(seen.x), Math.abs(seen.y)));
}
return worst;
};
it('haelt jeden Knoten im Bild, mit Rand, bei 76 Knoten', () => {
expect(everyPointInside(cloud(76, [900, 520, 140], 11))).toBeGreaterThan(0.02);
});
it('haelt jeden Knoten im Bild, mit Rand, bei 5000 Knoten', () => {
// Die Groesse der Vorschau, in der der Nutzer sein eigenes Projekt
// indiziert hat (5000 Knoten). Der Deckel des Panels ist dieselbe Zahl.
expect(everyPointInside(cloud(5000, [2400, 1500, 380], 23))).toBeGreaterThan(0.02);
});
it('haelt jeden Knoten im Bild, auch in einem schmalen und in einem breiten Panel', () => {
const points = cloud(800, [1400, 900, 260], 5);
expect(everyPointInside(points, 0.6)).toBeGreaterThan(0.02);
expect(everyPointInside(points, 3.1)).toBeGreaterThan(0.02);
});
it('sieht die duennste Richtung entlang, also auf die groesste Flaeche', () => {
const points = cloud(1200, [1600, 700, 60], 17);
const frame = principalFrame(points);
const fit = fitCamera(points, FOV, ASPECT)!;
const dot = (a: Vector3Like, b: Vector3Like): number => a.x * b.x + a.y * b.y + a.z * b.z;
expect(Math.abs(dot(fit.normal, frame.axes[2]))).toBeCloseTo(1, 6);
// Und die Oben-Richtung ist die zweitweiteste: sonst laege die lange
// Achse der Wolke senkrecht im Bild und braeuchte mehr Abstand.
expect(Math.abs(dot(fit.up, frame.axes[1]))).toBeCloseTo(1, 6);
expect(fit.width).toBeGreaterThan(fit.height);
expect(fit.height).toBeGreaterThan(fit.depth);
});
it('legt die halbe Tiefe auf den Abstand, damit auch die vordere Haelfte passt', () => {
const points = cloud(400, [800, 800, 600], 29);
const fit = fitCamera(points, FOV, ASPECT)!;
const planar = frameDistance(
{ centerX: 0, centerY: 0, width: fit.width, height: fit.height },
FOV,
ASPECT,
);
expect(fit.distance).toBeCloseTo(planar + fit.depth / 2, 6);
});
it('antwortet ohne Punkte mit nichts statt mit einer Kamera im Nirgendwo', () => {
expect(fitCamera([], FOV, ASPECT)).toBeNull();
expect(fitCamera([{ x: Number.NaN, y: Number.NaN, z: Number.NaN }], FOV, ASPECT)).toBeNull();
});
it('steht auf der Wurzel und nicht auf der Mitte, und haelt trotzdem jeden Knoten im Bild', () => {
// Eine Wolke, deren Wurzel am Rand liegt: die Mitte des Kastens ist weit weg.
const points = cloud(300, [900, 500, 160], 31).map((point) => ({ x: point.x + 380, y: point.y, z: point.z }));
const root = { x: 0, y: 0, z: 0 };
const fit = fitCamera([...points, root], FOV, ASPECT, FRAME_MARGIN, root)!;
expect(fit.center).toEqual(root);
const seen = project(root, fit, FOV, ASPECT);
expect(Math.abs(seen.x)).toBeLessThan(1e-9);
expect(Math.abs(seen.y)).toBeLessThan(1e-9);
for (const point of points) {
const at = project(point, fit, FOV, ASPECT);
expect(at.z).toBeGreaterThan(0);
expect(Math.max(Math.abs(at.x), Math.abs(at.y))).toBeLessThanOrEqual(1);
}
expect(fit.distance).toBeGreaterThan(fitCamera(points, FOV, ASPECT)!.distance);
});
it('steht bei einem einzigen Punkt an der Untergrenze und sieht ihn an', () => {
const fit = fitCamera([{ x: 40, y: -12, z: 5 }], FOV, ASPECT)!;
expect(fit.distance).toBe(FRAME_MIN_DISTANCE);
expect(fit.center).toEqual({ x: 40, y: -12, z: 5 });
});
});
/*
* Das naechste Bild desselben Scopes (Review-Befund G1).
*
* Ein Expand und die Antwort nach einer Vorschau passen nicht neu ein; die
* Kamera tritt entlang ihrer Blickrichtung nur so weit zurueck oder vor, dass
* der aeusserste Knoten mit Rand am Bildrand steht. Gerechnet im Blickraum:
* vor der Kamera ist z negativ.
*/
describe('containShift', () => {
const ASPECT = 1.5;
const half = Math.tan((FOV * Math.PI) / 360);
it('tritt genau so weit zurueck, dass der aeusserste Punkt am Rand steht', () => {
const point = { x: 0, y: 300, z: -200 };
const back = containShift([point], FOV, ASPECT);
expect(back).toBeGreaterThan(0);
expect((point.y * FRAME_MARGIN) / ((200 + back) * half)).toBeCloseTo(1, 6);
});
it('tritt vor, wenn ein kleineres Bild mit viel Rand dasteht', () => {
const points = [{ x: 0, y: 0, z: -400 }, { x: 100, y: -80, z: -500 }];
const shift = containShift(points, FOV, ASPECT);
expect(shift).toBeLessThan(0);
const fills = points.map((point) => Math.max(
(Math.abs(point.x) * FRAME_MARGIN) / ((-point.z + shift) * half * ASPECT),
(Math.abs(point.y) * FRAME_MARGIN) / ((-point.z + shift) * half)));
expect(Math.max(...fills)).toBeCloseTo(1, 6);
});
it('rechnet die Breite mit dem Seitenverhaeltnis und holt auch Punkte hinter der Kamera', () => {
const wide = { x: 600, y: 0, z: -100 };
const back = containShift([wide], FOV, ASPECT);
expect((wide.x * FRAME_MARGIN) / ((100 + back) * half * ASPECT)).toBeCloseTo(1, 6);
expect(containShift([{ x: 0, y: 0, z: 50 }], FOV, ASPECT)).toBeCloseTo(50, 6);
});
it('bleibt ohne brauchbare Punkte stehen, statt NaN zu liefern', () => {
expect(containShift([{ x: Number.NaN, y: 0, z: -1 }], FOV, ASPECT)).toBe(0);
expect(containShift([], FOV, ASPECT)).toBe(0);
});
});