2026-05-04-05-41-22 增强3D实体预览和位姿控制

工程分析/实现方案-2026-05-04-05-41-22.md

@@ -0,0 +1,82 @@
+# 实现方案 - 2026-05-04-05-41-22
+
+## 修改目标
+
+在不直接加载全部原始 STL 的前提下，提高 3D 模型预览的实体感，并加入整体位姿控制；改进 DICOM 长按切片时的连续图像反馈；精简逆向工作区重复标题与项目描述。
+
+## 涉及路径
+
+- `WebSite/src/components/ProjectLibrary.tsx`
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `WebSite/server.ts`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+### 1. 3D 模型实体化程度
+
+- 在项目库 3D 模型页增加“实体化程度”控制，建议分为：
+  - `预览`：维持较低三角面抽样，优先速度。
+  - `标准`：提高抽样数量，呈现连续表面。
+  - `精细`：进一步提高抽样数量，但仍保留上限防止卡顿。
+- 将当前固定 `/preview?limit=6000` 改为根据实体化程度动态请求，例如 `6000 / 16000 / 36000`。
+- Three.js 渲染继续使用 `MeshStandardMaterial`，但新增：
+  - `flatShading: false`
+  - 更强的环境光、主光和边缘光。
+  - 可选整体白色实体显示模式，让模型更接近用户参考图。
+- 保留每个 STL 构件的颜色和透明度控制，新增“整体白色实体”开关时临时覆盖颜色为白/灰，不破坏原配置。
+
+### 2. 3D 模型位姿控制
+
+- 在 3D 模型左侧画布上方或右侧面板增加整体位姿控制：
+  - 旋转 X/Y/Z 滑块，范围 `-180° ~ 180°`。
+  - 平移 X/Y/Z 微调，范围建议 `-2 ~ 2`。
+  - 缩放滑块，范围建议 `0.5 ~ 2`。
+  - 重置按钮。
+- 将自动旋转改为可开关；当用户调整位姿时，自动旋转默认关闭，避免控制冲突。
+- 将位姿状态传入 `NativeStlViewer`，渲染循环中应用到 group。
+
+### 3. DICOM 长按连续图像变化
+
+- 当前 `startSliceStep` 只是连续改变 `sliceIndex`，图像依赖 API 响应更新。为增强“动起来”的感觉：
+  - 将步进间隔保持在 `90~120ms`，同时在请求期间显示轻量切片过渡效果。
+  - 增加 `latestPreviewRequestRef` 或请求序列号，确保旧请求返回时不会覆盖新切片。
+  - 在 `sliceIndex` 变化时，立即更新右下角切片文字和 canvas 容器的轻微淡入/亮度变化。
+  - 若接口响应较慢，保留上一帧图像并叠加“正在切换”状态，避免画面停滞误解。
+
+### 4. 逆向工作区信息精简
+
+- 删除 `ReverseWorkspace` 页面内 `h2` 标题“逆向工作区”，保留全局 header 的标题。
+- 删除页面内副标题中的上方“当前项目：xxx”文本。
+- 保留下方标签行：
+  - `当前项目：头部 CT 模型逆向体素化演示`
+  - `DICOM 300`
+  - `STL 9`
+- 将标签字号从 `text-[11px]` 提升为 `text-sm` 或 `text-[13px]`，内边距加大，提高可读性。
+
+## 数据流或交互流程
+
+1. 用户进入项目库 3D 模型页。
+2. 前端根据实体化程度选择 STL preview limit 请求后端抽样数据。
+3. Three.js 将各 STL 抽样三角面生成实体 mesh，按当前实体化、颜色、透明度、白色实体模式、整体位姿状态渲染。
+4. 用户拖动位姿控制滑块，前端立即更新 group 的 rotation / position / scale。
+5. 用户在 DICOM 页长按切片按钮，前端连续改变 `sliceIndex`，后端返回切片预览，前端按最新请求序号绘制最新帧。
+6. 用户进入逆向工作区，只看到全局 header 的“逆向工作区”和加大后的当前项目标签行。
+
+## 兼容性与回滚方案
+
+- 实体化程度默认使用“标准”，若性能不佳可切回“预览”。
+- WebGL 不可用时继续使用二维投影兜底，实体化和位姿控制主要作用于 WebGL 路径。
+- 若提高抽样上限导致性能问题，可只回滚实体化程度 limit 参数，不影响项目列表、DICOM 和导出功能。
+- 逆向工作区文案调整为纯 UI 变更，可直接回滚组件 JSX。
+
+## 预计文件变更
+
+- `ProjectLibrary.tsx`：新增 3D 渲染控制状态、实体化程度、位姿控制 UI、DICOM 请求序号和切片过渡反馈。
+- `server.ts`：可能提高 STL preview 的安全上限。
+- `ReverseWorkspace.tsx`：删除重复标题/副标题，调整标签字号。
+- `经验记录.md`：执行后追加本次经验。
+
+## 人工审核状态
+
+用户已回复“确认方案”，按已确认方案执行项目业务代码修改。

