2026-05-07-16-20-46 修正DICOM比例和3D默认位姿

工程分析/实现方案-2026-05-04-05-56-34.md

@@ -0,0 +1,85 @@
+# 实现方案 - 2026-05-04-05-56-34
+
+## 修改目标
+
+修正 DICOM 矢状面/冠状面的物理比例，新增 DICOM 详细信息查询；简化 3D 模型显示控制，加入更高实体化档位，并实现画布内鼠标旋转、平移、滚轮缩放且同步整体位姿控件。
+
+## 涉及路径
+
+- `WebSite/server.ts`
+- `WebSite/src/types.ts`
+- `WebSite/src/lib/api.ts`
+- `WebSite/src/components/ProjectLibrary.tsx`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+### 1. DICOM 空间信息解析
+
+- 扩展后端 DICOM tag 解析：
+  - Pixel Spacing `(0028,0030)`：单张切片内行/列像素实际距离。
+  - Slice Thickness `(0018,0050)`。
+  - Spacing Between Slices `(0018,0088)`。
+  - Image Position Patient `(0020,0032)`：优先用相邻切片空间位置差计算真实切片间距。
+  - Patient、Study、Series、Modality、Manufacturer、Rows、Columns、Window、Rescale 等基础信息。
+- 在 DICOM volume cache 中保存 `rowSpacing`、`columnSpacing`、`sliceSpacing`。
+
+### 2. 多平面物理比例重采样
+
+- 当前矢状面/冠状面生成后先得到原始矩阵。
+- 根据物理尺寸计算目标比例：
+  - 横向：`切片数 * sliceSpacing`
+  - 矢状面纵向：`rows * rowSpacing`
+  - 冠状面纵向：`columns * columnSpacing`
+- 以较小物理间距作为输出采样单位，将重建图像最近邻重采样到接近真实物理比例的像素宽高。
+- 返回 `spacing` 和 `physicalSize`，供前端信息展示。
+
+### 3. DICOM 详细信息查询
+
+- 新增后端接口：`GET /api/projects/:projectId/dicom-info`。
+- 返回默认项目第一张 DICOM 与序列聚合信息：
+  - patient、study、series、image、window、spacing、sequence、source 等分组。
+- 前端 DICOM 影像页新增“信息”按钮，打开弹窗/面板展示基本信息、像素间距、切片间距、图像矩阵、物理尺寸、文件数量、首尾文件等。
+
+### 4. 3D 模型控制简化与增强
+
+- 去掉“白色实体”开关和“自动旋转”开关。
+- 默认模型不自动旋转，正向放置。
+- 实体化档位改为：`预览 / 标准 / 精细 / 超精细`。
+- 后端 STL preview 抽样上限提升到 `72000`，前端超精细档使用 `72000`。
+- 重置位姿按钮移动到“整体位姿”标题右侧。
+
+### 5. 鼠标/滚轮位姿交互
+
+- 在 `NativeStlViewer` 容器上监听 pointer 和 wheel：
+  - 左键拖拽：旋转 X/Y。
+  - 右键或 Shift+拖拽：平移 X/Y。
+  - 滚轮：缩放。
+- 交互时通过 `onPoseChange` 回写 React state，使滑块数值同步变化。
+- 禁用浏览器右键菜单，避免右键平移时弹出菜单。
+- 位姿仍作用于整体 group，不改变 STL 构件相对位置。
+
+## 数据流或交互流程
+
+1. 前端请求 DICOM preview，后端解析/缓存体数据和空间信息，按真实物理比例输出矢状面/冠状面。
+2. 前端点击 DICOM 信息按钮，请求 dicom-info，弹窗展示元数据和空间参数。
+3. 前端进入 3D 模型页，按当前实体化档位请求 STL preview。
+4. 用户拖拽/滚轮操作画布，`NativeStlViewer` 更新位姿并回写父组件，右侧滑块同步变化。
+5. 用户点击重置位姿，模型回到默认正向摆放。
+
+## 兼容性与回滚方案
+
+- 若某些 DICOM tag 缺失，后端使用默认 spacing `1mm`，并在详情中展示“未知/默认”。
+- 多平面重采样使用最近邻，避免引入新依赖；如比例异常可回滚到原始矩阵输出。
+- 超精细档可能更慢，但保留低档位可回退。
+- 鼠标交互只作用于项目库 3D 视图，不影响 DICOM、导出和逆向工作区。
+
+## 预计文件变更
+
+- 后端：DICOM metadata/spacing 解析、多平面重采样、dicom-info API、STL 上限。
+- 前端：DICOM 信息弹窗、3D 控件重构、鼠标交互回写位姿。
+- 文档：测试结果和经验记录追加。
+
+## 人工审核状态
+
+用户已明确本次无需人工二次确认，文档落地后直接执行。

