mol-paper-renderer（mol 纸张渲染器）

Publication-Quality Molecular Renderer

使用 xyzrender 生成论文级分子结构图。这不是普通的分子查看器，而是专门为科研出图设计的自动渲染工具。

触发条件

• 用户明确要求"论文级"、"出版质量"、"publication-quality"的图片
• 需要过渡态（TS）结构、非共价相互作用（NCI）展示
• 需要分子轨道（MO）、电子密度、静电势表面
• 需要晶体结构、晶胞、周期性结构
• 需要旋转 GIF 动画用于演示
• 需要凸包（convex hull）标注芳香环或配位 sphere
• 提供 cube 文件、ORCA/Gaussian/Q-Chem 输出文件
• 普通分子可视化但要求高质量输出

功能

输入格式

• ✅ XYZ - 标准坐标文件
• ✅ mol/SDF/MOL2 - 化学标准格式
• ✅ PDB - 蛋白质数据银行格式
• ✅ SMILES - 自动 3D 嵌入（需 rdkit）
• ✅ CIF - 晶体结构（需 ase）
• ✅ cube - 分子轨道、电子密度、ESP
• ✅ ORCA/Gaussian/Q-Chem 输出 - 直接渲染计算结果
• ✅ extXYZ - 带晶格信息的周期性结构
• ✅ VASP/Quantum ESPRESSO - 第一性计算结构

输出格式

• ✅ SVG - 矢量图（默认，适合出版物）
• ✅ PNG - 位图（适合网页、PPT）
• ✅ PDF - 矢量图（适合 LaTeX）
• ✅ GIF - 旋转动画、TS 振动、轨迹动画

高级功能

• ✅ 过渡态键 - 自动检测形成/断裂的键（虚线表示）
• ✅ 非共价相互作用 - 氢键、π-堆积等（点线表示）
• ✅ 分子轨道 - HOMO/LUMO 轨道渲染
• ✅ 电子密度表面 - 深度渐变半透明等值面
• ✅ 静电势（ESP） - 映射到密度表面
• ✅ 凸包（Convex Hull） - 标注芳香环、配位 sphere
• ✅ 晶体结构 - 晶胞盒、ghost atoms、晶轴箭头
• ✅ vdW 表面 - 范德华球体叠加
• ✅ GIF 动画 - 旋转、TS 振动、轨迹
• ✅ 原子性质着色 - 电荷、自旋密度等
• ✅ 测量标注 - 键长、键角、二面角
• ✅ 矢量箭头 - 偶极矩、力、电场

使用方法

对话框中使用

生成 caffeine 的论文级分子结构图
用 xyzrender 渲染这个 XYZ 文件，输出 SVG
画出过渡态结构，显示 TS 键
显示非共价相互作用（NCI）
生成 HOMO 轨道图（从 cube 文件）
创建旋转 GIF 动画用于 PPT
画出晶胞结构，显示周期性
标注芳香环的凸包

命令行使用

# 基础渲染（XYZ → SVG）
xyzrender molecule.xyz -o output.svg

# 指定输出格式
xyzrender molecule.xyz -o output.png
xyzrender molecule.xyz -o output.pdf

# 过渡态（自动检测 TS 键）
xyzrender ts.out --ts -o ts_figure.png

# 非共价相互作用
xyzrender hbond.xyz --nci -o nci.svg

# 旋转 GIF 动画
xyzrender molecule.xyz --gif-rot -o rotation.gif

# TS 振动 GIF
xyzrender ts.out --gif-ts -o ts_vibration.gif

# 分子轨道（HOMO/LUMO）
xyzrender caffeine_homo.cube --mo -o homo.svg

# 电子密度表面
xyzrender caffeine_dens.cube --dens -o density.svg

# 静电势映射
xyzrender caffeine_dens.cube --esp caffeine_esp.cube -o esp.svg

# 晶体结构
xyzrender caffeine_cell.xyz -o crystal.svg