工程分析/测试方案-2026-05-04-05-41-22.md

@@ -0,0 +1,73 @@
+# 测试方案 - 2026-05-04-05-41-22
+
+## 静态检查
+
+- 执行 `npm run lint`，确认 TypeScript 类型检查通过。
+- 执行 `npm run build`，确认生产构建通过。
+
+## 集成测试
+
+- 调用 STL preview API：
+  - `limit=6000`
+  - `limit=16000`
+  - `limit=36000`
+- 确认返回顶点数量随实体化程度增加，且响应不报错。
+- 调用 DICOM preview API，确认连续请求不同 slice 时均可返回合理 `slice/total/width/height`。
+
+## 关键业务场景验证
+
+### 3D 模型页
+
+- 默认进入后模型可见。
+- 实体化程度从“预览”切换到“标准/精细”后，模型表面更连续，而不是纯点云感。
+- 开启“整体白色实体”后，显示效果接近参考图的灰白实体模型。
+- 调整旋转 X/Y/Z、平移 X/Y/Z、缩放后，模型位姿即时变化。
+- 点击重置后，位姿恢复默认。
+- 隐藏/显示单个 STL、调整颜色、透明度仍正常。
+- WebGL 不可用时二维兜底仍可见，不出现空白画布。
+
+### DICOM 切片页
+
+- 长按上箭头时，切片编号连续增加，图像连续变化。
+- 长按下箭头时，切片编号连续减少，图像连续变化。
+- 快速连续切换时，不出现旧请求覆盖新切片的错帧。
+- 到达首帧/末帧时不越界。
+
+### 逆向工作区
+
+- 顶部全局 header 仍显示“逆向工作区”。
+- 页面内容区不再重复显示第二个“逆向工作区”。
+- 页面内容区不再出现上方重复“当前项目：xxx”副标题。
+- 项目标签行字号变大，且显示当前项目、DICOM 数量、STL 数量。
+
+## 医学影像数据相关边界验证
+
+- DICOM 连续切片时保留当前 plane、mode、rotation 状态。
+- STL 实体化程度不改变各构件的原始相对空间关系，只改变抽样密度和显示材质。
+- 位姿控制作用于整体模型 group，不改变单个 STL 的相对拼装位置。
+
+## 回归风险
+
+- 高实体化程度可能提升渲染压力，需要在 UI 中保留“预览”档位。
+- DICOM 连续请求可能造成响应乱序，需要请求序号保护。
+- 逆向工作区删除标题后仍需保证用户知道当前处于哪个页面，依赖全局 header。
+
+## 人工审核状态
+
+用户已回复“确认方案”，按本测试方案执行验证。
+
+## 执行结果
+
+- `npm run lint`：通过。
+- `npm run build`：通过；Vite 仍提示 bundle 超过 500 kB，为现有 Three.js/Recharts 依赖带来的非阻断警告。
+- STL preview API 验证：
+  - `limit=6000`：返回 `5795` 个抽样三角面、`52155` 个顶点数值。
+  - `limit=16000`：返回 `8692` 个抽样三角面、`78228` 个顶点数值。
+  - `limit=36000`：返回 `17384` 个抽样三角面、`156456` 个顶点数值。
+- DICOM 连续切片 API 验证：`slice=120~124` 均返回 `512x512`、`total=300`，文件名按 `121.dcm` 到 `125.dcm` 连续变化。
+- 无头 Chrome 前端验证：
+  - 3D 模型页存在“模型显示、预览、标准、精细、白色实体、整体位姿、旋转 X、平移 Z、缩放”等控件。
+  - WebGL 不可用场景仍生成二维预览 canvas，尺寸 `1172x567`。
+  - 逆向工作区正文不再重复页面标题：`逆向工作区` 只出现 1 次。
+  - `当前项目：头部 CT 模型逆向体素化演示` 只出现 1 次，并保留 `DICOM 300`、`STL 9`。
+- 已重新部署到 `http://192.168.3.11:4000/`，tmux 会话：`revoxelseg-dicom`。

工程分析/经验记录.md

