xyzrender安装与快速上手指南:从pip install到第一张分子图只要5分钟
xyzrender安装与快速上手指南:从pip install到第一张分子图只要5分钟
xyzrender 是一个发布级质量的分子结构可视化工具(Publication-quality molecular graphics):一条命令即可把 XYZ、PDB、SDF、SMILES、CIF、cube 以及 Gaussian/ORCA/Q-Chem 等量子化学输入输出文件,渲染成带深度感、自动取向、自动识别键级与芳香环的 SVG 矢量分子图,还能直接导出 PNG、PDF 和旋转 GIF 动画。本指南带你完成 xyzrender 安装,并在 5 分钟内画出第一张分子图。
一键安装 xyzrender:pip install 一步到位
要求 Python 3.10+,安装方式三选一:
pip install xyzrender # 最常用:从 PyPI 安装稳定版
uv tool install xyzrender # 使用 uv 管理命令行工具
uvx xyzrender mol.xyz # 免安装:临时运行一次试试
如果你需要 SMILES 输入、CIF 解析或 SHELXL 支持,可以按需加装可选依赖:
pip install 'xyzrender[smi]' # SMILES 输入(rdkit)
pip install 'xyzrender[cif]' # CIF 输入 + ASE 查看器(ase)
pip install 'xyzrender[shelxl]' # SHELXL .res/.ins 解析
pip install 'xyzrender[all]' # 一次装齐以上全部
想从源码安装也可以,克隆仓库后执行 pip install .:
git clone https://gitcode.com/gh_mirrors/xy/xyzrender
cd xyzrender
pip install .
安装完成后用 xyzrender --help 能列出全部参数,说明一切就绪。完整安装说明见 installation.md。
30 秒画出第一张分子图:一行命令出 SVG
用仓库自带的咖啡因结构 caffeine.xyz 试试(仓库中 examples/structures/ 目录还有乙醇、苯、MOF-5 等几十个可直接开玩的测试结构):
xyzrender caffeine.xyz
就这么一行,当前目录会生成 caffeine.svg——自动取向、深度雾化、键级和芳香环全部自动识别,无需任何 GUI 操作。下方就是这条命令直接得到的默认渲染效果:
输出格式由扩展名决定,用 -o 指定即可:
xyzrender caffeine.xyz -o render.svg # 矢量图,默认格式
xyzrender caffeine.xyz -o render.png # 位图,用于 PPT/网络
xyzrender caffeine.xyz -o render.pdf # 高质量印刷
也可以从标准输入读:cat caffeine.xyz | xyzrender;直接渲染量子化学输出文件(格式自动检测):xyzrender calc.out。CLI 完整说明见 quickstart_cli.md。
换预设与调风格:常用参数速查
内置 12 个预设(src/xyzrender/presets/ 中可看到对应的 JSON 定义),--config 一键切换风格:
| 命令示例 | 效果 |
|---|---|
xyzrender caffeine.xyz --config paton |
PyMOL 风格配色 |
xyzrender caffeine.xyz --config skeletal |
骨架式(只显示碳骨架) |
xyzrender caffeine.xyz --config vdw |
空间填充范德华球 |
xyzrender caffeine.xyz --hy |
显示全部氢原子 |
xyzrender caffeine.xyz --hl "N,O" |
高亮所有 N、O 原子 |
xyzrender caffeine.xyz -t |
透明背景 |
所有参数(配色、原子半径、键宽、雾效等)都可用命令行覆盖,完整参数表见 cli_reference.md。
生成旋转 GIF:让分子图在幻灯片里动起来
做演示文稿时,一个旋转动画比静态图更有说服力。给上一行命令加上 --gif-rot 和输出路径 -go:
xyzrender caffeine.xyz --gif-rot -go caffeine.gif
此外还支持弹跳动画(--gif-bounce 50)、轨迹动画(多帧 XYZ)、扩散/组装动画等多种类型,详见 animations 示例。
Python 与 Jupyter 快速上手:两步渲染
如果你更喜欢脚本化工作流,Python API 和 CLI 是一一对应的——每个命令行参数都能写成关键字参数:
from xyzrender import load, render, render_gif
mol = load("caffeine.xyz")
render(mol) # Jupyter 中直接内联显示
render(mol, output="caffeine.png", hy=True, config="paton")
render_gif(mol, gif_rot="y", output="caffeine.gif")
API 细节请参考 python_api.md。
进阶能力一瞥:不止是"画个球棍模型"
装好 xyzrender 后,你会发现它把分子可视化里最烦的手工活都自动化了:
- 过渡态虚键:从虚频振动自动识别形成/断裂的键,渲染成虚线(
--ts) - 非共价作用 NCI:氢键等弱相互作用自动检测并画成点线(
--nci) - 表面渲染:分子轨道、电子密度、ESP、NCI 表面的 cube 文件直接画(solid / mesh / contour / dot 多种样式)
- 立体化学标注:R/S、E/Z、螺旋手性等自动标注
- 晶体结构:晶胞框、幽灵原子、超胞、晶轴箭头自动识别(VASP、QE、CIF 等)
下图是一条命令同时渲染过渡态、NCI 表面、范德华球并做旋转的成片效果:
遇到问题怎么办:常见安装与使用排查
| 现象 | 解决办法 |
|---|---|
xyzrender: command not found |
重新运行 pip install -U xyzrender,并确认 pip 的 bin 目录在 PATH 中 |
| 想用 SMILES 却报错 | 先安装可选依赖 pip install 'xyzrender[smi]' |
| 想确认支持的输入格式 | 运行 xyzrender --help 查看 INPUT 支持的全部扩展名 |
| PNG 输出缺少滤镜效果 | 安装 [resvg-py] 后效果更佳,否则自动回退到 CairoSVG |
下一步:继续探索 xyzrender
- 官方文档安装页:installation.md
- 可运行的完整示例笔记本:examples.ipynb
- 命令入口源码:cli.py
- 更多功能示例:高亮与配色、分子叠加、凸包与孔道、晶体结构,全部收录在 docs/source/examples/ 中
从 pip install xyzrender 到 xyzrender caffeine.xyz,你已经掌握了发布级分子图的全部核心流程——剩下的,就是把手头的结构文件丢进去试试了。


