VESTA 命令行自动化

VESTA（Koichi Momma & Fujio Izumi）是一款晶体/电子结构三维可视化程序。它本身没有独立的脚本语言，
所谓"脚本"= 在 shell / Python 里循环调用 VESTA 可执行文件并传入一组命令行参数。所有可调用的命令
来自官方手册第 17 章（COMMAND LINE INTERFACE），且由作者在 2020 年幻灯片中进一步举例确认。

> 引用（发表图件时必须注明）：
> Momma, K. & Izumi, F. (2011). "VESTA 3 for three-dimensional visualization of crystal,
> volumetric and morphology data." J. Appl. Cryst. 44, 1272–1276.
> 官方手册：<https://jp-minerals.org/vesta/en/doc/VESTAch17.html>
> 作者命令行幻灯片：<https://www.rs.tus.ac.jp/hypermaterials/activity/documents/Hyper_Material20.05.28_Momma.pdf>

1. 两种调用模式（最关键）

VESTA 的命令分两类，必须分清，否则静默失败：

铁律：

• 想导出图片（-export_img）→ 必须走 GUI 模式（不能加 -nogui）。
• 想纯数据批处理（转换/计算）→ 加 -nogui，速度最快且不弹窗。
• VESTA 是单实例程序：在 Windows/Linux 上，重复执行 VESTA <参数> 会把命令发给已运行的实例；
  macOS 必须用 open -n -a VESTA.app --args ... 来启动/投递命令。
• 同一次调用里的参数从左到右顺序执行，所以可以一条命令链完成多步：
  VESTA -open a.cif -rotate_z 90 -flush -export_img scale=3 a.png

> ⚠️ 无头/服务会话陷阱：若运行环境没有交互桌面（例如自动化 Agent 的后台 Bash、CI、
> Windows 服务会话、无显示服务器的 Linux 且未用 xvfb），VESTA 的 GUI 渲染会卡死——
> 进程能启动但不创建可见窗口、写不出 PNG/TIFF，只能强杀（实测：PID 39864 卡 45s 未写任何图）。
> 此类环境请用第 8 节的 ASE 无头预览，或把渲染放到真实桌面执行。

2. 定位可执行文件

• Windows：建议把 VESTA.exe 所在目录加入 PATH，这样可直接用 VESTA.exe。路径务必纯英文、无空格、无中文，否则读写出错。
• macOS：不要直接调用 VESTA.app/Contents/MacOS/VESTA，而用：
  open -n -a /Applications/VESTA.app --args <命令>
  （-n 强制新实例，避免命令被已有窗口吞掉）。
• Linux 无显示服务器：渲染图片可用虚拟显示：xvfb-run -a VESTA -open a.cif -export_img scale=3 a.png

3. 命令全集（官方第 17 章 + 作者幻灯片）

3.1 无界面数据命令（配合 -nogui，macOS 不支持无界面）

3.2 GUI 可视化命令（需要窗口；macOS 用 open --args）

3.3 -export_img 支持的图片格式（按扩展名自动识别）

• 栅格：BMP, EPS, JPEG, JPEG2000, PNG, PPM, RAW, RGB(SGI), TGA, TIFF（.tif 与 .tiff 等价）
• 矢量：EPS, PDF, PS, SVG
• 出版建议用 PNG（无损）或 TIFF；需后期标注用 SVG/PDF/EPS。
• 清晰度只由 scale=n 控制（窗口尺寸的 n 倍），无 DPI 参数；出版级通常 scale=3~5。
• 导出 TIFF 示例（出版无损、无损压缩位图）：
  VESTA -open a.cif -rotate_z 90 -flush -export_img scale=3 a.tif
  （把输出扩展名换成 .png/.bmp/.jpg 即得到对应格式，其余参数不变。）

4. 自动化任务配方（复制即用）

> 下例以变量 $VESTA 表示可执行文件；Windows 用 VESTA.exe，并把命令中的 \ 换成 % 或写 .bat。

配方 A：批量格式转换（无界面，最快）

# cif -> VESTA 原生格式
VESTA -nogui -i input.cif -save output.vesta
# cif -> VASP POSCAR（笛卡尔坐标）
VESTA -nogui -i input.cif -save option=cartesian output.vasp
# cif -> XYZ
VESTA -nogui -i input.cif -save output.xyz
# cif -> PDB
VESTA -nogui -i input.cif -save output.pdb
# cif -> RIETAN-FP 输入 .ins
VESTA -nogui -i input.cif -save format=rietan output.ins

批量（bash，遍历目录）：

for f in *.cif; do
  VESTA -nogui -i "$f" -save "${f%.cif}.vesta"
done

配方 B：批量渲染高清结构图（GUI 模式，支持旋转）

# 单文件：打开 -> 绕 z 转 90° -> 刷新 -> 导出 3 倍尺寸 PNG
VESTA -open struct.cif -rotate_z 90 -flush -export_img scale=3 struct.png
# macOS：
open -n -a /Applications/VESTA.app --args -open struct.cif -rotate_z 90 -flush -export_img scale=3 struct.png
# 导出 TIFF（出版无损）：仅把扩展名改成 .tif
VESTA -open struct.cif -rotate_z 90 -flush -export_img scale=3 struct.tif

批量（bash / Linux·macOS，俯视/侧视两种视角；输出格式由扩展名决定，改 .png 为 .tif 即得 TIFF）。
可直接用 examples/batch_render.sh：

EXT=png   # 改成 tif 即导出 TIFF
for f in *.cif; do
  base="${f%.cif}"
  VESTA -open "$f" -rotate_x 90 -flush -export_img scale=3 "${base}_side.${EXT}"
  VESTA -open "$f" -rotate_z 90 -flush -export_img scale=3 "${base}_top.${EXT}"
