Merge pull request #198 from CU-ESIIL/codex/add-dynamic-drift-centering-behavior

ttuff · web-flow · commit 04933fc59a6d · 2026-01-09T14:38:53.000-07:00
Add dynamic drift-centering V1 to cube viewer
diff --git a/src/cubedynamics/plotting/cube_viewer.py b/src/cubedynamics/plotting/cube_viewer.py
@@ -25,6 +25,7 @@
     resolve_axis_rig_spec,
 )
 from cubedynamics.utils import _infer_time_y_x_dims
+from cubedynamics.utils.drift_centering import drift_centering_script
 from cubedynamics.plotting.progress import _CubeProgress
 from cubedynamics.plotting.viewer import show_cube_viewer
 from cubedynamics.vase import VasePanel
@@ -297,12 +298,24 @@ def _render_cube_html(
          --cd-axis-tick-l
          --cd-axis-stroke
       */
+      /* Drift centering tuning (DYNAMIC DRIFT CENTERING V1):
+         --cd-drift-max-px: maximum horizontal drift in pixels.
+         --cd-drift-rot-range-deg: rotation range (deg) that maps to full drift.
+         --cd-drift-scale-in: scale that cancels drift when zoomed in.
+         --cd-drift-scale-out: scale that enables full drift when zoomed out.
+         --cd-drift-smoothing: easing factor for motion smoothing.
+      */
       --cd-cube-size: {cube_size_css};
       --cube-size: var(--cd-cube-size);
       --cd-axis-font: clamp(11px, calc(var(--cd-cube-size) * 0.045), 18px);
       --cd-axis-pill-px: clamp(4px, calc(var(--cd-cube-size) * 0.010), 8px);
       --cd-axis-stroke: clamp(2px, calc(var(--cd-cube-size) * 0.006), 4px);
       --cd-axis-tick-l: clamp(10px, calc(var(--cd-cube-size) * 0.035), 18px);
+      --cd-drift-max-px: 220;
+      --cd-drift-rot-range-deg: 55;
+      --cd-drift-scale-in: 1.25;
+      --cd-drift-scale-out: 0.85;
+      --cd-drift-smoothing: 0.18;
       {css_vars}
     }}
     * {{ box-sizing: border-box; }}
