Zooming velocity in deep zoom

[ShaMan123]

Describe the bug 📝

Zooming is expected to be exponential to the wheel event
Deep zooming becomes linear.

Screen.Recording.2026-07-21.at.10.16.06.mov

Investigating via claude

infinityDolly produces two different zoom regimes, and the boundary between them is minDistance:

radius vs minDistance	per-notch step	feel
radius > minDistance	radius · k (multiplicative)	proportional / exponential — natural
radius ≤ minDistance	minDistance · k (constant, additive)	linear

Once you zoom in far enough that the orbit radius collapses to minDistance, camera-controls stops shrinking the radius and instead pushes the target/camera forward by a fixed world-space step every notch (_dollyInternal → _dollyToNoClamp, and the isMin branch in update() at line 2185-2190@node_modules/camera-controls/dist/camera-controls.module.js see code snippet below). My sweep confirms that step is exactly minDistance · k:

• minDistance = 0.01 → step 0.0015 — this was your original "decay": a frozen crawl.
• minDistance = 6 → step 0.942 — the current "linear at high zoom": a fixed step that no longer scales with how close you are.

So it's the same bug seen from two sides. My earlier fix moved you from the frozen end of the scale to the coarse end. Both are the constant-step regime; the constant is minDistance · k.

Why it reads as a "slowdown": in the proportional regime the thing under the cursor grows by a constant percentage per notch. In the constant regime the camera moves a fixed distance per notch, so when the target is far the on-screen growth per notch keeps shrinking — the zoom feels like it's grinding to a linear crawl. It bites specifically "at high zoom" because that's exactly when radius has pinned to minDistance.

The root problem: infinityDolly's step is governed by the fixed minDistance, which is decoupled from the actual distance to the geometry under the cursor. No single fixed minDistance can be right — small = frozen, large = coarse/linear.

// node_modules/camera-controls/dist/camera-controls.module.js
                const isMin = this._lastDollyDirection === DOLLY_DIRECTION.IN && this._spherical.radius <= this.minDistance;
                const isMax = this._lastDollyDirection === DOLLY_DIRECTION.OUT && this.maxDistance <= this._spherical.radius;
                if (this.infinityDolly && (isMin || isMax)) {
                    this._sphericalEnd.radius -= dollyControlAmount;
                    this._spherical.radius -= dollyControlAmount;
                    const dollyAmount = _v3B.copy(cameraDirection).multiplyScalar(-dollyControlAmount);
                    newTargetEnd.add(dollyAmount);
                }

Reproduction ▶️

No response

Steps to reproduce 🔢

No response

System Info 💻

n/a

Used Package Manager 📦

npm

Error Trace/Logs 📃

No response

Validations ✅

• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Make sure this is a repository issue and not a framework-specific issue. For example, if it's a THREE.js related bug, it should likely be reported to mrdoob/threejs instead.
• Check that this is a concrete bug. For Q&A join our Community.
• The provided reproduction is a minimal reproducible example of the bug.

[agviegas]

Confirmed your analysis in the camera-controls source: the radius shrinks multiplicatively until it hits minDistance, then the isMin branch pins it and pushes the target by roughly minDistance * k. #769 is merged but only changes which constant applies, so this stands.

One question before changing the step: should zooming still be able to take you through a surface?

Tying minDistance to the distance under the cursor means the radius never reaches it, so the fly-through stops firing and zoom becomes an asymptotic approach that never crosses. Fixes the linearity, but removes a capability people use in BIM. The alternative keeps the branch and scales its step by that distance instead, so zoom stays proportional and you can still pass through.

Which did you have in mind?

[ShaMan123]

