plot-CONTCAR 🧪🖼️

把 VASP 的 CONTCAR / POSCAR 一键变成漂亮的「俯视图 + 侧视图」结构图，并自动整理进 PPT

一个 iOS 风格 的本地 GUI 工具（同时提供命令行 / Python API）：给出一个根目录，递归找出其中所有 CONTCAR（或 .vesta），批量导出 俯视图 / 侧视图，自动整理成 PPT，并追加一页 原子 ball + label 图例。所有 VESTA 出图参数都做成了开关与输入框，无需改代码。

📦 免安装便携版：下载 plot-CONTCAR.exe（Windows x64）

✨ 特性

	功能	说明
🗂️	按目录检索	指定根目录，递归检索所有 `CONTCAR` 或 `.vesta`（单选）；结果表可勾选、标题可编辑、表头排序与上移/下移/置顶/置底
📄	支持 .vesta 输入	可直接检索并处理 `.vesta` 文件（跳过格式转换，按视图重新出图）
🌳	保持相对路径	导出的图片与 `.vesta` 完全镜像输入目录结构，便于归档对照
🔭	俯视 / 侧视图	俯视图沿 c 轴、侧视图 c 轴竖直（可选沿 a / b 轴看）
📐	模型占图约 80%	按非白像素包围盒自动调整，让模型本身占满整图约 80%，不顶边也不偏小
🎛️	参数全界面化	坐标轴 / 晶胞边界 / 化学键 / 显示边界 / 缩放平移 / 原子半径颜色 / 视角 / 画质 / 超时…
🧬	原子样式自动	自动读取结构元素并去重，填入默认半径与颜色（Jmol 配色），颜色支持色轮取色
🎨	内置色轮	原子颜色点击色块即弹出取色器，实时预览
📊	一键生成 PPT	标题页 + 每个结构一页（俯视 / 侧视对照，等高对齐、无边框）+ 原子图例页
🔵	原子图例页	用真实原子颜色渲染带高光的 3D 小球，球 + 元素标签一一对应
🧾	按视图导出 .vesta	每个结构输出 `CONTCAR_top.vesta` / `CONTCAR_side.vesta`
🖱️	防误触	滚动页面时，鼠标停在下拉框 / 数值框上不会误改数值
🪟	后台静默出图	用隐藏窗口（伪无头）调用 VESTA，屏幕不弹窗、可无人值守
⏯️	暂停 / 继续	处理过程中可随时暂停、继续，不丢进度
📌	窗口置顶	GUI 始终保持在最前，不会被 VESTA 窗口遮盖
🕶️	iOS 风格界面	无边框圆角弹窗、卡片阴影、滑动开关、胶囊按钮，支持高 DPI
📦	零配置启动	双击 `启动GUI.lnk` / `.vbs` 即可（无命令行黑框，带任务栏图标）

🔄 工作流程

根目录 ──► 递归检索 CONTCAR ──► 勾选 / 排序 / 自定义标题
                                      │
                                      ▼
                    CONTCAR ──► .vesta（应用显示设置）
                                      │
                    ┌─────────────────┴─────────────────┐
                    ▼                                   ▼
        俯视图 .vesta（SCENE）                 侧视图 .vesta（SCENE）
                    │                                   │
           VESTA 出图 + 模型占图≈80%           VESTA 出图 + 模型占图≈80%
                    │                                   │
         images/**/CONTCAR_top.png            images/**/CONTCAR_side.png
         vesta/**/CONTCAR_top.vesta           vesta/**/CONTCAR_side.vesta
                    └─────────────────┬─────────────────┘
                                      ▼
              PPT：标题页 + 结构页（俯视/侧视，等高）+ 原子图例页

🚀 快速开始

方式零：下载便携版（免安装）

在 Releases 下载 plot-CONTCAR.exe，双击即用（Windows x64，约 78 MB，无需安装 Python / 依赖）。运行前请自备 VESTA，并在界面里设置其路径。

未签名的自编译程序，首次运行若被 SmartScreen 拦截，点「更多信息 → 仍要运行」即可。

方式一：GUI（源码运行）

