Polish iso-level UX: viridis ramp, quantile default, iso sweep

- **Viridis color ramp** (`color-ramp.ts`): replaces the previous ad-hoc
  4-stop ramp with a perceptually-uniform 5-stop viridis sequence
  (purple → blue → teal → green → yellow). Matches the slice preview
  colormap so iso-level sweeps feel coherent with the 2D view.
- **Default iso at 95th percentile** (`App.tsx`): previous default of
  `mean + 2σ` sometimes clipped below meaningful density for highly
  skewed distributions. Now uses the pre-computed quantile table
  directly; still falls back to mean+2σ if quantiles aren't ready yet.
- **Iso sweep animation** (`Shift+I`): 4-second ease-in-out cycle
  through the full quantile range. Uses `requestAnimationFrame` + the
  `densityQuantiles` lookup so each frame advances to a valid density
  value. Re-pressing cancels mid-animation. Feels butter-smooth in GPU
  mode; CPU mode keeps up at lower frame rates.
- **Centralized quantile utilities**: `quantileToDensity` moved from
  `Controls.tsx` into `color-ramp.ts` (co-located with
  `densityToQuantile`) and re-exported from `@elvis/core`.

Author: ryan-williams

pkgs/core/src/components/Controls.tsx

@@ -1,4 +1,5 @@
 import { getElement } from '../utils/elements.ts'
