xyzrender安装与快速上手指南:从pip install到第一张分子图只要5分钟

原创2026-11-13 15:16:482,343 阅读

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 操作。下方就是这条命令直接得到的默认渲染效果:

xyzrender 默认预设渲染的咖啡因分子结构矢量图(第一张分子图效果)

输出格式由扩展名决定,用 -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

xyzrender 一行命令生成的咖啡因分子旋转 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 渲染的过渡态分子结构动画:自动识别断裂键、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

从 pip install xyzrender 到 xyzrender caffeine.xyz,你已经掌握了发布级分子图的全部核心流程——剩下的,就是把手头的结构文件丢进去试试了。

登录后查看全文
xyzrender