:: 双击以下任一文件即可
启动GUI.lnk      :: 无黑框，最省心
启动GUI.vbs      :: 无黑框
启动GUI.bat      :: 几乎无黑框

或手动运行：

D:\miniconda3\envs\chem_env\pythonw.exe gui_launcher.pyw

方式二：命令行（`vesta_tools.py`）

:: 1) 只转换格式：CONTCAR -> CONTCAR.vesta
python vesta_tools.py examples\CONTCAR --no-image

:: 2) 转格式 + 后台出图（默认不调整视角）
python vesta_tools.py examples\CONTCAR -o preview.png --scale 5

:: 3) 转换 + 改样式 + 出图（关闭坐标轴、生成化学键、缩放 1.2、指定原子颜色/半径）
python vesta_tools.py examples\CONTCAR -o styled.png --scale 5 ^
    --comps OFF --sbond ON --scale-frac 1.2 --atom-radius O=0.8 --atom-color O=255,0,0

方式三：Python API

from vesta_tools import Vesta

v = Vesta()                                   # 默认隐藏窗口（伪无头）
v.contcar_to_vesta("examples/CONTCAR")        # CONTCAR -> .vesta
v.contcar_to_image(                            # 一步：转格式 ->（改样式）-> PNG
    "examples/CONTCAR", "a.png", scale=5,
    modify={"comps": "OFF", "sbond": "ON", "scale_frac": 1.2},
)

🖼️ 输出结构

给定根目录：

structures/
├── CONTCAR
├── Pt/CONTCAR
└── Pt3Ni(111)/CONTCAR

处理后在输出目录得到（相对路径原样保留）：

output/
├── structures.pptx                     # 汇总 PPT（标题页 + 结构页 + 原子图例页）
├── images/                             # 截图（俯视 / 侧视）
│   ├── CONTCAR_top.png
│   ├── CONTCAR_side.png
│   ├── Pt/
│   │   ├── CONTCAR_top.png
│   │   └── CONTCAR_side.png
│   └── Pt3Ni(111)/
│       ├── CONTCAR_top.png
│       └── CONTCAR_side.png
└── vesta/                              # 每个结构按视图各存一份
    ├── CONTCAR_top.vesta / CONTCAR_side.vesta
    ├── Pt/CONTCAR_top.vesta / CONTCAR_side.vesta
    └── Pt3Ni(111)/CONTCAR_top.vesta / CONTCAR_side.vesta

PPT 每一页示例：

页	内容
1	标题页（结构数量、生成时间）
2…N	每个结构一页：俯视图 + 侧视图并排（等高对齐），标注自定义标题
末页	原子图例：每个元素一个 3D 小球 + 元素标签

_{由 examples/CONTCAR 经 VESTA 渲染（scale=3）}

🖥️ GUI 使用

界面从上到下分为 7 个区：

区	名称	主要项
①	输入文件	结构根目录（浏览 / 检索）、检索类型单选（CONTCAR / .vesta）、结果表（勾选 + 可编辑标题列，表头点击排序 + 上移/下移/置顶/置底手动排序）、全选 / 全不选 / 按选中刷新元素
②	输出设置	输出目录、PPT 保存路径、图片格式、画质 `scale`、超时、隐藏窗口、输出 `.vesta`、VESTA.exe 路径
③	视图设置	生成俯视图 / 侧视图、侧视方向、额外旋转 X/Y/Z、模型占图片比例（默认 0.8）、模型放大方式、幻灯片图片排版
④	VESTA 显示	`COMPS` / `UCOLP` / `SBOND` 开关、成键容差、`scale_frac`、`x/y_move`、显示边界 `BOUND`（已标注 a/b/c 轴；默认 a、b 轴 `-0.05 ~ 1.05`，c 轴 `-0.05 ~ 0.95`）
⑤	原子样式	启用原子样式处理开关（默认开）、元素 / 半径 / 颜色（点击色块用色轮取色），检索后按结构元素自动填充（可增删）
⑥	图例页	是否生成、球体直径、每行数量、是否标注半径、图例位置
⑦	运行	开始 / 暂停 / 继续 / 停止、进度条、实时日志

出图视角说明