+import { densityToQuantile, quantileToDensity } from '../utils/color-ramp.ts'
 import styles from './Controls.module.css'
 
 const ResetIcon = () => (
@@ -78,34 +79,6 @@ function fmtAngle(n: number): string {
   return s.endsWith('.0') ? s.slice(0, -2) : s
 }
 
-/** Convert a density value to its quantile position in [0, 1] via binary search. */
-function densityToQuantile(v: number, qs: Float32Array): number {
-  let lo = 0, hi = qs.length - 1
-  while (lo < hi) {
-    const mid = (lo + hi) >> 1
-    if (qs[mid] < v) lo = mid + 1
-    else hi = mid
-  }
-  // Refine between adjacent quantiles for smooth inverse
-  if (lo > 0 && qs[lo] > v) {
-    const span = qs[lo] - qs[lo - 1]
-    const frac = span > 0 ? (v - qs[lo - 1]) / span : 0
-    return (lo - 1 + frac) / (qs.length - 1)
-  }
-  return lo / (qs.length - 1)
-}
-
-/** Convert a quantile position in [0, 1] to a density value via linear interp. */
-function quantileToDensity(q: number, qs: Float32Array): number {
-  const n = qs.length
-  if (q <= 0) return qs[0]
-  if (q >= 1) return qs[n - 1]
-  const pos = q * (n - 1)
-  const i = Math.floor(pos)
-  const frac = pos - i
-  return qs[i] * (1 - frac) + qs[Math.min(n - 1, i + 1)] * frac
-}
-
 export function Controls({
   isoLevel,
   defaultIsoLevel,

pkgs/core/src/components/VolumeRenderer.tsx

@@ -179,7 +179,8 @@ void main() {
   // But simpler: just use the fracNormal direction in world space via the inverse transform
   vec3 worldNormal = normalize((inverse(uCartToFrac) * vec4(fracNormal, 0.0)).xyz);
 
-  // Lighting (Blinn-Phong)
+  // Blinn-Phong lighting (single directional + ambient). Matching the
+  // scene's three-light rig and getting CPU parity is follow-up work.
   vec3 lightDir = normalize(vec3(0.5, 1.0, 0.8));
   float diffuse = max(dot(worldNormal, lightDir), 0.0);
   float ambient = 0.3;

pkgs/core/src/index.ts

@@ -19,7 +19,7 @@ export { parsePymatgenChgcar } from './parsers/pymatgen-chgcar.ts'
 // Utils
 export { marchingCubes, extendPeriodicGrid } from './utils/marching-cubes.ts'
 export { fracToCart, latticeToMatrix4, cellVolume, unitCellEdges, unitCellBoundingBox } from './utils/lattice.ts'
-export { sampleRamp, densityToQuantile, DEFAULT_RAMP } from './utils/color-ramp.ts'
+export { sampleRamp, densityToQuantile, quantileToDensity, DEFAULT_RAMP } from './utils/color-ramp.ts'
 export type { ColorStop, SampledColor } from './utils/color-ramp.ts'
 export { computeTiles, atomOpacity, distFromPrimaryCell } from './utils/tiling.ts'
 export type { TileInfo } from './utils/tiling.ts'

pkgs/core/src/utils/color-ramp.ts

@@ -13,12 +13,18 @@ export interface ColorStop {
   opacity: number
 }
 
-/** Default ramp: diffuse cool → dense hot, mimicking a "charge temperature". */
+/**
+ * Default ramp: a viridis-like perceptual sequence. Low-quantile (diffuse)
+ * iso surfaces appear purple/blue with low opacity; high-quantile (tight
+ * atomic-core) surfaces appear yellow-green with higher opacity. Viridis is
+ * perceptually uniform and colorblind-friendly.
+ */
 export const DEFAULT_RAMP: ColorStop[] = [
-  { q: 0.0, color: [0.15, 0.25, 0.85], opacity: 0.25 },
-  { q: 0.5, color: [0.20, 0.70, 0.95], opacity: 0.50 },
-  { q: 0.9, color: [0.95, 0.80, 0.30], opacity: 0.75 },
-  { q: 1.0, color: [1.00, 0.40, 0.25], opacity: 0.90 },
+  { q: 0.0, color: [0.267, 0.004, 0.329], opacity: 0.22 }, // dark purple
+  { q: 0.25, color: [0.229, 0.322, 0.546], opacity: 0.38 }, // blue
+  { q: 0.5, color: [0.128, 0.567, 0.551], opacity: 0.55 }, // teal
+  { q: 0.75, color: [0.369, 0.788, 0.383], opacity: 0.72 }, // green
+  { q: 1.0, color: [0.993, 0.906, 0.144], opacity: 0.88 }, // yellow
 ]
 
 export interface SampledColor {
@@ -49,6 +55,17 @@ export function sampleRamp(stops: ColorStop[], q: number): SampledColor {
   return { color: last.color, opacity: last.opacity }
 }
 
+/** Linear interpolation in a sorted quantile array, q ∈ [0, 1] → density. */
+export function quantileToDensity(q: number, qs: Float32Array): number {
+  const n = qs.length
+  if (q <= 0) return qs[0]
+  if (q >= 1) return qs[n - 1]
+  const pos = q * (n - 1)
+  const i = Math.floor(pos)
+  const frac = pos - i
+  return qs[i] * (1 - frac) + qs[Math.min(n - 1, i + 1)] * frac
+}
+
 /**
  * Binary-search a density value `v` in a sorted quantile array (qs[i] = i/(n-1) quantile),
  * returning a quantile position in [0, 1] with linear refinement between adjacent bins.

pkgs/static/src/App.tsx

@@ -42,6 +42,15 @@ interface LoadedFile {
   filename: string
 }
 
+const DEFAULT_ISO_QUANTILE = 0.95
+
+function computeDefaultIsoFromQuantiles(qs: Float32Array): number {
+  // Quantiles array is sorted; index maps linearly to quantile.
+  const idx = Math.round(DEFAULT_ISO_QUANTILE * (qs.length - 1))
+  return qs[idx]
+}
+
+/** Fallback default when quantile table isn't available (early load). */
 function computeDefaultIsoLevel(data: Float32Array): number {
   let sum = 0
   let sumSq = 0
@@ -481,6 +490,40 @@ export default function App() {
     defaultBindings: ['shift+c'],
     handler: () => setColorByDensity(!colorByDensity),
   })
+  const densityQuantilesRef = useRef<Float32Array | null>(null)
+  const isoSweepRaf = useRef<number | null>(null)
+  useAction('iso:sweep', {
+    label: 'Sweep iso level',
+    description: 'Animate iso from low to high density over ~4s (re-press to cancel)',
+    keywords: ['iso', 'animation', 'sweep', 'density', 'quantile'],
+    group: 'Surface',
+    defaultBindings: ['shift+i'],
+    handler: () => {
+      if (isoSweepRaf.current !== null) {
+        cancelAnimationFrame(isoSweepRaf.current)
+        isoSweepRaf.current = null
+        return
+      }
+      const qs = densityQuantilesRef.current
+      if (!qs) return
+      const durationMs = 4000
+      const t0 = performance.now()
+      const tick = (now: number) => {
+        const elapsed = now - t0
+        const t = elapsed / durationMs
+        if (t >= 1) {
+          setIsoLevel(qs[qs.length - 1])
+          isoSweepRaf.current = null
+          return
+        }
+        const eased = 0.5 - 0.5 * Math.cos(Math.PI * t)
+        const idx = Math.round(eased * (qs.length - 1))
+        setIsoLevel(qs[idx])
+        isoSweepRaf.current = requestAnimationFrame(tick)
+      }
+      isoSweepRaf.current = requestAnimationFrame(tick)
+    },
+  })
   useActionPair('iso:step', {
     label: 'Decrease / increase iso level',
     description: 'Adjust isosurface threshold by keyboard step',
@@ -1116,15 +1159,18 @@ export default function App() {
     return max
   }, [primaryFile])
 
-  const defaultIsoLevel = useMemo(() => {
-    if (!primaryFile) return 0
-    return computeDefaultIsoLevel(primaryFile.data.grid.data)
-  }, [primaryFile])
-
   const densityQuantiles = useMemo(() => {
     if (!primaryFile) return null
     return computeDensityQuantiles(primaryFile.data.grid.data)
   }, [primaryFile])
+  densityQuantilesRef.current = densityQuantiles
+
+  const defaultIsoLevel = useMemo(() => {
+    if (!primaryFile) return 0
+    return densityQuantiles
+      ? computeDefaultIsoFromQuantiles(densityQuantiles)
+      : computeDefaultIsoLevel(primaryFile.data.grid.data)
+  }, [primaryFile, densityQuantiles])
 
   const effectiveIsoLevel = useMemo(
     () => Math.max(0, Math.min(isoLevel ?? defaultIsoLevel, maxDensity)),