From 55ce6d71291d2e656fe3abb3a5781821ab942059 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= <kvtodev@outlook.com>
Date: Thu, 24 Sep 2026 17:23:31 +0800
Subject: [PATCH] =?UTF-8?q?=E5=8F=96=E6=99=AF=E8=B7=9D=E7=A6=BB=E6=8A=AC?=
 =?UTF-8?q?=E5=88=B0=E4=B8=8D=E4=BC=9A=E8=AE=A9=E8=BD=A8=E9=81=93=E7=BC=A9?=
 =?UTF-8?q?=E6=94=BE=E8=8C=83=E5=9B=B4=E9=A2=A0=E5=80=92=E7=9A=84=E4=B8=8B?=
 =?UTF-8?q?=E9=99=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- packages/model3d-viewer/src/framing.ts：computeModel3dViewerFitDistance 对调用方传入的距离加下限（radius × 0.2 / 8），避免 distance 过小时 maxDistance 小于 minDistance，取景与轨道钳制同时失效
- packages/model3d-viewer/src/framing.test.ts：补极小距离的下限用例
---
 packages/model3d-viewer/src/framing.test.ts | 14 ++++++++++++++
 packages/model3d-viewer/src/framing.ts      |  8 +++++++-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/packages/model3d-viewer/src/framing.test.ts b/packages/model3d-viewer/src/framing.test.ts
index e92af8579..9c22589d8 100644
--- a/packages/model3d-viewer/src/framing.test.ts
+++ b/packages/model3d-viewer/src/framing.test.ts
@@ -143,6 +143,20 @@ describe('computeModel3dViewerFitDistance', () => {
 
     expect(distance).toBe(7);
   });
+
+  it('传入的距离小到会让缩放范围颠倒时，抬到能站住的下限', () => {
+    const framing = computeModel3dViewerFraming({
+      box: CUBE,
+      aspect: 1,
+      distance: computeModel3dViewerFitDistance({
+        box: CUBE,
+        aspect: 1,
+        distance: 0.001,
+      }),
+    });
+
+    expect(framing.maxDistance).toBeGreaterThanOrEqual(framing.minDistance);
+  });
 });
 
 describe('createModel3dViewerFitSolver', () => {
diff --git a/packages/model3d-viewer/src/framing.ts b/packages/model3d-viewer/src/framing.ts
index f1ecaad0e..1104f4731 100644
--- a/packages/model3d-viewer/src/framing.ts
+++ b/packages/model3d-viewer/src/framing.ts
@@ -218,7 +218,13 @@ export function computeModel3dViewerFitDistance(
   // 会让 maxDistance 小于 minDistance，取景与轨道钳制一起失效，故按无效处理。
   const distance = input.distance;
   if (distance !== undefined && Number.isFinite(distance) && distance > 0) {
-    return distance;
+    // `computeModel3dViewerFraming` 由这个距离推出 maxDistance = distance × 8、minDistance
+    // = radius × 0.2；距离小到 0.025 × radius 以下时两者会颠倒，取景与轨道钳制一起失效。
+    return Math.max(
+      distance,
+      (computeModel3dViewerBoxRadius(input.box) * MIN_DISTANCE_RATIO) /
+        MAX_DISTANCE_RATIO,
+    );
   }
   const solver = createModel3dViewerFitSolver({
     center: computeModel3dViewerBoxCenter(input.box),