# 头颈部 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`。