工具通过直接写入 .vesta 的 SCENE 矩阵来精确控制视角：

视图	SCENE 矩阵	含义
俯视图	`[1,0,0, 0,1,0, 0,0,1]`	沿 c 轴俯视
侧视图（沿 b）	`[1,0,0, 0,0,1, 0,-1,0]`	a 横、c 竖
侧视图（沿 a）	`[0,1,0, 0,0,1, 1,0,0]`	b 横、c 竖

模型占图片比例（约 80%）

VESTA 导出的 PNG 画布是固定的，模型往往只占中间一小块。工具会按 非白像素包围盒 自动调整，使 模型本身占据整图约 80%（上下或左右），既不顶到边、也不会太小：

方式	说明
裁剪留白（默认）	裁到模型外接框，再居中补白边，使模型恰占 80%
VESTA 缩放	测量模型占比后，调整 `SCENE` 的 `scale_frac` 重新导出，让模型在画布中占 80%
裁剪 + VESTA 缩放	先缩放再裁剪留白（分辨率更高）

模型占图片比例：默认 0.8，可调 0.3 ~ 0.95。
参考 mk-ppt 项目的包围盒裁剪思路实现，实测三种方式下模型占比均为 0.80，且不截断。

幻灯片图片排版

同页并排（默认）：俯视图 + 侧视图放在同一页；每页一张：各占一页。
图片在幻灯片中同样等比缩放到 约占页面 80%（上下或左右），完整显示、不越界。
同页多图统一高度（等高对齐）：同一页的图片高度一致，宽度按比例自适应；同时约束总宽与单图宽度，不会出现过高或过宽的图（适配二维材料 / 体材料 / 含真空层的 slab）。
幻灯片中的图片不添加任何边框。

页面标题与排序

检索后的表格第二列可直接编辑，作为每个结构所在 PPT 页面的标题（默认 = 相对路径）。表格支持点击表头按列排序；也可**选中某行后用「↑ 上移 / ↓ 下移 / ⤒ 置顶 / ⤓ 置底」**手动调整顺序（手动调整后自动关闭排序以保留顺序，再点表头又会恢复排序）。

滚动页面时，鼠标悬停在下拉框 / 数值输入框上不会误改它们的值（已禁用滑轮修改）。

🧰 命令行参数（`vesta_tools.py`）

usage: vesta_tools.py [-h] [-o OUTPUT] [-s SCALE] [--vesta-file VESTA_FILE]
                      [--no-image] [--keep-vesta] [--rotate-x/-y/-z ANGLE]
                      [--comps {ON,OFF}] [--ucolp {ON,OFF}] [--sbond {ON,OFF}]
                      [--boundary a,b,c,d,e,f] [--version a,b,...,i]
                      [--scale-frac F] [--x-move F] [--y-move F]
                      [--sbond-padding F] [--atom-color El=R,G,B] [--atom-radius El=r]
                      [--exe EXE] [--timeout S] [--show-window] [-q]
                      contcar [contcar ...]

参数	说明	默认
`contcar`	一个或多个 `CONTCAR` / `POSCAR`	必填
`-o, --output`	输出图片（仅单输入可用）	`<CONTCAR>.png`
`-s, --scale`	画质，越大越清晰	`5`
`--no-image`	仅格式转换，不出图	`False`
`--keep-vesta`	出图后保留 `.vesta`	`False`
`--comps/--ucolp/--sbond`	坐标轴 / 晶胞边界 / 化学键开关	不改
`--boundary`	显示边界（6 个分数坐标）	不改
`--version`	视角矩阵（9 个数）	不改
`--scale-frac / --x-move / --y-move`	缩放与平移	`1.0 / 0 / 0`
`--sbond-padding`	自动成键键长容差（Å）	`0.5`
`--atom-color El=R,G,B`	原子颜色（可重复）	不改
`--atom-radius El=r`	原子半径（可重复）	不改
`--exe / --timeout / --show-window / -q`	VESTA 路径 / 超时 / 显示窗口 / 静默	—

🛠️ 修改 `.vesta` 内容

vesta_modify.py 可在出图前直接修改 .vesta 的显示参数：