工程分析/实现方案-2026-05-07-16-20-46.md

@@ -0,0 +1,46 @@
+# 实现方案 - 2026-05-07-16-20-46
+
+## 修改目标
+
+修正项目库 3D 模型页默认位姿，使初次打开和点击“重置位姿”都恢复到类似参考图的正常俯视/正向姿态。
+
+## 涉及路径
+
+- `WebSite/src/components/ProjectLibrary.tsx`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+1. 默认位姿
+   - 保持 `defaultModelPose` 的旋转、平移和缩放为中性值，避免默认滑块显示已经偏转。
+   - 重置位姿继续设置为 `defaultModelPose`。
+
+2. 默认相机
+   - 将 `NativeStlViewer` 默认 camera 从斜向等距视角调整为更接近参考图的俯视视角。
+   - 使用 `camera.position.set(0, 0, 6)`、`camera.up.set(0, 1, 0)`、`camera.lookAt(0, 0, 0)`，让模型以 XY 平面正向进入视野。
+   - resize 后保留相机方向。
+
+3. 视觉验证
+   - 进入 3D 模型页后，模型不再以明显斜向等距视角显示。
+   - 通过鼠标/滚轮改变位姿后，点击重置回到标准默认视角。
+
+4. 与上一轮未提交改动合并
+   - 保留并验证 DICOM 空间比例、DICOM 信息面板、3D 超精细档、鼠标交互同步等改动。
+
+## 数据流或交互流程
+
+用户进入项目库 -> 点击 3D 模型 -> 前端创建 Three.js camera 并使用默认俯视相机 -> STL group 居中缩放 -> 默认位姿滑块为 0/0/0 与缩放 1 -> 用户交互后可点击重置恢复。
+
+## 兼容性与回滚方案
+
+- 如果参考视角需要再微调，可只调整 camera position/up，不影响 STL 数据和后端接口。
+- 回滚可恢复相机到原先 `(4.5, 3.5, 5)` 等距视角。
+
+## 预计文件变更
+
+- `ProjectLibrary.tsx` 中相机默认位置和说明文字。
+- `经验记录.md` 追加默认位姿经验。
+
+## 人工审核状态
+
+用户已明确本次无需人工二次确认，文档落地后直接执行。

工程分析/测试方案-2026-05-04-05-56-34.md

