first commit

使用说明.md

@@ -0,0 +1,191 @@
+# 头颈部 CT 仰头形变工具使用说明
+
+## 1. 工具用途
+
+本工具用于将一组头颈部 CT DICOM 序列模拟成“仰头/后伸”状态，并输出新的 DICOM 序列和一张前后对比图。
+
+适用场景：
+
+- PPT 展示
+- 方法演示
+- 头颈部体位变化的初步可视化
+- 插管体位下的仰头效果模拟
+
+注意：本工具生成的是模拟形变结果，不应直接作为临床诊断或治疗计划依据。
+
+## 2. 文件说明
+
+用户版文件夹内包含：
+
+- `启动头颈CT仰头形变工具.bat`：双击启动程序
+- `head_extension_app.py`：主程序
+- `generate_head_extension_video.py`：视频生成脚本
+- `video_generator_app.py`：视频生成图形界面
+- `requirements.txt`：Python 依赖包列表
+- `使用说明.md`：本说明文档
+- `生成0到20度仰头视频.bat`：生成角度连续变化视频
+
+## 3. 运行环境
+
+需要安装 Python 3.8 或以上版本。
+
+首次使用前，在当前文件夹打开命令行，执行：
+
+```bat
+pip install -r requirements.txt
+```
+
+如果已经在原电脑环境中配置好依赖，可直接双击启动。
+
+## 4. 启动程序
+
+双击：
+
+```bat
+启动头颈CT仰头形变工具.bat
+```
+
+若窗口没有打开，请在命令行中运行：
+
+```bat
+python head_extension_app.py
+```
+
+这样可以看到具体报错信息。
+
+## 5. 输入数据要求
+
+请选择一个只包含同一套 CT 序列 `.dcm` 文件的文件夹。
+
+建议：
+
+- 使用轴位 CT 序列
+- 同一文件夹内不要混入多个 series
+- 文件扩展名最好为 `.dcm`
+- 推荐使用层厚较薄、覆盖完整头颈部的序列
+
+## 6. 操作步骤
+
+1. 点击“选择”，选择输入 DICOM 文件夹。
+2. 点击“选择”，选择输出文件夹。
+3. 调节“仰头角度”滑块。
+4. 调节“过渡平滑宽度”滑块。
+5. 点击“更新预览”查看快速示意。
+6. 点击“生成形变 DICOM”。
+7. 等待完成提示。
+
+## 7. 参数说明
+
+### 仰头角度
+
+控制头部后伸程度。
+
+建议范围：
+
+- `5°`：轻微仰头
+- `10°-15°`：较明显仰头
+- `20°`：展示效果较强
+
+### 过渡平滑宽度
+
+控制头部旋转区域和肩颈固定区域之间的过渡范围。
+
+建议：
+
+- 默认 `90`
+- 如果连接处仍有割裂感，可增大到 `110-140`
+- 如果整体形变过软，可减小到 `60-80`
+- 不建议使用过小数值，否则颈椎附近可能出现上下两段不连续的视觉效果
+
+## 8. 输出结果
+
+程序会在输出文件夹中生成：
+
+- `ct_original/`：原始 Original 完整 DICOM 序列
+- `ct_hard_boundary/`：硬边界 Hard boundary 完整 DICOM 序列
+- `ct_gaussian_smooth/`：高斯平滑 Gaussian smooth 完整 DICOM 序列
+- `ct_soft_transition/`：软过渡 Soft transition 完整 DICOM 序列
+- `ct/`：兼容旧版本的软过渡 Soft transition DICOM 序列
+- `process_comparison_4states.png`：四种状态过程对比图
+- `process_screenshots/`：四种状态的单独截图
+- `before_after_preview.png`：前后对比图
+
+其中各个 `ct_*` 文件夹均可用 DICOM 查看器打开，也可作为后续 CT 三维重建的数据基础。
+
+## 9. 常见问题
+
+### 预览和最终 DICOM 完全一样吗？
+
+不完全一样。
+
+预览是快速 2D 示意，用于快速查看角度方向和大致效果；最终输出 DICOM 使用三维软过渡位移场生成。
+
+### 为什么输出需要一段时间？
+
+程序需要读取 CT、生成三维位移场、重采样体数据，并重新写出 DICOM。300 层 CT 通常需要 1-3 分钟。
+
+### 为什么连接处仍可能有轻微不自然？
+
+目前方法使用软过渡位移场模拟头颈后伸，不是完整的多节颈椎生物力学模型。如果需要更真实的临床级结果，需要进一步标注各颈椎旋转中心并建立多段运动模型。
+
+### 中文路径会不会影响运行？
+
+程序内部会自动把临时文件放到系统英文临时目录，尽量避免中文路径导致的第三方库兼容问题。输入和输出路径可以使用中文。
+
+## 10. 推荐展示设置
+
+用于 PPT 展示时，建议：
+
+- 仰头角度：`12°-20°`
+- 过渡平滑宽度：`90-120`
+- 使用输出的 `process_comparison_4states.png` 或 `before_after_preview.png`
+
+如果希望展示角度连续变化，可另行生成视频动画。
+
+## 11. 生成 0° 到 20° 连续变化视频
+
+用户版文件夹内提供了视频生成功能，可生成一段从 `0°` 平滑变化到 `20°` 的仰头动画。
+
+双击：
+
+```bat
+生成0到20度仰头视频.bat
+```
+
+程序会打开一个视频生成窗口。
+
+在窗口中可以：
+
+- 选择 DICOM 文件夹
+- 选择输出视频位置
+- 调节最大仰头角度
+- 调节动画时长
+- 点击“生成视频”
+
+生成的视频位于：
+
+```bat
+ppt_video\head_extension_0_to_20deg.mp4
+```
+
+视频参数：
+
+- 分辨率：`1920 × 1080`
+- 帧率：`30 fps`
+- 动画时长：约 `7 秒`
+- 内容：左侧为原始 0° 图像，右侧为从 0° 平滑变化到 20° 的仰头效果
+
+### 自定义视频角度和时长
+
+不需要使用命令行。
+
+在视频生成窗口中直接拖动滑块即可：
+
+- “最大仰头角度”：控制视频最终达到的角度
+- “动画时长”：控制从 0° 变化到最大角度所需时间
+
+### 视频生成方式说明
+
+视频使用轻量二维软弯曲预览算法生成，目的是用于 PPT 展示角度连续变化。它不会为每一帧重新生成完整三维 DICOM，因此速度较快。
+
+如果需要生成某一个具体角度下的完整 DICOM 结果，请使用主程序 `启动头颈CT仰头形变工具.bat`。