Heatmap legend: density-at-quantile ticks + q toggles free rot

Two related changes:

1. Legend tick labels now show raw density at the quantile
   position of each color band when equalize is on. Voxel
   distribution drives the labels rather than linear-interp of
   [min, max]; e.g. for mp-1000020 the bar now reads
   `3.29 / 9.14 / 19.59 / 52.23 / 3746.6` instead of
   `0 / 936 / 1873 / 2810 / 3746` — accurately reflecting that
   50% of voxels lie below ~20 and only the top ~25% spans
   the heavy-tail to 3746.

   Extracted CDF/quantile logic to `utils/density-quantile.ts`:
   `computeSortedSamples` runs once per volume in
   `DensityViewer`, shared by `HeatmapRenderer` (CDF LUT for the
   shader) and `HeatmapLegend` (`densityAtQuantile` for ticks)
   so colors and labels stay in sync.

2. `q` toggles between `rot=orbit` and `rot=free`. `shift+r`
   still cycles through all three; `q` is the fast-switch for
   the two modes most users will actually pick between.

Author: ryan-williams

pkgs/core/src/components/DensityViewer.tsx

@@ -18,6 +18,7 @@ import type { CameraSnapTarget } from './CameraController.tsx'
 import { SlicePlane3D } from './SlicePlane3D.tsx'
 import { fracToCart } from '../utils/lattice.ts'
 import { computeTiles } from '../utils/tiling.ts'
+import { computeSortedSamples } from '../utils/density-quantile.ts'
 import { volumeMinMax } from '../utils/volume-stats.ts'
 import { HeatmapLegend } from './HeatmapLegend.tsx'
 
@@ -146,6 +147,11 @@ export function DensityViewer({
     return computeTiles(volume.lattice, tilePadding, tileFade)
   }, [volume.lattice, tilePadding, tileFade])
 
