feat: add --point-size argument (#44)

Author: vstenby

packages/backend/embedding_atlas/cli.py

@@ -202,6 +202,12 @@ def find_available_port(start_port: int, max_attempts: int = 10, host="localhost
     type=str,
     help="Export the visualization as a standalone web application to the specified ZIP file and exit.",
 )
+@click.option(
+    "--point-size",
+    type=float,
+    default=None,
+    help="Size of points in the embedding view (default: automatically calculated based on density).",
+)
 @click.version_option(version=__version__, package_name="embedding_atlas")
 def main(
     inputs,
@@ -227,6 +233,7 @@ def main(
     port: int,
     enable_auto_port: bool,
     export_application: str | None,
+    point_size: float | None,
 ):
     logging.basicConfig(
         level=logging.INFO,
@@ -314,6 +321,9 @@ def main(
         },
     }
 
+    if point_size is not None:
+        metadata["point_size"] = point_size
+
     if x_column is not None and y_column is not None:
         metadata["columns"]["embedding"] = {
             "x": x_column,

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

@@ -20,6 +20,7 @@
     automaticLabels = false,
     mode = "density",
     minimumDensity = 1 / 16,
+    pointSize = null,
     customTooltip = null,
     customOverlay = null,
     querySelection = null,
@@ -85,4 +86,5 @@
   onViewportState={onViewportState}
   rangeSelection={rangeSelection}
   onRangeSelection={onRangeSelection}
+  userPointSize={pointSize}
 />

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

@@ -66,6 +66,7 @@
     pixelWidth: number,
     pixelHeight: number,
     pixelRatio: number,
+    userPointSize: number | null,
   ) {
     // Convert max density to per unit point (aka., CSS px unit).
     let viewDimension = Math.max(pixelWidth, pixelHeight) / pixelRatio;
@@ -81,8 +82,16 @@
 
     let factor = (Math.min(Math.max((scaleLevel - thresholdLevel) * 2, -1), 1) + 1) / 2;
 
-    let pointSizeAtThreshold = 0.25 / Math.sqrt(maxPointDensity);
-    let pointSize = Math.max(0.2, Math.min(5, pointSizeAtThreshold)) * pixelRatio;
+    let pointSize: number;
+    if (userPointSize != null) {
+      // Use user-provided point size, scaled by pixel ratio
+      pointSize = userPointSize * pixelRatio;
+    } else {
+      // Use automatic calculation based on density
+      let pointSizeAtThreshold = 0.25 / Math.sqrt(maxPointDensity);
+      pointSize = Math.max(0.2, Math.min(5, pointSizeAtThreshold)) * pixelRatio;
+    }
+
     let densityAlpha = 1 - factor;
     let pointsAlpha = 0.5 + factor * 0.5;
 
@@ -160,6 +169,7 @@
     rangeSelection = null,
     defaultViewportState = null,
     viewportState = null,
+    userPointSize = null,
     customTooltip = null,
     customOverlay = null,
     onViewportState = null,
@@ -236,6 +246,7 @@
       pixelWidth,
       pixelHeight,
       pixelRatio,
+      userPointSize,
     ),
   );
   let pointSize = $derived(viewingParams.pointSize);

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

@@ -47,6 +47,7 @@
     automaticLabels = false,
     mode = "density",
     minimumDensity = 1 / 16,
+    pointSize = null,
     customTooltip = null,
     customOverlay = null,
     onViewportState = null,
@@ -412,4 +413,5 @@
     effectiveRangeSelection = v;
     onRangeSelection?.(v);
   }}
+  userPointSize={pointSize}
 />

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