# 凸包（标注芳香环）
xyzrender benzene.xyz --hull 1-6 -o benzene_hull.svg

# vdW 表面
xyzrender molecule.xyz --vdw -o vdw.svg

# 显示氢原子
xyzrender ethanol.xyz --hy -o ethanol_all_h.svg

# 凯库勒化（显示双键）
xyzrender benzene.xyz --kekule -o benzene_kekule.svg

# 原子索引标注
xyzrender caffeine.xyz --idx -o caffeine_indexed.svg

# 键长测量标注
xyzrender ethanol.xyz --measure -o ethanol_measured.svg

# 从 SMILES 生成（自动 3D 嵌入）
xyzrender --smi "C1CC(O)CCC1O" --hy -o molecule.svg

# 使用预设样式
xyzrender molecule.xyz --config flat -o flat.svg
xyzrender molecule.xyz --config paton -o paton.svg

Python API

from xyzrender import load, render, render_gif, build_config

# 加载并渲染
mol = load("caffeine.xyz")
render(mol)  # Jupyter 内联显示
render(mol, output="caffeine.svg")  # 保存 SVG
render(mol, output="caffeine.png")  # 保存 PNG

# 从 SMILES 生成
smi = load("C1CC(O)CCC1O", smiles=True)
smi.to_xyz("smiles.xyz")
render(smi, output="smiles.svg")

# 使用预设配置
cfg = build_config("flat", atom_scale=1.5, gradient=False)
render(mol, config=cfg)

# 高级功能
render(mol, ts_bonds=[(1, 6)])  # 手动 TS 键
render(mol, nci_bonds=[(2, 8)])  # 手动 NCI 键
render(mol, vdw=True)  # vdW 球体
render(mol, hull=[1,2,3,4,5,6])  # 凸包
render(mol, mo=True)  # 分子轨道（cube 文件）
render(mol, dens=True)  # 密度表面
render(mol, esp="esp.cube")  # ESP 映射

# GIF 动画
render_gif("mol.xyz", gif_rot="y", output="rotation.gif")
render_gif("ts.out", gif_ts=True, output="ts_vib.gif")

参数说明

基础参数

样式参数

显示参数

过渡态/NCI

表面/轨道

凸包（需要 xyzrender >= 0.3）

注意: 凸包功能需要 xyzrender >= 0.3。当前安装版本为 0.2.1。

晶体

动画

标注

输出示例

基础分子渲染

$ xyzrender caffeine.xyz -o caffeine.svg
✓ 已生成：caffeine.svg (800x800, SVG)

过渡态结构

$ xyzrender sn2.out --ts -o sn2_ts.png
✓ 已生成：sn2_ts.png (800x800, PNG) [过渡态，自动检测 TS 键]

非共价相互作用

$ xyzrender hbond.xyz --nci -o hbond.svg
✓ 已生成：hbond.svg (800x800, SVG) [NCI 相互作用]

旋转 GIF 动画

$ xyzrender molecule.xyz --gif-rot -o rotation.gif
✓ 已生成：rotation.gif (800x800, 120 帧，10fps)

分子轨道（HOMO）

$ xyzrender caffeine_homo.cube --mo -o homo.svg
✓ 已生成：homo.svg (800x800, SVG) [HOMO 轨道]

静电势表面

$ xyzrender caffeine_dens.cube --esp caffeine_esp.cube -o esp.svg
✓ 已生成：esp.svg (800x800, SVG) [ESP 映射]

晶体结构

$ xyzrender caffeine_cell.xyz -o crystal.svg
✓ 已生成：crystal.svg (800x800, SVG) [晶胞，ghost atoms，晶轴]

凸包标注

$ xyzrender benzene.xyz --hull 1-6 -o benzene_hull.svg
✓ 已生成：benzene_hull.svg (800x800, SVG) [芳香环凸包]

样式预设

依赖安装

基础安装

pip install xyzrender

完整功能安装

# 所有功能
pip install 'xyzrender[all]'

