# 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
**A lightweight WebGL-based 3D medical image viewer for DICOM data**
[Try it out](#quick-start) · [Features](#features) · [Usage](#usage) · [Architecture](#architecture) · [FAQ](#faq)
[](LICENSE)
[](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5)
[](https://www.khronos.org/webgl/)
[](https://threejs.org/)
---
## 📞 Contact Us
If you're interested in this project or need custom development, feel free to scan the QR codes below to reach us:
| Official Website | Open Source Tech Community |
|:----------:|:-------------:|
|  |  |
| [https://www.yuyoung.cn](https://www.yuyoung.cn) | |
---
## 📖 About
3D DICOM Viewer is a **zero-deployment, pure front-end** medical image viewer that supports loading, browsing, and 3D reconstruction of multi-modality DICOM images (CT, MRI, etc.). No backend required — just open the HTML file and start using it.
Highlights:
- 🏥 **Runs entirely in the browser** — No software installation or server needed; a single HTML file does it all
- 🧊 **Three 3D rendering modes** — MIP (Maximum Intensity Projection), VR (Volume Rendering), Iso-surface extraction
- 🔲 **Multi-Planar Reconstruction (MPR)** — Real-time synchronized axial, coronal, and sagittal views
- 🎨 **Multiple colormaps** — Grayscale, Hot, Cool, Rainbow
- 🪟 **Window/Level adjustment** — Built-in presets for Bone, Lung, and Soft Tissue, plus free adjustment
- 📱 **Responsive layout** — Adapts to desktop and mobile devices with touch support
- 📦 **Flexible file loading** — ZIP archives, individual DCM files, folder upload, or drag-and-drop
---
## ✨ Features
### 3D Rendering
| Mode | Description | Use Case |
|------|-------------|----------|
| **MIP** | Maximum Intensity Projection — displays the maximum pixel value along each ray | Angiography, bone visualization |
| **VR** | Volume Rendering — accumulates opacity and lighting along rays | Soft tissue visualization, overall structure observation |
| **Surface** | Iso-surface extraction with Blinn-Phong lighting | Bone surface reconstruction, organ contour extraction |
### Multi-Planar Reconstruction (MPR)
- **Axial** — Transverse plane, sliced along the Z axis
- **Coronal** — Frontal plane, sliced along the Y axis
- **Sagittal** — Lateral plane, sliced along the X axis
- Mouse wheel for quick slice navigation
### Window/Level Presets
| Preset | Center (WC) | Width (WW) | Use Case |
|--------|-------------|------------|----------|
| 🦴 Bone | 300 | 1500 | Fractures, bone lesions |
| 🫁 Lung | -600 | 1500 | Lung nodules, pulmonary infections |
| 🫀 Soft Tissue | 50 | 350 | Liver, muscle, lymph nodes |
### Interactions
- 🖱️ **Rotate** — Click and drag to rotate the 3D view
- 🔍 **Zoom** — Scroll wheel to zoom in/out
- ⌨️ **Keyboard shortcuts** — `1-5` for view modes, `R` to reset, `Space` for auto-rotate
- 📷 **Screenshot export** — One-click export of the current 3D rendering as PNG
### Screenshots
> ⚠️ Screenshots to be added
    
---
## 🚀 Quick Start
### Usage
Open `3d.html` directly in a browser — no build step required.
```bash
# Clone the repository
git clone https://github.com/your-username/viewer-dcm.git
# Navigate into the project
cd viewer-dcm
# Open in browser
# Option 1: Double-click 3d.html
# Option 2: Use a local server (recommended to avoid CORS restrictions)
python -m http.server 8080
# Then visit http://localhost:8080/3d.html
```
### Loading DICOM Data
The following methods are supported:
1. **ZIP archive** — Click "Select Files" to upload a `.zip` containing multiple `.dcm` files
2. **Individual DCM files** — Select one or more `.dcm` files directly
3. **Folder upload** — Click "Select Folder" to upload an entire DICOM series
4. **Drag and drop** — Drag files into the upload zone
> ⚠️ A local HTTP server is recommended, as some browsers restrict cross-origin access on the `file://` protocol.
---
## 🏗️ Architecture
### Tech Stack
| Technology | Purpose |
|------------|---------|
| [Three.js](https://threejs.org/) | WebGL 3D rendering engine |
| [dicomParser](https://github.com/cornerstonejs/dicomParser) | DICOM file parsing |
| [JSZip](https://stuk.github.io/jszip/) | ZIP archive decompression |
| WebGL 2.0 | GPU-accelerated volume rendering (Ray Casting) |
| HTML5 Canvas | 2D slice rendering |
### Rendering Pipeline
```
DICOM Files → dicomParser → Pixel Data Extraction (HU Values)
↓
Sort & Build 3D Volume Texture
↓
┌─────────────────┼─────────────────┐
↓ ↓ ↓
MIP Mode VR Volume Surface Mode
(Max Intensity) (Accumulated α+Light) (Iso-surface+Phong)
└─────────────────┼─────────────────┘
↓
WebGL Ray Casting
↓
Screen Output
```
### Project Structure
```
viewer-dcm/
├── 3d.html # Main page (single-file application)
├── lib3d/ # Third-party dependencies
│ ├── dicomParser.min.js # DICOM parser library
│ ├── jszip.min.js # ZIP decompression library
│ └── three.min.js # Three.js rendering engine
├── dcm测试文件.zip # Sample DICOM data for testing
└── README.md # Documentation
```
### Core Implementation
- **Ray Casting Volume Rendering** — GPU-based ray casting via ShaderMaterial for single-pass volume rendering
- **3D Texture Mapping** — Uploads DICOM volume data as `Data3DTexture` with trilinear interpolation and anisotropic filtering
- **Auto Downsampling** — Automatically downsamples volume data exceeding 256³ to balance quality and performance
- **Adaptive Pixel Ratio** — Caps the maximum pixel ratio at 1.5–2.0 to reduce GPU load on low-end devices
- **WebGL Context Protection** — Listens for context lost/restored events to prevent crashes
---
## 🎮 Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `1` | Four-panel view |
| `2` | 3D view |
| `3` | Axial view |
| `4` | Coronal view |
| `5` | Sagittal view |
| `R` | Reset camera |
| `Space` | Toggle auto-rotate |
---
## ❓ FAQ
### Q: Can't load files after opening 3d.html directly?
A: Some browsers restrict cross-origin access on the `file://` protocol. Use a local HTTP server instead:
```bash
# Python
python -m http.server 8080
# Node.js
npx serve .
# PHP
php -S localhost:8080
```
### Q: Browser lag when loading a large number of slices?
A: The project includes automatic downsampling. If performance issues persist, try:
- Lowering the "Step Quality" parameter (64 or 32)
- Reducing the number of slices
- Using a browser with better WebGL support (Chrome, Edge)
### Q: Which DICOM modalities are supported?
A: Primarily tested with CT and MRI data. Other modalities (e.g., PET, Ultrasound) may require window/level adjustments.
### Q: Corrupted or black rendering?
A: This may be caused by GPU memory exhaustion leading to WebGL context loss. Suggestions:
- Close other GPU-intensive applications
- Lower the step quality and data volume
- Refresh the page
---
## 🤝 Contributing
Issues and Pull Requests are welcome!
1. Fork this repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
---
## 📄 License
This project is licensed under the [Apache License 2.0](LICENSE).
---
## 🙏 Acknowledgements
- [Three.js](https://threejs.org/) — Powerful WebGL 3D rendering library
- [dicomParser](https://github.com/cornerstonejs/dicomParser) — High-performance DICOM file parser
- [JSZip](https://stuk.github.io/jszip/) — Lightweight ZIP decompression library
---
## 🚀 Future Roadmap
We plan to continuously iterate and update this viewer in future releases, adding more practical features including:
- 🤖 **AI-Powered Analysis** — Integration of deep learning models to automatically detect and annotate abnormalities such as pulmonary nodules, fractures, and brain hemorrhages
- 📊 **Automated Report Generation** — One-click generation of structured medical imaging reports based on AI analysis results
- 🔍 **Multi-Modal Fusion** — Support for PET/CT, PET/MRI, and other multi-modal image fusion
- 📈 **Historical Comparison** — Timeline comparison of multiple exam images to track disease progression
- 🎯 **Precision Measurements** — Accurate measurement tools for distance, angle, volume, and more
We will continue optimizing user experience and introducing more AI capabilities to make medical image viewing more intelligent. For custom development needs, please don't hesitate to contact us.
---
**⚠️ This project is for learning and research purposes only. Not intended for clinical diagnosis.**