Implement camera frustum culling and enhance 3D rendering features

web/packages/geometry/bench/camera-culling.bench.ts

@@ -0,0 +1,129 @@
+import { performance } from 'node:perf_hooks';
+import { Camera3D, FrustumCuller } from '@axrone/geometry';
+
+interface BenchItem {
+    readonly id: number;
+    readonly bounds: {
+        readonly kind: 'sphere';
+        readonly center: readonly [number, number, number];
+        readonly radius: number;
+    };
+}
+
+interface BenchResult {
+    readonly mode: 'sync' | 'async';
+    readonly durationMs: number;
+    readonly visibleCount: number;
+    readonly opsPerSecond: number;
+}
+
+const parseIntegerArg = (name: string, fallback: number): number => {
+    const prefix = `--${name}=`;
+    const raw = process.argv.find((value) => value.startsWith(prefix));
+    if (!raw) {
+        return fallback;
+    }
+
+    const parsed = Number.parseInt(raw.slice(prefix.length), 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+const itemCount = parseIntegerArg('items', 50000);
+const iterations = parseIntegerArg('iterations', 8);
+const asyncBatchSize = parseIntegerArg('batchSize', 1024);
+
+const camera = Camera3D.perspective({
+    id: 'bench-camera',
+    projection: {
+        kind: 'perspective',
+        verticalFieldOfView: Math.PI / 3,
+        aspectRatio: 16 / 9,
+        near: 0.1,
+        far: 500,
+    },
+    pose: {
+        position: [0, 4, 16],
+        target: [0, 0, 0],
+    },
+});
+
+const createItems = (count: number): BenchItem[] => {
+    const items: BenchItem[] = new Array(count);
+    for (let index = 0; index < count; index += 1) {
+        const ring = index % 2048;
+        const layer = Math.floor(index / 2048);
+        const angle = ring * 0.017453292519943295;
+        const radius = 6 + (ring % 48) * 0.75;
+        const x = Math.cos(angle) * radius;
+        const y = ((layer % 9) - 4) * 1.5;
+        const z = -8 - layer * 0.9 - Math.sin(angle) * radius;
+        items[index] = {
+            id: index,
+            bounds: {
+                kind: 'sphere',
+                center: [x, y, z],
+                radius: 0.6 + (index % 5) * 0.1,
+            },
+        };
+    }
+    return items;
+};
+
+const items = createItems(itemCount);
+const culler = new FrustumCuller<BenchItem>({
+    bounds: (item) => item.bounds,
+    asyncBatchSize,
+});
+
+const runSync = (): BenchResult => {
+    const startedAt = performance.now();
+    for (let iteration = 0; iteration < iterations; iteration += 1) {
+        culler.cull(items, camera.frustum);
+    }
+    const durationMs = performance.now() - startedAt;
+    return {
+        mode: 'sync',
+        durationMs,
+        visibleCount: culler.visible.length,
+        opsPerSecond: (itemCount * iterations * 1000) / durationMs,
+    };
+};
+
+const runAsync = async (): Promise<BenchResult> => {
+    const startedAt = performance.now();
+    for (let iteration = 0; iteration < iterations; iteration += 1) {
+        await culler.cullAsync(items, camera.frustum, {
+            batchSize: asyncBatchSize,
+            scheduler: async () => undefined,
+        });
+    }
+    const durationMs = performance.now() - startedAt;
+    return {
+        mode: 'async',
+        durationMs,
+        visibleCount: culler.visible.length,
+        opsPerSecond: (itemCount * iterations * 1000) / durationMs,
+    };
+};
+
+const printResult = (result: BenchResult): void => {
+    const label = result.mode.padEnd(5, ' ');
+    console.log(
+        `${label} duration=${result.durationMs.toFixed(2)}ms visible=${result.visibleCount} throughput=${result.opsPerSecond.toFixed(0)} items/sec`
+    );
+};
+
+const main = async (): Promise<void> => {
+    console.log(
+        `geometry-culling-benchmark items=${itemCount} iterations=${iterations} batchSize=${asyncBatchSize}`
+    );
+    const syncResult = runSync();
+    const asyncResult = await runAsync();
+    printResult(syncResult);
+    printResult(asyncResult);
+};
+
+void main().catch((error: unknown) => {
+    console.error(error);
+    process.exitCode = 1;
+});

web/packages/geometry/package.json

@@ -16,6 +16,7 @@
         }
     },
     "scripts": {
+        "bench:culling": "tsx --tsconfig ../../tsconfig.json ./bench/camera-culling.bench.ts",
         "build": "rollup -c rollup.config.mjs",
         "clean": "rimraf dist",
         "test": "vitest run"

web/packages/geometry/src/__tests__/camera-frustum-culling.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest';
+import { Camera3D, CameraFrustum, FrustumCuller, createBoundingAabb, createBoundingSphere } from '@axrone/geometry';
+
+describe('camera frustum culling', () => {
+    it('classifies perspective spheres against the view frustum', () => {
+        const camera = Camera3D.perspective({
+            projection: {
+                kind: 'perspective',
+                verticalFieldOfView: Math.PI / 3,
+                aspectRatio: 1,
+                near: 0.1,
+                far: 100,
+            },
+            pose: {
+                position: [0, 0, 0],
+                target: [0, 0, -1],
+            },
+        });
+
+        expect(camera.classify(createBoundingSphere([0, 0, -5], 1))).toBe('inside');
+        expect(camera.classify(createBoundingSphere([5, 0, -5], 0.25))).toBe('outside');
+        expect(camera.classify(createBoundingSphere([0, 0, -0.05], 0.2))).toBe('intersects');
+    });
+
+    it('classifies orthographic boxes against the view frustum', () => {
+        const camera = Camera3D.orthographic({
+            projection: {
+                kind: 'orthographic',
+                left: -2,
+                right: 2,
+                bottom: -2,
+                top: 2,
+                near: 0.1,
+                far: 20,
+            },
+            pose: {
+                position: [0, 0, 5],
+                target: [0, 0, 0],
+            },
+        });
+
+        expect(camera.classify(createBoundingAabb([-1, -1, -1], [1, 1, 1]))).toBe('inside');
+        expect(camera.classify(createBoundingAabb([3, -1, -1], [5, 1, 1]))).toBe('outside');
+    });
+
+    it('serializes and restores camera state without losing classification behavior', () => {
+        const camera = Camera3D.perspective({
+            id: 'main-camera',
+            projection: {
+                kind: 'perspective',
+                verticalFieldOfView: Math.PI / 2,
+                aspectRatio: 16 / 9,
+                near: 0.5,
+                far: 250,
+            },
+            pose: {
+                position: [2, 3, 10],
+                target: [2, 3, 0],
+                up: [0, 1, 0],
+            },
+        });
+
+        const serialized = camera.toJSON();
+        const restored = Camera3D.fromJSON(serialized);
+
+        expect(restored.toJSON()).toEqual(serialized);
+        expect(restored.intersects(createBoundingSphere([2, 3, 1], 1))).toBe(true);
+        expect(restored.intersects(createBoundingSphere([50, 3, 1], 1))).toBe(false);
+    });
+
+    it('reuses culling buffers and tracks overflow without throwing by default', () => {
+        const camera = Camera3D.perspective({
+            projection: {
+                kind: 'perspective',
+                verticalFieldOfView: Math.PI / 3,
+                aspectRatio: 1,
+                near: 0.1,
+                far: 100,
+            },
+            pose: {
+                position: [0, 0, 0],
+                target: [0, 0, -1],
+            },
+        });
+
+        const items = [
+            { id: 'sphere:inside', bounds: createBoundingSphere([0, 0, -4], 0.5) },
+            { id: 'sphere:outside', bounds: createBoundingSphere([10, 0, -4], 0.5) },
+            { id: 'aabb:inside', bounds: createBoundingAabb([-0.5, -0.5, -3], [0.5, 0.5, -2]) },
+        ] as const;
+
+        const culler = new FrustumCuller<typeof items[number]>({
+            bounds: (item) => item.bounds,
+            maxResults: 1,
+            trackClassifications: true,
+        });
+
+        culler.cull(items, camera.frustum);
+
+        expect(culler.visible).toHaveLength(1);
+        expect(culler.stats.visibleCount).toBe(1);
+        expect(culler.stats.overflowed).toBe(true);
+        expect(culler.stats.sphereCount).toBe(2);
+        expect(culler.stats.aabbCount).toBe(1);
+        expect(culler.classifications?.get(items[1])).toBe('outside');
+    });
+
+    it('supports async culling with batched yielding', async () => {
+        const frustum = new CameraFrustum(Camera3D.perspective({
+            projection: {
+                kind: 'perspective',
+                verticalFieldOfView: Math.PI / 3,
+                aspectRatio: 1,
+                near: 0.1,
+                far: 100,
+            },
+            pose: {
+                position: [0, 0, 0],
+                target: [0, 0, -1],
+            },
+        }).viewProjectionMatrix);
+
+        const items = [
+            createBoundingSphere([0, 0, -3], 0.5),
+            createBoundingSphere([0, 0, -30], 0.5),
+            createBoundingSphere([30, 0, -3], 0.5),
+        ];
+        const culler = new FrustumCuller({
+            bounds: (item: (typeof items)[number]) => item,
+            trackClassifications: true,
+        });
+
+        await culler.cullAsync(items, frustum, { batchSize: 1 });
+
+        expect(culler.visible).toHaveLength(2);
+        expect(culler.stats.outsideCount).toBe(1);
+        expect(culler.classifications?.get(items[2])).toBe('outside');
+    });
+});