基于视觉的振动分析工具：用普通相机拍摄的视频，框选区域后用光流 / 互相关测量亚像素级振动位移，并用运动放大直观地"看见"振型。

百度网盘下载地址： https://pan.baidu.com/s/17UTbpJ0Pq9P_ubYNmdQXsg?pwd=ugt3

目录

1. 软件简介
2. 快速上手（5 分钟跑通）
3. 界面总览
4. 功能详解
5. 技术细节（重点）
6. 内存与性能（重点）
7. 常见问题与排错
8. 附录：算法论文出处

一、软件简介

像素振动是一款面向"微小振动测量"的桌面软件，它的前身是“视觉振动工具箱”，我们通过python和opencv重构了整个界面和交互逻辑，使其真正的从玩具蜕变成工具，这将是唯一一个不需要用户登录且有完整基础功能的版本。它只需要一台普通相机拍一段视频，就能做两件肉眼做不到的事：

1. 测量振动：在画面上框一个感兴趣区域（ROI），自动算出这个区域每一帧位移了多少像素，并给出位移波形和振动频率（频谱）——精度可以达到 0.01 像素级（亚像素）。
2. 看见振动：用"运动放大"把看不见的微小振动放大几十到几百倍，让你直接用眼睛看到物体是怎么振的（振型、节点、方向）。

典型应用场景：机械结构的共振/模态测试、管道/桥梁/塔架的健康监测、精密设备的微振动诊断、教学演示等。

运行方式

• 绿色免安装版：解压后双击 Pixel Vibration.exe 即可运行（整个文件夹要一起复制）。
• 源码运行：安装 Python 依赖后执行 python main.py。

依赖（源码运行才需要）：PySide6、numpy、scipy、opencv-python、pyqtgraph。

二、快速上手（5 分钟跑通）

第一次使用，按下面 6 步走一遍就能出结果：

1. 启动：双击 Pixel Vibration.exe。
2. 读视频：点左侧面板顶部「读取视频」按钮 → 选一个视频文件（或先点「生成演示视频」造一段测试视频）。
3. 定范围：在「读取视频帧」窗口里，可框选区域、拖动起止滑块定帧范围，然后点「读入工作区」。
4. 框 ROI：在播放器画面上拖动鼠标，框住你想测量的振动部位（出现一个彩色矩形框）。
5. 测振：在左侧「振动测量」分区选中该 ROI，点「计算」。等一两秒，波形/频谱窗口会自动弹出。
6. （可选）运动放大：在「运动放大」分区设好频带和放大倍数，点「计算放大」，再拖动「放大系数」滑块，就能在播放器里实时看到被放大的振动。

建议先点「生成演示视频」：软件会造一段"两个频率振动"的无损测试视频，用它能最快熟悉全部功能，不依赖你自己的素材。

三、界面总览

主界面是无边框窗口，左侧是固定工作区面板（上中下三张卡片），右侧是播放器（MDI 子窗口，可开多个素材）。

左侧工作区：三张卡片

右侧播放器

显示当前素材的画面，你在这里框选 ROI、播放/拖动视频、切换"原始 / 放大"显示，叠加 ROI 框和振动箭头。

四、功能详解

4.1 读取视频

点「读取视频」打开下面的对话框：

操作要点：

1. 选择文件：点「浏览…」选视频；或点「生成演示视频」造一段测试视频。
2. 预览：下方进度条可以拖动，随时看某一帧的画面。
3. 框选区域（可选）：点「框选区域」后在画面上拖一个矩形，只读这块区域（能大幅省内存、提速度）；点「用全图」恢复全图。
4. 定帧范围：用起止数字框或进度条上的范围滑块，只读某一段帧。
5. 彩色 / 灰度：勾选「彩色」读彩色；不勾则读灰度（灰度更省内存，测振和放大其实只用亮度）。
6. 内存估算：底部会实时显示"将读入 N 帧 × 宽×高 → 约 XXX"。如果超过 2 GB 会红字警告（见第六章）。

点「读入工作区」后，素材会出现在左侧素材列表里。

4.2 素材管理

