From bbc7d215e93e500f62457c3694863e576e23ddf9 Mon Sep 17 00:00:00 2001 From: admin <572701190@qq.com> Date: Thu, 7 May 2026 16:59:33 +0800 Subject: [PATCH] =?UTF-8?q?2026-05-07-16-53-23=20=E4=BF=AE=E6=AD=A33D?= =?UTF-8?q?=E6=A8=A1=E5=9E=8B=E4=B8=AD=E5=BF=83=E5=92=8C=E5=9D=90=E6=A0=87?= =?UTF-8?q?=E8=BD=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- WebSite/server.ts | 44 ++++++++-- WebSite/src/components/ProjectLibrary.tsx | 98 ++++++++++++++++++----- 工程分析/实现方案-2026-05-07-16-53-23.md | 82 +++++++++++++++++++ 工程分析/测试方案-2026-05-07-16-53-23.md | 51 ++++++++++++ 工程分析/经验记录.md | 18 +++++ 工程分析/需求分析-2026-05-07-16-53-23.md | 55 +++++++++++++ 6 files changed, 322 insertions(+), 26 deletions(-) create mode 100644 工程分析/实现方案-2026-05-07-16-53-23.md create mode 100644 工程分析/测试方案-2026-05-07-16-53-23.md create mode 100644 工程分析/需求分析-2026-05-07-16-53-23.md diff --git a/WebSite/server.ts b/WebSite/server.ts index 4e426b1..b7de5c7 100644 --- a/WebSite/server.ts +++ b/WebSite/server.ts @@ -705,22 +705,40 @@ function createStlPreview(filePath: string, fileName: string, limit: number) { const step = Math.max(1, Math.ceil(triangleCount / sampleLimit)); const vertices: number[] = []; let sampledTriangles = 0; + const bounds = { + min: { x: Infinity, y: Infinity, z: Infinity }, + max: { x: -Infinity, y: -Infinity, z: -Infinity }, + }; - for (let triangleIndex = 0; triangleIndex < triangleCount; triangleIndex += step) { + for (let triangleIndex = 0; triangleIndex < triangleCount; triangleIndex += 1) { const offset = 84 + triangleIndex * 50; if (offset + 50 > buffer.length) { break; } + const shouldSample = triangleIndex % step === 0; for (let vertex = 0; vertex < 3; vertex += 1) { const vertexOffset = offset + 12 + vertex * 12; - vertices.push( - Number(buffer.readFloatLE(vertexOffset).toFixed(3)), - Number(buffer.readFloatLE(vertexOffset + 4).toFixed(3)), - Number(buffer.readFloatLE(vertexOffset + 8).toFixed(3)), - ); + const x = buffer.readFloatLE(vertexOffset); + const y = buffer.readFloatLE(vertexOffset + 4); + const z = buffer.readFloatLE(vertexOffset + 8); + bounds.min.x = Math.min(bounds.min.x, x); + bounds.min.y = Math.min(bounds.min.y, y); + bounds.min.z = Math.min(bounds.min.z, z); + bounds.max.x = Math.max(bounds.max.x, x); + bounds.max.y = Math.max(bounds.max.y, y); + bounds.max.z = Math.max(bounds.max.z, z); + if (shouldSample) { + vertices.push( + Number(x.toFixed(3)), + Number(y.toFixed(3)), + Number(z.toFixed(3)), + ); + } + } + if (shouldSample) { + sampledTriangles += 1; } - sampledTriangles += 1; } const payload = { @@ -728,6 +746,18 @@ function createStlPreview(filePath: string, fileName: string, limit: number) { triangleCount, sampledTriangles, vertices, + bounds: { + min: { + x: Number(bounds.min.x.toFixed(3)), + y: Number(bounds.min.y.toFixed(3)), + z: Number(bounds.min.z.toFixed(3)), + }, + max: { + x: Number(bounds.max.x.toFixed(3)), + y: Number(bounds.max.y.toFixed(3)), + z: Number(bounds.max.z.toFixed(3)), + }, + }, }; modelPreviewCache.set(cacheKey, payload); return payload; diff --git a/WebSite/src/components/ProjectLibrary.tsx b/WebSite/src/components/ProjectLibrary.tsx index 94b3c78..df7ab75 100644 --- a/WebSite/src/components/ProjectLibrary.tsx +++ b/WebSite/src/components/ProjectLibrary.tsx @@ -49,6 +49,10 @@ interface ModelPreviewPayload { triangleCount: number; sampledTriangles: number; vertices: number[]; + bounds?: { + min: { x: number; y: number; z: number }; + max: { x: number; y: number; z: number }; + }; } type ModelPoseKey = keyof ModelPose; @@ -235,6 +239,53 @@ function DicomCanvas({ preview, rotation }: { preview: DicomPreview; rotation: n ); } +function OrientationGizmo({ pose }: { pose: ModelPose }) { + const axes = useMemo(() => { + const rotation = new THREE.Matrix4().makeRotationFromEuler(new THREE.Euler( + THREE.MathUtils.degToRad(pose.rotateX), + THREE.MathUtils.degToRad(pose.rotateY), + THREE.MathUtils.degToRad(pose.rotateZ), + 'XYZ', + )); + return [ + { id: 'X', color: '#ef4444', vector: new THREE.Vector3(1, 0, 0).applyMatrix4(rotation) }, + { id: 'Y', color: '#10b981', vector: new THREE.Vector3(0, 1, 0).applyMatrix4(rotation) }, + { id: 'Z', color: '#3b82f6', vector: new THREE.Vector3(0, 0, 1).applyMatrix4(rotation) }, + ] + .map((axis) => ({ + ...axis, + endX: 38 + axis.vector.x * 24 + axis.vector.z * 10, + endY: 38 - axis.vector.y * 24 + axis.vector.z * 8, + labelX: 38 + axis.vector.x * 30 + axis.vector.z * 12, + labelY: 38 - axis.vector.y * 30 + axis.vector.z * 10, + opacity: 0.55 + Math.max(-axis.vector.z, 0) * 0.45, + })) + .sort((a, b) => b.vector.z - a.vector.z); + }, [pose.rotateX, pose.rotateY, pose.rotateZ]); + + return ( +
+ + + {axes.map((axis) => ( + + + + + {axis.id} + + + ))} + +
+
X {Math.round(pose.rotateX)}°
+
Y {Math.round(pose.rotateY)}°
+
Z {Math.round(pose.rotateZ)}°
+
+
+ ); +} + function NativeStlViewer({ projectId, files, @@ -424,6 +475,7 @@ function NativeStlViewer({ scene.add(poseGroup); let loaded = 0; let failed = 0; + const loadedBounds: Array<{ min: THREE.Vector3; max: THREE.Vector3 }> = []; visibleFiles.forEach((fileName) => { fetch(`/api/projects/${projectId}/models/${encodeURIComponent(fileName)}/preview?limit=${detailLimit}`) @@ -451,18 +503,42 @@ function NativeStlViewer({ }), ); pivotGroup.add(mesh); + if (payload.bounds) { + loadedBounds.push({ + min: new THREE.Vector3(payload.bounds.min.x, payload.bounds.min.y, payload.bounds.min.z), + max: new THREE.Vector3(payload.bounds.max.x, payload.bounds.max.y, payload.bounds.max.z), + }); + } else { + geometry.computeBoundingBox(); + const geometryBox = geometry.boundingBox; + if (geometryBox) { + loadedBounds.push({ + min: geometryBox.min.clone(), + max: geometryBox.max.clone(), + }); + } + } loaded += 1; setProgress(Math.round(((loaded + failed) / visibleFiles.length) * 100)); setStatus(`已加载 ${loaded} / ${visibleFiles.length} 个 STL 预览`); if (loaded + failed === visibleFiles.length) { - const box = new THREE.Box3().setFromObject(pivotGroup); + const box = new THREE.Box3(); + if (loadedBounds.length) { + loadedBounds.forEach((bounds) => { + box.expandByPoint(bounds.min); + box.expandByPoint(bounds.max); + }); + } else { + box.setFromObject(pivotGroup); + } const center = box.getCenter(new THREE.Vector3()); const size = box.getSize(new THREE.Vector3()); const maxSize = Math.max(size.x, size.y, size.z) || 1; pivotGroup.traverse((object) => { if (object instanceof THREE.Mesh) { object.geometry.translate(-center.x, -center.y, -center.z); + object.geometry.computeBoundingBox(); object.geometry.computeBoundingSphere(); object.geometry.computeVertexNormals(); } @@ -545,23 +621,7 @@ function NativeStlViewer({ {status} )} -
-
-
- - - - X - Y - Z -
-
-
-
X {Math.round(pose.rotateX)}°
-
Y {Math.round(pose.rotateY)}°
-
Z {Math.round(pose.rotateZ)}°
-
-
+ ); } @@ -1217,7 +1277,7 @@ export default function ProjectLibrary({ onReverse }: { onReverse: (projId: stri diff --git a/工程分析/实现方案-2026-05-07-16-53-23.md b/工程分析/实现方案-2026-05-07-16-53-23.md new file mode 100644 index 0000000..4c87392 --- /dev/null +++ b/工程分析/实现方案-2026-05-07-16-53-23.md @@ -0,0 +1,82 @@ +# 实现方案 - 2026-05-07-16-53-23 + +## 修改目标 + +修复 3D 模型在细节档位切换和鼠标旋转时的中心漂移问题，并完善右下角坐标系联动和按钮样式。 + +## 涉及路径 + +- `WebSite/src/components/ProjectLibrary.tsx` + +## 技术路线 + +### 1. 分离 Three.js 渲染容器和 React overlay + +当前 `NativeStlViewer` 会对 `containerRef.current.innerHTML = ''`，容易把 React overlay 或其他子节点一起清掉。改为： + +- `viewportRef`：只用于挂载 Three.js canvas。 +- 外层 React 容器保留进度条、状态条、右下角坐标系等 overlay。 +- 清理时只清理 `viewportRef` 内的 canvas。 + +### 2. 修正模型重载后的中心与缩放 + +模型加载完成后： + +- 先把所有 mesh 加入 `pivotGroup`。 +- 基于 `pivotGroup` 的整体包围盒计算 `center` 和 `size`。 +- 将所有 mesh geometry 统一平移 `-center`，保证拼装后的整体中心落在局部原点。 +- 使用 `pivotGroup.rotation` 和 `pivotGroup.scale`，使用 `poseGroup.position` 做平移。 +- 每次切换细节档位时重建模型，但继承同一份 `modelPose`，并确保新模型仍以整体中心为 pivot。 + +### 3. 鼠标拖拽围绕模型中心旋转 + +- 鼠标左键拖拽只更新 `rotateX/rotateY`，不改变 `translateX/Y/Z`。 +- 旋转继续作用在 `pivotGroup`，而不是同时承担平移的 group。 +- 对 `poseRef.current` 做统一 clamp，保持鼠标、滑块、快捷按钮状态一致。 + +### 4. 坐标系随位姿同步旋转 + +新增一个轻量 SVG 坐标轴组件： + +- 根据 `rotateX/Y/Z` 构造 Three.js `Euler` 和 `Matrix4`。 +- 将 X/Y/Z 三个单位轴向量通过旋转矩阵变换后投影到 2D。 +- 在右下角 SVG 中绘制红色 X、绿色 Y、蓝色 Z 三条轴。 +- 继续显示 X/Y/Z 当前角度数值。 + +### 5. 调整按钮颜色 + +- 将 `重置平移缩放位姿` 的文字颜色改为 `text-blue-600 hover:text-blue-700`，与 `重置旋转位姿` 一致。 + +## 数据流或交互流程 + +1. 用户拖拽鼠标或点击位姿按钮。 +2. `modelPose` 更新并 clamp。 +3. `NativeStlViewer` 的动画循环读取 `poseRef.current`。 +4. `poseGroup` 只应用平移，`pivotGroup` 只应用旋转和缩放。 +5. 右下角坐标轴组件读取同一份 `pose`，同步更新方向。 +6. 切换模型显示细节档时重新请求 STL preview，但模型仍以整体包围盒中心作为 pivot。 + +## 兼容性与回滚方案 + +- 修改仅影响项目库 3D 模型页，不修改 DICOM 后端和 mask 导出。 +- 若 SVG 坐标轴表现不佳，可回滚为静态坐标轴加角度文本。 +- 若新的 viewportRef 清理方式导致 canvas 不显示，可回滚为原始 containerRef，但必须避免清掉 overlay。 + +## 预计文件变更 + +- `WebSite/src/components/ProjectLibrary.tsx` + - 新增 `OrientationGizmo`。 + - `NativeStlViewer` 改用 `viewportRef`。 + - 调整模型中心化和清理逻辑。 + - 调整重置按钮样式。 + +## 人工审核状态 + +- 本次免二次确认，方案写入后直接执行。 + +## 执行结果 + +- 已在 `WebSite/server.ts` 为 STL preview 增加全量包围盒 `bounds`。 +- 已在 `WebSite/src/components/ProjectLibrary.tsx` 使用所有可见 STL 的稳定全量包围盒计算整体中心和缩放基准。 +- 已将右下角静态坐标轴替换为基于 `rotateX/Y/Z` 投影的动态 SVG 坐标轴。 +- 已统一 `重置旋转位姿` 与 `重置平移缩放位姿` 的字体颜色。 diff --git a/工程分析/测试方案-2026-05-07-16-53-23.md b/工程分析/测试方案-2026-05-07-16-53-23.md new file mode 100644 index 0000000..d4c0456 --- /dev/null +++ b/工程分析/测试方案-2026-05-07-16-53-23.md @@ -0,0 +1,51 @@ +# 测试方案 - 2026-05-07-16-53-23 + +## 静态检查 + +1. `git status --short --branch` +2. `cd WebSite && npm run build` +3. `cd WebSite && npm run lint` + +## 单元或集成测试 + +当前项目没有独立单元测试体系，本次采用构建、类型检查、API 冒烟和浏览器人工验证。 + +## 关键业务场景验证 + +1. 打开 `http://192.168.3.11:4000/`。 +2. 进入 `项目库 - 3D 模型`。 +3. 验证模型正常加载，且右下角坐标系可见。 +4. 用滑块或 `±90°` 按钮旋转 X/Y/Z： + - 模型围绕自身中心旋转。 + - 右下角坐标系同步改变方向。 +5. 用鼠标左键拖拽旋转： + - 控件数值同步变化。 + - 旋转中心保持在模型内部几何中心。 +6. 在旋转后切换 `预览/标准/精细/超精细`： + - 模型不发生离谱偏移。 + - 当前旋转位姿继续保留。 +7. 检查两个重置按钮： + - `重置旋转位姿` 和 `重置平移缩放位姿` 字体颜色一致。 + - 重置逻辑仍分别只影响对应位姿维度。 + +## 医学影像数据相关边界验证 + +- 本次不修改 DICOM 解析、切片显示、分割结果导出。 +- 回归确认 `/api/projects` 能正常返回默认项目。 + +## 回归风险 + +- Three.js canvas 挂载容器变更可能导致尺寸计算或 resize 失效。 +- SVG 坐标轴投影使用当前欧拉角，需保证与模型旋转顺序一致。 +- 切换细节档时仍需重新请求 STL preview，加载中的短暂进度变化是预期行为。 + +## 人工审核状态 + +- 本次免二次确认。 + +## 执行记录 + +- `npm run build`：通过。 +- `npm run lint`：通过，实际执行 `tsc --noEmit`。 +- 重新部署后 `curl -I http://127.0.0.1:4000/`：返回 `HTTP/1.1 200 OK`。 +- 重新部署后请求 `会厌.stl` preview：返回 `bounds.min/max`，确认后端已提供稳定全量包围盒。 diff --git a/工程分析/经验记录.md b/工程分析/经验记录.md index eabca40..35c5a29 100644 --- a/工程分析/经验记录.md +++ b/工程分析/经验记录.md @@ -595,3 +595,21 @@ C. 解决问题方案 D. 后续如何避免问题 三维位姿控制应按旋转、平移、缩放分开管理；模型加载后必须先基于所有 STL 的整体包围盒做中心化，再把旋转和缩放应用到中心 pivot 上；涉及交互状态时，滑块、按钮和鼠标操作必须共享同一份 clamp 逻辑。 + +## 2026-05-07-16-53-23 STL 抽样中心漂移与动态坐标轴 + +A. 具体问题 + +用户旋转模型后切换 `预览/标准/精细/超精细`，模型位置会明显偏移；鼠标拖拽旋转时也感觉旋转中心没有落在模型内部；右下角坐标轴不随旋转位姿变化。 + +B. 产生问题原因 + +前端用当前抽样出来的 STL 顶点计算整体包围盒，不同细节档位的抽样集合不同，导致中心点和缩放基准随档位变化；右下角坐标轴是固定 HTML/CSS 图形，没有基于当前旋转矩阵更新。 + +C. 解决问题方案 + +后端 STL preview 在遍历完整二进制 STL 时同步计算全量 `bounds`，前端加载时使用所有可见 STL 的全量包围盒合成稳定中心和尺寸，再把抽样 geometry 平移到该中心；右下角坐标轴改为 SVG，根据 `rotateX/Y/Z` 生成 Three.js 旋转矩阵并投影 X/Y/Z 三轴。 + +D. 后续如何避免问题 + +任何用于配准、视角稳定、旋转中心的几何参数都必须来自全量模型或稳定元数据，不能来自随性能档位变化的抽样数据；坐标系、状态文字和模型实际位姿应共用同一份 pose 状态。 diff --git a/工程分析/需求分析-2026-05-07-16-53-23.md b/工程分析/需求分析-2026-05-07-16-53-23.md new file mode 100644 index 0000000..6ad6a83 --- /dev/null +++ b/工程分析/需求分析-2026-05-07-16-53-23.md @@ -0,0 +1,55 @@ +# 需求分析 - 2026-05-07-16-53-23 + +## 原始需求摘要 + +用户要求继续严格使用代码编纂工作流处理 3D 模型位姿问题，本次无需人工二次确认： + +1. 单击旋转 X/Y/Z 效果正常，但旋转后切换 `模型显示` 的预览/标准/精细/超精细时，模型位置会明显偏移。 +2. 使用鼠标拖拽旋转时，旋转中心感觉没有落在模型内部中心。 +3. 将 `重置平移缩放位姿` 的字体颜色改为与 `重置旋转位姿` 一致。 +4. 右下角坐标系需要随着旋转位姿变化而同步旋转。 + +## 业务目标 + +- 让 3D 模型在切换显示细节档位时保持当前视觉中心稳定，不出现跳走或离谱偏移。 +- 让鼠标拖拽旋转围绕模型自身中心进行，而不是绕画布或偏移点旋转。 +- 保持两个重置按钮视觉层级一致。 +- 右下角坐标系成为真实的当前位姿方向参考。 + +## 输入与输出 + +输入： + +- 用户在 `项目库 - 3D 模型` 中切换模型显示细节档位。 +- 用户通过滑块、快捷按钮、鼠标拖拽调整旋转位姿。 +- 用户点击重置按钮。 + +输出： + +- 切换 `预览/标准/精细/超精细` 后模型仍围绕同一中心展示。 +- 鼠标拖拽旋转时模型围绕内部几何中心旋转。 +- `重置平移缩放位姿` 与 `重置旋转位姿` 文字颜色一致。 +- 右下角 X/Y/Z 坐标系随 `rotateX/Y/Z` 变化同步旋转。 + +## 影响范围 + +- `WebSite/src/components/ProjectLibrary.tsx` + - `NativeStlViewer` 中 Three.js 模型中心化、相机、渲染层级、重载逻辑。 + - 鼠标拖拽旋转的状态更新方式。 + - 右下角坐标系 overlay。 + - 整体位姿按钮样式。 + +## 风险点 + +- 若渲染容器重建时没有清理旧 DOM，可能出现 overlay 被清空或事件丢失。 +- 若每个 STL 文件分别中心化，会破坏拼装关系；必须使用所有可见 STL 的整体包围盒中心。 +- 若切换细节档位后继承了旧平移/缩放，但新模型 baseScale 不一致，视觉上仍可能变化，需要保持统一相机距离和 pivot 中心。 +- HTML 坐标轴用 CSS 旋转只近似表达 3D 方位；更可靠方案是用 SVG 根据旋转矩阵投影三轴。 + +## 待确认问题 + +- 本次用户已明确“需求分析、实现方案、测试方案、执行修改都不用人工二次确认”，因此直接执行。 + +## 人工审核状态 + +- 本次免二次确认。