# Materials Viewer

[![PyPI version](https://badge.fury.io/py/materials-viewer-mp.svg)](https://badge.fury.io/py/materials-viewer-mp)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Materials Viewer 是一个基于 Python + Tkinter 的图形化工具，用于查询和可视化 [Materials Project](https://materialsproject.org/) 数据库中的材料信息。

## 功能特性

- 根据化学式查询 Materials Project 数据库
- 显示材料信息：ID、空间群（含序号）、能量、形成能、带隙
- 支持带隙范围筛选（如 0.05 - 10 eV）
- 支持空间群筛选（符号或序号，如 P4mm 或 99）
- 支持点击表头排序
- 支持下载 CIF 和 POSCAR 格式
- 支持3D结构可视化（VESTA/ASE）
- 支持批量下载
- API Key 和 VESTA 路径自动保存
- 化学式输入框支持回车键触发查询

## 安装

### 使用 pip 安装（推荐）

```bash
pip install materials-viewer-mp
```

### 从源码安装

```bash
git clone https://github.com/haiw201/materials-viewer.git
cd materials-viewer
pip install -e .
```

## 使用方法

### 命令行启动

```bash
# 使用简短命令
mv

# 或使用完整命令
materials-viewer
```

### Python 代码中调用

```python
from materials_viewer import MaterialsViewer
import tkinter as tk

root = tk.Tk()
app = MaterialsViewer(root)
root.mainloop()
```

## 首次使用配置

1. **设置 API Key**：点击"🔑 输入API Key"按钮，输入你的 Materials Project API Key
   - 获取 API Key：https://materialsproject.org/api
   - API Key 会自动加密保存到配置文件

2. **设置 VESTA 路径**（可选）：点击"⚙️ 设置VESTA路径"按钮，选择 VESTA 可执行文件路径
   - VESTA 用于3D结构可视化
   - 下载地址：https://jp-minerals.org/vesta/en/download.html

## 使用指南

### 查询材料

1. 在"化学式"输入框中输入化学式（如 `BaTiO3`、`SiO2`）
2. 按 **回车键** 或点击"🔍 查询"按钮
3. 等待查询结果显示

### 筛选材料

- **带隙筛选**：在"带隙范围"输入框中输入最小值和最大值，点击"应用筛选"
- **空间群筛选**：在"空间群"输入框中输入空间群符号（如 `P4mm`）或序号（如 `99`）
- **重置筛选**：点击"重置"按钮清除所有筛选条件

### 下载材料

- **单个下载**：点击表格中的"C"或"P"按钮下载 CIF 或 POSCAR 文件
- **批量下载**：点击"⬇ 下载全部"按钮下载所有查询结果

### 查看3D结构

双击表格中的任意一行，使用 VESTA 查看3D晶体结构（需要先设置 VESTA 路径）

## 系统要求

- Python 3.8 或更高版本
- 操作系统：Windows、macOS、Linux

## 依赖包

- pymatgen >= 2023.0.0
- ase >= 3.22.0

## 配置文件

配置文件保存在用户主目录下的 `.materials_viewer` 文件夹中：

- `config.json`：API Key（加密存储）和 VESTA 路径
- `app.log`：应用程序日志

## 常见问题

### Q: 查询时提示 API Key 错误？
A: 请确保已正确设置 Materials Project API Key。获取地址：https://materialsproject.org/api

### Q: 空间群显示为空？
A: 部分材料的空间群信息可能缺失，程序会显示为 "N/A"。

### Q: 如何更新到最新版本？
A: 运行 `pip install --upgrade materials-viewer-mp`

## 许可证

本项目采用 [MIT 许可证](LICENSE) 开源。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

- 项目主页：https://github.com/haiw201/materials-viewer
- 问题反馈：https://github.com/haiw201/materials-viewer/issues

## 致谢

- [Materials Project](https://materialsproject.org/) 提供材料数据
- [pymatgen](https://pymatgen.org/) 提供材料分析工具
- [ASE](https://wiki.fysik.dtu.dk/ase/) 提供原子模拟环境
