Closed bug report

Underside orbit stops near flat bottom view: asymmetric beta limits restrict tilt

Ray · ·closed by Colby Knox

Environment

Observed 2026-09-14 on Windows desktop, local molecule preview consuming the shared adom-3d-viewer-babylon9 ESM from wiki static/vendor. Runtime Babylon version: 9.5.0. Discoverable owning package: adom/adom-3d-viewer 0.7.0; static bundle package version not independently established. Board: STM32F411RET6 raw TSCI detailed GLB, Y-up, zUp:false. tscircuit 0.0.2516; CLI 0.1.2057. Pup is only the inspection transport, not an established cause.

Reproduction / user observation

  1. Load the F411 model in the shared viewer (our consumer is compact-preview.html?board=stm32f411ret6&group=mcu-self-contained).
  2. Orbit to the underside so the bottom markings read upright.
  3. Try to tilt through a flat bottom view and continue in the other direction.

Ray reports: "upside down seems to only want to tilt in the wrong direction/ won't let me tilt more than flat upwards". Expected: smooth, predictable orbit on both faces, including passage through the bottom pole, rather than an asymmetric stop near flat. Preserve upright front/back presets and the model coordinate-frame contract.

Live camera evidence (read only; no limits changed)

viewer.getCamera() returned:

{"alpha":-4.659872178598141,"beta":2.2824333946640127,"lowerBetaLimit":-100,"upperBetaLimit":3.1315926535897933,"allowUpsideDown":true,"upVector":[0,1,0]}

The upper beta limit equals PI-0.01 while the lower limit is -100. That asymmetry is consistent with reaching a stop near the bottom pole while the top permits further rotation. This is a likely cause, not a completed drag-event/root-cause diagnosis. No runtime exception was observed for the orbit behavior.

Our consumer initializes zUp:false, applies alpha=-PI/2 and beta=.25 for the initial front camera, and does not set beta limits or allowUpsideDown. Please check how the viewer's defaults interact with upside-down orbit/input direction. Regression coverage should exercise dragging across both poles and both raw Y-up / anchored Z-up molecule frames. Prefer an explicit full-orbit option if ground-limited orbit is needed by other consumers.

Attached screenshot is the actual live underside viewport after the report. This is distinct from adom/adom-3d-viewer#4 (view-cube mouse-down animation); the consumer has showViewCube:false. It is also distinct from the resolved adom/logic-molecule-workflows#1 frame-orientation fix and #3 mirrored bottom-text fix. No fix or PR created in this report.

live

3 Replies

Colby Knox ·

Confirmed and fixed, Ray. Your camera dump was the whole diagnosis: the viewer set lowerBetaLimit = -100 and left Babylon's default upperBetaLimit = PI - 0.01. With allowUpsideDown Babylon only wraps beta at the poles when a limit is null, so the orbit could go over the top forever but stopped dead just short of the flat bottom view, and the drag felt reversed there because you were pushing against a clamp.

0.7.1: both beta limits are null. Babylon wraps beta at plus or minus PI, so dragging through a flat bottom (or top) view keeps rotating the same way, in the raw Y-up frame and the anchored Z-up frame alike. Front and back presets and the view cube still land upright; nothing else about the coordinate-frame contract changed. Regression coverage is npm run test:orbit (test/orbit.test.mjs): headless Chrome, real pointer drags across both poles in both frames, asserting no clamp at PI - 0.01, the wrap past the pole, continued motion in the drag's direction, and unset limits.

Where to get it: the wiki's vendored bundle at static/vendor/adom-3d-viewer-babylon9 is 0.7.1 (?v=20260914a) on prod as of tag e0b3927, which is what your compact-preview consumer loads; the package is published as adom/adom-3d-viewer 0.7.1 with the bundle tarball attached as the release asset.

Not done: an explicit ground-limited orbit option. No consumer asked for one; if one does, it goes in as an init option with the full orbit staying the default.

Colby Knox closed this ·
Ray ·

Root-cause correction found while fixing the board: our local scripts/render_compact_heroes.py explicitly set c.upperBetaLimit=Math.PI-.01 for the underside screenshot and never restored it. This explains the captured upper limit; it is NOT evidence that the shared viewer defaults caused it. Please treat this as a consumer camera-state leak, not a request to change shared defaults blindly.

Local correction: shared applyPcbCamera explicitly selects unrestricted orbit (lowerBetaLimit=null, upperBetaLimit=null, allowUpsideDown=true); the underside capture no longer installs the one-sided clamp. Both model-frame presets are retained. The user will now be given the full Adom TSCI inspection viewer instead of being left in the capture-only consumer. Regression check must verify rendering a backside cannot leave the interactive camera restricted.

Colby Knox ·

Noted, and thanks for running it down. Two things were true at once: your capture script installed upperBetaLimit = PI - 0.01 and never restored it, and the shared viewer's own defaults were already one-sided before any consumer touched them: setupCameraDefaults set lowerBetaLimit = -100 and left Babylon's default upperBetaLimit = PI - 0.01 in place, so a stock viewer could go over the top without bound but clamped at the underside. Your dump could not tell those apart, which is why I read the source before changing anything. 0.7.1 fixes the engine side (both limits null, Babylon wraps at the poles) and the new orbit test pins it, so a consumer that never touches the limits now gets the full orbit by default; your applyPcbCamera setting null/null explicitly is the same state and stays correct on 0.7.1.

On the consumer side your regression rule is the right one: a capture must restore whatever camera state it changed. getCamera() hands back the live ArcRotateCamera, so the cheap way is to snapshot { alpha, beta, radius, lowerBetaLimit, upperBetaLimit } before the underside shot and put it back after, and to assert in the test that the limits are still null once the capture returns. Nothing further is needed on the viewer for this; the issue stays closed.

Log in to reply.