从分子动力学轨迹到结构分析结果,OVITO 鸿蒙PC版的 LAMMPS 与 XYZ 解析、Canvas 正交投影和修饰器管线
本文记录 OVITO 粒子可视化工作台在鸿蒙 PC 上的适配过程。这个应用要做的事可以一句话说完:把一份分子动力学轨迹的文本读进来,看到原子在哪、把不关心的那部分筛掉、对剩下那一帧算出结构量、把过程写成一份能复现的报告。听起来像是要一个图形引擎,实际上全程没有碰 WebGL——三维坐标在渲染层被算成二维像素,用 Canvas 2D 一个一个画圆,深度排序用的是一维数组排序,而不是任何形式的图形管线。文章按源码顺序拆解这条链路:主进程如何只用八个 IPC 就把开窗口、管授权、落盘三件事管住,七个纯函数引擎如何在渲染进程里按依赖顺序接起来,LAMMPS dump 与扩展 XYZ 两种文本格式如何收敛成同一份「盒子加粒子数组」的帧结构,修饰器管线为什么每一步都要返回新数组而不是就地修改,以及 RDF、配位数、MSD、簇分析这四件结构量为什么必须写死口径。文末给出逐条核出的十处工程缺陷与上架前必须做的替换项。
所有代码引用均来自仓库内 web_engine 模块下 resources/app 目录的真实文件,工程配置取自当前 ohos_hap 目录的实际状态。文中不出现虚构的性能数字与真机结论;凡是涉及耗时的表述,都以工程内可查的常量与源码路径为准。构建产物的字节数来自 electron/build/default/outputs 下实际存在的两个 hap 文件,体积构成按 libs/arm64-v8a 目录内四个 so 的真实大小换算。三张运行截图取自该构建在鸿蒙 PC 桌面环境下的实际界面。
欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
AtomGit 仓库地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_OVITO
说明:文中代码包含源码节选,省略处以注释标出;未展示完整函数、对象或条件分支的片段需要结合原始上下文阅读,不能独立运行。
一、技术架构分析
1.1 主进程只做三件事
main.js 的文件头把边界写得很直白:
/* OVITO 粒子工作台 —— 主进程
* 只做三件事:开窗口、管路径授权(对话框是唯一入口)、把轨迹 / 报告 / 场景落盘。
*
* 轨迹解析、渲染、管线与分析全在渲染层的纯函数引擎里跑:主进程不持有粒子数据,
* 所以打开大文件不会打断界面里的视角操作,分析也不经过 IPC。
*
* 能力边界写在 app:info 的 unsupported 里,界面照抄一遍:
* 不做 GPU 光线追踪、不读 OVITO 原生场景与二进制轨迹、不做 CNA/PTM 与 Python 脚本。
*/
「主进程不持有粒子数据」这句话是整个架构的分水岭。分子动力学轨迹动辄几十万行,如果按常见做法把文件内容过 IPC 一直在主进程留一份,一次旋转视角就要跨进程取数;这里反过来——主进程只把整段文本读成字符串递过去,渲染层解析完之后主进程立刻忘了它。之后所有的投影、拾取、切片、选择、分析、画图,全在同一条线程里对同一个数组做运算。
八个 IPC 通道在源码里编了号,从 1 到 8,一个不漏:
| 编号 | 通道 | 落点 | 作用 |
|---|---|---|---|
| 1 | app:info | 主进程 | 版本、平台、授权目录、五个上限、四条能力边界 |
| 2 | scene:save | 主进程 | 先 JSON.parse 校验,再走通用文本落盘 |
| 3 | scene:open | 主进程 | 只回文本,结构收敛交给渲染层 |
| 4 | traj:open | 主进程 | 只回文本,解析交给渲染层 |
| 5 | data:save | 主进程 | 分析数据,白名单 csv / json |
| 6 | report:save | 主进程 | 报告,白名单 md / json / csv / txt |
| 7 | clip:write | 主进程 | 写剪贴板,只回字符数 |
| 8 | shell:reveal | 主进程 | 在文件管理器里定位,唯一调 guard 的通道 |
八个通道里,只有 2、5、6 三个会写盘,3、4 两个会读盘,剩下三个分别是元数据、剪贴板与定位。所有读写都走同一个对话框入口,这一点在第四章展开。
通道少的原因不是功能少,而是功能全在渲染层。渲染层要什么,主进程就递什么——递进去的是一条 JSON 文本,递出来的是一个路径字符串,中间没有任何「对象」被序列化。这让整条链路在调试上简单得有点朴素:任何一个数值不对,只要看渲染层那七个引擎就够了,主进程不可能背着你改数。
能力边界同样是主进程声明的,写在 app:info 的 unsupported 数组里,界面的「环境与限制」面板原样照抄:
unsupported: [
'不做 GPU 光线追踪与环境光遮蔽:渲染是 Canvas 2D 正交投影 + 深度排序',
'只读文本轨迹(LAMMPS dump / 扩展 XYZ),不读 OVITO 原生 .ovito 场景与二进制轨迹',
'不做键角拓扑与 CNA / PTM 晶体结构识别:配位数按 cutoff 球内邻居计数',
'不提供 Python 脚本接口与批处理队列,分析在本进程内顺序执行'
]
这四条不是谦辞,是使用说明。原版 OVITO 是桌面端重资产软件,OpenGL 渲染、CNA/PTM 结构识别、Python 脚本接口一应俱全;这个壳明确不做这些,同时保证「读得进、看得见、算得出、写得下」。用户在界面上第一次点「环境与限制」,读到的就是这四句,不会在使用了半小时之后才发现没有光追。
1.2 七个纯函数引擎与四种依赖形态
七个引擎都放在 engines 目录下,文件名统一前缀 ov-,每个都是一个 UMD 工厂,浏览器里挂到 window 上,Node.js 里走 module.exports。ov-report.js 的头部是最完整的形态:
(function (root, factory) {
var U = (root && root.OvUtil)
|| ((typeof require === 'function') ? require('./ov-util.js') : null);
var V = (root && root.OvVec)
|| ((typeof require === 'function') ? require('./ov-vec.js') : null);
var S = (root && root.OvScene)
|| ((typeof require === 'function') ? require('./ov-scene.js') : null);
var api = factory(U, V, S);
if (typeof module !== 'undefined' && module.exports) module.exports = api;
if (root) root.OvReport = api;
})(typeof globalThis !== 'undefined' ? globalThis : this, function (U, V, S) {
这段样板重复了七遍,但每一遍的参数顺序不一样,这是一处必须盯着看的地方。ov-vec 只吃 U;ov-io 只吃 U;ov-scene 吃 (U, V);ov-pipeline 吃 (U, S, V);ov-analysis 与 ov-report 吃 (U, V, S)。也就是说 pipeline 把场景放在了第二个参数、把向量放在第三个,而 analysis 与 report 正好相反。工厂函数内部的形参名会告诉你真实顺序,但如果凭印象写错一位,运行时报的会是「S.typeKey is not a function」这类指向不明的错误。
依赖形态可以列成一张表:
| 引擎 | 行数 | 依赖 | 对外主要能力 |
|---|---|---|---|
| ov-util | 83 | 无 | num、clamp、round、fmt、stamp、nonEmptyLines |
| ov-vec | 122 | ov-util | 向量运算、minImage、rotate、project、fitScale |
| ov-io | 338 | ov-util | detect、parseLammps、parseXyz、formatLabel |
| ov-scene | 163 | ov-util、ov-vec | typeKey、types、frameStats、sceneStats、sanitizeScene |
| ov-pipeline | 207 | ov-util、ov-scene、ov-vec | normOp、describe、apply |
| ov-analysis | 337 | ov-util、ov-vec、ov-scene | rdf、coordination、msd、clusters |
| ov-report | 241 | ov-util、ov-vec、ov-scene | collect、toMarkdown、toCsv、build |
七个文件合计 1491 行、52144 字节。行数最多的两个是轨迹解析与结构分析,都是三百多行;最少的是通用小工具,83 行。这个分布符合直觉:真正难的从来不是把东西画出来,而是把别人的文本格式读对、把物理量算对。
index.html 里的引入顺序必须与依赖方向一致,一共八行 script:
engines/ov-util.js
engines/ov-vec.js
engines/ov-io.js
engines/ov-scene.js
engines/ov-pipeline.js
engines/ov-analysis.js
engines/ov-report.js
renderer.js
这个顺序不能随意调换。ov-scene 在加载时就要取到 OvUtil 与 OvVec,ov-pipeline 要取到 OvScene,ov-report 三个都要。虽然每个引擎都写了 root 兜底,缺依赖时不会直接抛异常,但工厂函数拿到的会是 null,等到第一次调用才炸——那时代码已经跑到了一半,堆栈里看不出是加载顺序的问题。
渲染层对引擎缺失做了一层防护,用的是 eng() 而不是直接取 window:
function eng(name) {
try { return window[name] || null; } catch (e) { return null; }
}
var U = eng('OvUtil');
var V = eng('OvVec');
var IO = eng('OvIo');
var SC = eng('OvScene');
var PL = eng('OvPipeline');
var AN = eng('OvAnalysis');
var RP = eng('OvReport');
boot() 的最后会检查这七个引用,缺任何一个就往状态条写一句「有引擎未装载:功能会降级,详情见「环境与限制」」。这不是防御性编程的花架子,而是在鸿蒙 PC 上真会遇到的情况:如果某个 js 文件因为打包问题没进 hap,页面仍然能打开,用户能看到是哪个引擎缺了,而不是对着白屏猜。
1.3 一份引擎结果喂三个消费者
渲染层文件头写着一条铁律,这句是本项目最关键的架构决定:
/* 一条铁律:画面、表格、报告读同一份引擎结果。粒子从 ov-io 解析进来,管线在
* ov-pipeline 里算出视图帧,分析结果在 ov-analysis 里落定,报告由 ov-report 组装;
* 渲染层只做三件事:把三维投影到 Canvas 2D、把结果摆进面板、把路径类操作交给主进程。
*/
落到代码上,这条铁律是一个 12 行的函数:
/* 管线结果优先:画面与分析都以「管线视图」为准 */
function curFrame() {
if (S.result && S.result.frame) return S.result.frame;
return baseFrame();
}
所有取帧的地方都调它,没有例外。画面的 drawScene 用它,面板的 renderTypes 用它,分析的 runAnalysis 用它,报告组装用的 reportCtx 也用它。这意味着界面上看到的粒子、报告里写的粒子数、RDF 积分用的粒子,永远是同一个数组。
这一致性不是自然形成的,而是靠一个叫 dropAnalysis 的开关守住的:
/* 管线一变,帧相关的分析就不再对应当前视图:宁可让人重新点一次,也不能让报告里
* 出现「新管线 + 旧数值」这种自相矛盾的组合。 */
function dropAnalysis() {
if (!S.analysis) return false;
S.analysis = null;
S.dataNote = '';
return true;
}
pushOp、applyTypeSelection、removeOp、clearPipeline、setFrame、loadScene、openScene,七处调用点全部在改完帧之后立刻把 S.analysis 清空。清空的代价是用户要重点一次「执行分析」,收益是报告里不会出现「粒子数 125,RDF 粒子对数 19900」这种一眼自相矛盾的组合。
报告这条链路最能说明问题。reportCtx 组装上下文时,帧取 curFrame(),场景统计重算一遍,管线日志取 S.result.log,分析结果取 S.analysis:
function reportCtx() {
return {
frame: curFrame(),
sceneStats: SC
? SC.sceneStats({ frames: S.frames, source: S.source || {} })
: { frames: S.frames.length, total: 0, minAtoms: 0, maxAtoms: 0 },
pipeline: {
ops: S.ops,
log: S.result ? S.result.log : [],
removed: S.result ? S.result.removed : 0,
selected: S.result ? S.result.selected : 0
},
analysis: S.analysis || {},
env: S.info || {},
source: S.source || {},
view: {
yaw: U.round(S.view.yaw, 4),
pitch: U.round(S.view.pitch, 4),
zoom: U.round(S.view.zoom, 3),
radius: U.round(S.radius, 3),
box: S.boxOn,
periodic: S.periodic,
colorMode: S.colorMode
}
};
}
注意 analysis 那一行:S.analysis || {}。分析没跑就是空对象,报告里的四段结构量会各自写成「本次没有计算」,而不是留白或写 0。一处小细节,但它决定了报告能不能被当成实验记录读——「没算」和「算出 0」是两件完全不同的事,前者是数据缺失,后者是物理结论。
二、环境准备
2.1 工程结构与模块依赖
ohos_hap 下是两个模块,一薄一厚:
| 模块 | 类型 | 内容 | 说明 |
|---|---|---|---|
| electron | entry | 三个 ability、两个 extensionAbility | 壳入口,负责窗口生命周期与系统能力 |
| web_engine | har | 四个 so、resfile 资源、权限清单 | 真正跑 Electron 的那一层 |
electron 的 oh-package.json5 只声明了一个依赖:
{
"name": "electron",
"main": "",
"version": "1.0.0",
"dependencies": {
"web_engine": 'file:../web_engine',
}
}
web_engine 的依赖则分两类,一类是 npm 侧的,一类是原生库:
{
"name": "web_engine",
"version": "1.0.0",
"main": "Index.ets",
"license": "Apache-2.0",
"devDependencies": {
'libadapter.so': 'file:./src/main/cpp/types/libadapter',
},
"dependencies": {
"inversify": "^6.0.1",
"reflect-metadata": "^0.1.13"
}
}
inversify 与 reflect-metadata 是 Electron 壳内部做依赖注入用的,跟 OVITO 这一层的业务代码没有关系——那七个引擎全是零依赖的原生 JavaScript,连 lodash 都没引。这一点对鸿蒙 PC 很重要:包体里任何多出来的纯 JS 依赖都要走一遍 ohpm 解析,而这里除了 Electron 本身的四个原生库,前端侧没有任何第三方运行时。
两个模块的 license 字段不一致:web_engine 写的是 Apache-2.0,electron 写的是空字符串。上架时如果审核要核对许可证,这个空值需要补上。
ovito 自己的应用资源全部在 web_engine 的 resfile 目录下,路径是:
web_engine/src/main/resources/resfile/resources/app/
这个目录一共 12 个文件、167727 字节、4875 行:
| 文件 | 字节 | 行数 | 职责 |
|---|---|---|---|
| index.html | 20026 | 391 | 七个面板、三块画布、引擎引入、关于对话框 |
| main.js | 12764 | 356 | 主进程:开窗、授权、落盘 |
| package.json | 555 | 21 | 名称、描述、npm 脚本 |
| renderer.js | 66997 | 1899 | 渲染层:投影、绘制、面板、IPC 调用 |
| styles/ovito.css | 15241 | 717 | 主题变量与四层布局 |
| engines/ov-util.js | 2201 | 83 | 通用小工具 |
| engines/ov-vec.js | 3892 | 122 | 向量与投影 |
| engines/ov-io.js | 13280 | 338 | 两种轨迹格式解析 |
| engines/ov-scene.js | 5153 | 163 | 场景统计与结构收敛 |
| engines/ov-pipeline.js | 7094 | 207 | 修饰器管线 |
| engines/ov-analysis.js | 10864 | 337 | RDF、配位数、MSD、簇 |
| engines/ov-report.js | 9660 | 241 | 三种格式的报告组装 |
占比上,renderer.js 一个文件就占了 39.9%,七个引擎合计 31.1%,样式表 9.1%,index.html 11.9%。渲染层比引擎还大,这在别的项目里通常是坏事,在这里却是必然:引擎是纯函数,一个函数就是一段逻辑;渲染层要把七块面板、二十个按钮、三块画布、八种状态徽标全部对齐,还要保证每个面板的提示语跟当前状态一致,横向展开就是一千九百行。
2.2 SDK 与构建配置
根 build-profile.json5 声明的产品配置很标准,但有三个字段值得单独看:
{
"app": {
"products": [
{
"name": "default",
"signingConfig": "default",
"compatibleSdkVersion": "5.0.5(17)",
"compatibleSdkVersionStage": "release",
"runtimeOS": "HarmonyOS",
"buildOption": {
"nativeLib": {
"collectAllLibs": true
}
}
}
]
}
}
compatibleSdkVersion 是 5.0.5(17),也就是 API 17;runtimeOS 是 HarmonyOS;collectAllLibs 打开,意味着构建时会把依赖模块里的原生库全部收进包里,而不是只收主模块引用到的那些。对一个要带四个 .so 的 Electron 壳来说,这一项必须为真,否则 libelectron.so 会在打包阶段被裁掉,装到设备上一启动就崩。
构建产物里的 pack.info 与这份配置对得上:
{"summary":{"app":{"bundleName":"com.huawei.ohos_electron","bundleType":"app","version":{"code":1000000,"name":"1.0.0"}},"modules":[{"mainAbility":"EntryAbility","deviceType":["2in1","tablet"],"abilities":[{"name":"EntryAbility","label":"$string:EntryAbility_label"},{"name":"BrowserAbility"},{"name":"StatelessAbility","label":"$string:StatelessAbility_label"}],"extensionAbilities":[{"name":"StatusBarEntryAbility"},{"name":"BrowserEmbeddedAbility"}],"distro":{"moduleType":"entry","installationFree":false,"deliveryWithInstall":true,"moduleName":"electron"},"apiVersion":{"compatible":17,"releaseType":"Release","target":20}}]},"packages":[{"deviceType":["2in1","tablet"],"moduleType":"entry","deliveryWithInstall":true,"name":"electron-default"}]}
注意 apiVersion 这一段:compatible 是 17,target 是 20。兼容下限与编译目标不一致是刻意为之——下限压到 API 17 是为了能装到更多鸿蒙 PC 上,编译目标拉到 20 是因为 hvigor 与 SDK 的默认工具链在那里。这种配置在绝大多数情况下没问题,但它意味着代码里不能出现只在 API 20 才有的新接口,否则在 API 17 的设备上会在调用处崩掉。
两个模块的 build-profile.json5 都开了混淆,文件结构也几乎一样:
{
"apiType": "stageMode",
"buildOptionSet": [
{
"name": "release",
"arkOptions": {
"obfuscation": {
"ruleOptions": {
"enable": true,
"files": [
"./obfuscation-rules.txt"
]
}
}
}
},
],
"targets": [
{
"name": "default"
}
]
}
这里是 web_engine 的版本,electron 的版本多一个 consumerFiles 与一个 ohosTest target。混淆只作用于 .ets 与 .ts 产物,resfile 下的 js 属于资源,不参与混淆——那七个引擎和 renderer.js 进包时是原文,这一点在排查设备上的异常时很有用,可以直接把 hap 解开对着源码看。
值得注意的一处细节:这四个配置文件和两个 module.json5 里一共出现了 8 处 JSON5 尾逗号。JSON5 标准允许尾逗号,hvigor 也能正常解析,所以构建不会报错;但如果有脚本或 CI 用严格 JSON 解析器去读这些文件,会在第一个尾逗号处失败。这属于「现在能用、换工具就崩」的隐患,第五节的上架清单里会把它列进去。
2.3 权限与资源清单
web_engine 的 module.json5 有 177 行,其中 160 行是权限声明。requestPermissions 数组里一共 26 条,另有 1 条被注释掉的 WEB_NATIVE_MESSAGING,以及 1 条在 definePermissions 里自定义的 LOCK_WINDOW_CURSOR,正则统计的 28 个 permission 字符串正好对上这三个数之和。
26 条权限按是否需要理由分成两组。前 15 条只有名字,没有 reason 与 usedScene:
| 权限 | 用途分类 |
|---|---|
| ohos.permission.INTERNET | 网络 |
| ohos.permission.GET_NETWORK_INFO | 网络状态 |
| ohos.permission.ACCESS_CERT_MANAGER | 证书 |
| ohos.permission.RUNNING_LOCK | 运行锁 |
| ohos.permission.PRINT | 打印 |
| ohos.permission.PREPARE_APP_TERMINATE | 退出准备 |
| ohos.permission.ACCESS_BIOMETRIC | 生物识别 |
| ohos.permission.FILE_ACCESS_PERSIST | 文件持久授权 |
| ohos.permission.PRIVACY_WINDOW | 隐私窗口 |
| ohos.permission.WINDOW_TOPMOST | 窗口置顶 |
| ohos.permission.GYROSCOPE | 陀螺仪 |
| ohos.permission.ACCELEROMETER | 加速度计 |
| ohos.permission.SET_ABILITY_INSTANCE_INFO | 实例信息 |
| ohos.permission.GET_FILE_ICON | 文件图标 |
| ohos.permission.LOCK_WINDOW_CURSOR | 锁定光标 |
后 11 条带 reason 与 usedScene,reason 一律指向 $string 资源:
| 权限 | reason 资源 |
|---|---|
| ohos.permission.READ_PASTEBOARD | access_pasteboard |
| ohos.permission.READ_WRITE_DOWNLOAD_DIRECTORY | download_dir |
| ohos.permission.READ_WRITE_DOCUMENTS_DIRECTORY | documents_dir |
| ohos.permission.READ_WRITE_DESKTOP_DIRECTORY | desktop_dir |
| ohos.permission.LOCATION | location |
| ohos.permission.APPROXIMATELY_LOCATION | location |
| ohos.permission.LOCATION_IN_BACKGROUND | location |
| ohos.permission.MICROPHONE | microphone |
| ohos.permission.CAMERA | camera |
| ohos.permission.ACCESS_BLUETOOTH | access_bluetooth |
| ohos.permission.CUSTOM_SCREEN_CAPTURE | screen_capture |
这 26 条权限来自 Electron 壳模板,是这个壳的能力上限,不是 OVITO 这一层业务用得到的集合。OVITO 工作台实际只用到文件对话框和剪贴板:轨迹从对话框读、报告从对话框写、路径定位调 shell、报告复制走 clipboard。位置、摄像头、麦克风、蓝牙、陀螺仪这些一条都没碰,index.html 里的 CSP 更是把 connect-src 直接设成了 ‘none’,网络请求在渲染层一个都发不出去。
这不是可以忽略的差异。上架审核时,权限清单与实际行为对不上是最常见的退回理由之一。第 5.3 节给出的替换清单里,第一件事就是把这份权限表裁剪到真正需要的范围。
resfile 的资源清单一共四个文件:index.html、main.js、package.json、renderer.js,加上 engines 与 styles 两个目录。三个画布的尺寸是硬编码在 index.html 里的——sceneCanvas 960×540、rdfCanvas 960×260、msdCanvas 960×220。这三个数字决定了投影与图表的坐标换算基准,后文所有关于像素的讨论都以它们为准。
三、核心适配流程
3.1 轨迹解析:两种文本格式,一套帧结构
ov-io.js 的文件头先把态度摆明:
/* OVITO 壳 —— 轨迹解析
*
* 只认两种文本格式:LAMMPS dump(ITEM: TIMESTEP 分段)与扩展 XYZ(首行粒子数)。
* 解析器不猜单位、不猜元素:LAMMPS 的 type 是整数标签,原样保留;XYZ 的 species 原样保留。
*
* 任何结构问题都返回中文原因而不是抛异常——界面上要能直接读到「第几行缺什么」。
*/
「不猜单位、不猜元素」这两句话省掉了后面无数的麻烦。分子动力学界的坐标单位五花八门,LAMMPS 用金属单位时长度是埃、用 real 单位时也是埃、用 SI 时却是米;如果一个查看器自作聪明去猜,用户永远不知道自己看到的 5.2 到底是埃还是别的什么。这里的做法是原样读、原样显示,把单位问题留给用户自己判断——反正报告的「能力边界」段落已经写明了这一点。
格式识别只有两个分支:
function detect(text) {
var s = String(text == null ? '' : text);
if (/^ITEM:\s*TIMESTEP/mi.test(s)) return 'lammps';
var lines = U.nonEmptyLines(s);
for (var i = 0; i < lines.length; i++) {
var t = lines[i].trim();
if (!t) continue;
if (/^\d+$/.test(t) && i + 1 < lines.length) return 'xyz';
return '';
}
return '';
}
先看有没有 ITEM: TIMESTEP 这种分段标记,有就是 dump;否则找第一行非空文本,纯粹是数字就看做 XYZ 的首行粒子数。这段代码里藏着一个值得记下来的细节:nonEmptyLines 这个函数其实并不滤空行,它只做 split:
function nonEmptyLines(text) {
return String(text == null ? '' : text).split(/\r?\n/);
}
名字与行为不符,所以 detect 在循环里又自己加了一句 if (!t) continue 来跳空行。这不是冗余,是在绕开一个名不符实的工具函数。第四章的缺陷清单里会专门说这件事,因为它影响的不止 detect 一处。
LAMMPS dump 的解析是状态机写法:外层找 TIMESTEP,内层读 NUMBER OF ATOMS、BOX BOUNDS、ATOMS 三个头,读到 ATOMS 就跳出内层按行数取数据。列头先建成一张列名到序号的映射表,然后按三种坐标约定取列:
var col = {};
header.forEach(function (w, j) { col[String(w).toLowerCase()] = j; });
var scaled = col.xs !== undefined && col.ys !== undefined && col.zs !== undefined;
var unwrapped = col.xu !== undefined && col.yu !== undefined && col.zu !== undefined;
var xi = scaled ? col.xs : (unwrapped ? col.xu : col.x);
var yi = scaled ? col.ys : (unwrapped ? col.yu : col.y);
var zi = scaled ? col.zs : (unwrapped ? col.zu : col.z);
if (xi === undefined || yi === undefined || zi === undefined) {
return fail('第 ' + startLine + ' 行的帧里,ITEM: ATOMS 列头没有 x/y/z(或 xs/ys/zs、xu/yu/zu)', warnings);
}
优先级是 scaled 高于 unwrapped 高于原始。这个顺序不是随便定的:dump 里同时存在 xs 与 x 是常态,而 xs 是归一化坐标,必须乘以盒长才能还原成实际位置;如果先取 x 就把归一化值当实际坐标了,画出来所有粒子都挤在 0 到 1 之间。scaled 的还原就在下面几行:
if (scaled) {
px = U.num(box && box.xlo, 0) + px * sfx;
py = U.num(box && box.ylo, 0) + py * sfy;
pz = U.num(box && box.zlo, 0) + pz * sfz;
}
三个错误分支都带行号,而且说的是「第几行缺什么」:
if (!(count > 0)) return fail('第 ' + startLine + ' 行的帧缺少有效的粒子数(NUMBER OF ATOMS)', warnings);
if (count > maxAtoms) return fail('单帧 ' + count + ' 个粒子,超过上限 ' + maxAtoms, warnings);
if (parts.length < header.length) {
return fail('第 ' + (ln + 1) + ' 行只有 ' + parts.length + ' 列,列头要求 ' + header.length + ' 列', warnings);
}
if (!isFinite(px) || !isFinite(py) || !isFinite(pz)) {
return fail('第 ' + (ln + 1) + ' 行的坐标不是数字', warnings);
}
一个用户在鸿蒙 PC 上打开一份自己手改过的 dump,最可能遇到的就是这几条。有行号就能直接去改,没有行号就只能整份文件从头找。这类细节不增加任何功能,但它决定了这个工具能不能被日常使用。
倾斜盒子(triclinic)的处理是明确承认近似:
if (rows[0].length > 2 || rows[1].length > 2 || rows[2].length > 2) tilted = true;
/* 此处省略其余实现 */
if (tilted) warnings.push('检测到倾斜盒子(xy/xz/yz),本壳按正交包围盒近似');
LAMMPS 的 triclinic 盒子在 BOX BOUNDS 里写的是修正后的六个数,真正的转换需要 xy、xz、yz 三个倾斜因子参与;这里只用 xlo 与 xhi 两个数当正交盒子,所以周期边界的折回、RDF 的剪切距离、体积计算在倾斜体系里都会有偏差。方案没有假装支持,而是在解析提示里明确写出来——界面上「解析提示」那一栏会显示「1 条」,点开就是这句话。
没有 BOX BOUNDS 的情况有兜底:
function boxFromAtoms(atoms) {
/* 此处省略其余实现 */
/* 二维薄片在某一轴上厚度为 0:补一点余量,后面算体积与投影都不至于除零 */
['x', 'y', 'z'].forEach(function (k) {
if (hi[k] - lo[k] < 1e-6) { lo[k] -= 0.5; hi[k] += 0.5; }
});
/* 此处省略其余实现 */
}
这段的意义不只是「不崩」。一块二维材料在 z 方向的厚度确实是 0,如果盒子那一维长度是 0,体积就是 0,数密度就会变成 Infinity,投影的 fitScale 也会除以 0。补上 1 埃的总余量,让所有下游计算都有定义。
扩展 XYZ 的解析更短,但条件分支更多。它要先从第二行的注释里抠出 Properties 与 Lattice 两个扩展字段:
function parseProperties(comment) {
var m = /Properties\s*=\s*([^\s"]+)/i.exec(String(comment || ''));
if (!m) return null;
var parts = m[1].split(':');
var map = {};
var col = 0;
for (var i = 0; i + 2 < parts.length; i += 3) {
var name = String(parts[i] || '').toLowerCase();
var cnt = Math.max(1, Math.round(U.num(parts[i + 2], 1)));
map[name] = { col: col, count: cnt };
col += cnt;
}
return map;
}
Properties 的格式是 symbol:1:pos:3 这种三元组序列,每三个值描述一列:名字、类型、占几列。循环里 i 每次加 3,col 累加占用列数——这样即便某个属性占三列,后面所有属性的起始列也都能算对。
没有 Properties 时,靠首列是不是数字来判断格式:
var hasSymbol = props && props.species ? true
: (props ? false : !isFinite(Number(firstCols[0])));
var symCol = props && props.species ? props.species.col : 0;
var posCol = props && props.pos ? props.pos.col : (hasSymbol ? 1 : 0);
三种情况:有 species 属性,就是带元素符号;有 Properties 但没有 species,就是纯坐标;完全没有 Properties,就看首列能不能转成数字。这个推断顺序与市面上绝大多数 XYZ 文件的实际情况吻合。
两种格式最终产出同一份帧结构:
frames.push({ index: frames.length, tick: tick, box: box, atoms: atoms });
每一帧只有四个字段:序号、时间步、盒子、粒子数组。每颗原子是 id、type、x、y、z,XYZ 解析时还多一个 element 字段。下游的投影、管线、分析、报告全部只认这几个字段,两种来源在进入渲染层之后就再也分不出来了。
三个上限对两种格式都生效:单帧 20000 个粒子、最多 200 帧、轨迹总粒子数 400000。超限的处理有两种:单帧或总数超限直接失败并说清楚原因,帧数超限则保留已读部分并往 warnings 里写一句。这个区别很合理——单帧超限说明这一帧就没法处理,继续读下去没有意义;帧数超限只是「读不完」,前面的数据依然有用。
3.2 投影:把三维算进 Canvas 2D
ov-vec.js 第一句就把方案说清了:
/* OVITO 壳 —— 三维向量与投影
*
* 渲染层只有 Canvas 2D,所以三维是算出来的:向量运算、绕 Y/X 的欧拉旋转、
* 正交投影、周期性最小镜像。全部纯函数,几何出错可以在单测里直接断言。
*/
旋转是两个角度的固定顺序:
/* 绕 Y 轴(yaw)再绕 X 轴(pitch)旋转:拖拽时两个角度各自独立累加 */
function rotate(p, yaw, pitch) {
var cy = Math.cos(U.num(yaw, 0));
var sy = Math.sin(U.num(yaw, 0));
var cp = Math.cos(U.num(pitch, 0));
var sp = Math.sin(U.num(pitch, 0));
var x1 = p.x * cy + p.z * sy;
var z1 = -p.x * sy + p.z * cy;
var y2 = p.y * cp - z1 * sp;
var z2 = p.y * sp + z1 * cp;
return v(x1, y2, z2);
}
先绕 Y 再绕 X,没有任何插值,也不是四元数。用欧拉角会有一个众所周知的万向节问题:pitch 到 ±90 度时画面会在某一方向翻转。这里的处理不是消灭它,而是把 pitch 夹在 ±1.45 弧度(约 ±83 度),在拖拽和滚轮两处都做了 clamp:
S.view.pitch = U.clamp(S.view.pitch + dy * 0.008, -1.45, 1.45);
83 度足够看清一个立方体的任何一面,同时又离奇点还有 7 度余量。用户不会觉得转不动,但也不会转到画面突然跳向另一侧。
投影本身只有一行公式:
/* 正交投影:模型坐标 → 画布像素,depth 用于画家算法排序(越大越远) */
function project(p, view, s, cx, cy) {
var r = rotate(p, view && view.yaw, view && view.pitch);
return {
x: cx + r.x * s,
y: cy - r.y * s,
depth: r.z,
view: r
};
}
y 用的是减法。模型坐标的 y 向上为正,画布坐标的 y 向下为正,所以乘完缩放要取反,否则整个场景是上下颠倒的。x 用加法,因为两者的正方向一致。这一行如果写反,表现是「拖拽方向与物体转动方向相反」,很容易被当成拖拽逻辑的 bug 而查错地方。
depth 取的是旋转后的 z 分量,语义是「越大越远」。这个约定与绘制顺序的排序函数严丝合缝:
items.sort(function (p, q) { return q.d - p.d; });
降序排列,z 大的排前面先画,z 小的后画盖在上面。这就是画家算法的全部——没有深度缓冲,没有三角形剔除,就是「远的先画、近的后画」。对球体这足够了,因为每颗原子都是一个独立的圆,圆的覆盖关系就是遮挡关系。
缩放用的是盒子对角线,而不是某个轴向的长度:
/* 让整条对角线落在画布里:旋转时物体大小保持不变,不会忽大忽小 */
function fitScale(box, w, h, fill) {
var s = boxSize(box);
var diag = Math.sqrt(s.lx * s.lx + s.ly * s.ly + s.lz * s.lz);
var f = U.num(fill, 0.82);
return Math.max(1e-6, (Math.min(w, h) * f) / diag);
}
这是本项目中一个容易被忽略但很关键的设计。如果按盒子的最大边长算,旋转时投影面积会变,画面里的晶体会随着转动一胀一缩;按对角线算,无论转到哪个角度,物体最远的两点在视平面上的投影距离都不会超过对角线,所以缩放恒定,看起来才是「在转」而不是「在呼吸」。
绘制时给 fitScale 传的是 0.78 而不是默认的 0.82,给盒子边框留了一点边距:
var scale = V.fitScale(box, W, H, 0.78) * S.view.zoom;
粒子的半径不是固定像素,而是按数密度反推:
var spacing = Math.pow(Math.max(1e-9, size.lx * size.ly * size.lz) / atoms.length, 1 / 3);
var rpx = U.clamp(S.radius * spacing * scale, 1.2, 26);
体积除以粒子数再开三次方,得到的是平均间距。半径取间距乘以用户设定的系数,再乘以投影缩放——这样在稀疏体系和致密体系里,粒子都会画成「差不多刚好碰到」的大小,不必手动调。上下夹在 1.2 到 26 像素之间:下限防止点太密时粒子缩成看不见的 0 像素,上限防止只有两颗粒子时画出两个巨型圆盘。
颜色分三种模式,都在同一个循环里分支:
ctx.globalAlpha = 0.55 + 0.45 * (1 - t);
if (S.colorMode === 'height') {
ctx.fillStyle = grad[Math.round(U.clamp((U.num(it.a.z, 0) - zlo) / zspan, 0, 1) * 32)];
} else if (S.colorMode === 'select') {
ctx.fillStyle = sel && sel[it.i] ? accentColor : faintColor;
} else {
var tk = SC ? SC.typeKey(it.a) : 't1';
if (!typeColors[tk]) typeColors[tk] = typeColor(tk);
ctx.fillStyle = typeColors[tk];
}
t 是归一化后的深度,(1 - t) 就是「离观察者有多近」,所以近的粒子 alpha 接近 1、远的只有 0.55。这不是物理上的景深,而是给人眼一个深度线索:在一片同色圆点里,如果远近完全一样,人的视觉会把它压平,看不出立体感。
高度渐变用了 33 级预混色,注释解释了原因:
/* 高度渐变先取 33 级:逐粒子混色要反复解析十六进制,两万个粒子时拖拽会掉帧 */
var grad = [];
for (gi = 0; gi <= 32; gi++) grad.push(mixColor(farColorA, farColorB, gi / 32));
mixColor 每次调用都要跑一遍正则、一次 parseInt、三次取位运算,两万个粒子就是两万次。预先算 33 个结果,绘制时只做一次数组索引——这是整个绘制循环里唯一一处需要提前优化的地方,因为它是唯一在每次拖拽重绘时都要跑两万遍的代码。
拾取靠的是绘制时留下的坐标表:
// 绘制阶段将坐标加入 items,随后保存坐标表供拾取使用。
S.drawn = items;
function pickAt(p) {
/* 此处省略其余实现 */
for (var i = S.drawn.length - 1; i >= 0; i--) {
/* 此处省略其余实现 */
var hit = Math.max(7, U.num(S.rpx, 6) + 3);
if (d <= hit && d < bestD) { best = it; bestD = d; }
}
/* 此处省略其余实现 */
}
从后往前遍历,也就是从近到远,第一个落在命中半径内的就返回。命中半径取「实际绘制半径加 3 像素」,并且有 7 像素的下限——粒子画得再小,手指或触控笔也能点中。这个 7 像素是可用性下限,不是美观选择。
拖拽重绘做了 16 毫秒合流:
/* 拖拽时鼠标事件比屏幕刷新快:合并到下一帧再重绘,大轨迹才拖得动 */
function scheduleDraw() {
if (S.paintTimer) return;
S.paintTimer = setTimeout(function () {
S.paintTimer = 0;
drawScene();
}, 16);
}
每次 mousemove 都重绘两万个圆是不现实的,鼠标事件的触发频率远高于屏幕刷新率。用一个挂起标记把同一帧内的多次移动合并成一次重绘,这是最省事也最有效的优化。
松手时必须把挂起的那次重绘兑现:
document.addEventListener('mouseup', function () {
if (!S.drag) return;
var drag = S.drag;
S.drag = null;
/* 松手前必须把挂起的重绘兑现,否则画面会停在半帧位置上 */
if (S.paintTimer) {
clearTimeout(S.paintTimer);
S.paintTimer = 0;
drawScene();
}
renderViewBadge();
if (drag.moved < 4) pickAt(drag.point);
});
这两行 if 是必须的。如果松手时只是取消定时器而不立刻重绘,画面就会停在最后一次实际重绘的位置,而用户最后一次拖动的那几十像素就丢了。表现出来是「快速甩一下鼠标,松手后视角跟鼠标位置对不上」。
拾取与拖拽的分界是 4 像素:
if (drag.moved < 4) pickAt(drag.point);
moved 累加的是每段位移的绝对值之和,所以它不是直线距离而是路径长度。手抖一下的抖动会有两三像素的累计,超过 4 就不当拾取。这个阈值调小了会把点击误判成拖拽(点不中粒子),调大了会把轻微拖动误判成点击(一旋转就跳出一个粒子的属性)。
3.3 修饰器管线:每步返回新数组
ov-pipeline.js 的头部把管线的语义定死了:
/* OVITO 壳 —— 修饰器管线
*
* 管线就是「按顺序作用在帧上的一串操作」,和 OVITO 的 modifier 一个意思:
* 切片 → 按类型选择 → 按表达式选择 → 删除选中 / 仅显示选中。
*
* 每一步都返回新的粒子数组,不改输入帧;每步记一条日志(前后粒子数、选中数),
* 界面上能直接看到「哪一步删掉了多少」,报告里也照抄这份日志。
*/
七种操作、五种字段、五种比较符,各是一个常量数组:
var MAX_OPS = 20;
var TYPES = ['slice', 'selectType', 'selectExpr', 'deleteSelected', 'showOnlySelected', 'invertSelection', 'clearSelection'];
var AXES = ['x', 'y', 'z'];
var FIELDS = ['x', 'y', 'z', 'id', 'type'];
var CMPS = ['>', '>=', '<', '<=', '=='];
类型归一化用一张小写映射表,而不是大小写不敏感的字符串比较:
/* 名字是 camelCase:归一化只用于匹配,返回值必须是规范写法 */
var TYPE_MAP = {
slice: 'slice',
selecttype: 'selectType',
selectexpr: 'selectExpr',
deleteselected: 'deleteSelected',
showonlyselected: 'showOnlySelected',
invertselection: 'invertSelection',
clearselection: 'clearSelection'
};
function normType(t) {
return TYPE_MAP[String(t || '').toLowerCase()] || '';
}
为什么要绕一圈?因为场景文件是用户可编辑的 JSON,里面写 deleteselected、deleteSelected、DeleteSelected 都该接受,但内部比较必须用唯一一种写法。用映射表的好处是不认识的值直接返回空串,normOp 随即返回 null,apply 会在出错时准确报出「第 N 个修饰器类型未知」。
apply 的主循环有七个分支,每个分支只做一件事:
if (o.type === 'slice') {
var keep = [];
var keepSel = [];
atoms.forEach(function (a, j) {
var c = o.axis === 'x' ? a.x : (o.axis === 'y' ? a.y : a.z);
if (Math.abs(c - o.center) <= o.thickness / 2) {
keep.push(a);
keepSel.push(!!selected[j]);
}
});
atoms = keep;
selected = keepSel;
} else if (o.type === 'selectType') {
selected = atoms.map(function (a) { return o.types.indexOf(S.typeKey(a)) >= 0; });
} else if (o.type === 'selectExpr') {
selected = atoms.map(function (a) {
return compare(S.vecOf(a, o.field), o.cmp, o.value);
});
} else if (o.type === 'deleteSelected') {
/* 此处省略其余实现 */
} else if (o.type === 'showOnlySelected') {
/* 此处省略其余实现 */
} else if (o.type === 'invertSelection') {
selected = atoms.map(function (a, j) { return !selected[j]; });
} else if (o.type === 'clearSelection') {
selected = atoms.map(function () { return false; });
}
切片保留选中位的做法值得单独看一眼:它不只是过滤 atoms,还同步过滤 selected 数组,因为删掉某些粒子之后,幸存粒子在数组里的下标全变了。如果忘了同步,后面所有按下标取选中态的地方都会错位——而这种错位不会报错,只会让画面上的选中圈出现在错误的粒子上。
删除与仅显示两个分支会累加 removed,仅显示还会把选中态全部置真:
} else if (o.type === 'showOnlySelected') {
var only = [];
atoms.forEach(function (a, j) {
if (selected[j]) only.push(a);
});
removed += atoms.length - only.length;
atoms = only;
selected = only.map(function () { return true; });
}
置真是合理的:既然画面里只剩选中的粒子,它们当然全都处于选中态。但这条语义会让日志里的「选中」一列在仅显示之后变成「保留数」,报告里的管线表格读起来就像「这一步之后全选中了」。这是第四章要点出的一处表述问题。
每一步都会往日志里追一条记录:
log.push({
index: i + 1,
type: o.type,
label: describe(o),
before: before,
after: atoms.length,
selected: countTrue(selected)
});
四个数字:第几步、这一步之前多少粒子、之后多少、选中多少。界面上的「管线」面板把 each 一条显示成「前 125 → 后 62 · 选中 62」这种形式,报告里的管线表格是同样四列。用户看一眼就知道粒子是在第几步被删掉的,这比只给一个最终数字有用得多。
describe 负责把操作翻译成人话:
if (o.type === 'slice') {
return '切片 ' + o.axis.toUpperCase() + ' ∈ [' + U.fmt(o.center - o.thickness / 2, 2) + ', ' +
U.fmt(o.center + o.thickness / 2, 2) + ']';
}
if (o.type === 'selectType') {
return '按类型选择:' + (o.types.length ? o.types.map(S.typeLabel).join('、') : '(未选类型)');
}
if (o.type === 'selectExpr') {
return '按表达式选择:' + o.field + ' ' + o.cmp + ' ' + U.fmt(o.value, 3);
}
切片的描述特意写成区间而不是中心加厚度。用户关心的是「留下哪一层」,而不是「中心在哪、厚多少」——后者要自己心算,前者看一眼就明白。
返回值是整个管线执行完之后的一份快照:
return {
success: true,
frame: {
index: frame.index,
tick: frame.tick,
box: frame.box,
atoms: atoms
},
log: log,
removed: removed,
beforeAtoms: beforeFrame,
selected: countTrue(selected),
selection: selected,
warnings: warnings
};
frame 里保留了原帧的 index、tick、box,只替换 atoms。这意味着经过管线之后,时间步和盒子依然是真实值,报告里写的 tick 是轨迹的 tick 而不是管线产物的序号。
渲染层对管线的操作有两个讲究。第一个是上限判断前置:
function pushOp(op) {
if (!hasData()) { notice('还没有轨迹:先打开轨迹或载入示例', 'warn'); return false; }
if (S.ops.length >= PL.MAX_OPS) {
notice('修饰器最多 ' + PL.MAX_OPS + ' 个:先移除几步或清空管线', 'warn');
return false;
}
S.ops.push(op);
rebuild();
dropAnalysis();
markReportDirty();
return true;
}
第二个是类型选择芯片的复用:
/* 类型芯片:复用最后一个 selectType,避免点五下生成五个操作 */
function applyTypeSelection() {
var last = S.ops.length ? S.ops[S.ops.length - 1] : null;
if (last && last.type === 'selectType') {
last.types = S.selTypes.slice();
} else if (!pushOp({ type: 'selectType', types: S.selTypes.slice() })) {
return;
}
rebuild();
dropAnalysis();
markReportDirty();
renderAll();
}
用户在选择面板点五个类型芯片,期望的结果是「这五个类型被选中」,而不是「管线里多出五步、最后一步只保留最后一个类型」。复用最后一步就把这个直觉落实了:连点几下只改同一个操作的参数。这个判断只在最后一步是 selectType 时成立,如果中间插了切片,新的类型选择就是一个新步骤——这个行为是对的,因为切片之后的类型选择在语义上确实是新的一层。
3.4 结构分析:RDF、配位数、MSD、簇
ov-analysis.js 的头部把四个量的口径一次写完,这段话是整个项目里最该被逐字读的部分:
/* OVITO 壳 —— 结构分析
*
* 四件在 OVITO 里对应的分析:径向分布函数(RDF)、配位数、均方位移(MSD)、簇分析。
*
* 口径写死在这里,界面与报告都读同一份结果:
* - RDF 用 g(r) = 2V/(N(N-1)) · n(r) / (4πr²dr),配位数是它的累计积分 2·Σn/N;
* - 距离默认走周期性最小镜像(正交盒子),关掉周期时按直线距离;
* - MSD 逐帧用最小镜像累加同一 id 的位移,避免包裹坐标在边界处跳变;
* - 簇分析按 cutoff 建连通图,数连通分量与最大簇。
*
* 粒子数超过 4000 时直接拒绝并提示先用管线缩小范围:O(N²) 在真机会卡住。
*/
「口径写死」四个字很重要。RDF 的归一化方式有好几种流派,有的除以理想气体密度,有的用 N/V 而不是 N(N-1)/2V,有的把 dr 的宽度并进壳体积。同一个体系用不同口径算出来的 g® 可以差一倍。这里的做法是在一处定死,界面、图表、CSV、Markdown 报告全部读这一份——这样至少在自己内部是自洽的。
邻近距离的判定用了独立的 pairDistance,而不是复用 ov-vec 的 distance:
function pairDistance(a, b, box, periodic) {
var dx = a.x - b.x;
var dy = a.y - b.y;
var dz = a.z - b.z;
if (periodic) {
var s = V.boxSize(box);
if (dx > s.lx / 2) dx -= s.lx;
if (dx < -s.lx / 2) dx += s.lx;
if (dy > s.ly / 2) dy -= s.ly;
if (dy < -s.ly / 2) dy += s.ly;
if (dz > s.lz / 2) dz -= s.lz;
if (dz < -s.lz / 2) dz += s.lz;
}
return Math.sqrt(dx * dx + dy * dy + dz * dz);
}
为什么不直接用 V.distance?因为这是内层循环里最热的函数,每次调用都要构造两个对象再销毁。这里直接对三个分量做标量运算,省掉对象分配——两万次配对就是两万次分配,在 O(N²) 里这个常数因子不能忽略。ov-vec 里那个通用版本则留给渲染层的非热路径使用。
RDF 的主体是标准的双循环加壳层归一:
var s = V.boxSize(frame.box);
var volume = s.lx * s.ly * s.lz;
var norm = (2 * volume) / (n * (n - 1));
var rows = [];
var cumulative = 0;
for (var k = 0; k < bins; k++) {
var rlo = k * dr;
var rhi = rlo + dr;
var shell = (4 / 3) * Math.PI * (rhi * rhi * rhi - rlo * rlo * rlo);
var g = shell > 0 ? (norm * counts[k]) / shell : 0;
cumulative += counts[k];
rows.push({
r: U.round(rlo + dr / 2, 4),
g: U.round(g, 4),
count: counts[k],
cn: U.round((2 * cumulative) / n, 3)
});
}
每一行的 r 取箱中点而不是箱左边界,这是分布式函数绘图的标准做法;cn 是累计配位数,公式 2·Σn/N 里的 2 是因为每一对粒子被数了两次(i<j 只数一次,但每个粒子的邻居数要算两次贡献)。最后一行就是截止半径内的平均邻居数。
第一峰的取法有一个容易做错的地方,注释里点明了:
/* 第一峰取「第一个明显隆起并回落的点」,而不是全局最高点:
* 简单立方里第二壳层有 12 个邻居,全局最高往往不在第一壳层。 */
function firstPeak(rows) {
var best = { r: 0, g: 0 };
for (var i = 1; i < rows.length - 1; i++) {
if (rows[i].g > 1.05 && rows[i].g >= rows[i - 1].g && rows[i].g >= rows[i + 1].g) {
return { r: rows[i].r, g: rows[i].g };
}
if (rows[i].g > best.g) best = { r: rows[i].r, g: rows[i].g };
}
/* 此处省略其余实现 */
}
取全局最高点是很多人会犯的错。在简单立方里,第一壳层有 6 个邻居、距离 a;第二壳层有 12 个邻居、距离 1.414a。第二壳层的壳面积更大但数量是两倍,两者在 g® 上常常是第二峰更高。如果按最高点报「第一峰」,得到的 r 会是次近邻距离——这个数值在报告里会被当成最近邻距离引用,结论就整个错了。这里用「第一个 g > 1.05 的局部极大」,先把位置定在第一壳层,再去取它自己的峰值。
配位数是单独算一遍的,因为它要给出每个粒子的邻居数分布,而不只是累计曲线:
for (i = 0; i < n - 1; i++) {
for (j = i + 1; j < n; j++) {
if (pairDistance(atoms[i], atoms[j], frame.box, periodic) <= cutoff) {
counts[i] += 1;
counts[j] += 1;
}
}
}
每一对如果在截断距离内,双方各加一。之后再把按类型的均值、直方图、最大最小值都算出来,界面上的「直方图峰值在 6 个邻居」就是从这份 counts 里得的。
MSD 是唯一一个跨帧的分析:
/* 均方位移:同一 id 逐帧累加最小镜像位移,任何一帧缺失的粒子下一帧重新登记 */
function msd(frames, opt) {
/* 此处省略其余实现 */
var maxFrames = Math.round(U.clamp(o.maxFrames === undefined ? 60 : o.maxFrames, 2, 200));
/* 此处省略其余实现 */
for (var f = 1; f < use.length; f++) {
var frame = use[f];
var sum = 0;
var cnt = 0;
frame.atoms.forEach(function (a) {
var p = prev[a.id];
if (!p) {
prev[a.id] = { x: a.x, y: a.y, z: a.z };
unwrapped[a.id] = { x: 0, y: 0, z: 0 };
return;
}
var dx = a.x - p.x;
var dy = a.y - p.y;
var dz = a.z - p.z;
if (periodic) {
var m = V.minImage(dx, dy, dz, frame.box);
dx = m.x; dy = m.y; dz = m.z;
}
var u = unwrapped[a.id];
u.x += dx;
u.y += dy;
u.z += dz;
prev[a.id] = { x: a.x, y: a.y, z: a.z };
sum += u.x * u.x + u.y * u.y + u.z * u.z;
cnt += 1;
});
/* 此处省略其余实现 */
}
}
关键在 unwrapped 这张表:它记的不是坐标,而是「从第一帧到现在的累计位移」。每一帧只算相邻两帧的最小镜像差值,再累加到累计量上。如果直接拿当前坐标减第一帧坐标,跨周期边界的粒子会在边界处发生一次巨大的跳变——累积出来的 MSD 会出现锯齿状的假增长。逐帧最小镜像把每一步都折回盒内,累积量就始终是真实的连续位移。
同一个 id 的匹配是 MSD 成立的前提。LAMMPS dump 的 id 是文件里带的,XYZ 的 id 是行序号,两者在本项目里都稳定。如果某一帧缺了某个 id,代码会把它从 prev 里删掉重新登记,累计位移归零——这个粒子在后续帧里从零开始,而不是从错误的历史继续。
簇分析是图上最朴素的做法:
var adj = new Array(n);
for (i = 0; i < n; i++) adj[i] = [];
for (i = 0; i < n - 1; i++) {
for (j = i + 1; j < n; j++) {
if (pairDistance(atoms[i], atoms[j], frame.box, periodic) <= cutoff) {
adj[i].push(j);
adj[j].push(i);
}
}
}
for (i = 0; i < n; i++) {
if (seen[i]) continue;
var stack = [i];
seen[i] = true;
var size = 0;
while (stack.length) {
var cur = stack.pop();
size += 1;
/* 此处省略其余实现 */
}
sizes.push(size);
}
先建邻接表,再用一个显式栈做深度优先遍历数连通分量。用栈而不是递归,是因为递归深度等于簇的大小,一个 4000 原子的簇会把调用栈打穿。结果按大小降序排,取前 12 个写进报告。
四个分析的上限是 4000 个粒子,超了直接拒绝:
function tooMany(n) {
return n > MAX_ANALYSIS_ATOMS
? '当前帧有 ' + n + ' 个粒子,超过分析上限 ' + MAX_ANALYSIS_ATOMS + ';先用切片或选择器缩小范围'
: '';
}
2500 万次配对在桌面 CPU 上是一两秒的事,在鸿蒙 PC 的移动级芯片上可能是十几秒甚至几十秒,期间界面完全卡死——因为这些计算全在渲染层的主线程上跑。4000 是让这个时间落在一秒以内的经验值,超了就给出一条可执行的建议(用切片缩小范围),而不是让人干等。
3.5 报告:三种格式读同一份 collect
ov-report.js 的头部交代了三条设计:
/* OVITO 壳 —— 报告组装
*
* 三种格式读的是同一份 collect() 结果:Markdown 给人看,JSON 给程序看,CSV 给表格工具。
* 报告不写本机应用目录——导出文件可能被转发,路径没有分享价值。
*/
collect 把所有输入组装成一个固定结构的数据对象,字段分九块:app、generatedAt、env、source、scene、frame、pipeline、analysis、view,外加从 LIMITS 复制的四条能力边界。frame 那一块里每一类粒子只留 key、label、count、share 四个字段,analysis 里四个量各自判空:
analysis: {
rdf: analysis.rdf ? {
n: analysis.rdf.n,
cutoff: analysis.rdf.cutoff,
bins: analysis.rdf.bins,
pairs: analysis.rdf.pairs,
firstPeak: analysis.rdf.firstPeak,
maxCN: analysis.rdf.maxCN,
rows: (analysis.rdf.rows || []).slice()
} : null,
/* 此处省略其余实现 */
}
判空的结果是 null 而不是空对象,所以在 Markdown 里可以按 null 走「本次没有计算」那个分支:
if (data.analysis.rdf) {
lines.push('- 径向分布函数:cutoff ' + num(data.analysis.rdf.cutoff, 3) + ',' +
data.analysis.rdf.bins + ' 个分箱,' + data.analysis.rdf.pairs + ' 对粒子');
lines.push('- RDF 第一峰:r = ' + num(data.analysis.rdf.firstPeak.r, 3) + ',g(r) = ' +
num(data.analysis.rdf.firstPeak.g, 3));
} else {
lines.push('- 径向分布函数:本次没有计算');
}
Markdown 报告一共六段:数据源、成分、管线、分析结果、能力边界、可复现性。成分与管线是两张表格,都有分隔行;能力边界那段把 LIMITS 四条原样列出;最后一行是这句:
lines.push('- 可复现性:同一份轨迹 + 同一组 cutoff / bins 得到同一份结果;渲染视角不影响分析数值');
这句话是报告能被称为报告的原因。它明确告诉读者:视角参数虽然也写进了 JSON 的 view 字段,但它不影响任何结构量。任何一个拿到这份报告的人,只要用同样的轨迹与同样的 cutoff、bins,就能得出同样的数值——不需要知道当时视角转了多少度。
CSV 只有五列:
function toCsv(data) {
var rows = ['tick,r,g,cn,count'];
var rdf = data.analysis && data.analysis.rdf;
var bins = rdf && rdf.rows ? rdf.rows : [];
if (!bins.length) return rows.join('\r\n') + '\r\n';
bins.forEach(function (b) {
rows.push([data.frame.tick, U.round(b.r, 4), U.round(b.g, 4), U.round(b.cn, 3), b.count].join(','));
});
return rows.join('\r\n') + '\r\n';
}
每一行是一个 RDF 分箱:时间步、壳半径、g®、累计配位数、这一箱的粒子对数。行尾用 \r\n 而不是 \n,是为了让 Windows 上的 Excel 打开时不至于把整个文件挤成一行。tick 取自当前帧,所以同一个文件里的所有行共享同一个 tick——这不是缺陷,而是「一个 CSV 对应一次分析」的约定。
渲染层把这份 CSV 也算了一次行数:
function saveData() {
/* 此处省略其余实现 */
var out = RP.build('csv', reportCtx());
var lines = out.text.split('\r\n').length - 2;
/* 此处省略其余实现 */
S.dataNote = '已导出 ' + Math.max(0, lines) + ' 行';
/* 此处省略其余实现 */
}
这个减二在第 4.3 节的缺陷清单里会被单独拿出来说,它少算了一行。
3.6 渲染层:七个面板与二十个按钮的同步
界面是七块面板加一条状态条:
var PANELS = [
{ id: 'p-source', name: '数据源', sub: '轨迹与帧' },
{ id: 'p-view', name: '视图', sub: '投影与拾取' },
{ id: 'p-select', name: '选择', sub: '类型与表达式' },
{ id: 'p-pipeline', name: '管线', sub: '修饰器链' },
{ id: 'p-analysis', name: '分析', sub: 'RDF · 配位 · MSD' },
{ id: 'p-report', name: '报告', sub: '导出与复现' },
{ id: 'p-env', name: '环境与限制', sub: '引擎自检' }
];
七个面板的顺序就是一条工作流:先有数据源,再看视图,然后从选择到管线把范围收窄,接着分析,最后出报告;最后一块「环境与限制」不属于流程,是随时可查的自检页。左侧导航每一项都是主标题加副标题两行,副标题写的是这一块到底干什么——「RDF · 配位 · MSD」比「分析」有用得多。
面板切换是整串 className 赋值,不做增删:
function showPanel(id, btn) {
var panels = document.querySelectorAll('.panel');
var i;
for (i = 0; i < panels.length; i++) {
panels[i].className = panels[i].id === id ? 'panel active' : 'panel';
}
var items = document.querySelectorAll('.nav-item');
for (i = 0; i < items.length; i++) {
items[i].className = 'nav-item' + (items[i] === btn ? ' active' : '');
}
if (id === 'p-view') drawScene();
if (id === 'p-analysis') { drawRdf(); drawMsd(); }
}
整串赋值而不是 classList.add / remove 的原因在鸿蒙的渲染层上:整串赋值只产生一次属性变更,classList 的增删各是一次。七个面板加七项导航,切一次页就是十四次 DOM 写入,用整串赋值可以砍掉一半。这不是微优化,在 ArkWeb 的渲染管线上,DOM 写入次数的下降是可观测的。
切到视图页与分析页时会主动重绘对应画布。原因是这两块画布在面板隐藏时不重绘——Canvas 的尺寸在 display:none 期间会变成 0,此时画出来的是空白。所以每次切过去都要补一次。
二十个按钮的启用状态由一个函数统一管:
function syncButtons() {
var on = hasData();
['btnAnalyze', 'btnPlay', 'btnPauseFrame', 'btnPrevFrame', 'btnNextFrame',
'btnAddSlice', 'btnAddDelete', 'btnAddOnly', 'btnAddInvert', 'btnAddClear',
'btnPipeApply', 'btnPipeClear', 'btnSelAll', 'btnSelNone', 'btnSelInvert',
'btnExprApply', 'btnDataSave', 'btnReportMake', 'btnReportSave', 'btnReportCopy'
].forEach(function (id) {
var b = $(id);
if (b) b.disabled = !on;
});
var f = $('frameRange');
if (f) f.disabled = !on || S.frames.length < 2;
}
二十个按钮全部认 hasData() 一个条件,帧滑块额外要求至少两帧。这个粗粒度的判断是够的:没有轨迹的时候,播放、分析、管线、报告、导出全都无意义;有轨迹之后,各项会在点下去的时候各自提示缺什么(比如「当前没有选中的粒子」)。用二十个按钮各自的细粒度条件去禁,代码会膨胀三倍,而用户并不会因此得到更好的体验——预先禁掉一个按钮,用户反而不知道为什么点不了。
自检面板列出六项能力:
var caps = [
{ name: '轨迹解析(ov-io)', on: !!IO, note: IO ? 'LAMMPS dump / 扩展 XYZ' : '未装载' },
{ name: '三维投影(ov-vec)', on: !!V, note: V ? '正交投影 + 最小镜像' : '未装载' },
{ name: '修饰器管线(ov-pipeline)', on: !!PL, note: PL ? '上限 ' + PL.MAX_OPS + ' 步' : '未装载' },
{ name: '结构分析(ov-analysis)', on: !!AN, note: AN ? '单帧上限 ' + AN.MAX_ANALYSIS_ATOMS : '未装载' },
{ name: '报告引擎(ov-report)', on: !!RP, note: RP ? RP.FORMATS.length + ' 种格式' : '未装载' },
{ name: '画布 2D 上下文', on: !!ctx, note: ctx ? cv.width + ' × ' + cv.height + ' 正交视图' : '取不到上下文' }
];
六项里前五项是引擎,第六项是画布上下文。第六项最有价值:Canvas 2D 上下文在小程序、某些嵌入式 WebView 或权限受限的容器里可能取不到,而这时页面其他部分一切正常,只是画不出来。单独探一次并显示出来,可以把「界面能开但一片空白」这种情况定位到具体原因。
自检结果同时写进状态条:
on('btnSelfTest', 'click', function () {
runSelfTest();
var off = S.caps.filter(function (c) { return !c.on; }).length;
notice(off ? '自检完成:' + off + ' 项能力缺失' : '自检完成:引擎与画布全部就绪', off ? 'err' : 'ok');
});
启动顺序也值得看一眼:
function boot() {
renderNav();
bindCanvas();
bind();
syncInputs();
renderAll();
runSelfTest();
renderEnv();
if (!U || !V || !IO || !SC || !PL || !AN || !RP) {
notice('有引擎未装载:功能会降级,详情见「环境与限制」', 'err');
} else {
notice('就绪:先打开轨迹或载入示例,再拖拽画布旋转视角', '');
}
call('app:info').then(function (res) {
if (!res.success) {
notice('读取运行环境失败:' + (res.error || '未知原因'), 'err');
return;
}
S.info = res;
renderEnv();
runSelfTest();
});
}
先渲染、再自检、再取环境,最后 app:info 回来之后重渲染一次环境并重跑一遍自检。重跑的原因是自检里用到了 app:info 带回来的上限数字(单帧上限、格式数量),第一遍跑的时候这些还是常量默认值。这种「先画个能看的,数据回来再补」的顺序,比白屏等 IPC 回来要友好。
四、鸿蒙稳定性适配
4.1 渲染层禁项与单通道样式
样式表开头有一句颜色纪律和一段平台禁项:
/* OVITO 粒子工作台 —— 主题与布局
*
* 一条约束:颜色只出现在 :root 的变量里,规则里一律 var(--x)。
* 布局四层:#app 纵向 grid(顶栏 / 主体)→ #body 两栏(侧栏 + 工作区)→
* #workspace 滚动容器 → .panel.active 纵向 flex,内部用 .sect 平面分区。
*
* 平台禁项:不使用 position:fixed、@keyframes、animation、transition、transform,
* 也不做 text-transform;视角旋转全部由 canvas 重绘完成。
*/
这段注释是可以被验证的。把 717 行样式表整个扫一遍,几个关键字的位置如下:
| 关键字 | 出现次数 | 位置 |
|---|---|---|
| transition | 1 | 第 7 行注释 |
| animation | 1 | 第 7 行注释 |
| @keyframes | 1 | 第 7 行注释 |
| transform | 2 | 第 7 行与第 8 行注释,第 8 行是 text-transform |
| position: fixed | 1 | 第 7 行注释 |
| will-change | 0 | 无 |
| !important | 0 | 无 |
| @media | 2 | 第 609、614 行的真实规则 |
| box-shadow | 1 | 第 668 行的真实规则 |
也就是说,五个禁项在真实规则里一次都没出现,全部只出现在那段注释里。整个文件里只有两处 @media 断点与一处 box-shadow,后者用在关于对话框的浮层上。
这不是一份「随便写写」的样式表。715 行真实规则里 0 个过渡、0 个动画、0 个变换,意味着所有视觉变化都是瞬时的:鼠标按下去按钮就变色,切面板就换内容,没有 200 毫秒的淡入。在鸿蒙 PC 上这个选择很实际——过渡与动画会触发合成层的额外工作,而在一个要同时重绘两万个圆的界面里,任何一点合成开销都会叠在拖拽的掉帧上。
布局四层从外层往里数:
* { box-sizing: border-box; }
html, body {
margin: 0;
padding: 0;
height: 100%;
background: var(--bg);
color: var(--ink);
#app 是纵向 grid,顶栏一行、主体一行、状态条一行;#body 是两栏,左侧 172 像素的导航栏加右侧自适应的工作区;#workspace 是滚动容器;每个面板是纵向 flex,内部用 .sect 切成若干平面区块。四层各管一件事,没有一层同时负责布局与滚动。
颜色全部走变量。:root 里一共 36 个自定义属性,分四组:
| 组 | 数量 | 例子 |
|---|---|---|
| 基础色 | 15 | –bg、–bg-2、–panel、–line、–ink、–ink-dim、–ink-faint、–accent、–accent-2、–ok、–warn、–err |
| 字体 | 2 | –mono、–sans |
| 元素色板 | 13 | –el-h、–el-c、–el-n、–el-o、–el-fe、–el-cu 等 |
| 类型色板 | 6 | –t1 至 --t6 |
规则里一共出现 135 次 var(–x),没有一个字面量颜色。这个纪律的价值在于画布:Canvas 2D 不能读 CSS 变量,如果颜色硬编码在样式表和 js 两处,改主题就要改两个地方,而漏改的那一边会表现为「界面是深色、画布还是浅色」。
这里的解法是反过来让 js 去读 CSS:
function cssVar(name) {
try {
return String(getComputedStyle(document.documentElement).getPropertyValue(name) || '').trim();
} catch (e) { return ''; }
}
function need(name, dflt) {
var v = cssVar(name);
return v || dflt;
}
绘制时所有颜色都从 need 取,第二个参数是兜底值:
ctx.fillStyle = need('--bg-2', '#11161d');
ctx.strokeStyle = need('--line', '#253041');
var farColorA = need('--accent-2', '#37c2a0');
var farColorB = need('--warn', '#e0a44a');
这样样式表是唯一的颜色来源,画布只是它的消费者。兜底值存在的意义是 getComputedStyle 在某些容器里可能返回空串,此时至少还有一个能看的颜色,而不是黑底黑字。
浮层是禁项里唯一需要改方案的地方:
/* 平台禁项含 fixed,浮层改用绝对定位,锚在 #app(已声明 position: relative)。 */
#aboutDialogLayer.about-layer {
position: absolute;
top: 0;
left: 0;
right: 0;
bottom: 0;
background: rgba(6, 9, 13, 0.72);
display: flex;
align-items: center;
justify-content: center;
z-index: 9999;
}
#aboutDialogLayer.hide { display: none; }
position: fixed 用来做全屏遮罩是标准做法,但它绕开文档流,在某些嵌入容器里会跑到错误的位置甚至溢出窗口。改成绝对定位、四个方向都设 0 并锚在有相对定位的 #app 上,效果一样,但遮罩严格被限制在 #app 的盒子里。
两处 @media 断点是按窗口宽度收缩侧栏与表单的:
@media (max-width: 1280px) {
#workspace { padding: 14px 16px 22px; }
.kv-grid { grid-template-columns: repeat(auto-fill, minmax(172px, 1fr)); }
}
@media (max-width: 1120px) {
#body { grid-template-columns: 172px minmax(0, 1fr); }
.tb-sub { display: none; }
.tb-state { max-width: 100%; }
.form-grid { grid-template-columns: repeat(auto-fill, minmax(180px, 1fr)); }
}
1120 这个数字与主进程的最小窗口宽完全一致:
minWidth: Math.min(1120, winW),
也就是说,窗口被拖到最小的时候正好落到第二个断点上,侧栏收到 172 像素、顶栏副标题隐藏、状态条占满宽度。设计下限与断点值对齐,是为了避免出现「窗口还能再窄一点,但断点已经不生效」的中间状态。
4.2 路径闸门与对话框唯一入口
主进程的路径纪律由六个函数构成,第一个是把反斜杠统一成正斜杠:
function fwd(p) { return String(p == null ? '' : p).replace(/\\/g, '/'); }
第二个是带平台差异的归一化比较:
function normForCompare(p) {
var s = fwd(p);
if (s.length > 1 && /\/$/.test(s)) s = s.slice(0, -1);
return process.platform === 'win32' ? s.toLowerCase() : s;
}
Windows 上路径大小写不敏感,Linux 上敏感,所以比较前要先按平台决定要不要转小写。末尾斜杠要被去掉,否则 /a/b 与 /a/b/ 会被当成两个不同的目录。
第三个是包含判断,这里有一行容易写错的地方:
function isInside(child, parent) {
var c = normForCompare(child), p = normForCompare(parent);
if (!c || !p) return false;
return c === p || c.indexOf(p + '/') === 0;
}
判的是 p 加斜杠,不是裸的 p。如果写成 c.indexOf§ === 0,那么 /data/app2/file 会被判定在 /data/app 之内——因为它们的前缀相同。加上斜杠之后,只有真正处在下一层的路径才成立。
第四个是遍历全部授权根:
function isAllowed(p) {
var full = fwd(path.resolve(String(p || '')));
for (var i = 0; i < allowedRoots.length; i++) {
if (isInside(full, allowedRoots[i])) return true;
}
return false;
}
注意 path.resolve 这一步:它会把相对路径与 … 展开成绝对路径。如果少了这一步,一个形如 …/…/etc/passwd 的输入在字符串比较上可能绕开判断,而 resolve 之后它就落在某个真实位置上,再拿去比较。
第五个是抛错:
function guard(p) {
if (!isAllowed(p)) {
var err = new Error('该路径不在本应用已授权的目录内,请先用对话框选择文件');
err.code = 'EGUARD';
throw err;
}
}
第六个是登记根目录:
function rememberRoot(p) {
var full = fwd(path.resolve(String(p || '')));
if (!full) return;
for (var i = 0; i < allowedRoots.length; i++) {
if (normForCompare(allowedRoots[i]) === normForCompare(full)) return;
}
allowedRoots.push(full);
}
登记前先查重,所以同一个目录被选十次也只有一条记录。
这六个函数里,guard 只在一个 IPC 里被调用:
/* 8. 在文件管理器里定位 */
handle('shell:reveal', function (req) {
var file = fwd(req.path || '');
guard(file);
if (!fs.existsSync(file)) return { success: false, error: '路径不存在' };
shell.showItemInFolder(file);
return { success: true, path: file };
});
这是刻意的。其余七个通道要么不碰路径,要么路径来自对话框——而对话框本身就是系统级的授权动作,用户自己点过的路径不需要再过一遍闸门。shell:reveal 是唯一一个路径由渲染层直接提供、可能来自任意地方(比如从一份手工编辑过的场景文件里读出来的字符串)的通道,所以它必须过闸门。
读文件时的顺序是先登记授权、再读内容:
async function openText(dialogOpt, what) {
var r = await dialog.showOpenDialog(mainWindow, dialogOpt);
if (r.canceled || !r.filePaths.length) return { success: false, canceled: true };
var file = fwd(r.filePaths[0]);
rememberRoot(path.dirname(file));
var st = fs.statSync(file);
if (!st.isFile()) return { success: false, error: '不是一个文件' };
if (!st.size) return { success: false, error: (what || '文件') + '是空的' };
if (st.size > MAX_TEXT_BYTES) {
return { success: false, error: (what || '文件') + ' ' + sizeText(st.size) + ' 超过 ' + sizeText(MAX_TEXT_BYTES) + ' 上限' };
}
return {
success: true,
path: file,
name: baseName(file),
bytes: st.size,
text: fs.readFileSync(file, 'utf8')
};
}
这里登记的是 dirname 而不是文件本身。理由很直接:用户选了 /data/run1/dump.lammps,那么 /data/run1 整个目录被授权,之后在同一个目录里导出报告就不会被拒。如果只登记文件本身,每一次导出都要重新弹一次保存对话框。
大小检查在读之前做。32 MB 的上限对应 MAX_TEXT_BYTES 这个常量,一行 dump 数据大约 40 字节的话,32 MB 能装八十万行——足以覆盖这个壳支持的 400000 个总粒子数还绰绰有余。检查在 statSync 之后、readFileSync 之前,所以超限的文件一个字节都不会被读进内存。
写文件时的顺序是对话框、补后缀、登记、建目录、写:
var r = await dialog.showSaveDialog(mainWindow, {
title: o.title || '保存文件',
defaultPath: name,
filters: [
{ name: o.filterName || (ext.toUpperCase() + ' 文件'), extensions: [ext] },
{ name: '全部文件', extensions: ['*'] }
]
});
if (r.canceled || !r.filePath) return { success: false, canceled: true };
var file = fwd(r.filePath);
if (suffixOf(file) !== ext) file += '.' + ext;
rememberRoot(path.dirname(file));
fs.mkdirSync(path.dirname(file), { recursive: true });
fs.writeFileSync(file, text, 'utf8');
return { success: true, path: file, name: baseName(file), bytes: bytes };
两处后缀校正值得注意。第一处在弹对话框之前:
var ext = String(o.ext || 'txt').toLowerCase().replace(/[^a-z0-9]/g, '') || 'txt';
var name = String((req && req.defaultName) || ('ovito.' + ext));
if (suffixOf(name) !== ext) name = name.replace(/\.[A-Za-z0-9]+$/, '') + '.' + ext;
它保证对话框里预填的文件名带正确后缀。第二处在对话框返回之后,因为用户可能在对话框里把名字改成了别的后缀,或者是完全不带后缀。两道都做,是因为用户改名的机会在对话框里,而对话框是不可控的。
建目录用了 recursive,这一点是必须的。用户如果手动在对话框里输入了一个不存在的子目录路径,fs.mkdirSync 不带 recursive 会直接报 ENOENT。
错误文案全部中文化,一共 12 条:
var ERR_TEXT = {
EACCES: '没有访问权限(换一个位置再试)',
EPERM: '系统不允许这个操作',
ENOENT: '文件或目录不存在(可能已被移走)',
EEXIST: '目标文件已存在',
EISDIR: '目标是一个目录',
ENOTDIR: '路径中间有一层不是目录',
ENOSPC: '磁盘空间不足',
EMFILE: '同时打开的文件过多',
EBUSY: '文件正被其他程序占用',
EROFS: '所在位置是只读的',
EGUARD: '该路径不在本应用已授权的目录内,请先用对话框选择文件',
EBADJSON: '文件内容不是合法的 JSON'
};
兜底那一步的判断有讲究:
function errText(e) {
var code = String((e && e.code) || '');
if (ERR_TEXT[code]) return ERR_TEXT[code];
var msg = String((e && e.message) || e || '');
if (/[\u4e00-\u9fa5]/.test(msg)) return msg;
return code ? '系统调用失败(错误码 ' + code + ')' : '系统调用失败';
}
先查码表,查不到再看消息里有没有中文——有就直通。这一条是为了让业务代码里自己抛的中文错误(比如「场景内容不是合法的 JSON」)能原样显示,而不被套上一层「系统调用失败」。只有当消息里一个中文都没有时,才用码表兜底。这条规则把英文系统原文与绝对路径都挡在了状态条外面。
4.3 十处工程缺陷
逐条核过 app 目录与两个模块的配置之后,能确认的问题有十处。表格里给位置与影响,后面挑影响最大的四条展开。
| 编号 | 位置 | 现象 | 影响 |
|---|---|---|---|
| D1 | ov-util.js 第 68 行 | nonEmptyLines 只做 split,不滤空行 | 名字误导调用方,LAMMPS 数据块内出现空行即解析失败 |
| D2 | ov-util.js 与 ov-vec.js | copy、slug、cross、unit、distance 五个导出在 app 内无调用点 | 死代码,增加理解成本 |
| D3 | main.js 第 282 至 293 行 | report:save 放行四种后缀,ov-report 的 FORMATS 只有三种 | txt 分支永远走不到,白名单口径不一 |
| D4 | renderer.js 第 1389 行 | CSV 行数用 split 长度减二 | 有数据时少算一行 |
| D5 | main.js 第 37 行 | allowedRoots 纯内存,无持久化通道 | 重启后上次导出的目录失效 |
| D6 | ov-analysis.js 第 314 行 | analyzeAll 注释称共用一条曲线,实际重算 O(N²),且无人调用 | 注释与实现不符 |
| D7 | ov-pipeline.js 第 135 行 | selectType 覆盖选中集而不是合并 | 管线里两个 selectType 时前一个失效 |
| D8 | ov-pipeline.js 第 157 行 | showOnlySelected 之后选中位全真 | 报告管线表的「选中」列语义漂移 |
| D9 | package.json 第 9 至 10 行 | test 与 test:ipc 指向不存在的脚本 | npm test 直接失败 |
| D10 | ovito.css 第 680 行 | 注释是乱码 | 维护者读不到这句设计意图 |
第一条要展开的是 nonEmptyLines。这个函数的实现与名字不符:
function nonEmptyLines(text) {
return String(text == null ? '' : text).split(/\r?\n/);
}
它只做换行切分,一行空串也会被留在数组里。ov-io.js 里共有三处调用:第 34 行的 detect、第 75 行的 parseLammps、第 226 行的 parseXyz。用它在数据块里按行号取数时,行号与实际数据的对应关系就直接受空行影响:
for (var a = 0; a < count; a++) {
var ln = i + a;
var parts = String(lines[ln] || '').trim().split(/\s+/).filter(Boolean);
if (parts.length < header.length) {
return fail('第 ' + (ln + 1) + ' 行只有 ' + parts.length + ' 列,列头要求 ' + header.length + ' 列', warnings);
}
/* 此处省略其余实现 */
}
如果 ITEM: ATOMS 与数据行之间、或者数据行中间夹了一个空行,lines 的索引会整体偏移一格,最后几行会取到下一帧的文件头,于是报出「第 N 行只有 2 列,列头要求 5 列」。这个错误信息看起来像是文件坏了,实际是解析器没有跳过空行。detect 里已经在绕开这个行为(自己加了 if (!t) continue),但 parseLammps 与 parseXyz 没有。修法是把函数真正实现成过滤空行,或者在两个解析器里统一用切片前的过滤结果。
第二条是白名单口径。主进程的报告通道接受四种后缀:
if (['md', 'json', 'csv', 'txt'].indexOf(ext) < 0) {
return { success: false, error: '报告只支持 MD / JSON / CSV / TXT,收到的是 ' + (ext || '无后缀') };
}
但渲染层能拿到的后缀来自报告引擎的格式表,那里只有三种:
var FORMATS = [
{ key: 'markdown', label: 'Markdown', ext: 'md' },
{ key: 'json', label: 'JSON', ext: 'json' },
{ key: 'csv', label: 'CSV', ext: 'csv' }
];
saveReport 里取后缀的方式就是查这张表:
var f = RP ? RP.formatOf(S.format) : { ext: 'md' };
call('report:save', { text: S.reportText, ext: f.ext, defaultName: 'ovito-' + U.stamp() + '.' + f.ext });
所以 txt 这一项永远不可能被发过来。这不造成任何错误,但它意味着两处白名单会各自演化——某天有人在引擎里加一个 txt 格式,主进程这边恰好放行;反过来有人在主进程里收窄到三种,引擎那边就会开始报错。放行列表应当由同一份常量派生,而不是两处各写一遍。
第三条是 CSV 行数。saveData 里的算法是:
var lines = out.text.split('\r\n').length - 2;
toCsv 保证每一行都以 \r\n 结尾,包括最后一行。所以对 N 行内容(含表头),text 是 N 个「内容加换行」的拼接,split(‘\r\n’) 之后得到 N 加 1 个元素,最后一个是空串。正确的行数就是长度减一。这里减二,于是有数据时总是少算一行。
以 100 个分箱为例:表头加 100 行数据共 101 行,界面提示写的是「已导出 99 行」,而文件里实实在在是 101 行。无数据时恰好对:只有表头一行,split 得 2 个元素,减二等于 0,与「没有数据行」一致。这种「边界情况对、正常情况错」的偏差最难发现,因为一旦有人拿小样本验证就会通过。
第四条是 allowedRoots 不落盘。这个数组在 main.js 里只有两种来源:
app.whenReady().then(function () {
rememberRoot(fwd(app.getPath('userData')));
rememberRoot(fwd(__dirname));
registerIpc();
createWindow();
/* 此处省略其余实现 */
});
加上运行时用户通过对话框选出来的目录。没有第三个来源,因为整份代码里没有任何 prefs 或 session 通道,也没有把 allowedRoots 写进任何文件的语句。后果是每次启动之后,能合法访问的目录只有两个内置根,上一次导出报告的目录已经不在闸门内。此时用户点「在文件夹中显示」,S.lastPath 是空串(S 在每次启动时重置),所以会收到「还没有导出过文件」的提示而不是 EGUARD——这个提示是准确的,但用户的意图是「我刚才导出的文件在哪」,却只能重新导出一遍。
第六条值得单独说,因为它是一处注释与实现的错位:
/* RDF 与配位数共用同一条曲线:界面上点「配位」时不必重算第二遍 */
function analyzeAll(frame, opt) {
var o = opt || {};
var r = rdf(frame, o);
if (!r.success) return { success: false, error: r.error };
var c = coordination(frame, o);
if (!c.success) return { success: false, error: c.error };
return { success: true, rdf: r, coordination: c };
}
注释说「共用同一条曲线、不必重算」,但函数体里明明又调了一次 coordination,而 coordination 内部是一模一样的双循环,复杂度还是 O(N²)。更关键的是渲染层根本没用这个函数:runAnalysis 里是分开调的:
var r = AN.rdf(frame, opt);
if (!r.success) { /* 此处省略实现 */ }
var c = AN.coordination(frame, opt);
var cl = AN.clusters(frame, { cutoff: cc, periodic: opt.periodic });
var m = AN.msd(S.frames, { periodic: opt.periodic });
所以这是一个既没有兑现注释承诺、也没有被调用的函数。真要省那一遍,做法是让 coordination 接受 rdf 已算好的 counts,而不是再跑一次双循环。
4.4 一致性纪律:管线变了分析就得作废
第四章前面讲的都是「不出错」,这一节讲的是「不出自相矛盾的界面」。这两件事的难度不在一个量级上——前者是写对一段代码,后者是管住状态在时间和空间上的传播。
第一条纪律在切帧时:
function setFrame(i, silent) {
if (!hasData()) return;
var k = Math.round(U.clamp(i, 0, S.frames.length - 1));
if (k === S.idx) return;
S.idx = k;
S.pick = null;
/* 帧换了,帧相关的 RDF / 配位 / 簇都作废:宁可让人重新点一次分析 */
var hadAnalysis = !!S.analysis;
if (hadAnalysis) S.analysis = null;
S.dataNote = '';
markReportDirty();
if (hadAnalysis && !silent) notice('已切到第 ' + (k + 1) + ' 帧:帧相关分析已清空,需要重新执行', 'warn');
rebuild(true);
renderAll();
}
三个动作连在一起:清拾取、清分析、标脏报告。播放时传 silent 为真,不弹提示——每 0.42 秒弹一次会让状态条一直在跳。手动切帧时弹,并且说清楚「帧相关分析已清空,需要重新执行」,让用户知道为什么刚才的数值不见了。
第二条纪律在换数据源时:
function loadScene(src) {
stopPlay();
S.source = { /* 此处省略对象字段 */ };
S.frames = src.frames || [];
S.idx = 0;
/* 场景可以先于轨迹打开:把等着的管线接过来,打开文件后自动跑一遍;
* 否则管线属于旧数据源,必须清掉——丢了多少步由调用方告知用户。 */
var dropped = 0;
if (S.pendingOps) {
S.ops = S.pendingOps.slice();
S.pendingOps = null;
} else {
dropped = S.ops.length;
S.ops = [];
}
/* 此处省略其余实现 */
}
这里有个双向的决策。pendingOps 非空意味着「用户先打开了场景、后打开轨迹」,此时管线是从场景里读出来的,正是为这份数据准备的,所以要接过来并立刻跑一遍。pendingOps 为空意味着管线属于上一份数据,它的切片坐标、类型编号在新数据上毫无意义,必须清空;清空了几步要通过返回值告诉调用方,由调用方写进提示里:
var dropped = loadScene(sc);
notice('已载入示例:' + SAMPLE_N * SAMPLE_N * SAMPLE_N + ' 个粒子 × 3 帧;试试拖拽旋转、执行分析' +
(dropped ? '(上一份 ' + dropped + ' 步管线已清空)' : ''), 'ok');
「丢了多少步」这件事必须让用户看见。静默清空会让人以为管线还在,而画面已经变回原始帧了。
第三条纪律在重建失败时:
function rebuild(silent) {
/* 视图要重算了,原来拾取的那个粒子未必还在画面里 */
S.pick = null;
if (!hasData()) { S.result = null; return false; }
if (!S.ops.length) { S.result = null; return false; }
var out = PL.apply(baseFrame(), S.ops);
if (!out.success) {
S.result = null;
if (!silent) notice(out.error || '管线执行失败', 'err');
return false;
}
S.result = out;
if (!silent && out.warnings && out.warnings.length) notice(out.warnings[0], 'warn');
return true;
}
注意 pick 在函数第一行就被清掉了,而且是在任何判断之前。原因写在注释里:视图重算之后,S.drawn 里的坐标全变了,原来的拾取点可能已经不在这颗粒子上了。如果保留,画面上会出现一个圈套在错误的粒子上。
第四条纪律在打开场景失败时:
var ok = rebuild();
dropAnalysis();
S.dataNote = '';
markReportDirty();
renderAll();
/* rebuild 失败时已把中文原因写到状态条,不要再用成功提示盖掉它 */
if (!ok) return;
notice('场景已恢复:' + S.ops.length + ' 步管线、视角与渲染参数', 'ok');
这个 if (!ok) return 只有两行,但它是整个文件里最容易漏的一处。如果漏了,用户看到的是「场景已恢复」这条绿色提示,而实际上管线一步都没执行成功——真正的原因(比如某个修饰器类型无法识别)刚被写进状态条,立刻就被成功提示覆盖了。用户在界面上找不到任何异常,只会觉得「场景打开了但没生效」。
第五条纪律是报告与预览的同步。任何会改变数据的动作之后,都要调 markReportDirty:
function markReportDirty() {
S.reportText = '';
var out = $('reportOut');
if (out) out.value = '';
setBadge('reportBadge', '未生成');
}
它把已生成但已过期的那份文本清掉。如果不清楚,用户会在改完管线之后直接点「另存为」,导出的还是改之前的报告。这个错误的隐蔽性在于:文件确实生成了,内容也确实是一份合法的报告,只是它描述的是五分钟前的状态。
这五条纪律加起来,构成了「任何一个数字都能追溯到当前状态」这个性质。它们没有一条是复杂的算法,全是在动作发生的那一刻顺手把相关的旧状态清掉。难的不是写,是想到要写——每一次新增一个会改变数据的功能,都要问一遍:还有哪些面板正在显示旧值。
五、构建与部署

图 1 冷启动后的空状态。数据源面板显示「还没有轨迹」,帧控制是 0/0,左栏三个摘要项都是 0 或破折号,底栏「关于」入口在右下角。窗口标题是 OVITO 粒子工作台,状态条右侧一行提示「就绪:先打开轨迹或载入示例,再拖拽画布旋转视角」。

图 2 载入内置示例并打开关于对话框。背后可以看到 125 个粒子、3 帧、375 总粒子数、1 条解析提示;对话框里三段分别是开源声明、免责声明与完全开源,许可证写的是 Apache-2.0。

图 3 示例载入后的数据源面板。盒子 6 × 6 × 6 埃、体积 216 埃三次方、视图数密度 0.5787 每立方埃、当前 tick 2000、周期边界「开(折回盒内)」、管线视图 125 个粒子,类型芯片是 Fe × 125。
5.1 构建产物与签名
electron 模块的输出目录下只有三个文件:
| 文件 | 字节数 |
|---|---|
| electron-default-signed.hap | 195364518 |
| electron-default-unsigned.hap | 193904198 |
| pack.info | 752 |
两个 hap 相差 1460320 字节,这就是签名材料(证书链、profile 与签名块)的体积。签名包是 186.3 MB,未签名包是 184.9 MB,按 1048576 换算下来分别是 186.31 MB 与 184.92 MB。
构建日志留在 .hvigor/outputs/build-logs 下,一共六个文件,最大的两个是 build.log.2 的 2417678 字节与 build.log.5 的 2339824 字节,最小的 build.log 是 215046 字节。日志的大小主要来自原生库收集与打包阶段的逐条文件记录——四个 .so 加起来 166 MB,每一条都要打一行。
pack.info 是描述这次产物的一份快照,第二章已经引过全文。几个字段值得再点一次:bundleType 是 app,versionCode 是 1000000、versionName 是 1.0.0,moduleName 是 electron,moduleType 是 entry,deviceType 是 2in1 与 tablet,compatible 是 17、target 是 20、releaseType 是 Release。这些值与 AppScope 的 app.json5 和根 build-profile.json5 完全对得上,说明构建时没有取到任何隐式默认值。
5.2 体积构成
未签名包的 193904198 字节里,四个原生库占了绝大部分:
| 文件 | 字节数 | 占未签名包 |
|---|---|---|
| libelectron.so | 167471912 | 86.38% |
| libadapter.so | 2621200 | 1.35% |
| libffmpeg.so | 2181528 | 1.13% |
| libc++_shared.so | 1825624 | 0.94% |
| 四个合计 | 174100264 | 89.79% |
| 其余全部 | 19803934 | 10.21% |
libelectron.so 一个文件就占了 86.38%,这是 Electron 壳类应用无法回避的成本——Chromium 与 Node.js 的运行时全在它里面。
这一层真正有意思的地方在剥离。仓库根目录下的 lib.unstripped 里放着两个带完整符号表的原始文件:
| 文件 | 未剥离字节 | 进包字节 | 剥离比 |
|---|---|---|---|
| libelectron.so | 1143668440 | 167471912 | 6.83 |
| libadapter.so | 15494016 | 2621200 | 5.91 |
libelectron 从 1.07 GB 压到 159.7 MB,缩减 6.83 倍;libadapter 从 14.8 MB 压到 2.5 MB,缩减 5.91 倍。断点符号与调试信息在发布包里没有任何用处,剥掉它们不影响运行,但会让崩溃栈里的地址变成纯数字。
构建中间产物里有一处细节值得注意。stripped_native_libs 目录与 libs 目录的四个文件逐个比对,三个大库的字节数完全一致,只有 libc++_shared.so 变了:
| 文件 | libs 目录 | stripped_native_libs 目录 |
|---|---|---|
| libelectron.so | 167471912 | 167471912 |
| libadapter.so | 2621200 | 2621200 |
| libffmpeg.so | 2181528 | 2181528 |
| libc++_shared.so | 1825624 | 1334688 |
libc++_shared 减少了 490936 字节,约 26.9%。另外三个一字节不差,说明它们在进入 ohos_hap/electron/libs 之前就已经是剥离过的版本——lib.unstripped 里那两个才是原始件。这也解释了为什么剥离比要用根目录的 lib.unstripped 来算,而不是用构建中间产物。
OVITO 自己的应用资源在这 166 MB 面前几乎不可见:
| 项 | 字节数 | 占未签名包 |
|---|---|---|
| app 目录全部 12 个文件 | 167727 | 0.087% |
| 其中七个引擎 | 52144 | 0.027% |
| 其中 renderer.js | 66997 | 0.035% |
一万六千分之一的体量换来整个界面与全部功能。这个比例说明了一件事:在这个项目里,优化前端代码的体积是没有意义的——即便把 renderer.js 全部删掉,包体也只小 0.035%。真正需要关注的是那 89.79%,而那一部分不归业务代码管。
5.3 上架前的替换清单
| 项 | 当前状态 | 上架前处理 |
|---|---|---|
| bundleName | com.huawei.ohos_electron | 换成自有域名的反向写法 |
| AppScope 的 app_name | Electron | 改为 OVITO 粒子工作台 |
| vendor | example | 改为实际发布方 |
| web_engine 权限清单 | 26 条,含位置、摄像头、麦克风、蓝牙 | 裁剪到文件对话框与剪贴板所需 |
| electron 的 license 字段 | 空字符串 | 补成与 web_engine 一致的 Apache-2.0 |
| 关于对话框三段文字 | 已写全 | 核对许可证与实际仓库一致 |
| 版本号 | 1.0.0 / 1000000 | 按上架规则递增 |
| package.json 的 test 脚本 | 指向不存在的文件 | 补脚本或删掉两个 test 项 |
| 四个配置文件里的尾逗号 | 共 8 处 | 若 CI 用严格 JSON 解析器则需去掉 |
| ovito.css 第 680 行的乱码注释 | 乱码 | 修复为可读中文 |
| README.OpenHarmony_CN.md | 项目根目录没有 | 补齐,其余同批项目都有 |
| 窗口标题 | OVITO 粒子工作台 | 与 app_name 保持一致 |
其中前四项是必须改的。bundleName 与 vendor 用的是模板默认值,装上设备之后在应用列表里会显示成 Electron;权限清单里那些位置、摄像头、麦克风条目与实际行为完全不符,是审核最容易拦下来的地方;license 空字符串在一份声明 Apache-2.0 的工程里显得自相矛盾。
第八项与第十二项都是「说了却没做到」的问题。package.json 里的两个脚本:
"scripts": {
"start": "electron .",
"test": "node test-ovito-engine.js",
"test:ipc": "node test-ovito-ipc.js"
}
在 app 目录下实际只有 index.html、main.js、package.json、renderer.js 四个顶层文件,test-ovito-engine.js 与 test-ovito-ipc.js 都不存在。这会让任何尝试 npm test 的人得到一个「Cannot find module」的报错,比没有测试脚本更让人困惑。
第十一项是一个同批次的横向对照:这一批 Electron 壳项目的根目录都有一份 README.OpenHarmony_CN.md,只有 OVITO 这一份没有,根目录下只有一份 26274 字节的 README.md 与 .gitattributes。补齐它不属于代码工作,但它影响的是别人第一次打开这个仓库时能不能看懂这是什么。
六、常见问题与解决方案
Q1 打开 dump 文件后,提示「第 N 行只有 0 列,列头要求 5 列」,但文件看起来是好的
问题现象。用户拿一份自己手改过的 LAMMPS dump 打开,状态条报出「第 42 行只有 0 列,列头要求 5 列」。用编辑器打开第 42 行,那里是一行空行;文件里其他帧都正常。
根因分析。parseLammps 按 count 逐行取数,行号靠 ITEM: ATOMS 之后的行偏移算,中间任何一个空行都会让后面的索引整体错一格。行数不够时,最后几行会取到下一帧的文件头或完全空的字符串,于是 parts.length 变成 0 或 1,触发了「列头要求 N 列」这条判断。而 ov-util 的 nonEmptyLines 只做 split 不做过滤,名字容易让人以为它已经跳过了空行。
解决方案。要么在解析前把空行真正过滤掉,要么在两个解析器各自的第一行加一句跳过。前者的风险是行号会与原始文件对不上(过滤之后 ln 算出来的是过滤后的行号,而用户看到的文件是过滤前的),所以更稳的做法是不改数组,而是在取数据行时遇到空串就往后多看一行:
while (a < count) {
var ln = i + a;
var parts = String(lines[ln] || '').trim().split(/\s+/).filter(Boolean);
if (!parts.length) { i++; continue; }
/* 此处省略其余实现 */
}
这样行号依然指向原始文件,只是把空行当成了不存在。
教训。工具函数的名字必须等于它的行为。nonEmptyLines 这个名字一旦被信任,后面所有调用点都不会再自己判一次空。而它当前的行为与名字的差距,恰好只在「文件里有空行」这一种情况下暴露——正常文件永远测不出来。
Q2 倾斜盒子体系里,周期性最小的镜像距离算出来跟预测对不上
问题现象。用户打开一个 triclinic 体系的 dump,画面上粒子位置基本对,但 RDF 的第一峰位置与文献值差了百分之几,配位数也偏低。
根因分析。dump 的 BOX BOUNDS 在 triclinic 情况下会写六个倾斜因子,而解析器只取了每行的前两个数当 xlo、xhi,构造出一个正交盒子:
box = {
xlo: rows[0][0], xhi: rows[0][1],
ylo: rows[1][0], yhi: rows[1][1],
zlo: rows[2][0], zhi: rows[2][1]
};
解析器在检测到倾斜时确实写了警告,但警告只是一句话,不影响数值。而且 LAMMPS 的 triclinic 盒子里这三个范围本身已经是包含倾斜修正的 bounding box,直接当正交盒子用,会把体积算大、把最短距离算错。
解决方案。在倾斜体系里把周期最小镜像关掉,用非周期模式算距离。非周期模式下 cutoffFor 的上限是盒子对角线而不是最小边长的一半:
var max = (opt && opt.periodic === false) ? Math.sqrt(s.lx * s.lx + s.ly * s.ly + s.lz * s.lz) : half;
return U.clamp(want, 0.01, Math.max(0.02, max));
对一个小体系这足够,对大体系则等于放弃了周期。真正的修法是读进六个倾斜因子并实现 triclinic 的最小镜像,那是一个独立的几何问题。
教训。能力边界写在界面上,和写在注释里,效果完全不同。这一条在解析提示里明说了「按正交包围盒近似」,所以用户至少知道偏差是从哪来的;如果只写在源码注释里,用户只会觉得这个软件算得不准。
Q3 点了「执行分析」没有任何反应,也没有提示
问题现象。用户打开一份 8000 个粒子的轨迹,直接点分析,按钮点下去之后状态条闪了一下就没了,图还是空的。
根因分析。runAnalysis 的第一道判断是 RDF:
var r = AN.rdf(frame, opt);
if (!r.success) {
dropAnalysis();
renderAnalysis();
notice(r.error || 'RDF 计算失败', 'err');
return;
}
rdf 内部会先调 tooMany,超过 4000 就返回「当前帧有 8000 个粒子,超过分析上限 4000;先用切片或选择器缩小范围」。这条错误确实被写进了状态条,但写的是红色的短提示,如果用户当时在看画布或者图表,很可能一眼扫过去没注意到。而且 dropAnalysis 会把已有的结果清掉,图表也随之变空,看起来像是「点了没用」而不是「被拒绝了」。
解决方案。超限这种「有明确解决办法」的情况应该给更醒目的处理——至少要在分析面板里留一条持久提示,而不是只写状态条。当前代码里 anaHint 在部分失败时会更新,但被 tooMany 拒绝这条路径只写了状态条。
var msg = (!c.success && c.error) || (!cl.success && cl.error) || (m && !m.success && m.error) || '';
if (msg) setText('anaHint', '部分分析未完成:' + msg);
这一段只处理了配位数、簇与 MSD 的失败,没有处理 RDF 失败。把 r.error 也接到 anaHint 上,用户在面板里就能一直看到原因。
教训。被拒绝的操作必须留下痕迹。状态条会被下一次任何提示覆盖,而面板里的提示不会。凡是「用户主动点了、但系统没做」的情况,都应该写到最后那个不会被轻易覆盖的地方。
Q4 管线里加了两次「按类型选择」,第一次选的类型不生效了
问题现象。用户先选类型 1 加了一步,又选类型 2 加了一步,结果画面上只剩类型 2 的粒子。
根因分析。ov-pipeline 的 selectType 分支是覆盖,不是合并:
} else if (o.type === 'selectType') {
selected = atoms.map(function (a) { return o.types.indexOf(S.typeKey(a)) >= 0; });
}
每一次都从头重新算选中集,与之前的选择无关。这本身是符合 OVITO 修饰器语义的——在 OVITO 里连续的 Select type 修饰器也是后面的覆盖前面的,要用并集得显式加一个逻辑或。但从界面上走的时候,这个问题不会出现,因为 applyTypeSelection 会复用最后一步:
if (last && last.type === 'selectType') {
last.types = S.selTypes.slice();
}
所以用户在面板上连点几个类型芯片,改的是同一个操作。真正会撞上覆盖行为的只有一种情况:从场景文件恢复,或者手工编辑过管线,让两个 selectType 相邻。
解决方案。如果确实需要并集,就在界面上提供一个「保留既有选择」的开关,把它翻译成管线的连接方式;或者干脆在 describe 里把语义写清楚,让用户看到「按类型选择」这一步的全量替换效果。当前的 describe 只写了类型名:
return '按类型选择:' + (o.types.length ? o.types.map(S.typeLabel).join('、') : '(未选类型)');
加上「替换为」或「并入」的措辞,能省掉一次困惑。
教训。界面上的操作合并,会掩盖引擎里的覆盖语义。用户从 UI 学到的行为与从文件加载时的行为不一致,是这个项目里最容易长期潜伏的问题类型。
Q5 导出的 CSV 文件明明有 101 行,界面说只导出了 99 行
问题现象。用户分析完以后导出 RDF 数据,界面提示「已导出 99 行」,用 Excel 打开却是 100 行数据加一行表头。
根因分析。saveData 里用字符串切分算行数:
var lines = out.text.split('\r\n').length - 2;
toCsv 保证最后一行也带换行:
return rows.join('\r\n') + '\r\n';
所以对 N 行内容,split 之后得到 N 加 1 个元素,最后一个是空串。正确的行数是长度减一,这里减二,于是有数据时总是少一行。无数据时(只有表头一行)split 得 2 个元素,减二等于 0,恰好正确——这就是为什么这个问题在小样本上测不出来。
解决方案。两种改法:一是减一,二是干脆用分析结果里的分箱数:
var lines = S.analysis && S.analysis.rdf ? S.analysis.rdf.rows.length : 0;
后一种更稳,因为它不依赖字符串的具体拼接方式,换行符从 \r\n 改成 \n 也不受影响。
教训。凡是靠字符串格式反推行数的写法,都在赌格式不变。这里的数据本来就在手边(rdf.rows 的长度),绕一圈去切字符串反而引入了偏差。
Q6 重启应用之后,点「在文件夹中显示」提示「还没有导出过文件」
问题现象。用户上一次会话里导出了一份报告,关掉应用再打开,想找到那份文件,点按钮却收到「还没有导出过文件:先另存报告或导出 CSV」。
根因分析。S.lastPath 是渲染层的会话内状态,每次启动初始化为空串:
var S = {
/* 此处省略其余实现 */
lastPath: '',
/* 此处省略其余实现 */
};
而主进程侧的 allowedRoots 同样是纯内存的,只有一个在启动时登记的两个根:
rememberRoot(fwd(app.getPath('userData')));
rememberRoot(fwd(__dirname));
没有任何持久化通道把上次的目录写下来再读回来。所以即便 lastPath 能跨会话保留,重启之后它也落在闸门外面,shell:reveal 依然会抛 EGUARD。
解决方案。要让「上次导出的目录」跨会话可用,需要两件事同时做:把 lastPath 写进 userData 下的一个偏好文件、在启动时把它的 dirname 重新登记进 allowedRoots。这两件事都必须走主进程,因为渲染层无权改 allowedRoots——如果允许渲染层自己加根,闸门就形同虚设。
教训。授权的持久化必须与状态的持久化一起设计。只存路径不存授权,等于把「打开」做成了一次性动作;只在启动时授权两个内置根,则意味着用户每次开新会话都要重新选目录。
Q7 npm test 直接报 Cannot find module
问题现象。接手这个项目的人先跑 npm start 验证环境,成功了;再跑 npm test,报错说找不到 test-ovito-engine.js。
根因分析。package.json 里声明了两个测试脚本,但对应的文件并不存在:
"test": "node test-ovito-engine.js",
"test:ipc": "node test-ovito-ipc.js"
app 目录下的 12 个文件里没有这两个。引擎源码的注释里反复提到「全纯函数,几何出错可以在单测里直接断言」,说明这些测试曾经存在过或者计划要写,但没有落到文件上。
解决方案。两条路:把测试补上,或者把两个脚本删掉。补的价值很大——七个引擎全是无 DOM 依赖的纯函数,UMD 形态让它们在 Node.js 里可以直接 require:
var U = (root && root.OvUtil)
|| ((typeof require === 'function') ? require('./ov-util.js') : null);
这意味着 fitScale 在对角线缩放上的恒定、minImage 对边界值的折回、firstPeak 对第二峰更高的处理、csv 的行尾,全都可以在没有任何浏览器的情况下断言。一个两三百行的测试文件能覆盖住项目里最容易出错的地方。
教训。工程里任何一条声称「有测试」的痕迹,只要脚本指向不存在的文件,就是在消耗后来者的时间。删掉比留着好,补上更好。
七、总结
这个项目最终呈现出来的形态,可以用一张表说清:
| 层 | 规模 | 承担的事 | 关键约束 |
|---|---|---|---|
| 主进程 | 356 行 | 开窗、授权、落盘 | 八个 IPC,不持有粒子数据 |
| 轨迹解析 | 338 行 | dump 与 XYZ 收敛成帧结构 | 不猜单位、错误带行号 |
| 矢量投影 | 122 行 | 欧拉旋转、正交投影、最小镜像 | 纯函数,先 Y 后 X |
| 场景统计 | 163 行 | 类型、盒子、数密度、结构收敛 | 只读,不改粒子 |
| 修饰器管线 | 207 行 | 七种操作,每步返回新数组 | 每步一条日志 |
| 结构分析 | 337 行 | RDF、配位、MSD、簇 | 口径写死,单帧上限 4000 |
| 报告组装 | 241 行 | 三种格式读同一份 collect | 不写本机路径 |
| 渲染层 | 1899 行 | 投影绘制、七面板、IPC 调用 | 一条铁律:读同一份结果 |
| 样式 | 717 行 | 四层布局、36 个变量 | 0 过渡、0 动画、0 变换 |
| 应用资源合计 | 12 文件、4875 行 | 全部功能 | 占包体 0.087% |
第一,把「三维」算成「二维」,而不是交给图形管线。这个决定带来的不只是 122 行代码,而是一整条可控的链路:哪里有遮挡可以靠一个 sort 决定,粒子画多大可以按数密度反推,点击拾取可以直接在手边留下的坐标表里找最近的。代价是没有光照、没有体积、没有几百万粒子的能力——而这几点恰好被写进了 app:info 的 unsupported 里,成为界面上可以读到的一句话。
第二,一致性的代价远低于不一致带来的后果。dropAnalysis 只有四行,markReportDirty 只有五行,rebuild 第一行清拾取也只有一行。这三处加起来不到十行,却守住了「界面看到的、图表画的、报告写的永远是同一份数据」这个性质。反过来,如果任由「新管线配旧数值」存在一次,用户对整份报告的信任就没了,而这十行代码省下来的时间去解释「为什么数字对不上」,远远不止。
第三,能力边界必须写在两个地方:源码注释里给维护者看,app:info 里给用户看。这个项目把四条不做的事同时写在了两处,界面的「环境与限制」面板直接渲染主进程返回的数组。倾斜盒子、4000 粒子上限、不读二进制轨迹这些限制,用户在使用中一定会撞上,区别只在于撞上时是看到一句准确的中文说明,还是看到一个空白界面然后怀疑软件坏了。
上架平台之前,必须把 bundleName 从模板默认值改成自有域名的反向写法,否则装上去在应用列表里显示的是别人的名字。必须把 26 条权限裁剪到文件对话框与剪贴板真正需要的范围,因为位置、摄像头、麦克风这些条目与实际行为不符,是审核最容易拦下来的地方。必须把 AppScope 里的 app_name 从 Electron 改成 OVITO 粒子工作台,让窗口标题、桌面图标与应用列表三处名称一致。必须补齐测试脚本或删除那两个指向不存在文件的 npm 项,让后来接手的人第一次 npm test 就不会撞上空文件。这四件事没有一件属于功能开发,但它们决定了这个已经能跑的构建,能不能变成一份可以被别人安装和信任的产物。
更多推荐



所有评论(0)