十二、常见问题与故障排查

Qbics-Molstar 分子可视化平台用户手册

官方网站：https://molstar.szbl.ac.cn/viewer

官方文档：https://molstar.szbl.ac.cn/docs

第三方文档：https://rxht.github.io/molstar/

本章汇总Qbics‑Molstar使用过程中高频问题、操作误区与异常解决方案，覆盖3D视图操作、结构选择、显示样式、测量标注、结构叠加、导出、交互显示等核心场景，便于快速定位与排除故障。

1 3D 视图操作类问题

1.1 无法旋转/平移/缩放结构

• 问题原因：处于错误交互模式、快捷键冲突、触控/鼠标按键未正确使用。
• 解决方法：
  1. 退出选择模式/编辑模式，回到默认视图模式。
  2. 旋转：长按鼠标左键拖动；或 Shift+左键拖动。
  3. 平移：长按鼠标右键拖动；或 Ctrl+左键拖动。
  4. 缩放：滚动鼠标滚轮；触控板双指上下滑动。
  5. 聚焦局部：右键单击目标残基/原子，自动居中并放大。
  6. 裁剪平面调整：Shift+滚轮调整前后裁剪面。

1.2 视图突然黑屏/结构消失

• 问题原因：视角被移出视野、裁剪面异常、组件被隐藏。
• 解决方法：
  1. 按视图重置快捷键恢复默认视角。
  2. 检查Components Panel，确认对应组件未被隐藏（眼睛图标为开启状态）。
  3. 重新加载结构文件。

2 结构选择类问题

2.1 无法选中原子/残基/链

• 问题原因：拾取粒度（Picking Level）不匹配、处于不可选模式。
• 解决方法：
  1. 进入Selection Mode，在工具栏设置正确的Picking Level（Atom/Residue/Chain/Structure）。
  2. 确认未锁定视图、未开启只读模式。
  3. 在3D画布或序列面板(Sequence Panel)中进行点选/框选。

2.2 选择逻辑异常（添加/减去/相交/替换失效）

• 问题原因：未正确使用选择模式工具栏的四个集合操作按钮。
• 解决方法：
  1. Add/Union：在现有选择基础上追加新选择。
  2. Subtract/Remove：从现有选择中移除新选择区域。
  3. Intersect：保留新旧选择的交集。
  4. Set：用新选择完全替换当前选择。
  5. 操作前先清空选择，避免历史选择干扰。

2.3 如何快速选择二级结构/特定氨基酸

• 选择二级结构（螺旋/折叠）： Selection Mode → Set Selection → Structure Property → 选择 Helix 或 Beta Strand/Sheet。
• 选择特定氨基酸： Selection Mode → Set Selection → Amino Acid → 点击目标氨基酸（如Histidine）。

2.4 如何反选/选择周围残基

• 反选：Set Selection → Manipulate Selection → Inverse/Complement of Selection。
• 选择某选择周围5Å残基：Set Selection → Manipulate Selection → Surrounding Residues (5 Å)。

3 显示与样式类问题

3.1 无法按链/序列/疏水性/二级结构上色

• 问题原因：未对正确组件设置着色、路径错误。
• 解决方法：
  1. 进入Components Panel → 找到Polymer组件。
  2. 点击右侧Options → Set Coloring。
  3. 按链上色：Chain Property → Chain Id。
  4. 按序列彩虹上色：Residue Property → Sequence Id。
  5. 按疏水性上色：Residue Property → Hydrophobicity。
  6. 按二级结构上色：Residue Property → Secondary Structure。

3.2 只想给某条链/某个区域改颜色/表示方式

• 解决方法：
  1. 用Selection Mode选中目标链/区域。
  2. 点击创建组件(Create Component)，生成独立组件。
  3. 在Components Panel对该组件单独设置颜色、表示方式、透明度。

3.3 无法显示表面/氢键/非共价相互作用

• 显示表面：Components Panel → Polymer → Options → Add Representation → 选择 Gaussian Surface 或 Molecular Surface。
• 显示非共价相互作用（含氢键）：
  1. Add Representation → Non-covalent Interactions。
  2. 点开交互选项，开启所需作用类型（氢键、疏水作用等）。
  3. 建议同时开启Ball & Stick以便观察原子位置。

3.4 如何调整透明度

1. 选中目标结构/区域。
2. 点击Apply Theme to Selection。
3. Action选择Transparency，拖动Value滑块调整。
4. 点击Apply Theme生效。

3.5 如何隐藏/显示部分结构

1. 选中需要隐藏的区域并创建组件。
2. 在Components Panel点击对应组件的眼睛图标，切换显示/隐藏。

4 测量与标注类问题

4.1 无法测量距离/角度

• 测量距离：选中两个原子/点 → Measurements Panel → Add → Distance。
• 测量角度：选中三个原子/点（第二个为顶点）→ Measurements Panel → Add → Angle。
• 常见错误：选中数量不对、未激活测量面板。

4.2 无法添加标注

1. 选中要标注的对象。
2. Measurements Panel → Add → Label。
3. 标注会显示在3D视图，并在Controls生成对应控制项。

5 多结构叠加（Superposition）类问题

5.1 无法叠加多个结构

• 解决方法：
  1. 上传两个及以上结构。
  2. 打开Superposition Panel。
  3. 按链叠加：选择多条链 → 点击Superpose。
  4. 按原子叠加：选择多结构中对应的原子 → 点击Superpose。
  5. 查看底部Log面板的RMSD值评估叠加质量。

5.2 RMSD 过大，如何优化

• 按链叠加时：排除柔性环、末端，只选择螺旋/折叠等刚性区域叠加。
• 按原子叠加时：选择更多分布均匀的核心原子，避免只选局部少数原子。
• 优先对齐结构核心区域，再观察整体匹配度。

5.3 多结构上传后，无法只显示其中一个

1. 打开Structure Panel → Structures列表。
2. 先点None取消全选，再单选目标结构。
3. 在Components Panel对该结构的组件执行显示/隐藏。
4. 重复操作切换不同结构显示。

6 导出类问题

6.1 图片导出模糊/带背景/尺寸不对

• 导出前在Screenshot/State Snapshot面板设置正确分辨率。
• 需要透明图：开启Transparent=on（仅PNG/WebP有效）。
• 需要自定义背景：先进入Setting修改背景色，再截图。
• 支持格式：PNG、JPEG、WebP。

6.2 模型导出失败/格式异常

• 确认结构已完整加载、无显示异常。
• 选择目标软件兼容的格式（如pdb、cif、xyz、mol2、smi等）。
• 多文件导出会自动打包为ZIP，解压后使用。
• 检查存储空间是否充足。

6.3 批量导出图片只导出部分文件

• 确认在Export Images界面Files选择All。
• 检查所有结构均已正常加载。
• 有轨迹数据的结构需正确设置轨迹帧再导出。

7 通用故障排查（必看）

1. 结构加载失败：文件损坏、格式不识别、路径含中文/特殊字符。
   • 重新下载文件；改名并使用纯英文路径；检查格式支持列表。
2. 界面卡顿/渲染慢：结构过大、分辨率过高、显卡驱动老旧。
   • 降低视图分辨率；简化表示方式（关闭过多表面、标签）；更新显卡驱动。
3. 快捷键/鼠标失效：退出选择/编辑模式；重启视图；刷新页面/重启软件。
4. 颜色/表示不生效：确认选中正确组件；先应用再检查；重建组件重试。
5. 导出文件为空/损坏：导出前预览正常；保证磁盘空间；不使用特殊字符命名。