# 或按需安装
pip install xyzrender[smiles]  # SMILES 支持（rdkit）
pip install xyzrender[cif]     # CIF 支持（ase）
pip install xyzrender[crystal] # VASP/QE 支持（phonopy）
pip install xyzrender[v]       # 交互式查看器（vmol，Linux only）
pip install xyzrender[gif]     # GIF 生成（cairosvg, Pillow）

使用 uv 安装

uv tool install xyzrender
uv tool install --editable .  # 开发模式

与其他技能配合

与 mol_2d_viewer 配合

• mol_2d_viewer: 快速 2D 结构预览
• mol_paper_renderer: 论文级最终出图

# 快速预览
python3 scripts/mol_2d_viewer.py -s "CCO" -o ethanol_preview.png

# 论文级渲染
xyzrender ethanol.xyz -o ethanol_paper.svg --config paton

与 mol_3d_viewer 配合

• mol_3d_viewer: 生成 3D 坐标、SDF 文件、可交互 HTML
• mol_paper_renderer: 从 3D 坐标生成出版质量图片

# 生成 3D 坐标
python3 scripts/mol_3d_viewer.py -s "CCO" -o ethanol

# 使用生成的 XYZ 进行论文级渲染
xyzrender ethanol.xyz -o ethanol_paper.svg --config paton --hy

与 iupac_to_smiles 配合

# 1. 转换名称为 SMILES
python3 scripts/iupac_to_smiles.py -n "caffeine" -o result.json

# 2. 提取 SMILES 并生成 3D 坐标
SMILES=$(cat result.json | jq -r '.results[0].smiles')
xyzrender --smi "$SMILES" --hy -o caffeine.svg

完整工作流程示例

示例 1: 从 SMILES 到论文级图片

# 一键生成（SMILES → 3D 嵌入 → 论文级 SVG）
xyzrender --smi "C1=CC(=CC=C1C(=O)O)C(=O)O" --hy --config paton -o aspirin.svg

示例 2: 过渡态分析

# 从 ORCA 输出直接渲染 TS 结构
xyzrender ts_freq.out --ts --hy --vdw 84-169 -o ts_figure.svg

# 生成 TS 振动 GIF
xyzrender ts_freq.out --gif-ts --gif-rot -o ts_animation.gif

示例 3: 非共价相互作用分析

# 从几何结构自动检测 NCI
xyzrender complex.xyz --nci -o nci_auto.svg

# 或使用 NCIPLOT cube 文件
xyzrender complex_dens.cube --nci-surf complex_grad.cube -o nci_surface.svg

示例 4: 分子轨道可视化

# 从 ORCA 生成 cube 文件后渲染
orca_plot calculation.out -i
# 选择 HOMO 轨道，生成 caffeine_homo.cube

# 渲染 HOMO
xyzrender caffeine_homo.cube --mo -o homo.svg

# 渲染 LUMO
xyzrender caffeine_lumo.cube --mo --mo-colors teal orange -o lumo.svg

示例 5: 晶体结构

# 从 extXYZ 渲染（自动检测晶格）
xyzrender caffeine_cell.xyz -o crystal.svg

# 沿 [111] 方向观察
xyzrender caffeine_cell.xyz --axis 111 -o crystal_111.svg

# 生成旋转 GIF
xyzrender caffeine_cell.xyz --gif-rot 111 -o crystal_rot.gif

示例 6: 静电势分析

# 从 ORCA 生成密度和 ESP cube
orca_plot calculation.out -i
# 生成 density.cube 和 esp.cube

# 渲染 ESP 映射表面
xyzrender density.cube --esp esp.cube -o esp_map.svg

注意事项