@@ -430,6 +443,8 @@ def _render_cube_html(
     .cube-scene {{
       position: relative;
       inset: 0;
+      width: 100%;
+      height: 100%;
       perspective: 950px;
       transform-style: preserve-3d;
       --rot-x: 0rad;
@@ -454,6 +469,12 @@ def _render_cube_html(
       pointer-events: auto;
     }}
 
+    .cd-drift-center-fallback {{
+      --cd-drift-x: 0px;
+      --cd-drift-base-transform: none;
+      transform: translateX(var(--cd-drift-x, 0px)) var(--cd-drift-base-transform, none);
+    }}
+
     .cd-cube {{
       position: absolute;
       inset: 0;
@@ -623,26 +644,28 @@ def _render_cube_html(
     <div class=\"cube-main\">
       <div class=\"cube-inner\">
         <div class=\"cube-container\">
-          <div id=\"cube-wrapper-{viewer_id}\" class=\"cube-wrapper\" style=\"--rot-x: {rot_x_rad:.4f}rad; --rot-y: {rot_y_rad:.4f}rad; --zoom: {zoom};\">
-            <canvas class=\"cube-canvas\" id=\"cube-canvas-{viewer_id}\"></canvas>
-            <div class=\"cube-rotation\" id=\"cube-rotation-{viewer_id}\">
-              {cube_faces_html}
-              {interior_html}
-              {vase_html}
-              {axis_rig_markup}
+          <div class=\"cube-scene\" id=\"cube-scene-{viewer_id}\">
+            <div id=\"cube-wrapper-{viewer_id}\" class=\"cube-wrapper\" style=\"--rot-x: {rot_x_rad:.4f}rad; --rot-y: {rot_y_rad:.4f}rad; --zoom: {zoom};\">
+              <canvas class=\"cube-canvas\" id=\"cube-canvas-{viewer_id}\"></canvas>
+              <div class=\"cube-rotation\" id=\"cube-rotation-{viewer_id}\">
+                {cube_faces_html}
+                {interior_html}
+                {vase_html}
+                {axis_rig_markup}
+              </div>
+              <div class=\"cube-drag-surface\" id=\"cube-drag-{viewer_id}\"></div>
             </div>
-            <div class=\"cube-drag-surface\" id=\"cube-drag-{viewer_id}\"></div>
-          </div>
 
-          <div class=\"axis-label cube-label cube-label-x axis-x-min\">{x_meta.get('min','')}</div>
-          <div class=\"axis-label cube-label cube-label-x axis-x-max\">{x_meta.get('max','')}</div>
-          <div class=\"axis-label cube-label cube-label-y axis-y-min\">{y_meta.get('min','')}</div>
-          <div class=\"axis-label cube-label cube-label-y axis-y-max\">{y_meta.get('max','')}</div>
-          <div class=\"axis-label cube-label cube-label-time axis-t-min\">{time_meta.get('min','')}</div>
-          <div class=\"axis-label cube-label cube-label-time axis-t-max\">{time_meta.get('max','')}</div>
-          <div class=\"axis-label cube-label cube-label-x axis-x-name\">{x_meta.get('name','')}</div>
-          <div class=\"axis-label cube-label cube-label-y axis-y-name\">{y_meta.get('name','')}</div>
-          <div class=\"axis-label cube-label cube-label-time axis-t-name\">{time_meta.get('name','')}</div>
+            <div class=\"axis-label cube-label cube-label-x axis-x-min\">{x_meta.get('min','')}</div>
+            <div class=\"axis-label cube-label cube-label-x axis-x-max\">{x_meta.get('max','')}</div>
+            <div class=\"axis-label cube-label cube-label-y axis-y-min\">{y_meta.get('min','')}</div>
+            <div class=\"axis-label cube-label cube-label-y axis-y-max\">{y_meta.get('max','')}</div>
+            <div class=\"axis-label cube-label cube-label-time axis-t-min\">{time_meta.get('min','')}</div>
+            <div class=\"axis-label cube-label cube-label-time axis-t-max\">{time_meta.get('max','')}</div>
+            <div class=\"axis-label cube-label cube-label-x axis-x-name\">{x_meta.get('name','')}</div>
+            <div class=\"axis-label cube-label cube-label-y axis-y-name\">{y_meta.get('name','')}</div>
+            <div class=\"axis-label cube-label cube-label-time axis-t-name\">{time_meta.get('name','')}</div>
+          </div>
         </div>
       </div>
     </div>
@@ -660,6 +683,7 @@ def _render_cube_html(
   </div>
 
   {axis_rig_meta_block}
+  {drift_centering_script(viewer_id)}
   <script>
     (function() {{
       const viewerId = "{viewer_id}";
diff --git a/src/cubedynamics/utils/drift_centering.py b/src/cubedynamics/utils/drift_centering.py
@@ -0,0 +1,137 @@
+"""Shared HTML/JS helpers for drift centering the cube viewer."""
+
+from __future__ import annotations
+
+
+def drift_centering_script(viewer_id: str | None = None) -> str:
+    """Return the drift-centering script tag for cube viewers."""
+
+    viewer_id_js = f'"{viewer_id}"' if viewer_id else "null"
+    return f"""
+  <script id="cd-drift-center-v1-js">
+    (function() {{
+      // Drift centering defaults (DYNAMIC DRIFT CENTERING V1):
+      // MAX_DRIFT_PX=220, ROT_RANGE_DEG=55, SCALE_IN=1.25, SCALE_OUT=0.85, SMOOTHING=0.18
+      const viewerId = {viewer_id_js};
+      const defaults = {{
+        maxDriftPx: 220,
+        rotRangeDeg: 55,
+        scaleIn: 1.25,
+        scaleOut: 0.85,
+        smoothing: 0.18,
+      }};
+
+      const registry = window.__cdDriftCenterV1 || {{
+        viewers: new Set(),
+        rafId: null,
+      }};
+      window.__cdDriftCenterV1 = registry;
+      window.__cdDriftCenterInstalled = true;
+
+      function readNumber(styles, name, fallback) {{
+        const value = parseFloat(styles.getPropertyValue(name));
+        return Number.isFinite(value) ? value : fallback;
+      }}
+
+      function resolveConfig(root) {{
+        const styles = getComputedStyle(root);
+        return {{
+          maxDriftPx: readNumber(styles, "--cd-drift-max-px", defaults.maxDriftPx),
+          rotRangeDeg: readNumber(styles, "--cd-drift-rot-range-deg", defaults.rotRangeDeg),
+          scaleIn: readNumber(styles, "--cd-drift-scale-in", defaults.scaleIn),
+          scaleOut: readNumber(styles, "--cd-drift-scale-out", defaults.scaleOut),
+          smoothing: readNumber(styles, "--cd-drift-smoothing", defaults.smoothing),
+        }};
+      }}
+
+      function getViewerRoots() {{
+        if (viewerId) {{
+          const root = document.getElementById("cube-figure-" + viewerId);
+          return root ? [root] : Array.from(document.querySelectorAll(".cube-figure"));
+        }}
+        return Array.from(document.querySelectorAll(".cube-figure"));
+      }}
+
+      function applyDrift(state, x) {{
+        if (state.supportsTranslate) {{
+          state.scene.style.translate = `${{x}}px 0px`;
+          return;
+        }}
+        if (!state.fallbackReady) {{
+          const baseTransform = getComputedStyle(state.scene).transform;
+          state.scene.style.setProperty(
+            "--cd-drift-base-transform",
+            baseTransform && baseTransform !== "none" ? baseTransform : "none",
+          );
+          state.scene.classList.add("cd-drift-center-fallback");
+          state.fallbackReady = true;
+        }}
+        state.scene.style.setProperty("--cd-drift-x", `${{x}}px`);
+      }}
+
+      function updateViewer(state) {{
+        const transform = getComputedStyle(state.rotation).transform;
+        const matrix = new DOMMatrixReadOnly(transform === "none" ? undefined : transform);
+        const scale = Math.hypot(matrix.m11, matrix.m12, matrix.m13) || 1;
+        const rotY = Math.atan2(matrix.m13, matrix.m11);
+        const rotDeg = rotY * 180 / Math.PI;
+        const normRot = Math.max(-1, Math.min(1, rotDeg / state.config.rotRangeDeg));
+        const z = Math.max(
+          0,
+          Math.min(
+            1,
+            (scale - state.config.scaleOut) / (state.config.scaleIn - state.config.scaleOut),
+          ),
+        );
+        const strength = 1 - z;
+        state.targetX = -normRot * state.config.maxDriftPx * strength;
+        state.currentX = state.currentX + (state.targetX - state.currentX) * state.config.smoothing;
+        applyDrift(state, state.currentX);
+      }}
+
+      function tick() {{
+        registry.viewers.forEach((state) => {{
+          if (!state.root.isConnected) {{
+            registry.viewers.delete(state);
+            return;
+          }}
+          updateViewer(state);
+        }});
+        if (registry.viewers.size > 0) {{
+          registry.rafId = window.requestAnimationFrame(tick);
+        }} else {{
+          registry.rafId = null;
+        }}
+      }}
+
+      function registerViewer(root) {{
+        if (!root || root.dataset.cdDriftCenterInstalled === "true") return;
+        const rotation = root.querySelector(".cube-rotation");
+        const scene =
+          root.querySelector(".cube-scene")
+          || root.querySelector(".cube-wrapper");
+        if (!rotation || !scene) return;
+        root.dataset.cdDriftCenterInstalled = "true";
+        const state = {{
+          root,
+          rotation,
+          scene,
+          config: resolveConfig(root),
+          currentX: 0,
+          targetX: 0,
+          supportsTranslate: "translate" in document.documentElement.style,
+          fallbackReady: false,
+        }};
+        registry.viewers.add(state);
+        if (!registry.rafId) {{
+          registry.rafId = window.requestAnimationFrame(tick);
+        }}
+      }}
+
+      getViewerRoots().forEach(registerViewer);
+    }})();
+  </script>
+    """
+
+
+__all__ = ["drift_centering_script"]
diff --git a/src/cubedynamics/viewers/cube_viewer.py b/src/cubedynamics/viewers/cube_viewer.py
@@ -12,6 +12,7 @@
 from matplotlib import colormaps
 
 from ..deprecations import warn_deprecated
+from ..utils.drift_centering import drift_centering_script
 
 
 def _infer_dims(da: xr.DataArray) -> Tuple[str, str, str]:
@@ -174,6 +175,7 @@ def write_cube_viewer(
         .replace("__SCALE_X__", f"{scale_x:.6f}")
         .replace("__SCALE_Y__", f"{scale_time:.6f}")
         .replace("__SCALE_Z__", f"{scale_y:.6f}")
+        .replace("__CD_DRIFT_CENTER_JS__", drift_centering_script())
     )
 
     out_path = Path(out_html)
diff --git a/src/cubedynamics/viewers/templates/cube_viewer_template.html b/src/cubedynamics/viewers/templates/cube_viewer_template.html
@@ -93,6 +93,7 @@
     </div>
   </div>
 
+  __CD_DRIFT_CENTER_JS__
   <!-- Minimal embedded three-like renderer (self contained, no CDN) -->
   <script>
     // Utility math helpers
diff --git a/tests/test_cube_viewer_interactivity.py b/tests/test_cube_viewer_interactivity.py
@@ -37,6 +37,7 @@ def test_cube_viewer_emits_interactive_markup(tmp_path):
     assert 'id="cube-rotation-' in html
     assert 'id="cube-drag-' in html
     assert 'id="cube-js-warning-' in html
+    assert 'id="cd-drift-center-v1-js"' in html
     assert 'addEventListener("pointerdown"' in html
     assert 'addEventListener("wheel"' in html
     assert 'passive: false' in html