段	参数	作用
`COMPS`	`comps="ON"/"OFF"`	显示 / 隐藏晶胞坐标轴
`UCOLP`	`ucolp="ON"/"OFF"`	显示 / 隐藏晶胞边界线
`SBOND`	`sbond="ON"/"OFF"`	按 `r_a + r_b + padding` 自动生成化学键
`BOUND`	`boundary=[6 个数]`	显示 / 裁剪边界
`ATOMT` / `SITET`	`atom_params=[{...}]`	原子半径与颜色
`SCENE`	`version=[9 个数]`、`scale_frac`、`x/y_move_frac`	视角矩阵、缩放与平移

🧩 项目结构

plot-CONTCAR/
├── vesta_gui.py            # iOS 风格 GUI（PySide6）+ 批量出图 / PPT 逻辑
├── gui_launcher.pyw        # 无控制台启动器（pythonw）
├── vesta_tools.py          # 核心类 Vesta + 命令行入口
├── vesta_modify.py         # .vesta 内容修改（COMPS/UCOLP/SBOND/BOUND/ATOMT/SITET/SCENE）
├── 启动GUI.lnk / .vbs / .bat # Windows 免黑框启动方式
├── build_exe.bat           # 打包便携 exe（PyInstaller）
├── assets/
│   ├── app.ico             # 程序图标（窗口 / 任务栏 / 快捷方式）
│   └── app.png
├── requirements.txt
├── docs/
│   └── screenshot.png
├── examples/
│   ├── CONTCAR
│   └── preview.png
├── LICENSE
└── README.md

🖥️ 环境要求

项目	要求
操作系统	Windows（VESTA 出图依赖 GUI / OpenGL 渲染）
Python	3.9+（推荐 `D:\miniconda3\envs\chem_env`）
VESTA	64 位版，默认 `D:\software\VESTA-win64\VESTA-win64\VESTA.exe`
依赖	`PySide6`、`python-pptx`、`Pillow`、`numpy`（见 `requirements.txt`）

pip install -r requirements.txt

打包便携 exe

:: 依赖建好后双击（需先 pip install pyinstaller）
build_exe.bat
:: 产物：dist\plot-CONTCAR.exe

conda 环境下 pyexpat 依赖的 libexpat.dll 已在 build_exe.bat 中通过 --add-binary 打入。

🧠 实现细节 & FAQ

为什么不能真正用 -nogui 无头出图？

VESTA 出图依赖 GUI/OpenGL，真正的 -nogui 不会产生图片。本工具仍用 GUI 进程渲染，但通过 Windows STARTUPINFO(SW_HIDE) 把窗口隐藏，实现「不弹窗、无人值守」。

为什么导出图片后进程不退出 / 返回码异常？

VESTA 即使带 -close 也不会自动退出，且返回码不可靠（成功也可能是 0xFFFFFFFF）。工具以「输出文件存在且非空」为成功判据，并在文件大小稳定后主动结束进程。

模型在图片里太小 / 太大怎么办？

在 ③ 视图设置里调整「模型占图片比例」（默认 0.8）与「模型放大方式」： 裁剪留白（默认）、VESTA 缩放、裁剪 + VESTA 缩放，三种方式都能让模型约占整图 80%。

能找到元素但读不到元素名（VASP4 格式）怎么办？

VASP4 的 CONTCAR 第 6 行是原子数而非元素符号，无法自动识别元素；此时原子样式留空即可，VESTA 会使用默认样式。

任务栏图标还是 python 图标？

程序已设置 AppUserModelID 与窗口图标，正常应显示本程序图标；若仍是旧图标，是 Windows 图标缓存所致，重启资源管理器或注销重登一次即可。

能在无用户登录的服务 / 计划任务里跑吗？

隐藏窗口仍需要可用的交互式桌面 / 图形会话；无登录场景下 OpenGL 可能不可用。

📝 更新日志

v1.1.0