done

配方 C：计算结构因子并写出文件（无界面）

# X 射线，波长 0.7107 Å，分辨率 0.8 Å，含异常散射
VESTA -nogui -i struct.cif -calcf out=sf.hkl source=0 lambda=0.7107 resolution=0.8 anomalous=1
# 中子衍射
VESTA -nogui -i struct.cif -calcf out=sf.hkl source=1

配方 D：提取几何参数（键/角/多面体）

VESTA -nogui -i struct.cif -list bond angle poly

⚠️ 注意：-list 输出写到 VESTA 的文本区，Windows 命令行看不到、macOS 无界面也不显示。
需要程序化抓取几何量时，改用语料库工具（见第 5 节）更可靠。

配方 E：去除重复原子（合并 split site）

VESTA -nogui -i messy.cif -merge_split_site dmin=0.1 -save cleaned.vesta

配方 F：跨平台 Python 封装（推荐在流水线中使用）

见 examples/vesta_cli.py：提供 convert() / render() / calcf() / batch_render() 函数，
render() 的 outfile 扩展名决定格式（.png/.tif/...），batch_render(out_ext="tif") 可批量导出 TIFF；
封装自动处理 macOS 的 open --args 与 Windows 可执行文件名。

5. CLI 做不到的事 → 替代方案

VESTA 命令行不支持以下操作，需改用其他工具，再用 VESTA 渲染成品：

超晶胞示例（pymatgen，随后用 VESTA 渲染）：

from pymatgen.core import Structure
from pymatgen.transformations.standard_transformations import SupercellTransformation
s = Structure.from_file("POSCAR")
SupercellTransformation.from_scaling_factors(2,2,2).apply_transformation(s).to("POSCAR_super")

6. 常见坑与排错

1. macOS 不支持 -nogui：无界面转换/计算在 macOS 上要用 open -n -a VESTA.app --args -i x.cif -save y.vesta（GUI 实例但不显示窗口）。
2. Windows 上 -list 无输出：结果在 VESTA 文本区，命令行看不到。需要数值就走 pymatgen/ase。
3. 旋转后导出是旧视角：旋转/缩放后加 -flush 再 -export_img。
4. 中文/空格路径导致读写出错：VESTA 安装目录与数据目录都用纯英文路径（程序安装目录含空格通常可接受，但数据文件/工作目录尽量纯英文无空格）。
5. 单实例吞命令：批量循环里若上一次实例未退出，新命令可能发到旧窗口。链式写在同一行（-open ... -export_img ...）可让 VESTA 处理完自行退出；必要时在循环间加短延时。
6. Linux 服务器无显示器：用 xvfb-run -a VESTA -open a.cif -export_img scale=3 a.png。
7. -save 格式靠扩展名：写 out.vasp 才是 POSCAR；写 out.ins 默认是 SHELX，要 RIETAN 必须加 format=rietan。
8. 无头/服务会话 GUI 渲染卡死：后台 Bash、Windows 服务、CI 没有交互桌面（WinSta0），VESTA 启动后无法初始化窗口、写不出图。验证：启动后 ~45s 内输出目录无图片即判定无头。解决：① 在真实交互桌面双击 .bat；② 无显示 Linux 用 xvfb-run；③ 无头又要即时预览 → 见第 8 节 ASE 方案。

7. 何时不要用本 skill

• 用户只想手动在 GUI 里点选、调色、看结构 → 直接给操作指引即可，无需命令行。
• 需要真正的脚本语言（循环里读变量、条件判断）→ 用 Python/bash 包一层（见 examples/vesta_cli.py），VESTA 本身只接受固定参数列表。

8. 无头环境出图替代：ASE 球棍预览

当 VESTA GUI 不可用（无头/服务会话、无显示器服务器且不便用 xvfb）时，可用 ASE + matplotlib(Agg) 立即渲染球棍模型图片，无需任何 GUI：

pip install ase
python examples/render_preview_ase.py a.cif b.cif --outdir previews

• 输出：每个 CIF 各一张俯视（_top）与侧视（_side）PNG。
• 视角：俯视绕 x 轴转 90°（看 ab 面），侧视绕 z 轴转 90°。
• ⚠️ 这不是 VESTA 渲染：风格为 ASE 球棍 + 晶胞线框，原子配色/键样式不同；非正交晶胞按笛卡尔近似，非严格晶面投影。仅作结构即时确认，论文用图仍应在真实桌面用 VESTA 渲染（用配方 B 的 bash 脚本、或 examples/vesta_cli.py 的 batch_render()）。
• ⚠️ 读 triclinic / 某些空间群时 ASE 会警告 crystal system ... is not interpreted for space group ...，但 CIF 内原子坐标已直接读取，警告不影响结构，可忽略。
• 若需要 VESTA 真图且环境无桌面，优先把渲染放到有桌面的机器双击 render_vesta.bat（或等价脚本）。

9. 版本与更新记录

• v1.0.0（2026-09-30）：首个正式版本，固化本机（Eric Ye, Windows）实测经验。
• 两种调用模式（-nogui 数据操作 / GUI 出图）、官方第 17 章命令全集、三平台调用差异与单实例命令链。
• 导出格式由扩展名自动识别，显式支持 TIFF（.tif）。
• 跨平台 Python 封装 examples/vesta_cli.py（convert/render/calcf/batch_render）。
• 无头/服务会话 GUI 渲染卡死的限制说明，及 ASE 无头预览 examples/render_preview_ase.py 替代方案。
• 示例仅含跨平台脚本（.sh / .py），不含 .bat。