CrystalPath 是一个面向晶体结构与后续离子通道分析的轻量 CIF 查看器。V0.3 在可靠结构显示基础上加入第一版间隙位点与配位多面体分析。
- 读取 CIF，并展开为完整晶胞
- 显示晶胞参数、空间群、组成和位点数
- 球棍模型、周期成键与非正交晶胞线框
- 以指定元素为配位中心，补齐晶胞外的周期配位原子
- 默认仅显示 2.40 Å 内的配位键，可在界面中调整元素和键长
- 按元素显示、隐藏和高亮
- 每种元素提供参考显示半径，可手动调节并一键恢复
- 原子按元素批量渲染，化学键与周期场景缓存，支持流畅旋转和快速重绘
- 顶部提供放大、缩小和恢复初始等轴视角按钮
- 自动寻找晶胞间隙并按四面体型、八面体型等局部几何分类
- 将选中类型显示为半透明配位多面体，可叠加中心点和自由半径球
- 点击原子查看分数坐标、笛卡尔坐标和占位率
- 分别沿 a、b、c 方向生成超晶胞
- 恢复原始晶胞、重置视角、保存 PNG
- 对部分占位原子使用透明度提示
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m crystalpath激活包含项目依赖的 Python 环境后，也可以直接运行 ./run_crystalpath.command。项目需要 Python 3.11 或更高版本。
source .venv/bin/activate
python -m pip install -e '.[test]'
python -m pytest可以先打开 examples/fcc_cu.cif 和 examples/bcc_fe.cif 验证基础结构及间隙分析。
点击顶部“间隙分析”打开分析面板：
- 勾选作为几何障碍物的元素。
- 设置独立的分析半径。
- 点击“分析当前 CIF 晶胞”。
- 在结果树中选择四面体型、八面体型或其他类型。
- 调节多面体透明度，并可显示间隙中心和最大自由半径球。
examples/fcc_cu.cif 是 FCC 验收样例，应得到 8 个四面体间隙和 4 个八面体间隙；examples/bcc_fe.cif 是 BCC 验收样例，应得到 12 个四面体间隙和 6 个八面体间隙。
V0.3.2 起候选点不再局限于 Voronoi 顶点，还会分析 Voronoi 面中心和棱中心。局部配位分类允许多个距离壳层，因此可以识别 BCC 中由 2 个近邻 + 4 个较远邻 构成的畸变八面体。位于晶胞面或棱上的间隙按周期等价位点只计一次，但多面体会使用相邻晶胞的周期原子像完整显示，不会在晶胞边界切断。
V0.3.3 在结果树中进一步按“晶胞内部、晶胞面上、晶胞棱上、晶胞角点”分组。每个位置分组和每个具体位点都可独立勾选显示。例如 BCC 的八面体结果会明确列出“晶胞面上 3”和“晶胞棱上 3”，用户可根据采用的晶胞计数或材料学判断隐藏任意一组，而不会删除分析结果。
V0.3.4 将整个间隙分析面板改为可滚动页面。“间隙类型与位点”具有更大的默认高度，并可通过下方分隔条上下拖动调整。面板底部的“收起到下方”会释放右侧显示空间，同时在状态栏保留“展开间隙分析”按钮。
V0.3.5 增加第一版 macOS 打包原型。项目使用 PyInstaller 的 onedir App 模式，将 Python、Qt、VTK 与晶体学依赖打包进 CrystalPath.app。当前 Release 压缩包面向 Apple Silicon，仅使用本地 ad-hoc 签名，未使用 Developer ID 签名，也未经过 Apple 公证。
当前版本只分析几何间隙位点和局部配位多面体，不分析间隙网络、瓶颈、迁移通道或真实迁移能垒。低对称结构可能输出“畸变 CN”或“其他 CN”类型；这些是几何候选，不能直接等同于稳定的离子占位。部分占位位点暂按全部存在的保守方式处理。
原胞可以只包含 1 个或 2 个原子，分析会先生成周期原子像，不要求 CIF 本身至少列出 4 个位点。结果树中的间隙数量始终按原始 CIF 晶胞报告；当显示设置为超晶胞时，多面体、中心点、自由半径球和选中高亮会复制到整个超晶胞。
本项目目前未附带开源许可证。仓库公开可见不代表授予复制、修改或再分发代码的许可。
在 Apple Silicon Mac 上创建独立构建环境并安装部署依赖：
python3 -m venv .venv-build
source .venv-build/bin/activate
python -m pip install -e '.[test,deploy]'
./packaging/macos/build_app.sh构建完成后，应用位于 dist/macos/CrystalPath.app。运行独立启动检查：
CRYSTALPATH_SMOKE_TEST=1 \
dist/macos/CrystalPath.app/Contents/MacOS/CrystalPath生成 GitHub Release 使用的 ZIP。脚本会在临时目录清除 Finder 元数据、执行 ad-hoc 签名并严格验证，再创建压缩包：
./packaging/macos/package_release.sh生成带有 Applications 快捷方式、可拖动安装的 DMG：
./packaging/macos/package_dmg.sh压缩包和磁盘映像分别写入 release/CrystalPath-0.3.5-macos-arm64.zip 与 release/CrystalPath-0.3.5-macos-arm64.dmg，并各自生成 SHA-256 校验文件。该原型只有 ad-hoc 签名，没有 Developer ID 签名，也未经过 Apple 公证；从互联网下载后可能需要在 macOS“系统设置 → 隐私与安全”中选择“仍要打开”。