# 高中化学三维晶胞可视化系统

这是一个用于高中化学教学的三维晶胞可视化系统，支持预置晶胞展示和CIF文件渲染。

## 🌟 功能特性

### 预置晶胞库
- NaCl（氯化钠） - 面心立方离子晶体
- CaF₂（氟化钙） - 萤石结构
- 金刚石（C） - 原子晶体
- 铜（Cu） - 面心立方金属
- 铁（Fe） - 体心立方金属
- 六方石墨（C） - 层状结构
- CsCl（氯化铯） - 体心立方离子晶体
- 钙钛矿（CH₃NH₃PbI₃） - 太阳能电池材料
- 石英（SiO₂） - 原子晶体
- 干冰（CO₂） - 分子晶体
- 镁（Mg） - 六方密堆积金属

### CIF文件渲染
- 上传 `.cif` 格式晶体结构文件
- 自动解析晶胞参数和原子坐标
- 3D交互式展示（旋转、缩放、平移）

### 交互功能
- 3D模型自动旋转
- 显示/隐藏化学键
- 显示/隐藏原子标签
- 视角重置
- 缩放控制

## 🛠️ 系统架构

### 前端
- **HTML/CSS/JavaScript** - 基础框架
- **3Dmol.js** - 晶体结构3D渲染
- **Three.js** - 辅助3D效果（可选）

### 后端
- **PHP桥接层** - 文件上传和API转发
- **Python Flask API** - CIF文件解析
- **pymatgen库** - 专业晶体结构分析

### 数据流
```
用户 → 前端HTML → PHP桥接 → Python API → pymatgen解析 → 返回JSON → 3D渲染
```

## 📁 文件结构

```
/
├── index.html                    # 主页面
├── css/
│   └── style.css                # 样式文件
├── js/
│   ├── main.js                  # 主逻辑
│   ├── preset-crystals.js       # 预置晶胞数据
│   ├── 3dmol.min.js             # 3Dmol.js库（需下载）
│   └── three.min.js             # Three.js库（需下载）
├── php/
│   └── upload_cif.php           # PHP桥接API
├── python-api/
│   ├── app.py                   # Flask API主程序
│   ├── cif_parser.py            # CIF解析逻辑
│   ├── requirements.txt         # Python依赖
│   └── static/uploads/          # 上传文件存储
└── README.md                    # 本文档
```

## 🚀 快速部署

### 1. 前端部署
1. 下载3Dmol.js和Three.js库：
   ```bash
   # 下载3Dmol.js
   wget https://cdn.jsdelivr.net/npm/3dmol@latest/build/3Dmol-min.js -O js/3dmol.min.js
   
   # 下载Three.js
   wget https://cdn.jsdelivr.net/npm/three@latest/build/three.min.js -O js/three.min.js
   ```

2. 将整个目录上传到你的Web服务器（如宝塔面板）

### 2. 后端部署

#### Python API服务
1. 安装Python依赖：
   ```bash
   cd python-api
   pip install -r requirements.txt
   ```

2. 启动Python API：
   ```bash
   python app.py
   ```
   或使用生产服务器：
   ```bash
   gunicorn -w 4 -b 0.0.0.0:5000 app:app
   ```

#### PHP桥接配置
修改 `php/upload_cif.php` 中的API地址：
```php
$PYTHON_API_URL = 'http://localhost:5000';  // 根据实际情况修改
```

### 3. 宝塔面板配置
1. 创建网站，绑定域名
2. 将文件上传到网站根目录
3. 确保PHP已安装并启用
4. 配置Python环境（可选使用宝塔Python项目管理器）

## 🔧 技术细节

### CIF文件解析
系统使用 `pymatgen` 库解析CIF文件，提取：
- 晶格参数（a, b, c, α, β, γ）
- 空间群信息
- 原子坐标（分数坐标）
- 化学式
- 晶体系统

### 3D渲染
- 使用3Dmol.js进行分子/晶体3D渲染
- 支持CPK原子配色方案
- 可交互的晶胞框架
- 自动检测化学键（简化算法）

### 跨域支持
- PHP桥接层处理CORS
- JSON格式数据交换
- 错误处理和用户反馈

## 📊 数据格式

### 预置晶胞数据格式
```json
{
  "id": "nacl",
  "name": "氯化钠 (NaCl)",
  "formula": "NaCl",
  "crystalSystem": "立方晶系",
  "spaceGroup": "Fm-3m",
  "latticeParams": [5.64, 5.64, 5.64, 90, 90, 90],
  "atoms": [
    {"element": "Na", "x": 0, "y": 0, "z": 0},
    {"element": "Cl", "x": 0.5, "y": 0.5, "z": 0.5}
  ]
}
```

### API响应格式
```json
{
  "success": true,
  "data": {
    "formula": "NaCl",
    "crystal_system": "cubic",
    "space_group": "Fm-3m",
    "lattice_params": [5.64, 5.64, 5.64, 90, 90, 90],
    "atoms": [...],
    "atom_count": 8
  }
}
```

## 🔍 故障排除

### Python API无法启动
1. 检查pymatgen是否安装：`pip show pymatgen`
2. 检查端口占用：`netstat -tlnp | grep 5000`
3. 查看错误日志：`tail -f python-api/app.py`

### 文件上传失败
1. 检查PHP文件上传限制
2. 检查Python API是否运行
3. 查看浏览器控制台错误

### 3D渲染问题
1. 检查3Dmol.js库是否正确加载
2. 检查浏览器WebGL支持
3. 查看JavaScript控制台错误

## 📱 浏览器支持
- Chrome 60+ ✅
- Firefox 55+ ✅
- Safari 11+ ✅
- Edge 79+ ✅

## 📄 许可证
MIT License

## 👥 贡献
欢迎提交Issue和Pull Request改进系统！

## 📞 联系
如有问题，请提交Issue或联系开发者。

---

**✨ 教学应用价值**
- 直观展示晶体结构
- 加深对晶胞概念的理解
- 支持CIF标准格式，可用于科研教学
- 交互式学习体验