@@ -0,0 +1,68 @@
+# 测试方案 - 2026-05-04-05-56-34
+
+## 静态检查
+
+- 执行 `npm run lint`，确认 TypeScript 类型检查通过。
+- 执行 `npm run build`，确认生产构建通过。
+
+## 集成测试
+
+- DICOM preview API：
+  - 验证 axial/sagittal/coronal 均返回。
+  - 验证 sagittal/coronal 返回的 `spacing`、`physicalSize`、`width/height` 合理。
+- DICOM info API：
+  - 验证返回 patient/study/series/image/window/spacing/sequence/source 分组。
+  - 验证 Pixel Spacing、Slice Spacing、Rows、Columns、文件数量等信息存在。
+- STL preview API：
+  - 验证 `limit=6000/16000/36000/72000` 返回不报错。
+
+## 关键业务场景验证
+
+- DICOM 影像页：
+  - 矢状面/冠状面不再异常扁平。
+  - 点击信息按钮弹出详情面板。
+  - 详情面板展示像素间距、切片间距、切片厚度、矩阵、物理尺寸。
+- 3D 模型页：
+  - 不再显示白色实体和自动旋转开关。
+  - 实体化档位包含“超精细”。
+  - 默认正向静止摆放。
+  - 重置位姿按钮位于“整体位姿”标题右侧。
+  - 左键拖拽旋转，右键/Shift 拖拽平移，滚轮缩放。
+  - 画布交互后右侧整体位姿滑块数值同步变化。
+
+## 医学影像数据相关边界验证
+
+- DICOM tag 缺失时使用 fallback，不导致接口 500。
+- 切片间距优先 Image Position Patient 差值，再 fallback 到 Spacing Between Slices、Slice Thickness、1mm。
+- 多平面物理比例不改变切片总数和当前切片编号逻辑。
+
+## 回归风险
+
+- 物理比例重采样可能增大图像尺寸，需要限制最大输出尺寸。
+- 超精细 STL 预览可能变慢，需要保留低档位。
+- 鼠标交互需避免页面滚动和右键菜单干扰。
+
+## 人工审核状态
+
+用户已明确本次无需人工二次确认，按本方案执行验证。
+
+## 执行结果
+
+- `npm run lint`：通过。
+- `npm run build`：通过；Vite 仍提示 bundle 超过 500 kB，为现有 Three.js/Recharts 依赖导致的非阻断警告。
+- DICOM preview API 验证：
+  - `sagittal` 返回 `384x421`，`spacing.slice=1mm`、`displayY=0.78125mm`，物理尺寸约 `300mm x 328.906mm`。
+  - `coronal` 返回 `384x512`，`spacing.slice=1mm`、`displayY=0.78125mm`，物理尺寸约 `300mm x 400mm`。
+- DICOM info API 验证：
+  - 返回患者 `WANG FANG`、`CT`、文件数 `300`、矩阵 `512x512`。
+  - 返回 `row/column spacing=0.781mm`、`slice=1mm`，来源 `ImagePositionPatient`。
+  - 返回物理尺寸 `400mm x 400mm x 299mm`。
+- STL preview API 验证：
+  - `limit=6000/16000/36000/72000` 均返回，首个 STL 在超精细档达到原始 `17384` 个三角面。
+- 无头 Chrome 前端验证：
+  - DICOM 信息按钮存在。
+  - DICOM 信息弹窗存在，并展示像素行间距、切片间距、物理尺寸。
+  - 3D 页存在“超精细”，已移除“白色实体”和“自动旋转”。
+  - 默认位姿滑块为 `0,0,0 / 0,0,0 / 1`。
+  - 页面包含“左键旋转”和“滚轮缩放”提示。
+- 已重新部署到 `http://192.168.3.11:4000/`，tmux 会话：`revoxelseg-dicom`。

工程分析/测试方案-2026-05-07-16-20-46.md

@@ -0,0 +1,45 @@
+# 测试方案 - 2026-05-07-16-20-46
+
+## 静态检查
+
+- 执行 `npm run lint`。
+- 执行 `npm run build`。
+
+## 集成测试
+
+- 验证 STL preview API 在 `6000/16000/36000/72000` 档位下可返回。
+- 验证 DICOM preview 与 DICOM info API 仍可返回，确保上一轮相关改动未受影响。
+
+## 前端验证
+
+- 无头 Chrome 登录后进入项目库 3D 模型页：
+  - 控件包含“超精细”，不包含“白色实体/自动旋转”。
+  - 默认位姿滑块为旋转 0、平移 0、缩放 1。
+  - canvas 非空。
+- 模拟拖拽/滚轮后检查位姿数值变化。
+- 点击重置位姿后检查数值恢复默认。
+
+## 回归风险
+
+- 无头 Chrome 可能走二维兜底预览，但仍可验证控件和位姿状态。
+- 真实 WebGL 视角需要用户目视确认参考图匹配度；本次以默认俯视相机为工程修正。
+
+## 人工审核状态
+
+用户已明确本次无需人工二次确认，按本方案执行验证。
+
+## 执行结果
+
+- `npm run lint`：通过。
+- `npm run build`：通过；Vite 大 chunk 体积提示为非阻断警告。
+- 已将 3D 默认相机从斜向等距视角改为俯视相机：`camera.position=(0,0,6)`，`lookAt(0,0,0)`。
+- 无头 Chrome 前端验证：
+  - 3D 页 canvas 非空，尺寸 `1172x567`。
+  - 默认位姿滑块为 `0,0,0 / 0,0,0 / 1`。
+  - “超精细”存在，“白色实体/自动旋转”不存在。
+  - DICOM 信息面板仍可打开。
+- 关联 API 回归验证：
+  - DICOM 多平面物理比例接口正常。
+  - DICOM 信息接口正常。
+  - STL 四档预览接口正常。
+- 已重新部署到 `http://192.168.3.11:4000/`，tmux 会话：`revoxelseg-dicom`。

工程分析/经验记录.md