@@ -57,6 +57,9 @@ export interface EmbeddingViewProps {
    */
   minimumDensity?: number | null;
 
+  /** Override the automatically calculated point size. If not specified, point size is calculated based on density. */
+  pointSize?: number | null;
+
   /** A custom renderer to draw the tooltip content. */
   customTooltip?: CustomComponent<HTMLDivElement, { tooltip: DataPoint }> | null;
 

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

@@ -99,6 +99,9 @@ export interface EmbeddingViewMosaicProps {
    * The density is measured as number of points per square points (aka., px in CSS units). */
   minimumDensity?: number | null;
 
+  /** Override the automatically calculated point size. If not specified, point size is calculated based on density. */
+  pointSize?: number | null;
+
   /** A custom renderer to draw the tooltip content. */
   customTooltip?: CustomComponent<HTMLDivElement, { tooltip: DataPoint }> | null;
 

packages/viewer/src/Test.svelte

@@ -4,7 +4,7 @@
 
   import Viewer from "./Viewer.svelte";
 
-  import type { DataColumns, DataSource } from "./data_source.js";
+  import type { ViewerConfig, DataSource } from "./data_source.js";
   import { initializeDatabase } from "./lib/database_utils.js";
 
   export class TestDataSource implements DataSource {
@@ -14,7 +14,7 @@
       this.count = count;
     }
 
-    async initializeCoordinator(coordinator: Coordinator, table: string): Promise<DataColumns> {
+    async initializeCoordinator(coordinator: Coordinator, table: string): Promise<ViewerConfig> {
       await initializeDatabase(coordinator, "wasm");
 
       await coordinator.exec(`

packages/viewer/src/Viewer.svelte

@@ -6,7 +6,7 @@
   import EmbeddingAtlas from "./lib/EmbeddingAtlas.svelte";
   import Spinner from "./lib/Spinner.svelte";
 
-  import type { DataColumns, DataSource } from "./data_source.js";
+  import type { ViewerConfig, DataSource } from "./data_source.js";
   import type { EmbeddingAtlasState } from "./lib/api.js";
   import { systemDarkMode } from "./lib/dark_mode_store.js";
   import { type ExportFormat } from "./lib/mosaic_exporter.js";
@@ -25,7 +25,7 @@
   let error = $state(false);
   let status = $state("Loading...");
   let initialState: any | null = $state.raw(null);
-  let columns: DataColumns | null = $state.raw(null);
+  let columns: ViewerConfig | null = $state.raw(null);
 
   onMount(async () => {
     try {
@@ -71,6 +71,7 @@
       neighborsColumn={columns.neighbors}
       cache={dataSource.cache}
       automaticLabels={true}
+      pointSize={columns.pointSize}
       onExportApplication={dataSource.downloadArchive ? onDownloadArchive : null}
       onExportSelection={dataSource.downloadSelection ? onExportSelection : null}
       onStateChange={debounce(onStateChange, 200)}

packages/viewer/src/backend_data_source.ts

@@ -3,7 +3,7 @@
 import type { Coordinator } from "@uwdata/mosaic-core";
 import * as SQL from "@uwdata/mosaic-sql";
 
-import type { DataColumns, DataSource } from "./data_source.js";
+import type { DataSource, ViewerConfig } from "./data_source.js";
 import { initializeDatabase } from "./lib/database_utils.js";
 import { exportMosaicSelection, filenameForSelection, type ExportFormat } from "./lib/mosaic_exporter.js";
 import { downloadBuffer } from "./lib/utils.js";
@@ -22,13 +22,14 @@ function joinUrl(a: string, b: string) {
 }
 
 interface Metadata {
-  columns: DataColumns;
+  columns: ViewerConfig;
   is_static?: boolean;
   database?: {
     type: "wasm" | "socket" | "rest";
     uri?: string;
     load?: boolean;
   };
+  point_size?: number;
 }
 
 export class BackendDataSource implements DataSource {
@@ -50,7 +51,7 @@ export class BackendDataSource implements DataSource {
     coordinator: Coordinator,
     table: string,
     onStatus: (message: string) => void,
-  ): Promise<DataColumns> {
+  ): Promise<ViewerConfig> {
     let metadata = await this.metadata();
 
     onStatus("Initializing DuckDB...");
@@ -90,7 +91,10 @@ export class BackendDataSource implements DataSource {
       };
     }
 
-    return metadata.columns;
+    return {
+      ...metadata.columns,
+      pointSize: metadata.point_size,
+    };
   }
 
   private async fetchEndpoint(endpoint: string, init?: RequestInit) {

packages/viewer/src/data_source.ts

@@ -12,7 +12,7 @@ export interface Cache {
   set(key: string, value: any): Promise<void>;
 }
 
-export interface DataColumns {
+export interface ViewerConfig {
   /** The column for unique identifiers */
   id: string;
   /** The columns for the embedding view */
@@ -27,6 +27,9 @@ export interface DataColumns {
 
   /** The column for pre-computed nearest neighbors */
   neighbors?: string;
+
+  /** The point size for the embedding view */
+  pointSize?: number;
 }
 
 /** A data source for the viewer */
@@ -36,7 +39,7 @@ export interface DataSource {
     coordinator: Coordinator,
     table: string,
     onStatus: (message: string) => void,
-  ): Promise<DataColumns>;
+  ): Promise<ViewerConfig>;
 
   /** Downloads a zip archive of the dataset plus static assets of the viewer */
   downloadArchive?: () => Promise<void>;