• 列表四列：名称 / 尺寸 / 帧率 / 内存（把鼠标悬停在"内存"上，能看到帧数据、振动数据、放大缓存各自占多少）。
• 顶部按钮：读取视频（新素材）、加载素材（打开 .vvm 文件）、删除素材（删除选中，释放内存）。
• 底部显示"共 N 个素材，合计 XXX"——多个素材的内存是叠加的，不用了就删掉。

4.3 振动测量（ROI）

• 添加 ROI：在播放器里拖动框选，或在 ROI 列表里添加。
• 计算方法：LK 光流 / 互相关(NCC) / 基于相位，三种算法怎么选见第五章 5.3。
• 计算：对选中的 ROI 计算位移，完成后自动弹出波形/频谱窗口。
• 箭头倍率：控制画面上"振动箭头"的长度（箭头长 = 位移 × 倍率，只是显示用，不影响测量结果）。

4.4 运动放大

• 算法：线性(欧拉) / 里斯金字塔（实时预览只支持这两种；复可控金字塔只在导出时用）。
• 带通下限 / 上限：只放大这个频率段的振动（Hz）。必须小于采样率的一半（奈奎斯特频率），否则会报错。
• 放大系数（gain）：拖动即可实时预览放大效果，不用重新计算（这是本软件的设计亮点）。
• 金字塔层数 / 相位平滑 σ：高级参数，一般留"自动/默认"即可。
• 计算放大 / 取消放大 / 释放缓存：算完后点「释放缓存」能立刻释放大量内存（见第六章）。

4.5 播放器

• 底部控件：播放/暂停、进度条拖动、起止范围滑块。
• 显示切换：原始画面 放大画面。
• ROI 框与振动箭头会叠加在画面上，箭头方向和长度表示当前帧的位移。

4.6 导出

• 原始画面 / 放大画面：导出哪一种。
• 叠加标注：勾选后把 ROI 框、振动箭头画进导出的视频里。
• 高阶：基于相位的运动放大（复可控金字塔）：质量最高，但计算量极大，可能耗时 30 分钟以上，请谨慎使用。
• 也支持导出振动数据 CSV（所有 ROI 的位移时程，可用 Excel 打开）和保存素材 .vvm。

4.7 设置

可设置 ROI 框的样式、界面主题、默认是否读彩色、运动放大的默认参数等。一般保持默认即可。

五、技术细节（重点）

这一章面向完全没有图像处理基础的读者，从零讲起，一步一步解释本软件"背后在算什么"。已经懂的人可以跳到 5.3 直接看算法对比。

5.1 零基础铺垫：先搞懂几个概念

① 像素与灰度

视频的每一帧就是一张图，由一个个小方格（像素）组成。灰度图里每个像素用一个数字表示亮度：0 是黑，255 是白。一个"移动了 1 个像素"的物体，就是它对应的那些像素值整体往旁边挪了一格。

② 帧率与采样率

视频一秒钟有很多帧，这个数量叫帧率（fps）。例如 120 fps 就是每秒 120 张图。帧率就是测量的"采样率"：它决定了我们能测到多高的振动频率（最高能测到采样率的一半，即奈奎斯特频率）。

③ 频率与频谱

"振动"就是某个东西在一段时间里来回动。频率 = 一秒钟来回几次，单位赫兹（Hz）。把一段位移波形做数学变换（傅里叶变换 FFT），就能拆出"里面有哪些频率、各有多强"，这就是频谱——它告诉我们物体到底在哪个频率上振。

④ 带通滤波

带通滤波 = 只保留"下限~上限"之间的频率，其余全滤掉。作用：只放大/只测量你关心的振动，把噪声、晃动、呼吸、摄像机抖动等都排除掉。

⑤ 图像金字塔

把一张图逐层缩小（每层宽高各缩一半），就像一座金字塔。缩小前是"细节 + 大块"，缩小后只剩"大块趋势"。"细节层"恰恰对微小运动最敏感，所以测振和放大都要先做金字塔分解。

⑥ 相位

可以把"振动"理解成一列波。波上每个点处于"波峰、波谷、还是中间"的状态叫相位。物体移动一点，波峰位置就挪一点——相位的变化就对应位移。相位法测振和相位放大，本质都是"测量 / 放大相位的变化"。

5.2 软件架构与数据流

