Benchmark tools#

Audience: developers + performance-minded users
Time: 10–25 minutes
What you’ll learn:

  • How to run the built-in synthetic rendering benchmark

  • How to interpret the metrics (FPS, frame time, GPU memory, LOD)

  • How to use “Copy Situation Report” for bug reports and regressions

  • What this benchmark does not measure (and how to benchmark those separately)

Prerequisites:

  • Cellucid open in a current stable desktop release of Chrome, Edge, Firefox, or Safari with WebGL2 enabled

Where the benchmark lives (UI location)#

Open:

  • Left sidebar → Performance Benchmark accordion

It includes:

  • quick presets (100K → 20M points),

  • a custom point count input,

  • synthetic “data patterns” (clusters, batch effects, atlas-like, etc.),

  • a Load Synthetic Data button,

  • live stats (FPS, frame time, GPU memory, LOD),

  • a Copy Situation Report button,

  • and an Analyze Performance tool that suggests what to change.

Important

The synthetic benchmark loads synthetic data into the viewer.

Use it when:

  • you want to test rendering limits without needing a real dataset, or

  • you want to compare hardware/browser builds.

Do not use it to benchmark:

  • real dataset loading,

  • gene expression fetching,

  • analysis runtime,

  • or figure export.

For those, use Benchmarking methodology and metrics.

What this benchmark measures (and why it’s useful)#

This benchmark is primarily a rendering stress test:

  • how many points your GPU can render smoothly,

  • how well LOD/frustum culling helps,

  • and how GPU memory scales with point count.

It is especially useful for answering questions like:

  • “Can this laptop handle a 1M-cell dataset interactively?”

  • “Did a renderer change reduce FPS on the same machine?”

  • “Is the bottleneck likely GPU vs CPU?”

Quick start (3 minutes)#

  1. Open Performance Benchmark in the left sidebar.

  2. Click a preset like 500K or 1M.

  3. Click Load Synthetic Data.

  4. Orbit/pan/zoom for ~10 seconds and watch:

    • FPS

    • Frame Time

    • GPU Memory

  5. If it feels slow, click Analyze Performance and read the “What to do” list.

If you want a copy/paste summary for a bug report, click Copy Situation Report.

Data patterns (how to choose)#

The pattern dropdown controls the spatial distribution of synthetic points.

Practical guidance:

  • Uniform Random: worst-case for LOD/frustum culling (points everywhere).

  • Gaussian Clusters: closer to “clustered embedding” intuition.

  • Batch Effects / Atlas-like: useful for “many groups across space” intuition.

  • Flat UMAP: approximates a dense 2D manifold style.

If you are testing rendering limits, Uniform Random is often the harshest. If you are testing realistic single-cell scenes, Clusters/Atlas-like are usually more representative.

How to interpret the stats#

FPS and frame time#

  • 60 FPS is the “smooth” target on most displays.

  • Frame Time is usually shown in milliseconds:

    • 16.7ms/frame ≈ 60 FPS

    • 33ms/frame ≈ 30 FPS

Interpretation:

  • If FPS drops as you increase point count: you’re hitting a GPU throughput limit.

  • If FPS is unstable with long spikes (high p95/max frame time): you are seeing “jank” (stutters).

GPU memory#

GPU memory is the main predictor of “WebGL context lost” on large datasets.

Interpretation:

  • If GPU memory climbs close to your GPU’s limit, you can see context loss.

  • If memory is fine but FPS is low, you’re compute/pixel-bound rather than memory-bound.

LOD level and visible points#

LOD exists to reduce the number of rendered points when zoomed out.

Interpretation:

  • If LOD reduces visible points and FPS improves, the renderer is successfully adapting.

  • If visible points stays high and FPS stays low, you may need:

    • LOD enabled in Visualization, or

    • fewer views/pixels, or

    • lower shader quality.

Related docs:

“Copy Situation Report” (use this for bug reports)#

The Copy Situation Report button is meant to produce a compact block of text you can paste into:

  • a GitHub issue,

  • a performance regression note,

  • or a lab internal thread.

Best practice:

  • include the report and your scenario description (“what I was doing when it was slow”).

If you’re filing an issue, follow Reporting performance bugs.

“Analyze Performance” (why is it slow?)#

The Analyze Performance button runs a short measurement and produces:

  • a verdict (e.g., “GPU-limited”, “pixel-bound”, etc.),

  • a list of detected problems,

  • and a prioritized “What to do” checklist.

Use it as a triage assistant:

  • If it says “pixel-bound”: reduce window size and/or reduce view count.

  • If it says “shader overhead”: lower shader quality.

  • If it says “LOD overhead”: enable LOD and avoid forcing high LOD levels.

Safety notes and footguns#

  • Synthetic benchmark data is not your real dataset. Reload the page to restore your original data.

  • Don’t start with 20M points on a laptop. Ramp up: 100K → 500K → 1M → 5M.

  • If you hit “WebGL context lost”, reduce point count and/or reduce GPU load (fewer views, smaller window).

Next steps#