+  // Sample-based sorted density distribution. Shared by HeatmapRenderer (CDF
+  // LUT for histogram equalization) and HeatmapLegend (density-at-quantile
+  // ticks) so the colorbar labels and shader colors stay in sync.
+  const sortedSamples = useMemo(() => computeSortedSamples(volume.grid.data), [volume.grid.data])
+
   const center = useMemo(() => {
     const c = fracToCart(volume.lattice, [0.5, 0.5, 0.5])
     return new Vector3(...c)
@@ -193,7 +199,7 @@ export function DensityViewer({
         {glbUrl
           ? <GlbPreviewRenderer url={glbUrl} opacity={surfaceOpacityOverride ?? opacity} color={surfaceColor ?? undefined} />
           : useHeatmap
-            ? <HeatmapRenderer volume={volume} dataMin={dataRange.min} dataMax={dataRange.max} signed={heatmapSigned} opacity={surfaceOpacityOverride ?? heatmapOpacity ?? opacity} gamma={heatmapGamma} lowCutoff={heatmapLowCutoff} stepCount={heatmapStepCount} equalize={heatmapEqualize} clipAtoms={showAtoms} tiles={tiles} tilePadding={tilePadding} tileFade={tileFade} />
+            ? <HeatmapRenderer volume={volume} dataMin={dataRange.min} dataMax={dataRange.max} signed={heatmapSigned} opacity={surfaceOpacityOverride ?? heatmapOpacity ?? opacity} gamma={heatmapGamma} lowCutoff={heatmapLowCutoff} stepCount={heatmapStepCount} equalize={heatmapEqualize} sortedSamples={sortedSamples} clipAtoms={showAtoms} tiles={tiles} tilePadding={tilePadding} tileFade={tileFade} />
             : useGpuVolume
               ? <VolumeRenderer volume={volume} isoLevel={isoLevel} opacity={surfaceOpacityOverride ?? opacity} tiles={tiles} tilePadding={tilePadding} tileFade={tileFade} color={surfaceColor ?? undefined} />
               : <IsosurfaceRenderer volume={volume} isoLevel={isoLevel} opacity={surfaceOpacityOverride ?? opacity} tiles={tiles} tilePadding={tilePadding} tileFade={tileFade} color={surfaceColor ?? undefined} />
@@ -230,6 +236,8 @@ export function DensityViewer({
           gamma={heatmapGamma ?? 2.5}
           lowCutoff={heatmapLowCutoff ?? 0}
           units={heatmapUnits}
+          equalize={heatmapEqualize}
+          sortedSamples={sortedSamples}
         />
       )}
     </div>

pkgs/core/src/components/HeatmapLegend.tsx

@@ -1,5 +1,6 @@
 import { useMemo } from 'react'
 import { turbo, diverging } from '../utils/colormap.ts'
+import { densityAtQuantile } from '../utils/density-quantile.ts'
 
 interface HeatmapLegendProps {
   dataMin: number
@@ -9,6 +10,11 @@ interface HeatmapLegendProps {
   gamma: number
   lowCutoff: number
   units?: string
+  /** When true (and `sortedSamples` provided), tick labels show density at the
+   *  quantile position of the colorbar (so each color band spans equal voxel
+   *  count). When false, ticks are linear interpolation of `[dataMin, dataMax]`. */
+  equalize?: boolean
+  sortedSamples?: Float32Array
 }
 
 const BAR_WIDTH = 22
@@ -25,7 +31,7 @@ function formatValue(v: number): string {
   return v.toFixed(1)
 }
 
-export function HeatmapLegend({ dataMin, dataMax, signed, gamma, lowCutoff, units }: HeatmapLegendProps) {
+export function HeatmapLegend({ dataMin, dataMax, signed, gamma, lowCutoff, units, equalize, sortedSamples }: HeatmapLegendProps) {
   const gradient = useMemo(() => {
     // CSS linear-gradient: bottom (0%, low) → top (100%, high). Alpha follows the
     // shader's `pow(v, gamma)` curve so the legend visually matches the rendering.
@@ -44,12 +50,19 @@ export function HeatmapLegend({ dataMin, dataMax, signed, gamma, lowCutoff, unit
 
   const ticks = useMemo(() => {
     const out: { fraction: number; value: number }[] = []
+    // In equalize mode, each visual fraction `f` corresponds to "voxel at
+    // quantile f" — so tick labels are the raw density at that quantile.
+    // In linear mode, labels are the linear interpolation across [min, max].
+    const useQuantile = equalize && sortedSamples && !signed
     for (let i = 0; i < N_TICKS; i++) {
       const fraction = i / (N_TICKS - 1)
-      out.push({ fraction, value: dataMin + fraction * (dataMax - dataMin) })
+      const value = useQuantile
+        ? densityAtQuantile(sortedSamples, fraction)
+        : dataMin + fraction * (dataMax - dataMin)
+      out.push({ fraction, value })
     }
     return out
-  }, [dataMin, dataMax])
+  }, [dataMin, dataMax, equalize, sortedSamples, signed])
 
   return (
     <div

pkgs/core/src/components/HeatmapRenderer.tsx

@@ -9,6 +9,7 @@ import type { VolumeData } from '../types.ts'
 import { fracToCart } from '../utils/lattice.ts'
 import { getElement } from '../utils/elements.ts'
 import type { TileInfo } from '../utils/tiling.ts'
+import { buildCDFLUT, identityLUT } from '../utils/density-quantile.ts'
 
 interface HeatmapRendererProps {
   volume: VolumeData
@@ -35,6 +36,10 @@ interface HeatmapRendererProps {
    *  density linear mapping (legacy behavior). Unsigned mode only; signed
    *  (diff) keeps its diverging mapping. */
   equalize?: boolean
+  /** Sorted samples of raw density values (pre-computed in `DensityViewer`
+   *  via `computeSortedSamples`). Shared with `HeatmapLegend` so tick labels
+   *  match the equalized colormap exactly. */
+  sortedSamples?: Float32Array
   /**
    * When true (default), terminate rays that enter an atom sphere. Prevents glow from
    * accumulating past atoms (visible artifact when atoms are opaque). Set false to render
@@ -263,36 +268,9 @@ void main() {
 }
 `
 
-/** Build a 256-entry CDF LUT from the raw density samples. Maps normalized val
- *  in [0, 1] to its quantile position. Sample-based for perf (deterministic
- *  stride; LUT depends only on `data` and the [dataMin, dataMax] window). */
-function computeCDFLUT(data: Float32Array, dataMin: number, dataMax: number, lutSize = 256, sampleTarget = 16384): Float32Array {
-  const range = dataMax - dataMin || 1
-  const stride = Math.max(1, Math.floor(data.length / sampleTarget))
-  const nSamples = Math.floor(data.length / stride)
-  const samples = new Float32Array(nSamples)
-  for (let i = 0, j = 0; i < nSamples; i++, j += stride) {
-    samples[i] = (data[j] - dataMin) / range
-  }
-  samples.sort()
-  const lut = new Float32Array(lutSize)
-  for (let i = 0; i < lutSize; i++) {
-    const v = i / (lutSize - 1)
-    // Binary search for first sample >= v.
-    let lo = 0, hi = nSamples
-    while (lo < hi) {
-      const mid = (lo + hi) >>> 1
-      if (samples[mid] < v) lo = mid + 1
-      else hi = mid
-    }
-    lut[i] = lo / Math.max(nSamples - 1, 1)
-  }
-  return lut
-}
-
 export function HeatmapRenderer({
   volume, dataMin, dataMax, signed = false, opacity, gamma = 2.5, lowCutoff = 0, stepCount = 256,
-  clipAtoms = true, equalize = true,
+  clipAtoms = true, equalize = true, sortedSamples,
   tiles: _tiles, tilePadding = 0, tileFade = 1,
 }: HeatmapRendererProps) {
   const { camera } = useThree()
@@ -316,19 +294,17 @@ export function HeatmapRenderer({
     return tex
   }, [data, dims, dataMin, dataMax])
 
-  // CDF LUT for histogram equalization. Computed once per dataset; safe to
-  // skip if `equalize=false` (uniform-identity LUT is cheap to keep around).
+  // CDF LUT for histogram equalization. Uses externally-computed sortedSamples
+  // (shared with HeatmapLegend) so tick labels and shader colors stay in sync.
   const lutTexture = useMemo(() => {
-    const lut = equalize ? computeCDFLUT(data, dataMin, dataMax) : (() => {
-      const id = new Float32Array(256)
-      for (let i = 0; i < 256; i++) id[i] = i / 255
-      return id
-    })()
+    const lut = (equalize && sortedSamples)
+      ? buildCDFLUT(sortedSamples, dataMin, dataMax)
+      : identityLUT()
     const tex = new DataTexture(lut, lut.length, 1, RedFormat, FloatType, UVMapping,
       ClampToEdgeWrapping, ClampToEdgeWrapping, LinearFilter, LinearFilter)
     tex.needsUpdate = true
     return tex
-  }, [data, dataMin, dataMax, equalize])
+  }, [sortedSamples, dataMin, dataMax, equalize])
 
   const cartToFrac = useMemo(() => {
     const L = volume.lattice

pkgs/core/src/utils/density-quantile.ts

@@ -0,0 +1,64 @@
+/** Sample-based density-distribution analysis for histogram equalization
+ *  (shader CDF LUT) and the colorbar legend (density-at-quantile ticks). Both
+ *  consume the same sorted-samples array so the legend's tick labels exactly
+ *  correspond to the colors the shader paints. */
+
+/** Stride-sample the volume and return raw density values sorted ascending.
+ *  Cheap to call (~16k samples by default, one sort, no normalization). */
+export function computeSortedSamples(data: Float32Array, sampleTarget = 16384): Float32Array {
+  const stride = Math.max(1, Math.floor(data.length / sampleTarget))
+  const n = Math.max(1, Math.floor(data.length / stride))
+  const samples = new Float32Array(n)
+  for (let i = 0, j = 0; i < n && j < data.length; i++, j += stride) {
+    samples[i] = data[j]
+  }
+  samples.sort()
+  return samples
+}
+
+/** Build a 256-entry CDF LUT from sorted raw-density samples. Maps
+ *  normalized val (in `[0, 1]` over the `[dataMin, dataMax]` window) to its
+ *  quantile position in the empirical distribution. */
+export function buildCDFLUT(
+  sortedSamples: Float32Array,
+  dataMin: number,
+  dataMax: number,
+  lutSize = 256,
+): Float32Array {
+  const range = dataMax - dataMin || 1
+  const lut = new Float32Array(lutSize)
+  const n = sortedSamples.length
+  for (let i = 0; i < lutSize; i++) {
+    const v = i / (lutSize - 1)
+    const rawV = v * range + dataMin
+    let lo = 0, hi = n
+    while (lo < hi) {
+      const mid = (lo + hi) >>> 1
+      if (sortedSamples[mid] < rawV) lo = mid + 1
+      else hi = mid
+    }
+    lut[i] = lo / Math.max(n - 1, 1)
+  }
+  return lut
+}
+
+/** Identity LUT — used when histogram equalization is disabled. */
+export function identityLUT(lutSize = 256): Float32Array {
+  const lut = new Float32Array(lutSize)
+  for (let i = 0; i < lutSize; i++) lut[i] = i / (lutSize - 1)
+  return lut
+}
+
+/** Density value at the given quantile position `q ∈ [0, 1]` in the
+ *  sorted-samples distribution. Linear interpolation between adjacent samples. */
+export function densityAtQuantile(sortedSamples: Float32Array, q: number): number {
+  const n = sortedSamples.length
+  if (n === 0) return 0
+  if (q <= 0) return sortedSamples[0]
+  if (q >= 1) return sortedSamples[n - 1]
+  const idx = q * (n - 1)
+  const lo = Math.floor(idx)
+  const hi = Math.min(lo + 1, n - 1)
+  const t = idx - lo
+  return sortedSamples[lo] * (1 - t) + sortedSamples[hi] * t
+}

pkgs/static/src/App.tsx

@@ -1113,6 +1113,14 @@ export default function App() {
       setRotMode(next)
     },
   })
+  useAction('nav:toggle-quat-rot', {
+    label: 'Toggle quaternion rotation',
+    description: 'Toggle between orbit (default) and free (quaternion) rotation mode',
+    keywords: ['rotate', 'rotation', 'quaternion', 'free', 'pole', 'q'],
+    group: 'Camera',
+    defaultBindings: ['q'],
+    handler: () => setRotMode(rotMode === 'free' ? 'orbit' : 'free'),
+  })
 
   // Auto-restore on mount: ?m= param (OPFS cache → fetch) or last active OPFS volume
   const initialMaterialId = useRef(materialId)