@@ -505,3 +505,75 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 页面级标题应由全局导航或内容区二选一承担；当前对象信息只保留在最醒目的单一位置，减少重复文本造成的噪声。
+
+## 2026-05-04-05-56-34 DICOM 多平面物理比例
+
+A. 具体问题
+
+矢状面和冠状面只按像素矩阵重建，没有考虑切片间距与单张图像内像素间距，导致图像观感过扁。
+
+B. 产生问题原因
+
+后端重建平面时直接使用 `切片数 x 行/列数` 作为输出尺寸，默认把切片方向和像素方向当成等距网格。
+
+C. 解决问题方案
+
+解析 `PixelSpacing`、`SliceThickness`、`SpacingBetweenSlices` 和 `ImagePositionPatient`；优先用相邻 `ImagePositionPatient` 距离估计真实切片间距，并按 `sliceSpacing` 与像素间距做最近邻重采样，返回 spacing 与 physicalSize。
+
+D. 后续如何避免问题
+
+医学影像任意重建平面都必须带着物理 spacing 计算，不应只看像素数量；当 DICOM tag 缺失时要明确 fallback 来源。
+
+## 2026-05-04-05-56-34 DICOM 信息面板
+
+A. 具体问题
+
+前端缺少 DICOM 详细信息查询，用户无法看到像素间距、切片间距等判断空间比例的关键信息。
+
+B. 产生问题原因
+
+原有 API 只服务于灰度预览，没有暴露 DICOM 元数据和序列级空间统计。
+
+C. 解决问题方案
+
+新增 `GET /api/projects/:projectId/dicom-info`，返回患者、检查、序列、图像矩阵、窗宽窗位、spacing、物理尺寸和首尾切片位置；前端增加“信息”按钮和 DICOM 详细信息弹窗。
+
+D. 后续如何避免问题
+
+影像显示功能旁应提供可审计的元数据入口，特别是任何影响几何比例、配准和导出的空间参数。
+
+## 2026-05-04-05-56-34 3D 模型交互控制简化
+
+A. 具体问题
+
+3D 模型页存在不需要的白色实体模式和自动旋转，同时缺少更高细节档位；鼠标拖拽、滚轮等画布操作不能同步到右侧位姿控件。
+
+B. 产生问题原因
+
+前一版位姿控制主要依赖右侧滑块，画布本身只负责渲染；显示开关也偏演示型，没有完全贴近用户的实际浏览习惯。
+
+C. 解决问题方案
+
+移除白色实体和自动旋转；新增“超精细”档，后端 STL 抽样上限提升到 `72000`；画布监听左键旋转、右键或 Shift 平移、滚轮缩放，并回写整体位姿 state。
+
+D. 后续如何避免问题
+
+三维浏览默认应遵循常见交互习惯，UI 控件与鼠标操作必须共享同一份状态；演示型开关要及时剔除，避免干扰核心工作流。
+
+## 2026-05-07-16-20-46 3D 默认位姿
+
+A. 具体问题
+
+网页端 3D 模型默认位姿看起来不像用户参考图中的正常位姿，打开后更像斜向观察。
+
+B. 产生问题原因
+
+默认 Three.js 相机使用 `(4.5, 3.5, 5)` 斜向等距视角，而用户期望的是接近俯视/轴向的标准视角。
+
+C. 解决问题方案
+
+将默认相机改为俯视方向：`camera.up=(0,1,0)`、`camera.position=(0,0,6)`、`lookAt(0,0,0)`；保留默认位姿滑块为旋转 0、平移 0、缩放 1，重置位姿也回到同一基准。
+
+D. 后续如何避免问题
+
+默认位姿应该由相机预设和模型位姿共同定义；如果用户提供标准视图截图，应优先匹配相机视角，再决定是否需要固定模型 Z 轴校正。

工程分析/需求分析-2026-05-04-05-56-34.md

