feat: add viewport-dependent density-based downsampling (#118)

Add GPU-accelerated viewport-dependent downsampling to the point cloud renderer. When rendering large datasets, the system automatically reduces the number of rendered points while preserving visual fidelity by biasing the sampling toward dense regions. This unlocks a much higher upper bound for the size of datasets the viewer can work with, in practice.

See #118 for more details.

Author: maxdumas

packages/component/src/demo/EmbeddingViewDemo.svelte

@@ -5,7 +5,7 @@
 
   import EmbeddingView from "../lib/embedding_view/EmbeddingView.svelte";
 
-  let dataset = generateSampleDataset({ numPoints: 500000, numCategories: 3, numSubClusters: 32 });
+  let dataset = generateSampleDataset({ numPoints: 5000000, numCategories: 3, numSubClusters: 32 });
   let data = {
     x: new Float32Array(dataset.map((r) => r.x)),
     y: new Float32Array(dataset.map((r) => r.y)),
@@ -19,6 +19,7 @@
   let mode: "points" | "density" = $state.raw("density");
   let colorScheme: "light" | "dark" = $state.raw("light");
   let minimumDensity: number = $state.raw(1 / 16);
+  let downsampleMaxPoints: number | null = $state.raw(4000000);
   let viewportState: ViewportState | null = $state.raw(null);
 
   async function querySelection(x: number, y: number, unitDistance: number): Promise<DataPoint | null> {
@@ -59,15 +60,37 @@
     </select>
   </label>
 
-  <input type="range" bind:value={minimumDensity} min={0} max={0.2} step={0.0001} />
-  {minimumDensity.toFixed(4)}
+  <label style="display:flex;align-items:center;gap:4px">
+    Min Density:
+    <input type="range" bind:value={minimumDensity} min={0} max={0.2} step={0.0001} />
+    {minimumDensity.toFixed(4)}
+  </label>
+
+  <label style="display:flex;align-items:center;gap:4px">
+    Max Points:
+    {#if downsampleMaxPoints != null}
+      <input type="range" bind:value={downsampleMaxPoints} min={50000} max={50000000} step={50000} />
+      {downsampleMaxPoints >= 1000000
+        ? (downsampleMaxPoints / 1000000).toFixed(1) + "M"
+        : (downsampleMaxPoints / 1000).toFixed(0) + "K"}
+      <button onclick={() => (downsampleMaxPoints = null)}>Disable</button>
+    {:else}
+      <span>Disabled</span>
+      <button onclick={() => (downsampleMaxPoints = 4000000)}>Enable</button>
+    {/if}
+  </label>
 </div>
 
 <div style="display:flex;gap:8px">
   <div style:border="1px solid black">
     <EmbeddingView
       data={data}
-      config={{ mode: mode, colorScheme: colorScheme, minimumDensity: minimumDensity }}
+      config={{
+        mode: mode,
+        colorScheme: colorScheme,
+        minimumDensity: minimumDensity,
+        downsampleMaxPoints: downsampleMaxPoints,
+      }}
       tooltip={tooltip}
       onTooltip={(v) => {
         tooltip = v;

packages/component/src/lib/embedding_view/EmbeddingViewImpl.svelte

@@ -225,6 +225,8 @@
   let userPointSize = $derived(config?.pointSize ?? null);
   let mode = $derived(config?.mode ?? "points");
   let autoLabelEnabled = $derived(config?.autoLabelEnabled);
+  let downsampleMaxPoints = $derived(config?.downsampleMaxPoints ?? 4000000);
+  let downsampleDensityWeight = $derived(config?.downsampleDensityWeight ?? 5);
 
   let viewingParams = $derived(
     viewingParameters(
@@ -256,6 +258,8 @@
       category: data.category,
       categoryCount,
       categoryColors: resolvedCategoryColors,
+      downsampleMaxPoints,
+      downsampleDensityWeight,
       ...viewingParams,
     });
 

packages/component/src/lib/embedding_view/embedding_view_config.ts

@@ -28,4 +28,14 @@ export interface EmbeddingViewConfig {
 
   /** The stop words for automatic label generation. By default use NLTK stop words. */
   autoLabelStopWords?: string[] | null;
+
+  /** Maximum number of points to render when downsampling is active.
+   * Points are sampled with bias toward sparse regions (fewer points kept in dense areas).
+   * Default: 4000000. Set to null or Infinity to disable downsampling. */
+  downsampleMaxPoints?: number | null;
+
+  /** Density weight for downsampling (0-10).
+   * Higher values mean more aggressive culling in dense areas.
+   * Default: 5 */
+  downsampleDensityWeight?: number | null;
 }

packages/component/src/lib/renderer_interface.ts

@@ -32,6 +32,11 @@ export interface EmbeddingRendererProps {
   gamma: number;
   width: number;
   height: number;
+
+  /** Maximum points to render. null/Infinity = no limit. Default: 4000000 */
+  downsampleMaxPoints: number | null;
+  /** Density weight for downsampling (0-10). Default: 5 */
+  downsampleDensityWeight: number;
 }
 
 export interface DensityMap {

packages/component/src/lib/webgl2_renderer/renderer.ts

@@ -61,6 +61,9 @@ export class EmbeddingRendererWebGL2 implements EmbeddingRenderer {
       gamma: 2.2,
       width: width,
       height: height,
+
+      downsampleMaxPoints: 4000000,
+      downsampleDensityWeight: 5,
     };
 
     this.viewport = new Viewport({ x: 0, y: 0, scale: 1 }, width, height);
@@ -81,6 +84,8 @@ export class EmbeddingRendererWebGL2 implements EmbeddingRenderer {
       height: df.value(height),
       pointSize: df.value(this.props.pointSize),
       densityBandwidth: df.value(this.props.densityBandwidth),
+      downsampleMaxPoints: df.value(this.props.downsampleMaxPoints),
+      downsampleDensityWeight: df.value(this.props.downsampleDensityWeight),
     };
     this.dataBuffers = dataBuffers(df, gl, this.renderInputs);
     this.renderer = renderCommand(df, gl, this.renderInputs, this.dataBuffers);
@@ -116,6 +121,8 @@ export class EmbeddingRendererWebGL2 implements EmbeddingRenderer {
     this.renderInputs.height.value = this.props.height;
     this.renderInputs.pointSize.value = this.props.pointSize;
     this.renderInputs.densityBandwidth.value = this.props.densityBandwidth;
+    this.renderInputs.downsampleMaxPoints.value = this.props.downsampleMaxPoints;
+    this.renderInputs.downsampleDensityWeight.value = this.props.downsampleDensityWeight;
     return needsRender;
   }
 
@@ -161,6 +168,8 @@ interface RenderInputs {
   matrix: ValueNode<Matrix3>;
   width: ValueNode<number>;
   height: ValueNode<number>;
+  downsampleMaxPoints: ValueNode<number | null>;
+  downsampleDensityWeight: ValueNode<number>;
 }
 
 interface DataBuffers {

packages/component/src/lib/webgpu_renderer/bind_groups.ts

@@ -16,6 +16,7 @@ export interface BindGroups {
   group2A: Node<GPUBindGroup>;
   group2B: Node<GPUBindGroup>;
   group3: Node<GPUBindGroup>;
+  // Note: group4 for downsampling is managed separately in downsample.ts
 }
 
 export function makeBindGroupLayouts(device: GPUDevice): {