# viewer-dcm
**Repository Path**: forproject/viewer-dcm
## Basic Information
- **Project Name**: viewer-dcm
- **Description**: 纯前端 3D DICOM 查看器，零部署、单 HTML 文件运行。支持最大密度投影(MIP)、体绘制(VR)、等值面提取三种渲染模式，以及轴位/冠状位/矢状位三平面重组。基于 Three.js + dicomParser 构建。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-04-30
## Categories & Tags
**Categories**: Uncategorized
**Tags**: HTML, JavaScript
## README
# 🔬 3D DICOM Viewer
**基于 WebGL 的轻量级 DICOM 医学影像三维查看器**
[在线体验](#快速开始) · [功能特性](#功能特性) · [使用说明](#使用说明) · [技术架构](#技术架构) · [常见问题](#常见问题)
[](LICENSE)
[](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5)
[](https://www.khronos.org/webgl/)
[](https://threejs.org/)
---
## 📞 联系我们
如果您对该项目感兴趣，或有定制开发的需求，可以扫描下方二维码联系我们：
| 昱扬科技官网 | 开源技术交流群 |
|:----------:|:-------------:|
|  |  |
| [https://www.yuyoung.cn](https://www.yuyoung.cn) | |
---
## 📖 项目简介
3D DICOM Viewer 是一个**零部署、纯前端**的医学影像查看器，支持 CT/MRI 等多模态 DICOM 影像的加载、浏览与三维重建。无需后端服务，打开 HTML 文件即可使用。
主要特点：
- 🏥 **纯浏览器运行** — 无需安装任何软件或服务端，单个 HTML 文件即可启动
- 🧊 **三种 3D 渲染模式** — MIP 最大密度投影、VR 体绘制、等值面提取
- 🔲 **三平面重组（MPR）** — 轴位、冠状位、矢状位实时同步浏览
- 🎨 **多种颜色映射** — 灰度、热图、冷色、彩虹
- 🪟 **窗宽窗位调节** — 内置骨骼/肺窗/软组织预设，支持自由调节
- 📱 **响应式布局** — 适配桌面端与移动端，支持触控操作
- 📦 **多格式加载** — 支持 ZIP 压缩包、单个 DCM 文件、文件夹上传、拖拽上传
---
## ✨ 功能特性
### 三维渲染
| 模式 | 说明 | 适用场景 |
|------|------|----------|
| **MIP** | 最大密度投影，沿射线取最大像素值 | 血管显影、骨骼观察 |
| **VR** | 体绘制，累积透明度与光照 | 软组织可视化、整体结构观察 |
| **Surface** | 等值面提取 + Blinn-Phong 光照 | 骨骼表面重建、器官轮廓提取 |
### 三平面重组（MPR）
- **轴位（Axial）** — 横断面，沿 Z 轴切片
- **冠状位（Coronal）** — 冠状面，沿 Y 轴切片
- **矢状位（Sagittal）** — 矢状面，沿 X 轴切片
- 支持鼠标滚轮快速切换切片位置
### 窗宽窗位
| 预设 | 窗位 (WC) | 窗宽 (WW) | 适用场景 |
|------|-----------|-----------|----------|
| 🦴 骨骼 | 300 | 1500 | 骨折、骨病变 |
| 🫁 肺窗 | -600 | 1500 | 肺结节、肺部感染 |
| 🫀 软组织 | 50 | 350 | 肝脏、肌肉、淋巴结 |
### 交互操作
- 🖱️ **旋转** — 鼠标拖拽旋转 3D 视图
- 🔍 **缩放** — 鼠标滚轮缩放
- ⌨️ **快捷键** — `1-5` 切换视图模式，`R` 重置，`空格` 自动旋转
- 📷 **截图导出** — 一键导出当前 3D 渲染画面为 PNG
### 功能截图
> ⚠️ 截图待补充
    
---
## 🚀 快速开始
### 在线使用
直接用浏览器打开 `3d.html` 文件即可，无需任何构建步骤。
```bash
# 克隆仓库
git clone https://github.com/your-username/viewer-dcm.git
# 进入目录
cd viewer-dcm
# 用浏览器打开
# 方式一：双击 3d.html
# 方式二：使用本地服务器（推荐，避免跨域限制）
python -m http.server 8080
# 然后访问 http://localhost:8080/3d.html
```
### 加载 DICOM 数据
支持以下方式加载影像数据：
1. **ZIP 压缩包** — 点击「选择文件」上传包含多个 `.dcm` 文件的 `.zip`
2. **单个/多个 DCM 文件** — 直接选择 `.dcm` 文件
3. **文件夹上传** — 点击「选择文件夹」上传整个 DICOM 序列
4. **拖拽上传** — 将文件拖入上传区域
> ⚠️ 建议使用本地 HTTP 服务器访问，部分浏览器对 `file://` 协议的跨域有限制。
---
## 🏗️ 技术架构
### 技术栈
| 技术 | 用途 |
|------|------|
| [Three.js](https://threejs.org/) | WebGL 3D 渲染引擎 |
| [dicomParser](https://github.com/cornerstonejs/dicomParser) | DICOM 文件解析 |
| [JSZip](https://stuk.github.io/jszip/) | ZIP 压缩包解压 |
| WebGL 2.0 | GPU 加速体绘制（Ray Casting） |
| HTML5 Canvas | 2D 切片渲染 |
### 渲染管线
```
DICOM 文件 → dicomParser 解析 → 像素数据提取 (HU 值)
↓
排序 & 构建 3D 体积纹理
↓
┌───────────────────┼───────────────────┐
↓ ↓ ↓
MIP 模式 VR 体绘制 Surface 模式
(最大密度投影) (累积透明度+光照) (等值面+Phong光照)
└───────────────────┼───────────────────┘
↓
WebGL Ray Casting
↓
屏幕输出
```
### 项目结构
```
viewer-dcm/
├── 3d.html # 主页面（单文件应用）
├── lib3d/ # 第三方依赖库
│ ├── dicomParser.min.js # DICOM 解析库
│ ├── jszip.min.js # ZIP 解压库
│ └── three.min.js # Three.js 渲染引擎
├── dcm测试文件.zip # 测试用 DICOM 数据
└── README.md # 项目文档
```
### 核心实现
- **Ray Casting 体绘制** — 基于 GPU 的光线投射算法，通过 ShaderMaterial 实现单 Pass 体渲染
- **3D 纹理映射** — 将 DICOM 体积数据上传为 `Data3DTexture`，支持三线性插值与各向异性过滤
- **自动降采样** — 当体积数据超过 256³ 时自动降采样，兼顾渲染质量与性能
- **自适应像素比** — 限制最大像素比为 1.5-2.0，降低低端设备 GPU 压力
- **WebGL 上下文保护** — 监听上下文丢失/恢复事件，防止崩溃
---
## 🎮 快捷键
| 快捷键 | 功能 |
|--------|------|
| `1` | 四联视图 |
| `2` | 3D 视图 |
| `3` | 轴位视图 |
| `4` | 冠状位视图 |
| `5` | 矢状位视图 |
| `R` | 重置相机 |
| `空格` | 切换自动旋转 |
---
## ❓ 常见问题
### Q: 打开 3d.html 后无法加载文件？
A: 部分浏览器对 `file://` 协议的跨域访问有限制，建议使用本地 HTTP 服务器：
```bash
# Python
python -m http.server 8080
# Node.js
npx serve .
# PHP
php -S localhost:8080
```
### Q: 加载大量切片时浏览器卡顿？
A: 项目内置了自动降采样机制。如仍有性能问题，可尝试：
- 降低「步进质量」（64 或 32）
- 减少切片数量
- 使用 Chrome/Edge 等对 WebGL 支持较好的浏览器
### Q: 支持哪些 DICOM 模态？
A: 目前主要测试了 CT 和 MRI 数据。其他模态（如 PET、超声）可能需要适配窗宽窗位参数。
### Q: 渲染出现花屏或黑屏？
A: 可能是 GPU 内存不足导致 WebGL 上下文丢失。建议：
- 关闭其他占用 GPU 的程序
- 降低步进质量和数据量
- 刷新页面重试
---
## 🤝 参与贡献
欢迎提交 Issue 和 Pull Request！
1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 发起 Pull Request
---
## 📄 许可证
本项目基于 [Apache License 2.0](LICENSE) 开源。
---
## 🙏 致谢
- [Three.js](https://threejs.org/) — 强大的 WebGL 3D 渲染库
- [dicomParser](https://github.com/cornerstonejs/dicomParser) — 高性能 DICOM 文件解析器
- [JSZip](https://stuk.github.io/jszip/) — 轻量级 ZIP 解压库
---
## 🚀 未来规划
我们计划在后续版本中持续迭代更新，为该查看器增加更多实用功能，包括但不限于：
- 🤖 **AI 智能分析** — 集成深度学习模型，自动检测和标注肺部结节、骨折、脑出血等异常区域
- 📊 **自动化报告生成** — 基于 AI 分析结果，一键生成结构化医学影像报告
- 🔍 **多模态融合** — 支持 PET/CT、PET/MRI 等多模态影像融合显示
- 📈 **历史对比** — 支持多次检查影像的时间轴对比，追踪病情变化
- 🎯 **精准测量** — 提供距离、角度、体积等精准测量工具
我们将持续优化用户体验，引入更多 AI 能力，让医学影像查看更加智能化。如有定制开发需求，欢迎联系我们。
---
**⚠️ 本项目仅供学习与研究使用，不可用于临床诊断。**