🖥️ iOS 风格 GUI（PySide6）：无边框圆角窗口、卡片阴影、滑动开关、胶囊按钮、高 DPI
🗂️ 按根目录检索 CONTCAR；结果表可勾选、标题可编辑、表头排序 + 上移/下移/置顶/置底
🌳 导出图片与 .vesta 保持相对路径结构；.vesta 按视图输出 _top / _side
📐 模型占导出图片约 80%（裁剪留白 / VESTA 缩放 / 两者），不顶边不截断
🧬 原子样式按结构元素自动填充；颜色支持色轮取色
📊 PPT：标题页 + 结构页（俯视 / 侧视，等高对齐、无边框）+ 原子图例页
🎛️ 所有 VESTA 参数界面化；禁用滚轮误改下拉 / 数值框
🪟 免黑框启动（.lnk / .vbs / .bat）；新增程序图标（窗口 / 任务栏 / 快捷方式）

v1.1.1

📦 提供单文件便携版 plot-CONTCAR.exe（免安装 Python / 依赖，约 74 MB）
📄 检索类型支持 CONTCAR / .vesta 单选；.vesta 可直接处理（跳过转换）
⏯️ 运行中支持 暂停 / 继续
📌 窗口始终置顶，不被 VESTA 遮盖
🧬 原子样式新增 启用开关（默认开）

v1.0.0

首个正式版：CONTCAR → VESTA 出图 + PPT + 原子图例，iOS 风格 GUI、命令行与 Python API

📄 License

本项目基于 MIT License 开源。

VESTA 为第三方软件，版权归其原作者所有，本项目仅调用其命令行接口。

_{如果这个工具帮到了你，欢迎点一个 ⭐ Star！}

English Summary

plot-CONTCAR converts VASP CONTCAR / POSCAR files into VESTA .vesta format and exports top-view and side-view structure images in batch, then assembles them into a PPT with a dedicated atom ball + label legend slide. It ships with an iOS-style PySide6 GUI, a CLI (vesta_tools.py), and a Python API. Given a root folder, it recursively finds all CONTCAR files, lets you pick which to process, and preserves the relative folder structure in both the image and .vesta outputs. The model is auto-scaled to occupy ~80% of each exported image.

Requires Windows, Python 3.9+, VESTA 64-bit, and PySide6 + python-pptx.

Navigation Menu

Repository files navigation

plot-CONTCAR 🧪🖼️

📑 目录

✨ 特性

🔄 工作流程

🚀 快速开始

方式零：下载便携版（免安装）

方式一：GUI（源码运行）

方式二：命令行（`vesta_tools.py`）

方式三：Python API

🖼️ 输出结构

🖥️ GUI 使用

出图视角说明

模型占图片比例（约 80%）

幻灯片图片排版

页面标题与排序

🧰 命令行参数（`vesta_tools.py`）

🛠️ 修改 `.vesta` 内容

🧩 项目结构

🖥️ 环境要求

打包便携 exe

🧠 实现细节 & FAQ

📝 更新日志

v1.1.0

v1.1.1

v1.0.0

📄 License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
assets		assets
docs		docs
examples		examples
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
build_exe.bat		build_exe.bat
gui_launcher.pyw		gui_launcher.pyw
requirements.txt		requirements.txt
vesta_gui.py		vesta_gui.py
vesta_modify.py		vesta_modify.py
vesta_tools.py		vesta_tools.py
启动GUI.bat		启动GUI.bat
启动GUI.vbs		启动GUI.vbs

Latest commit

History

Folders and files

Repository files navigation

plot-CONTCAR 🧪🖼️

📑 目录

✨ 特性

🔄 工作流程

🚀 快速开始

方式零：下载便携版（免安装）

方式一：GUI（源码运行）

方式二：命令行（vesta_tools.py）

方式三：Python API

🖼️ 输出结构

🖥️ GUI 使用

出图视角说明

模型占图片比例（约 80%）

幻灯片图片排版

页面标题与排序

🧰 命令行参数（vesta_tools.py）

🛠️ 修改 .vesta 内容

🧩 项目结构

🖥️ 环境要求

打包便携 exe

🧠 实现细节 & FAQ

📝 更新日志

v1.1.0

v1.1.1

v1.0.0

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

方式二：命令行（`vesta_tools.py`）

🧰 命令行参数（`vesta_tools.py`）

🛠️ 修改 `.vesta` 内容