软件分为三层，依赖自上而下、单向调用：

• ui（界面层）：只负责显示和交互。
• core（核心层）：Workspace 是"唯一数据源"，所有数据写操作都发生在这里；后台任务用 TaskRunner 跑在线程里，界面不卡。
• algo / data_io（算法与读写层）：纯函数、不依赖界面，可以脱离界面单独测试——这是算法可靠、易维护的关键。

数据流动方向如下：

5.3 测振算法

测振的目标只有一个：算出 ROI 区域每一帧相对第一帧移动了多少像素（dx、dy）。软件内置三种算法，各有各的思路。

5.3.1 LK 光流法（默认，最常用）

一句话：先在 ROI 里找一批"好跟踪的角点"，然后逐帧跟踪这些点往哪儿跑了，取所有点位移的中位数。

比喻：在物体表面贴几个荧光点，用摄像头持续盯着它们怎么移动。

分步解释：

1. 找角点（goodFeaturesToTrack）：角点就是图像里"纹理丰富、拐角明显"的点，容易跟踪。软件在 ROI 里最多找 60 个这样的点。
2. 逐帧跟踪（calcOpticalFlowPyrLK）：用"金字塔光流"——先在缩小图上粗跟踪，再逐层放大细化，又快又稳。每一帧都算出每个点移动了多少。
3. 取中位数：60 个点会给出 60 个位移，取它们的中位数作为整块 ROI 的位移。取中位数（而不是平均数）的好处是：个别点跟踪错了也不会把结果带偏。
4. 输出波形：把所有帧的位移连起来，就是 dx/dy 随时间变化的波形，再做频谱得到振动频率。

• 优点：精度高、抗噪好，适合大多数情况。
• 缺点：ROI 里纹理太少（比如纯色墙面）会找不到足够角点而报错。

5.3.2 NCC 互相关法

一句话：从第一帧 ROI 里扣一块小模板，到每一帧里"滑动搜索"这块模板最像的位置，位置挪了多少就是位移。

比喻：拼图找位置——拿一块模板到每帧画面里比对，看它"挪到了哪儿"。

分步解释：

1. 扣模板：从第一帧的 ROI 中心内缩，取一小块当"参照物"。
2. 逐帧滑动搜索（matchTemplate，归一化互相关系数 TM_CCOEFF_NORMED）：在每一帧的 ROI 范围内逐像素滑动模板，算出每个位置的"相似度"，相似度最高的位置就是模板当前所在位置。
3. 抛物线亚像素插值：搜索只能精确到整像素，但真正的位移往往在两个像素之间。软件在"峰值位置"附近用一条抛物线拟合，求出更精细的亚像素偏移（可到 0.01 像素）。
4. 输出波形：同样得到 dx/dy 波形（并做中值去毛刺）。

• 优点：对弱纹理、长时间稳定的场景更稳。
• 缺点：适合小位移；ROI 太小会报错（至少要 24×24 像素左右）。

5.3.3 相位法测振

一句话：把位移"读作相位差"——用里斯变换算出每帧的局部相位，相对第一帧的相位差就是运动量。

比喻：看水波——不追某一个水分子，而是看"波峰/波谷的相位"移动了多少。

分步解释：

1. 金字塔分解：对 ROI 做拉普拉斯金字塔，取细节最丰富的第 0 层（对微小运动最敏感）。
2. 里斯变换：把这一层变成"幅值 + 相位"（相位带有方向和大小）。
3. 求相位差：每一帧的相位减去第一帧的相位，得到"相位差"——它正比于运动量。
4. 幅值加权 + 标定：幅值大的地方信号更可信，做加权平均；最后用 NCC 的位移结果自动标定比例，把"相位差"换算成"像素"。

• 优点：擅长测亚像素微振动，主频直接精确。
• 缺点：实现最复杂，计算稍重。

5.3.4 三种测振算法怎么选？

提示：ROI 尽量框在有纹理、对比度明显的地方（如边缘、花纹），避免纯色区域，三种算法的精度都会明显更好。

5.4 运动放大算法

运动放大回答另一个问题：怎么让看不见的微小振动"看得见"。软件内置三种算法，都来自 MIT 的经典论文。