@@ -451,3 +451,57 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 工作区首屏应优先显示“当前正在处理哪个项目”和“下一步操作”，底层路径只在诊断、详情或设置区域出现。
+
+## 2026-05-04-05-41-22 STL 实体化程度与位姿控制
+
+A. 具体问题
+
+3D 模型虽然可以显示，但抽样三角面过少时视觉上偏稀疏，用户希望更接近白色实体 STL 拼装效果，并且能够手动调整整体模型位姿。
+
+B. 产生问题原因
+
+项目库为了避免大体积 STL 造成浏览器卡顿，使用固定低抽样量预览；同时模型 group 只有自动旋转，没有暴露旋转、平移、缩放等用户控制。
+
+C. 解决问题方案
+
+新增“预览/标准/精细”实体化程度，后端 STL preview 抽样上限提升到 `36000`；前端新增白色实体模式、自动旋转开关、旋转 X/Y/Z、平移 X/Y/Z、缩放和重置位姿控制，所有位姿变换作用在整体 group 上。
+
+D. 后续如何避免问题
+
+大模型预览应提供性能档位，而不是在“速度”和“实体感”之间固定取舍；位姿控制必须作用于整体模型容器，避免破坏各 STL 构件的相对拼装关系。
+
+## 2026-05-04-05-41-22 DICOM 长按切片反馈
+
+A. 具体问题
+
+长按切片上下箭头时，编号会变化，但用户希望图像也有连续变化的运动感。
+
+B. 产生问题原因
+
+前端连续修改 `sliceIndex` 后依赖异步 API 返回更新图像，缺少请求乱序保护和切片切换中的视觉反馈。
+
+C. 解决问题方案
+
+将长按步进间隔缩短到 `95ms`，为 DICOM preview 请求加入递增序号，只允许最新请求更新画面；切片切换时给 canvas 容器增加轻微缩放、亮度和状态提示。
+
+D. 后续如何避免问题
+
+连续浏览医学影像时，必须同时处理“状态连续变化”“图像异步返回”和“旧请求覆盖新请求”三个问题；前端应保留上一帧并提供明确切换反馈。
+
+## 2026-05-04-05-41-22 逆向工作区标题去重
+
+A. 具体问题
+
+逆向工作区同时出现全局标题和页面内标题，也重复显示“当前项目”。
+
+B. 产生问题原因
+
+页面局部标题和全局 header 没有统一职责，项目上下文既出现在副标题，也出现在标签行。
+
+C. 解决问题方案
+
+保留全局 header 的“逆向工作区”，删除页面内重复标题和副标题；保留并放大当前项目、DICOM 数量、STL 数量标签。
+
+D. 后续如何避免问题
+
+页面级标题应由全局导航或内容区二选一承担；当前对象信息只保留在最醒目的单一位置，减少重复文本造成的噪声。

工程分析/需求分析-2026-05-04-05-41-22.md

@@ -0,0 +1,51 @@
+# 需求分析 - 2026-05-04-05-41-22
+
+## 原始需求摘要
+
+用户基于当前项目库和逆向工作区提出 3 项调整：
+
+1. 3D 模型已有显示效果，但希望更接近参考图中的实体 STL 拼装效果，而不是现在偏点云/稀疏预览；同时需要可以调整整体 3D 模型位姿。
+2. DICOM 切片长按上下箭头时，图片也要连续跟随变化，形成明显的图像运动感。
+3. 逆向工作区中存在重复信息：
+   - 有两个“当前项目：头部 CT 模型逆向体素化演示”，删除上方那个。
+   - 有两个“逆向工作区”，删除下方那个。
+   - “当前项目：头部 CT 模型逆向体素化演示  DICOM 300  STL 9”字号调大。
+
+## 业务目标
+
+项目库的 3D 模型视图应能更像真实 STL 实体表面预览，用户可通过控件调整模型整体姿态，便于对照参考图观察头颅、气管、肿瘤等结构；DICOM 切片浏览需要有连续播放/滚动的即时反馈；逆向工作区标题区应减少重复文本，强化当前项目上下文。
+
+## 输入与输出
+
+- 输入：
+  - `Head_CT_ReConstruct/` 中的 STL 文件。
+  - `Head_CT_DICOM/` 中的 DICOM 序列。
+  - 用户在 UI 上的切片长按、实体化程度、位姿调节输入。
+- 输出：
+  - 3D 模型实体化程度控制与位姿控制 UI。
+  - 长按切片时连续请求并绘制 DICOM 图像。
+  - 精简后的逆向工作区头部信息。
+
+## 影响范围
+
+- `WebSite/src/components/ProjectLibrary.tsx`
+  - STL 预览渲染方式、实体化/点云程度控制、整体位姿控制。
+  - DICOM 长按切片刷新节奏与视觉反馈。
+- `WebSite/src/components/ReverseWorkspace.tsx`
+  - 删除页面内重复标题和上方重复“当前项目”描述。
+  - 调整项目状态标签字号。
+- `WebSite/src/App.tsx`
+  - 保留全局 header 的“逆向工作区”，页面内不再重复。
+- `WebSite/server.ts`
+  - 如需提高实体化程度，可能调整 STL 预览抽样上限或返回更多三角面数据。
+
+## 风险点
+
+- STL 原始文件总量较大，提高实体化程度会增加网络传输和浏览器渲染压力。
+- 如果直接加载完整 STL，可能再次导致页面卡顿或空白；应采用可调采样密度或分级预览。
+- 长按切片连续刷新会增加 DICOM preview API 请求频率，需要节流并避免响应乱序。
+- 位姿控制需要避免和自动旋转逻辑互相冲突。
+
+## 待确认问题
+
+本次用户没有明确跳过二次确认，因此按照工作流，需等待实现方案和测试方案审核确认后再修改业务代码。