• ✅ 论文级质量 - 专为出版物设计，默认 SVG 矢量输出
• ✅ 自动检测 - TS 键、NCI、芳香性自动识别
• ✅ 多种输入 - 支持几乎所有化学/计算化学格式
• ✅ 高级功能 - 轨道、密度、ESP、凸包、晶体
• ✅ 动画支持 - 旋转、TS 振动、轨迹 GIF
• ⚠️ SMILES 需要 rdkit - pip install xyzrender[smiles]
• ⚠️ 晶体需要 phonopy - pip install xyzrender[crystal]
• ⚠️ GIF 需要 cairosvg+Pillow - pip install xyzrender[gif]
• ⚠️ 交互查看器仅 Linux - pip install xyzrender[v]
• ⚠️ cube 文件需外部生成 - 使用 ORCA/Gaussian 的 cubegen

错误处理

技术实现

键级检测

• 库: xyzgraph
• 方法: 基于几何距离的键级感知
• 支持: 单键、双键、三键、芳香键

TS 键检测

• 库: graphRC
• 方法: 从虚频振动模式分析
• 输出: 形成/断裂的键（虚线）

NCI 检测

• 库: xyzgraph
• 方法: 几何判据（距离、角度）
• 支持: 氢键、卤键、π-堆积、阳离子-π

晶体渲染

• 库: phonopy（可选）、ase（CIF）
• 功能: 晶胞盒、ghost atoms、晶轴箭头
• 方向: 支持 Miller 指数 [HKL] 观察

GIF 生成

• 库: CairoSVG、Pillow
• 类型: 旋转、TS 振动、轨迹
• 控制: 帧率、帧数、旋转轴

性能参考

输出文件位置

默认输出目录：~/.openclaw/media/mol-paper-renderer/

mkdir -p ~/.openclaw/media/mol-paper-renderer

高级技巧

自定义样式配置

创建 my_style.json：

{
  "canvas_size": 1200,
  "atom_scale": 2.0,
  "bond_width": 3.0,
  "gradient": true,
  "fog": true,
  "background": "#f8f8f8",
  "colors": {
    "C": "#333333",
    "H": "#ffffff",
    "N": "#3050F8",
    "O": "#FF0000"
  }
}

使用：

xyzrender molecule.xyz --config my_style.json -o custom.svg

批量标注

创建 labels.txt：

1 2 d
2 3 4 a
1 2 3 4 t
7 "Partial charge: +0.5"

使用：

xyzrender molecule.xyz --label labels.txt -o labeled.svg

原子性质着色

创建 charges.txt：

1 0.512
2 -0.234
3 0.041

使用：

xyzrender molecule.xyz --cmap charges.txt --cmap-range -0.5 0.5 -o colored.svg

版本说明

当前安装版本: xyzrender 0.2.1

已测试功能（✅ 可用）

• ✅ SMILES → 3D 嵌入并渲染
• ✅ XYZ/SDF/PDB 文件渲染
• ✅ SVG/PNG/GIF 输出
• ✅ 样式预设（default, flat, paton）
• ✅ 氢原子显示/隐藏
• ✅ 凯库勒键级
• ✅ vdW 球体表面
• ✅ 原子索引标注
• ✅ 键长/键角/二面角测量
• ✅ 旋转 GIF 动画
• ✅ TS 振动 GIF（需要 QM 输出文件）
• ✅ 分子轨道渲染（需要 cube 文件）
• ✅ 电子密度表面
• ✅ 静电势映射
• ✅ NCI 相互作用检测
• ✅ 晶体结构（需要 phonopy）

需要更新版本的功能（⚠️ 0.3+）

• ⚠️ 凸包（Convex Hull）
• ⚠️ 某些高级标注功能

如需使用最新功能，可升级：

pip install --upgrade xyzrender --break-system-packages

资源链接

• GitHub: https://github.com/aligfellow/xyzrender
• 文档: https://xyzrender.readthedocs.io
• Web App: https://xyzrender-web.streamlit.app
• 依赖:

- xyzgraph: https://github.com/aligfellow/xyzgraph - graphRC: https://github.com/aligfellow/graphRC - v (viewer): https://github.com/briling/v - xyz2svg (inspiration): https://github.com/briling/xyz2svg