5.4.1 线性（欧拉）放大 —— 放大"亮度的波动"

一句话：把"像素亮度随时间的小波动"放大 N 倍，再叠回原画面。

比喻：物体振动时，它边缘的像素会一明一暗地周期性变化（因为边缘一会儿盖住背景、一会儿移开）。把这种明暗变化放大，就"看见"振动了。

分步解释：

1. 金字塔分解：把画面按尺度拆开（粗趋势 + 各层细节）。
2. 时域带通：对每一层沿时间轴做带通，只留下你指定频率段（比如 1~5 Hz 的振动）。
3. 乘放大倍数：把这些过滤出来的微小变化乘以放大倍数 N。
4. 加回原图重建：放大后的波动叠加回原始画面。

核心公式：输出帧 = 原始帧 + 放大倍数 × 带通残差。

• 优点：快、能实时预览，实现简单。
• 缺点：放大倍数大时噪声也会被放大，可能出现"过曝/亮斑"伪影。

5.4.2 里斯金字塔放大 —— 放大"相位"（推荐）

一句话：不放大亮度，而是放大"局部相位"（相位 = 位置的编码）。

比喻：把运动编码成"相位"，放大相位就等于放大位移；因为只动相位、不动亮度，所以更干净、噪声更少。

分步解释：

1. 拉普拉斯金字塔分解：按尺度拆开，逐层处理。
2. 里斯变换：把每一层变成"幅值 + 方向相位"。这里用了正则化里斯变换（-i·ω/√(‖ω‖²+ε²)），避免直流分量处的奇异性。
3. 相位差 + 带通：每帧相对第一帧求相位差（四元数共轭积，带方向两分量），再只留振动频率段。
4. 幅值加权去噪：幅值大的地方权重高，压制噪声。
5. 放大相位 + 重建：相位差 × 放大倍数，再逆变换、金字塔重建回整帧。

• 优点：比线性法支持更大倍率、噪声更少，是实时预览的默认推荐。
• 缺点：比线性法计算稍重，缓存更占内存（见第六章）。

软件亮点：放大中间量（各层相位）是与倍率无关的，所以算完后拖动"放大系数"滑块可以实时预览，不用重新计算。

5.4.3 复可控金字塔（相位法）—— 最高质量，仅导出用

一句话：用更精细的"多尺度 × 多方向"复可控金字塔分解，质量最高，但计算量极大。

比喻：把画面从"多个尺度"和"4 个方向"同时拆解，每个方向单独处理相位，因此对任意方向、任意尺度的运动都处理得最好。

分步解释：

1. 每帧 FFT 到频域：整段视频批量傅里叶变换。
2. 多尺度 × 多方向滤波：复可控金字塔滤波器把画面拆成多个尺度、4 个方向的子带。
3. 相位差 + 带通 + 去噪：每个子带相对首帧求相位差，带通 + 幅值加权去噪。
4. 相位放大（防混叠）：相位差 × 倍率，并裁剪到不超过 π/2 防止混叠伪影。
5. 逆变换重建：各子带拼回画面，去除 padding 得到结果。

• 优点：质量最高、伪影最少、能支持最大倍率。
• 缺点：固定倍率、一次性算完所有放大帧，计算量极大（可能 30 分钟以上），所以只在"导出放大视频"时可选。

5.4.4 三种放大算法对比

算法	速度	质量	实时预览	何时用
线性(欧拉)	快	一般		快速看看、倍率不大
里斯金字塔	中	好		日常默认
复可控金字塔	极慢	最好	（仅导出）	出高质量成品视频

5.5 信号处理细节（进阶）

• 去趋势（detrend）：测振结果（光流/相位累积）会有缓慢漂移，软件用最小二乘拟合一条直线并减掉，避免频谱低频端出现假峰、RMS 被抬高。
• 频谱（spectrum）：单边幅值谱，默认加 Hanning 窗并做幅值修正，窗函数可选 Hanning / Hamming / 矩形。
• 去毛刺（despike）：用 MAD 中值法，把波形里孤立的尖峰替换成中值，抗个别跟踪错误。

六、内存与性能（重点）

试用时最常见的报错，十有八九是"内存超了"。这一章把它彻底讲清楚。

