@ericchen1990/pano-view 3.6.1 → 3.6.3

package/README.md

@@ -879,7 +879,7 @@ function TourPlayer() {
 
 The two deprecated auto-rotation handle methods (`startAutoRotate`, `stopAutoRotate`) remain for compatibility. Mouse, touch, and keyboard input are enabled by default — you do not need to render control components for ordinary viewing. Render `MouseControls`, `TouchControls`, or `KeyboardControls` only to override properties (the child replaces that channel's default instance). Tune shared behaviour through `controls` (`inertia`, `invert`, `bouncingLimits`, `fovSpeed`, `frictionStop`, `rotateDamping`, `zoomDamping`, and top-level `rotateSpeed` / `zoomSpeed`). Disable a channel with `controls.mouse` / `touch` / `keyboard` set to `false`, or pass an options object (including `enabled`) to override defaults without mounting a child. Auto-rotation is off until you render `AutoRotate`. A default context menu (Reset view / Enter fullscreen) is also mounted — see [`PanoContextMenu`](#panocontextmenu).
 
-Mouse, pen, and single-touch drags anchor the grabbed panorama point and update rotation once per render frame, with a short time-based filter (about 10ms of following delay during steady movement) to smooth uneven input samples. The grabbed point aligns exactly once movement settles. View limits and positions near the poles can restrict tracking. The default `rotateSpeed` of `0.35` gives 1:1 tracking; other values scale pointer displacement relative to it, `0` disables rotation, and `invert` reverses direction. The separate `rotateDamping` setting does not apply during anchored drags; release inertia is retained. Pinch and wheel zoom continue to follow the target FOV smoothly.
+Mouse, pen, and single-touch drags anchor the grabbed panorama point and update rotation once per render frame, with a short time-based filter (about 10ms of following delay during steady movement) to smooth uneven input samples. The grabbed point aligns once movement settles, and releasing the pointer completes that alignment immediately. Flick inertia follows the latest pointer motion, so a pause before release does not continue an earlier flick. View limits and positions near the poles can restrict tracking. The default `rotateSpeed` of `0.35` gives 1:1 tracking; other values scale pointer displacement relative to it, `0` disables rotation, and `invert` reverses direction. The separate `rotateDamping` setting does not apply during anchored drags; release inertia is retained. Pinch and wheel zoom continue to follow the target FOV smoothly.
 
 Other rotation input and zoom update a target view that the camera follows smoothly. `rotateDamping` and `zoomDamping` control that following speed in seconds^-1 (defaults: `14` and `16` respectively); smaller positive values make the camera approach the target more gradually, while `0` disables smoothing for that axis. Both values must be non-negative finite numbers. Imperative `setView()` and `reset()` remain immediate.
 

package/README.zh-CN.md

@@ -852,7 +852,7 @@ function TourPlayer() {
 
 两个已废弃的自动旋转方法（`startAutoRotate`、`stopAutoRotate`）继续保留以兼容。鼠标、触控与键盘输入默认启用 — 普通浏览无需再渲染控件组件。仅当需要覆盖属性时渲染 `MouseControls`、`TouchControls` 或 `KeyboardControls`（子组件会替换该通道的默认实例）。通过 `controls` 调节共享行为（`inertia`、`invert`、`bouncingLimits`、`fovSpeed`、`frictionStop`、`rotateDamping`、`zoomDamping`，以及顶层的 `rotateSpeed` / `zoomSpeed`）。将 `controls.mouse` / `touch` / `keyboard` 设为 `false` 可关闭某通道，或传入选项对象（含 `enabled`）在不挂载子组件的情况下覆盖默认值。自动旋转在渲染 `AutoRotate` 之前处于关闭状态。默认右键菜单（重置视图 / 进入全屏）也会挂载 — 见 [`PanoContextMenu`](#panocontextmenu)。
 
-鼠标、笔和单指拖拽会锚定按下的全景点，并在每个渲染帧更新旋转；使用短暂的时间平滑吸收输入采样的波动（匀速移动时约 10ms 跟随延迟），停住并收敛后按下点会准确对齐指针；视角边界或极点附近可能限制跟随。`rotateSpeed` 默认 `0.35` 表示 1:1 跟随，其他值按其相对倍率调整指针位移，`0` 禁止旋转；`invert` 反转方向。双指缩放和滚轮继续更新目标 FOV，相机平滑跟随。拖拽释放后保留惯性。`rotateDamping` 与 `zoomDamping` 控制跟随速度（旋转平滑不作用于锚定拖拽期间），单位为秒⁻¹（默认分别为 `14` 与 `16`）；较小的正值使相机更缓慢地接近目标视角，`0` 表示该轴不做平滑。两者必须为非负有限数。命令式 `setView()` 与 `reset()` 仍为即时生效。
+鼠标、笔和单指拖拽会锚定按下的全景点，并在每个渲染帧更新旋转；使用短暂的时间平滑吸收输入采样的波动（匀速移动时约 10ms 跟随延迟）。指针停住并收敛后，按下点会与指针对齐；松手时也会立刻完成这次对齐。甩动惯性只跟随最近一段指针运动，松手前如果已经停住，不会把更早的速度继续带出去。视角边界或极点附近可能限制跟随。`rotateSpeed` 默认 `0.35` 表示 1:1 跟随，其他值按其相对倍率调整指针位移，`0` 禁止旋转；`invert` 反转方向。双指缩放和滚轮继续更新目标 FOV，相机平滑跟随。拖拽释放后保留惯性。`rotateDamping` 与 `zoomDamping` 控制跟随速度（旋转平滑不作用于锚定拖拽期间），单位为秒⁻¹（默认分别为 `14` 与 `16`）；较小的正值使相机更缓慢地接近目标视角，`0` 表示该轴不做平滑。两者必须为非负有限数。命令式 `setView()` 与 `reset()` 仍为即时生效。
 
 画布光标默认为 `grab`，鼠标拖拽时为 `grabbing`，悬停在可交互热点上为 `pointer`，拖拽热点时为 `move`。可通过 `cursors`（`default`、`dragging`、`hotspot`、`hotspotDragging`）覆盖，或传 `cursors={false}` 保持画布光标不变。热点可设置 `cursor`，仅替换该热点的悬停光标。
 

package/dist/index.cjs

@@ -2896,7 +2896,12 @@ var PanoramaViewRuntime = (0, import_react3.forwardRef)(function PanoramaViewRun
       }
     }
     markDirty();
-    if (applyOptions?.recordVelocity && !gyroControlsView) {
+    const releaseVelocity = applyOptions?.velocity;
+    if (!gyroControlsView && releaseVelocity && Number.isFinite(releaseVelocity.yaw) && Number.isFinite(releaseVelocity.pitch)) {
+      yawVelocityRef.current = releaseVelocity.yaw;
+      pitchVelocityRef.current = releaseVelocity.pitch;
+      lastVelocitySampleAtRef.current = performance.now();
+    } else if (applyOptions?.recordVelocity && !gyroControlsView) {
       const now = performance.now();
       const previousAt = lastVelocitySampleAtRef.current;
       const elapsed = previousAt === null ? 1 / 60 : Math.max((now - previousAt) / 1e3, 1 / 120);
@@ -3736,6 +3741,26 @@ var import_react9 = require("react");
 var import_three2 = require("three");
 var DEFAULT_POINTER_DRAG_SPEED = 0.35;
 var POINTER_FOLLOW_TIME_SECONDS = 0.01;
+var MIN_VELOCITY_SAMPLE_SECONDS = 1 / 120;
+function pointerReleaseVelocity(samples, releasedAt, solve, maxAgeMs = POINTER_VELOCITY_MAX_AGE_MS) {
+  if (samples.length < 2) return { yaw: 0, pitch: 0 };
+  const newest = samples[samples.length - 1];
+  if (releasedAt < newest.at || releasedAt - newest.at > maxAgeMs) return { yaw: 0, pitch: 0 };
+  let oldest = newest;
+  for (let index = samples.length - 1; index >= 0; index -= 1) {
+    const sample = samples[index];
+    if (releasedAt - sample.at <= maxAgeMs) oldest = sample;
+    else break;
+  }
+  if (oldest === newest) return { yaw: 0, pitch: 0 };
+  const elapsed = Math.max((newest.at - oldest.at) / 1e3, MIN_VELOCITY_SAMPLE_SECONDS);
+  const from = solve(oldest);
+  const to = solve(newest);
+  return {
+    yaw: normalizeViewYaw(to.yaw - from.yaw) / elapsed,
+    pitch: (to.pitch - from.pitch) / elapsed
+  };
+}
 var PointerDragAnchor = class {
   constructor(start, origin, rect, projection) {
     this.start = start;
@@ -3744,12 +3769,18 @@ var PointerDragAnchor = class {
     this.projection = projection;
     this.local = new import_three2.Vector3();
     this.rotation = new import_three2.Euler(0, 0, 0, "YXZ");
-    this.anchor = this.ray(start).clone().applyEuler(this.rotation.set(
+    const startRay = this.ray(start).clone();
+    this.baseAzimuth = Math.atan2(startRay.x, -startRay.z);
+    this.baseElevation = Math.atan2(startRay.y, -startRay.z);
+    this.anchor = startRay.clone().applyEuler(this.rotation.set(
       import_three2.MathUtils.degToRad(origin.pitch),
       import_three2.MathUtils.degToRad(-origin.yaw),
       0,
       "YXZ"
     ));
+    const originPitch = import_three2.MathUtils.degToRad(origin.pitch);
+    const roots = this.pitchRoots(startRay, originPitch);
+    this.useSupplementary = Math.abs(roots.supplementary - originPitch) + 1e-6 < Math.abs(roots.principal - originPitch);
   }
   ray(point) {
     return this.local.set(
@@ -3758,6 +3789,21 @@ var PointerDragAnchor = class {
       0.5
     ).applyMatrix4(this.projection.projectionMatrixInverse).normalize();
   }
+  /** Pitch roots of the level-camera constraint. The supplementary root is unwrapped toward the press. */
+  pitchRoots(ray, originPitch) {
+    const latitude = Math.asin(import_three2.MathUtils.clamp(
+      this.anchor.y / Math.max(Math.hypot(ray.y, ray.z), 1e-12),
+      -1,
+      1
+    ));
+    const offset = Math.atan2(ray.y, -ray.z);
+    const principal = latitude - offset;
+    const turned = Math.PI - latitude - offset;
+    return {
+      principal,
+      supplementary: originPitch + Math.atan2(Math.sin(turned - originPitch), Math.cos(turned - originPitch))
+    };
+  }
   solve(point, speed = DEFAULT_POINTER_DRAG_SPEED, invert = false) {
     const multiplier = (Number.isFinite(speed) && speed >= 0 ? speed : DEFAULT_POINTER_DRAG_SPEED) / DEFAULT_POINTER_DRAG_SPEED * (invert ? -1 : 1);
     if (multiplier === 0) return { yaw: 0, pitch: 0 };
@@ -3765,22 +3811,27 @@ var PointerDragAnchor = class {
       x: this.start.x + (point.x - this.start.x) * multiplier,
       y: this.start.y + (point.y - this.start.y) * multiplier
     });
-    const latitude = Math.asin(import_three2.MathUtils.clamp(this.anchor.y / Math.max(Math.hypot(ray.y, ray.z), 1e-12), -1, 1));
-    const offset = Math.atan2(ray.y, -ray.z);
     const originPitch = import_three2.MathUtils.degToRad(this.origin.pitch);
-    const candidates = [latitude - offset, Math.PI - latitude - offset, -Math.PI - latitude - offset];
-    let pitch = candidates[0];
-    let distance = Infinity;
-    for (const candidate of candidates) {
-      const bounded = import_three2.MathUtils.clamp(candidate, -Math.PI / 2, Math.PI / 2);
-      const nextDistance = Math.abs(candidate - bounded) * 10 + Math.abs(bounded - originPitch);
-      if (nextDistance < distance) {
-        pitch = bounded;
-        distance = nextDistance;
-      }
-    }
-    const z = Math.sin(pitch) * ray.y + Math.cos(pitch) * ray.z;
-    const yaw = import_three2.MathUtils.radToDeg(Math.atan2(this.anchor.x, -this.anchor.z) - Math.atan2(ray.x, -z));
+    const roots = this.pitchRoots(ray, originPitch);
+    const exactPitch = import_three2.MathUtils.clamp(
+      this.useSupplementary ? roots.supplementary : roots.principal,
+      -Math.PI / 2,
+      Math.PI / 2
+    );
+    const stablePitch = originPitch - (Math.atan2(ray.y, -ray.z) - this.baseElevation);
+    const fromPole = Math.asin(Math.min(1, Math.hypot(this.anchor.x, this.anchor.z)));
+    const pointerLock = import_three2.MathUtils.smoothstep(fromPole, import_three2.MathUtils.degToRad(8), import_three2.MathUtils.degToRad(18));
+    const pitchTurn = Math.atan2(Math.sin(exactPitch - stablePitch), Math.cos(exactPitch - stablePitch));
+    const pitch = import_three2.MathUtils.clamp(
+      pointerLock >= 1 ? exactPitch : stablePitch + pointerLock * pitchTurn,
+      -Math.PI / 2,
+      Math.PI / 2
+    );
+    const pitchedZ = Math.sin(exactPitch) * ray.y + Math.cos(exactPitch) * ray.z;
+    const exactYaw = Math.atan2(this.anchor.x, -this.anchor.z) - Math.atan2(ray.x, -pitchedZ);
+    const stableYaw = import_three2.MathUtils.degToRad(this.origin.yaw) + Math.atan2(ray.x, -ray.z) - this.baseAzimuth;
+    const yawTurn = Math.atan2(Math.sin(exactYaw - stableYaw), Math.cos(exactYaw - stableYaw));
+    const yaw = import_three2.MathUtils.radToDeg(stableYaw + pointerLock * yawTurn);
     return { yaw: normalizeViewYaw(yaw - this.origin.yaw), pitch: import_three2.MathUtils.radToDeg(pitch) - this.origin.pitch };
   }
 };
@@ -3793,8 +3844,11 @@ function createPointerDrag(camera, element, runtime, source) {
   let lastPoint;
   let fresh = false;
   let lastFrameDelta = 1 / 60;
+  let samples = [];
+  let gestureSpeed = DEFAULT_POINTER_DRAG_SPEED;
+  let gestureInvert = false;
   const key = (rect) => `${rect.left},${rect.top},${rect.width},${rect.height},${camera.projectionMatrix.elements.join(",")}`;
-  const start = (point) => {
+  const place = (point) => {
     const handle = runtime();
     displayed = { ...point };
     lastPoint = { ...point };
@@ -3806,69 +3860,113 @@ function createPointerDrag(camera, element, runtime, source) {
     projectionKey = key(rect);
     anchor = new PointerDragAnchor(point, handle.getView(), rect, camera.clone());
   };
-  const apply = (point, previous, speed, invert, recordVelocity) => {
+  const remember = (point, at) => {
+    samples.push({ x: point.x, y: point.y, at });
+    const cutoff = at - POINTER_VELOCITY_MAX_AGE_MS;
+    while (samples.length > 2 && samples[0].at < cutoff) samples.shift();
+  };
+  const apply = (point, previous, speed, invert, recordVelocity, releaseVelocity) => {
     const handle = runtime();
     if (!handle) return;
     const rect = element.getBoundingClientRect();
     if (anchor && key(rect) !== projectionKey) {
       const queued = pending;
-      start(displayed ?? previous);
+      place(displayed ?? previous);
       pending = queued;
     }
+    const options = {
+      recordVelocity: releaseVelocity ? false : recordVelocity,
+      source,
+      ...releaseVelocity ? { velocity: releaseVelocity } : {}
+    };
     if (anchor) {
       handle.applyViewDelta(anchor.solve(point, speed, invert), {
-        pointerOrigin: anchor.origin,
-        recordVelocity,
-        source
+        ...options,
+        pointerOrigin: anchor.origin
       });
     } else {
       handle.applyViewDelta({
         yaw: -(point.x - previous.x) * 360 * speed / Math.max(rect.width, 1) * (invert ? -1 : 1),
         pitch: (point.y - previous.y) * 180 * speed / Math.max(rect.height, 1) * (invert ? -1 : 1)
-      }, { recordVelocity, source });
+      }, options);
     }
   };
+  const valid = () => revision === (runtime()?.getPointerDragState().revision ?? -1) && !runtime()?.isInteractionLocked();
+  const clear = () => {
+    anchor = void 0;
+    revision = -1;
+    pending = void 0;
+    displayed = void 0;
+    samples = [];
+  };
   return {
-    start,
-    valid: () => revision === (runtime()?.getPointerDragState().revision ?? -1) && !runtime()?.isInteractionLocked(),
-    clear: () => {
-      anchor = void 0;
-      revision = -1;
-      pending = void 0;
-      displayed = void 0;
+    start(point, at = performance.now()) {
+      gestureSpeed = DEFAULT_POINTER_DRAG_SPEED;
+      gestureInvert = false;
+      samples = [];
+      remember(point, at);
+      place(point);
     },
+    valid,
+    clear,
     suspend: () => {
       anchor = void 0;
       pending = void 0;
       displayed = void 0;
+      samples = [];
     },
-    move(point, previous, speed, invert) {
+    move(point, previous, speed, invert, at = performance.now()) {
       fresh = true;
+      gestureSpeed = speed;
+      gestureInvert = invert;
+      remember(point, at);
       pending = { point, previous: lastPoint ?? previous, speed, invert };
     },
-    flush(deltaSeconds = lastFrameDelta, immediate = false) {
-      lastFrameDelta = deltaSeconds;
+    flush(deltaSeconds = lastFrameDelta, immediate = false, releaseVelocity) {
+      if (deltaSeconds > 0) lastFrameDelta = deltaSeconds;
       if (!pending) return;
       const sample = pending;
       if (!anchor || immediate) {
         pending = void 0;
-        apply(sample.point, sample.previous, sample.speed, sample.invert, fresh);
+        apply(sample.point, sample.previous, sample.speed, sample.invert, fresh, releaseVelocity);
         fresh = false;
         lastPoint = sample.point;
         displayed = sample.point;
         return;
       }
+      const dt = deltaSeconds > 0 ? deltaSeconds : lastFrameDelta;
       const previousDisplay = displayed ?? sample.previous;
       const dx = sample.point.x - previousDisplay.x;
       const dy = sample.point.y - previousDisplay.y;
       const distance = Math.hypot(dx, dy);
-      const ratio = distance > 0.01 ? POINTER_FOLLOW_TIME_SECONDS / (POINTER_FOLLOW_TIME_SECONDS + deltaSeconds) : 0;
+      const ratio = distance > 0.01 ? POINTER_FOLLOW_TIME_SECONDS / (POINTER_FOLLOW_TIME_SECONDS + dt) : 0;
       const point = { x: sample.point.x - dx * ratio, y: sample.point.y - dy * ratio };
       apply(point, sample.previous, sample.speed, sample.invert, fresh);
       fresh = false;
       lastPoint = sample.point;
       displayed = point;
       if (ratio === 0) pending = void 0;
+    },
+    release() {
+      const handle = runtime();
+      if (!handle || !valid()) {
+        clear();
+        return;
+      }
+      const newestAt = samples[samples.length - 1]?.at ?? 0;
+      const velocity = pointerReleaseVelocity(samples, Math.max(performance.now(), newestAt), (point) => {
+        if (anchor) return anchor.solve(point, gestureSpeed, gestureInvert);
+        const origin = samples[0] ?? point;
+        const rect = element.getBoundingClientRect();
+        const sign = gestureInvert ? -1 : 1;
+        return {
+          yaw: -(point.x - origin.x) * 360 * gestureSpeed / Math.max(rect.width, 1) * sign,
+          pitch: (point.y - origin.y) * 180 * gestureSpeed / Math.max(rect.height, 1) * sign
+        };
+      });
+      if (pending) this.flush(lastFrameDelta, true, velocity);
+      else handle.applyViewDelta({}, { velocity, source });
+      clear();
     }
   };
 }
@@ -3884,6 +3982,9 @@ var BUTTON_FLAG = {
 function resolveSpeed2(value, fallback) {
   return Number.isFinite(value) && value >= 0 ? value : fallback;
 }
+function pointerAt(event) {
+  return event.timeStamp > 0 ? event.timeStamp : performance.now();
+}
 function resolveButtons(buttons) {
   const list = buttons && buttons.length > 0 ? buttons : ["left"];
   return new Set(list.map((button) => BUTTON_FLAG[button]));
@@ -3970,7 +4071,7 @@ function MouseControls({
       });
       element.setPointerCapture?.(event.pointerId);
       syncActive();
-      drag.start({ x: event.clientX, y: event.clientY });
+      drag.start({ x: event.clientX, y: event.clientY }, pointerAt(event));
     };
     const onPointerMove = (event) => {
       if (!isMouseLike(event)) {
@@ -3991,15 +4092,15 @@ function MouseControls({
       };
       pointersRef.current.set(event.pointerId, next);
       const speed = resolveSpeed2(optionsRef.current.rotateSpeed, DEFAULT_ROTATE_SPEED2);
-      drag.move(next, previous, speed, optionsRef.current.invert);
+      drag.move(next, previous, speed, optionsRef.current.invert, pointerAt(event));
     };
     const releasePointer = (event) => {
       if (!pointersRef.current.has(event.pointerId)) {
         return;
       }
-      if (event.type === "pointerup") drag.flush();
+      if (event.type === "pointerup") drag.release();
+      else drag.clear();
       pointersRef.current.delete(event.pointerId);
-      drag.clear();
       if (element.hasPointerCapture?.(event.pointerId)) {
         element.releasePointerCapture?.(event.pointerId);
       }
@@ -5642,6 +5743,9 @@ function notifyScenesHost(host) {
 var import_fiber8 = require("@react-three/fiber");
 var import_react18 = require("react");
 var DEFAULT_ROTATE_SPEED3 = 0.35;
+function pointerAt2(event) {
+  return event.timeStamp > 0 ? event.timeStamp : performance.now();
+}
 function resolveSpeed3(value, fallback) {
   return Number.isFinite(value) && value >= 0 ? value : fallback;
 }
@@ -5710,7 +5814,7 @@ function TouchControls({
       });
       element.setPointerCapture?.(event.pointerId);
       syncActive();
-      drag.start({ x: event.clientX, y: event.clientY });
+      drag.start({ x: event.clientX, y: event.clientY }, pointerAt2(event));
       if (pointersRef.current.size >= 2) {
         drag.suspend();
         const [first, second] = Array.from(pointersRef.current.values());
@@ -5757,15 +5861,16 @@ function TouchControls({
         return;
       }
       const speed = resolveSpeed3(optionsRef.current.rotateSpeed, DEFAULT_ROTATE_SPEED3);
-      drag.move(next, previous, speed, optionsRef.current.invert);
+      drag.move(next, previous, speed, optionsRef.current.invert, pointerAt2(event));
     };
     const releasePointer = (event) => {
       if (!pointersRef.current.has(event.pointerId)) {
         return;
       }
-      if (event.type === "pointerup") drag.flush();
+      const pinch = pointersRef.current.size >= 2;
+      if (event.type === "pointerup" && !pinch) drag.release();
+      else drag.clear();
       pointersRef.current.delete(event.pointerId);
-      drag.clear();
       if (element.hasPointerCapture?.(event.pointerId)) {
         element.releasePointerCapture?.(event.pointerId);
       }
@@ -5774,7 +5879,7 @@ function TouchControls({
       }
       syncActive(event.type !== "pointerup");
       const remaining = pointersRef.current.values().next().value;
-      if (remaining) drag.start(remaining);
+      if (remaining) drag.start(remaining, pointerAt2(event));
     };
     element.addEventListener("pointerdown", onPointerDown);
     element.addEventListener("pointermove", onPointerMove);