Personally I prefer fly through - but I think it can be a great mid flight toggle.
Opting out will allow a user to zoom very quickly to the surface, holding the ctrl key will allow passing through it.
I have made real progress with the functions needed for correcting the logic making zooming feel fluid and correct (including updating clip bounds to avoid partially rendered tiles from being cut inside the frustrum):

  /**
   * Recompute the cached world bounds ({@link clipBox}/{@link clipSphere}) from
   * every loaded model and its grids. The bounds only change when a model/grid
   * is added or removed, so this runs on those events — never per camera move.
   *
   * Grids extend past the model geometry, so they are unioned in too; otherwise
   * the tight near/far planes would slice axis lines and labels.
   */
  protected updateClipBounds() {
    this.clipBox.makeEmpty();
    for (const [, model] of this.fragments.list) {
      if (!model.box.isEmpty()) this.clipBox.union(model.box);
    }
    for (const [, { grids }] of this.modelData) {
      this.clipBox.expandByObject(grids.object);
    }
    this.boundsValid = !this.clipBox.isEmpty();
    if (this.boundsValid) this.clipBox.getBoundingSphere(this.clipSphere);
  }

  /**
   * Fit the camera near/far planes to the cached bounds. Cheap (O(1)) — called
   * on every camera move.
   *
   * `OrthoPerspectiveCamera` defaults to a near=1 / far=1000 frustum and never
   * auto-adjusts it; with `autoCoordinate = false` our models keep their real
   * (metre-to-tens-of-metres) world coordinates, so anything past 1000 units
   * from the camera would be clipped. Bracketing the planes around the current
   * camera→bounds distance keeps the near:far ratio (depth precision) tight
   * rather than relying on one huge static far plane.
   */
  protected fitCameraClipping() {
    if (!this.boundsValid) return;

    const camera = this.world.camera.three;
    const dist = camera.position.distanceTo(this.clipSphere.center);
    const margin = this.clipSphere.radius * 1.2 + 1;
    // Absolute floor keeps `near > 0`: a degenerate (zero-extent) bounds would
    // otherwise give near=0 and a degenerate perspective projection.
    camera.near = Math.max(0.01, dist - margin);
    camera.far = dist + margin;
    camera.updateProjectionMatrix();
  }

  /**
   * Scale the camera-controls `minDistance` to the loaded model, so wheel zoom
   * stays responsive at any model size. Called on bounds change (model load /
   * removal), never per-frame — the distance limits only change with scale.
   *
   * Why this matters: the controls run with `dollyToCursor` + `infinityDolly`
   * (set in `@thatopen/components` `SimpleCamera.newCameraControls`), where the
   * wheel step is *proportional to the orbit radius* — so as you zoom in the
   * step shrinks and the motion decays. `infinityDolly`'s constant-speed push
   * (which pushes the target instead of shrinking the radius) only engages once
   * the radius reaches `minDistance`. So `minDistance` is the radius at which
   * zoom stops decaying and starts flying through — it must track model scale.
   *
   * `OrthoPerspectiveCamera`'s `OrbitMode.activateOrbitControls` hard-codes
   * `minDistance = 1` (and `SimpleCamera` defaults it to `6`). Both are fixed
   * metre values tuned for a specific model size; on a model whose framing
   * radius is tens of metres, a 1 m threshold sits so deep that the whole
   * usable range decays before it ever engages (the symptom fixed upstream only
   * partially by ThatOpen/engine_components#769 → follow-up #770). Tying it to
   * `clipSphere.radius` makes the zoom feel identical across model sizes.
   *
   * The ratio is the fraction of the bounding radius at which constant-speed
   * zoom kicks in — larger = snappier but transitions to fly-through sooner.
   */
  protected fitCameraDistanceLimits() {
    if (!this.boundsValid || !this.world.camera.hasCameraControls()) return;
    const { controls } = this.world.camera;
    const MIN_DISTANCE_RATIO = 0.25;
    const target = this.clipSphere.radius * MIN_DISTANCE_RATIO;
    // Floor keeps it > 0 for a degenerate/tiny model; cap below `maxDistance`
    // so the controls' `minDistance < maxDistance` invariant always holds.
    controls.minDistance = Math.min(
      Math.max(0.5, target),
      controls.maxDistance * 0.5
    );
  }

  /**
   * Frame the camera on `items` (or on everything, when omitted) without the
   * model-scaled `minDistance` floor clamping the approach: `fitToItems` dollies
   * via camera-controls `dollyTo`, which clamps the fitted distance to
   * `[minDistance, maxDistance]` — with the floor at a quarter of the WHOLE
   * scene's bounding radius, any selection smaller than ~1/8 of that radius
   * would stop far short of filling the view. Same trick as the orbit-point
   * anchor (Highlight's `setOrbitPoint`): drop the floor for the placement,
   * then recompute it from the bounds (idempotent) once the fit settles.
   */
  async fitCameraToItems(items?: OBC.ModelIdMap) {
    const camera = this.world.camera;
    if (!camera.hasCameraControls()) return;
    camera.controls.minDistance = 0.01;
    try {
      await camera.fitToItems(items);
    } finally {
      this.fitCameraDistanceLimits();
    }
  }

  /**
   * Camera-controls "update" listener
   */
  onCameraControlsUpdate = () => {
    if (this.disposed) return;
    this.fitCameraClipping();
    void this.fragments.core.update();
    this.requestRender();
  };

restoreCamera() {
      const { controls: cameraControls } = this.world.camera;
      cameraControls.fromJSON(persistedCameraData, false);
      // `fromJSON` restores minDistance/maxDistance too, and this async read
      // races the model loads: landing after the last `loadChunk` would
      // resurrect limits persisted for a differently-scaled model set. Recompute
      // from the current bounds (no-op while nothing is loaded — the next
      // `fitCameraDistanceLimits` on load wins anyway).
      this.fitCameraDistanceLimits();
      camera.updateAspect();
      camera.three.updateProjectionMatrix();
}

onModelChange() {
    this.updateClipBounds();
    this.fitCameraClipping();
    this.fitCameraDistanceLimits();
}