---

name: 3d-camera-interaction description: Three.js 中处理 3D 模型拖拽、缩放、边界检测的正确方法。解决鼠标移动与模型移动不同步、缩放后只能看到模型一部分等问题。

3D 相机交互：拖拽与边界检测

症状

• 缩放后拖拽模型，鼠标移动 100px 但模型移动的屏幕距离不是 100px
• 放大模型后只能看到腿/身体的一部分，无法正常平移
• 拖动开始时模型位置"跳变"

根本原因

原因 1: 固定 panSpeed 导致移动不同步

问题: 使用固定的 panSpeed = 0.01 进行平移计算

Copy// ❌ 错误方式
const panSpeed = 0.01;
newPosition.add(right.multiplyScalar(deltaX * panSpeed));

为什么发生: 相机距离变化时，同样的世界空间距离在屏幕上的像素表现不同。距离近时像素多，距离远时像素少。

解决方案: 根据相机距离和 FOV 动态计算像素→世界空间的映射

Copy// ✅ 正确方式：动态计算
const cameraDistance = camera.position.distanceTo(modelCenter);
const fov = camera.fov * (Math.PI / 180);
const screenHeight = renderer.domElement.clientHeight;
const screenWidth = renderer.domElement.clientWidth;

// 在相机距离处，视口的世界空间高度
const worldHeight = 2 * Math.tan(fov / 2) * cameraDistance;
const worldWidth = worldHeight * (screenWidth / screenHeight);

// 每像素对应的世界空间距离
const pixelToWorldX = worldWidth / screenWidth;
const pixelToWorldY = worldHeight / screenHeight;

// 应用：鼠标移动的像素 × 每像素对应的世界空间距离
newPosition.add(right.multiplyScalar(deltaX * pixelToWorldX));
newPosition.add(up.multiplyScalar(-deltaY * pixelToWorldY));

原因 2: 基于中心点的边界限制

问题: 使用模型中心点的 NDC 坐标判断是否出界

Copy// ❌ 错误方式：限制中心点位置
const ndc = position.clone().project(camera);
if (ndc.y > 0.2) clampedY = 0.2; // 限制顶部

为什么发生: 模型放大后，中心点在屏幕中心，但身体大部分已超出屏幕。限制中心点 = 限制只能看到身体中间部分。

解决方案: 计算模型在屏幕上的可见区域（像素），只在可见区域过小时才校正

Copy// ✅ 正确方式：基于可见像素
const MIN_VISIBLE_PIXELS = 50;

// 1. 计算模型包围盒并投影到屏幕
const box = new THREE.Box3().setFromObject(vrm.scene);
const corners = [/* 8个顶点 */];

let modelMinX = Infinity, modelMaxX = -Infinity;
let modelMinY = Infinity, modelMaxY = -Infinity;

corners.forEach(corner => {
    const projected = corner.clone().project(camera);
    const screenX = (projected.x * 0.5 + 0.5) * screenWidth;
    const screenY = (-projected.y * 0.5 + 0.5) * screenHeight;
    // 更新边界...
});

// 2. 计算可见区域
const visibleWidth = Math.max(0, Math.min(screenWidth, modelMaxX) - Math.max(0, modelMinX));
const visibleHeight = Math.max(0, Math.min(screenHeight, modelMaxY) - Math.max(0, modelMinY));
const visiblePixels = visibleWidth * visibleHeight;

// 3. 只在可见区域太小时校正
if (visiblePixels < MIN_VISIBLE_PIXELS) {
    // 将模型拉回可见区域
}

关键公式

像素到世界空间转换

CopyworldHeight = 2 × tan(fov/2) × cameraDistance
pixelToWorld = worldHeight / screenHeight

世界坐标到屏幕坐标

Copyconst ndc = worldPos.clone().project(camera);
const screenX = (ndc.x * 0.5 + 0.5) * screenWidth;
const screenY = (-ndc.y * 0.5 + 0.5) * screenHeight; // Y 轴反向

关键经验

• 📐 相机距离影响一切: 所有像素↔世界空间的转换都需要考虑相机距离
• 🔲 使用包围盒而非中心点: 边界检测应基于模型实际占用的屏幕区域
• 🔄 与 2D 保持一致: Live2D/VRM 等不同类型模型应使用相同的交互逻辑阈值