@@ -0,0 +1,49 @@
+# 需求分析 - 2026-05-04-05-56-34
+
+## 原始需求摘要
+
+用户要求严格使用代码编纂工作流，但本次需求分析、实现方案、测试方案、执行修改均不需要人工二次确认。当前需求包括：
+
+1. DICOM 矢状面、冠状面需要根据切片间距、单张切片内像素间距进行真实物理比例计算，当前图像看起来过扁。
+2. DICOM 影像增加详细信息查询按钮，提取 DICOM 基本信息，并列出像素间距、切片间距等必要的新信息。
+3. 3D 模型去掉白色实体模式和自动旋转；实体化程度在“预览、标准、精细”基础上再增加一个更细致档位；默认正向摆放；重置位姿放到“整体位姿”标题右侧；支持在图中用鼠标/滚轮操作旋转、平移、缩放，并把操作变化映射回整体位姿控件。
+
+## 业务目标
+
+DICOM 多平面重建应尽量符合真实空间比例，辅助用户正确理解矢状面和冠状面的解剖形态；DICOM 信息查询应展示基础元数据和关键空间参数；3D 模型交互应贴近常见三维软件操作习惯，减少无用开关，增强手动操控。
+
+## 输入与输出
+
+- 输入：
+  - `Head_CT_DICOM/` 中 DICOM 序列及其 DICOM tag。
+  - `Head_CT_ReConstruct/` 中 STL 模型。
+  - 用户鼠标拖拽、滚轮、位姿滑块操作。
+- 输出：
+  - 物理比例修正后的矢状面/冠状面预览。
+  - DICOM 详细信息面板。
+  - 调整后的 3D 实体化档位和手动位姿交互。
+
+## 影响范围
+
+- `WebSite/server.ts`
+  - 解析 Pixel Spacing、Slice Thickness、Spacing Between Slices、Image Position Patient 等 DICOM 空间信息。
+  - 多平面重建按物理比例重采样。
+  - 新增 DICOM 信息 API。
+- `WebSite/src/types.ts`
+  - 补充 DICOM 预览空间信息和详情信息类型。
+- `WebSite/src/lib/api.ts`
+  - 增加 DICOM 详情接口。
+- `WebSite/src/components/ProjectLibrary.tsx`
+  - 增加 DICOM 信息按钮/弹窗。
+  - 修改 3D 模型控件和鼠标交互。
+
+## 风险点
+
+- 当前 DICOM 解析器是轻量解析器，不覆盖所有 DICOM 传输语法；本次仍以现有数据集可解析为目标。
+- 多平面物理重采样会改变返回图像尺寸，前端布局需要继续保持自适应。
+- 高实体化档位会显著增加 STL 预览顶点数和浏览器渲染压力。
+- 自研鼠标旋转/平移/滚轮缩放需要与位姿滑块状态双向同步，避免 UI 状态漂移。
+
+## 待确认问题
+
+用户已明确本次无需人工二次确认，按合理工程假设直接执行。

工程分析/需求分析-2026-05-07-16-20-46.md

@@ -0,0 +1,34 @@
+# 需求分析 - 2026-05-07-16-20-46
+
+## 原始需求摘要
+
+用户要求严格使用代码编纂工作流，本次无需人工二次确认。用户指出正常情况下的 3D 模型默认位姿应类似图 1：模型以更标准的正向/俯视视角展示，而当前网页端默认位姿感觉不正确。
+
+## 业务目标
+
+项目库 3D 模型页首次打开时，应直接呈现接近用户参考图的正常默认视角，避免用户进入页面后看到斜向、侧向或难以判断解剖结构方向的模型姿态。重置位姿也应恢复到同一标准默认视角。
+
+## 输入与输出
+
+- 输入：`Head_CT_ReConstruct/` 中 STL 模型，以及用户提供的标准位姿参考截图。
+- 输出：调整后的默认相机视角/默认整体位姿，确保默认和重置位姿一致。
+
+## 影响范围
+
+- `WebSite/src/components/ProjectLibrary.tsx`
+  - `defaultModelPose`
+  - `NativeStlViewer` 的默认 camera position / lookAt / up 方向
+  - 可能涉及位姿滑块初始值与重置逻辑
+- 延续上一轮未提交相关改动：
+  - DICOM 空间比例和信息接口
+  - 3D 模型超精细档、鼠标交互和位姿同步
+
+## 风险点
+
+- STL 坐标系不一定与 Three.js 默认相机坐标完全一致，需要通过合理默认 camera 与旋转组合匹配参考图。
+- 若只改 camera 不改 reset，用户重置后仍可能回到旧姿态。
+- 若只改 group rotation 不改相机，鼠标交互与滑块显示可能不直观。
+
+## 待确认问题
+
+用户已明确本次无需人工二次确认，按合理工程假设直接执行。参考图呈现为近似俯视/轴向视角，因此默认采用俯视相机和零位姿组合。