6.1 内存都去哪了？

软件把数据放在内存（RAM）里计算，主要三块：

下图是一个真实例子（1280×720 灰度视频，10 秒 @120fps）：

结论一目了然：放大缓存才是内存大头，里斯金字塔放大缓存 ≈ 原始帧的 27 倍。

为什么这么夸张？因为运动放大要做金字塔分解，把画面拆成多层；每一层还要存多个 float32 缓冲（里斯法存 5 个：亮度、里斯两分量、相位差两分量），而 float32 是 uint8 的 4 倍。几层金字塔加起来，内存就翻了几十倍。

6.2 为什么"读的时候没事，一算放大就报错"？

这是关键，也是很多人误解的地方：

1. 软件在读视频时有一个 2 GB 警告：读入的帧数据如果超过 2 GB，会红字提醒你"建议缩小区域或减少帧数"。
2. 但这个警告只针对"原始帧"，不针对"放大缓存"。
3. 于是典型流程是：读入 1 GB 的帧（没超 2 GB，没有警告）→ 点「计算放大」→ 放大缓存突然要 27 GB → 内存爆了，报 MemoryError / 程序卡死或崩溃。

所以"试用时报错"，绝大多数不是 bug，而是素材尺寸/帧数 × 里斯放大，超出了电脑的内存上限。

6.3 如何避免内存超限（照做即可）

1. 优先读灰度：彩色是灰度的 3 倍内存，而测振和放大只用亮度，多数情况用灰度即可。
2. 缩小 ROI / 裁剪区域：只读你关心的那块区域，帧数据直线下降。
3. 减少帧数：只读需要的那一段（比如振动持续的那几秒），不要整段全读。
4. 放大用完后点「释放缓存」：放大缓存很占内存，不看了就点「释放缓存」，立刻释放。
5. 删除不用的素材：多个素材的内存是叠加的，处理完一个删一个。
6. 内存小的机器优先用「线性」放大：线性缓存 ≈ 8 倍帧数据，比里斯（27 倍）省得多。

6.4 性能小提示

• 测振很快：三种测振都是逐帧轻量运算，通常几秒内完成。
• 实时放大不卡：放大中间量与倍率无关，算完后拖倍率滑块是实时预览。
• 复可控金字塔极慢：只在导出高质量视频时用，可能 30 分钟以上，期间请耐心等待、不要关程序。
• 取消有秒级延迟：单次 FFT/滤波是原子运算，无法中途打断，点"取消"后要等当前这一步算完才停，这是正常的。

七、常见问题与排错

Q1：报错"内存不足 / MemoryError / 程序直接闪退"

这是内存超限（见第六章）。按 6.3 的步骤：读灰度 → 缩小区域 → 减少帧数 → 用线性放大 → 用完释放缓存 → 删旧素材。

Q2：测振报错"ROI 内纹理不足，找不到足够特征点"

LK 光流需要纹理丰富的区域。换到有边缘/花纹的地方框 ROI，或改用「互相关(NCC)」算法（对纹理要求更低）。

Q3：报错"ROI 太小，至少要 24×24 像素"

把 ROI 框大一点即可。

Q4：报错"带通参数不合法：X ~ Y Hz"

带通必须满足 0 < 下限 < 上限 < 采样率的一半（奈奎斯特频率）。例如 120 fps 的视频，采样率 120 Hz，上限必须 < 60 Hz。

Q5：打不开视频文件

确认视频格式受支持（OpenCV 支持 mp4/avi/mjpeg 等常见格式）。换个文件或转码后再试。

Q6：波形乱、漂移、低频有假峰

• 尽量固定相机（三脚架），减少整体晃动。
• ROI 选纹理清晰处。
• 软件已内置"去趋势"和"去毛刺"，如仍乱，可缩小 ROI 或换算法。

Q7：点"取消"后界面像卡住

后台任务是单线程原子运算，取消要等当前这一步算完（秒级延迟），属正常现象，稍等即可。

附录：算法论文出处

延伸阅读：上述论文均可在作者主页或学术搜索引擎免费获取，适合想深入了解原理的读者。

本文档由「像素振动」项目自动生成图文版与 Markdown 版，内容与软件实现一致。