Add LOD generation to pointclouds

.gitignore

@@ -28,6 +28,7 @@ draw-server
 docs/public/playground
 docs/src/content/docs/api/*.md
 viamrobotics-motion-tools-*.tgz
+.wireit
 
 # Logs
 *-debug.log*

src/lib/attribute.ts

@@ -1,8 +1,9 @@
 import { BufferAttribute, BufferGeometry } from 'three'
 
-import type { Metadata } from './metadata'
-
+import { ColorFormat } from './buf/draw/v1/metadata_pb'
 import { colorStride, STRIDE } from './buffer'
+import type { LODLevel } from './loaders/pcd/messages'
+import type { Metadata } from './metadata'
 
 export const createBufferGeometry = (positions: Float32Array, metadata?: Metadata) => {
 	const geometry = new BufferGeometry()
@@ -20,6 +21,43 @@
 	return geometry
 }
 
+export interface LODGeometryLevel {
+	geometry: BufferGeometry
+	distance: number
+}
+
+export const createLODGeometries = (levels: LODLevel[]): LODGeometryLevel[] => {
+	return levels.map((level) => ({
+		geometry: createBufferGeometry(level.positions, {
+			colors: level.colors ?? undefined,
+			colorFormat: ColorFormat.RGB,
+		}),
+		distance: level.distance,
+	}))
+}
+
+export const updateLODGeometries = (
+	existing: LODGeometryLevel[],
+	levels: LODLevel[]
+): LODGeometryLevel[] => {
+	if (existing.length !== levels.length) {
+		for (const { geometry } of existing) {
+			geometry.dispose()
+		}
+		return createLODGeometries(levels)
+	}
+
+	for (let i = 0; i < levels.length; i++) {
+		updateBufferGeometry(existing[i]!.geometry, levels[i]!.positions, {
+			colors: levels[i]!.colors ?? undefined,
+			colorFormat: ColorFormat.RGB,
+		})
+		existing[i]!.distance = levels[i]!.distance
+	}
+
+	return existing
+}
+
 export const updateBufferGeometry = (
 	geometry: BufferGeometry,
 	positions: Float32Array,

src/lib/components/Entities/Points.svelte

@@ -3,7 +3,8 @@
 	import type { Snippet } from 'svelte'
 
 	import { T, useTask, useThrelte } from '@threlte/core'
-	import { OrthographicCamera, Points, PointsMaterial } from 'three'
+	import { Detailed } from '@threlte/extras'
+	import { LOD, OrthographicCamera, Points, PointsMaterial } from 'three'
 
 	import { asColor, isSingleColor } from '$lib/buffer'
 	import { traits, useTrait } from '$lib/ecs'
@@ -23,10 +24,11 @@
 
 	const worldMatrix = useTrait(() => entity, traits.WorldMatrix)
 	const geometry = useTrait(() => entity, traits.BufferGeometry)
+	const lodData = useTrait(() => entity, traits.PointCloudLOD)
+	const opacity = useTrait(() => entity, traits.Opacity)
 	const entityColor = useTrait(() => entity, traits.Color)
 	const colors = useTrait(() => entity, traits.Colors)
 	const entityPointSize = useTrait(() => entity, traits.PointSize)
-	const opacity = useTrait(() => entity, traits.Opacity)
 	const invisible = useTrait(() => entity, traits.InheritedInvisible)
 	const renderOrder = useTrait(() => entity, traits.RenderOrder)
 	const materialProps = useTrait(() => entity, traits.Material)
@@ -35,12 +37,22 @@
 		entityPointSize.current ? entityPointSize.current * 0.001 : settings.current.pointSize
 	)
 	const orthographic = $derived(settings.current.cameraMode === 'orthographic')
+	const hasLOD = $derived(lodData.current !== undefined && lodData.current.levels.length > 0)
 
 	const points = new Points()
 	points.matrixAutoUpdate = false
 	const material = points.material as PointsMaterial
 	material.toneMapped = false
 
+	let lodRef = $state<LOD>()
+
+	const lodPoints = $derived(
+		lodData.current?.levels.map((level) => ({
+			points: new Points(level.geometry, material),
+			distance: level.distance,
+		})) ?? []
+	)
+
 	$effect.pre(() => {
 		material.size = pointSize
 	})
@@ -95,8 +107,10 @@
 
 	$effect.pre(() => {
 		if (worldMatrix.current) {
-			points.matrix.copy(worldMatrix.current)
-			points.updateMatrixWorld()
+			const target = hasLOD && lodRef ? lodRef : points
+			target.matrixAutoUpdate = false
+			target.matrix.copy(worldMatrix.current)
+			target.updateMatrixWorld()
 		}
 	})
 
@@ -121,7 +135,25 @@
 	})
 </script>
 
-{#if geometry.current}
+{#if hasLOD}
+	<Detailed
+		bind:ref={lodRef}
+		name={entity}
+		visible={invisible.current !== true}
+		renderOrder={renderOrder.current}
+		{...events}
+	>
+		{#each lodPoints as { points: childPoints, distance } (childPoints)}
+			<T
+				is={childPoints}
+				{distance}
+				bvh={{ maxDepth: 40, maxLeafSize: 20 }}
+			/>
+		{/each}
+
+		{@render children?.()}
+	</Detailed>
+{:else if geometry.current}
 	<T
 		is={points}
 		name={entity}

src/lib/ecs/traits.ts

@@ -4,7 +4,7 @@
 import { type Entity, trait } from 'koota'
 import { Matrix4, BufferGeometry as ThreeBufferGeometry } from 'three'
 
-import { createBufferGeometry, updateBufferGeometry } from '$lib/attribute'
+import { createBufferGeometry, updateBufferGeometry, type LODGeometryLevel } from '$lib/attribute'
 import { ColorFormat } from '$lib/buf/draw/v1/metadata_pb'
 import { createBox, createCapsule, createSphere } from '$lib/geometry'
 import { parsePcdInWorker } from '$lib/loaders/pcd'
@@ -172,6 +172,11 @@
 
 export const BufferGeometry = trait(() => new ThreeBufferGeometry())
 
+export const PointCloudLOD = trait(() => ({
+	levels: [] as LODGeometryLevel[],
+	diagonal: 0,
+}))
+
 export const GLTF = trait(() => ({
 	source: { url: '' } as { url: string } | { gltf: ThreeGltf } | { glb: Uint8Array },
 	animationName: '',

src/lib/hooks/usePointclouds.svelte.ts

@@ -1,4 +1,4 @@
-import type { Entity } from 'koota'
+import type { ConfigurableTrait, Entity } from 'koota'
 
 import { CameraClient } from '@viamrobotics/sdk'
 import {
@@ -8,11 +8,16 @@ import {
 } from '@viamrobotics/svelte-sdk'
 import { getContext, setContext, untrack } from 'svelte'
 
-import { createBufferGeometry, updateBufferGeometry } from '$lib/attribute'
+import {
+	createBufferGeometry,
+	createLODGeometries,
+	updateBufferGeometry,
+	updateLODGeometries,
+} from '$lib/attribute'
 import { ColorFormat } from '$lib/buf/draw/v1/metadata_pb'
 import { RefetchRates } from '$lib/components/overlay/RefreshRate.svelte'
 import { hierarchy, traits, useWorld } from '$lib/ecs'
-import { parsePcdInWorker } from '$lib/loaders/pcd'
+import { parsePcdWithLOD } from '$lib/loaders/pcd'
 import { useLogs } from '$lib/plugins'
 
 import { useEnvironment } from './useEnvironment.svelte'
@@ -141,37 +146,73 @@ export const providePointclouds = (partID: () => string) => {
 					}
 				}
 
-				parsePcdInWorker(data)
-					.then(({ positions, colors }) => {
+				parsePcdWithLOD(data)
+					.then(({ levels, boundingBoxDiagonal }) => {
 						if (disposed) {
 							return
 						}
 
 						const existing = entities.get(queryKey)
+						const finest = levels.find((l) => l.level === 0) ?? levels[0]!
 						const metadata = {
-							colors,
+							colors: finest.colors ?? undefined,
 							colorFormat: ColorFormat.RGB,
 						}
 
 						if (existing) {
 							hierarchy.setParent(existing, name)
 							const geometry = existing.get(traits.BufferGeometry)
+							const existingLOD = existing.get(traits.PointCloudLOD)
 
 							if (geometry) {
-								updateBufferGeometry(geometry, positions, metadata)
-								return
+								updateBufferGeometry(geometry, finest.positions, metadata)
+							}
+
+							if (levels.length > 1) {
+								if (existingLOD) {
+									// Update geometry buffers in place without setting the trait
+									// to avoid triggering re-renders and component remounts.
+									// BVH is not recomputed here — it drifts slightly between
+									// frames but avoids expensive main-thread recomputation.
+									existingLOD.levels = updateLODGeometries(existingLOD.levels, levels)
+									existingLOD.diagonal = boundingBoxDiagonal
+								} else {
+									existing.add(
+										traits.PointCloudLOD({
+											levels: createLODGeometries(levels),
+											diagonal: boundingBoxDiagonal,
+										})
+									)
+								}
+							} else if (existingLOD) {
+								for (const { geometry } of existingLOD.levels) {
+									geometry.dispose()
+								}
+								existing.remove(traits.PointCloudLOD)
 							}
+
+							return
 						}
 
-						const geometry = createBufferGeometry(positions, metadata)
+						const geometry = createBufferGeometry(finest.positions, metadata)
 
-						const entity = world.spawn(
+						const entityTraits: ConfigurableTrait[] = [
 							...hierarchy.parentTraits(name),
 							traits.Name(`${name} pointcloud`),
 							traits.BufferGeometry(geometry),
-							traits.Points
-						)
+							traits.Points,
+						]
+
+						if (levels.length > 1) {
+							entityTraits.push(
+								traits.PointCloudLOD({
+									levels: createLODGeometries(levels),
+									diagonal: boundingBoxDiagonal,
+								})
+							)
+						}
 
+						const entity = world.spawn(...entityTraits)
 						entities.set(queryKey, entity)
 					})
 					.catch((error) => {