mcpRHEEDanalysics

RHEED（反射高能电子衍射）数据的 MCAP / 视频 查看与 逐像素锁相 分析工具。从 Foxglove CompressedImage 录制或录屏视频中读取帧序列，在 GUI 中框选 ROI、绘制生长周期与强度曲线，并按周期基频做锁相，导出振幅、相位、残差等结果。

功能概览

• 多源输入：.mcap（默认话题 image/output）或常见视频格式（MP4、AVI、MKV、MOV 等）
• ROI 与背景扣除：可框选 RHEED 分析区域、背景 ROI、多个信号 ROI；强度曲线支持「信号 − 背景」
• 生长周期标注：周期文本（如 Ba220s, Dy117s, Cu252s）在曲线上显示彩色区段；可拖动红线标定周期相位、白线标定锁相起点
• 逐像素锁相：相邻帧相位相关配准后，以 f = 1/T 为基频做同频投影，得到振幅、相位、残差
• 结果导出：PNG 伪彩图、lockin.npz、residual_lockin.mcap、meta.json 等（详见下方「锁相输出」）

环境要求

• Windows（提供一键 .bat）或任意支持 Python 3.11 的系统
• uv（推荐，用于创建 .venv 并安装依赖）
• 可选：PyTurboJPEG + libturbojpeg，加速 JPEG 解码（运行 安装依赖_快速JPEG.bat）

快速开始（Windows）

1. 克隆仓库并进入目录：

   git clone https://github.com/JMjimike/mcpRHEEDanalysics.git
   cd mcpRHEEDanalysics
   

2. 双击 安装依赖.bat（安装 Python 3.11 并 uv sync）

3. 双击 启动RHEED查看器.bat

4. 在界面中点击 「打开文件…」，选择 MCAP 或视频文件

大体积原始数据（.mcap、.mp4 等）未纳入 Git 仓库，请在本机自行准备测试文件。

命令行

# 使用 uv（推荐）
uv sync
uv run python mcap_roi_viewer.py

# 指定 MCAP 图像话题（默认 image/output）
uv run python mcap_roi_viewer.py --topic image/output

# rheed_lockin_analysis.py 会转调查看器（参数原样传递）
uv run python rheed_lockin_analysis.py

启动后请在 GUI 中 「打开文件…」 选择数据；命令行中的路径参数仅作兼容提示，不会自动打开文件。

典型工作流

1. 启动查看器 → 打开文件… 加载 MCAP 或视频
2. （可选）框选 RHEED 分析区域（绿色虚线，未框选则整幅图）
3. （可选）框选背景 ROI（青色虚线），用于强度曲线扣除散射底
4. （可选）添加多个 强度 ROI，查看均值随时间变化
5. 在底部编辑 生长周期文本，拖动 红线（周期 t=0）与 白线（锁相起点）
6. 配置锁相参数后点击 「运行逐像素锁相」
7. 在输出目录查看 PNG / NPZ / 残差 MCAP；可在查看器中加载残差序列对比

锁相输出

默认写入用户指定的输出目录（如 lockin_out/），主要包括：

| 文件 | 说明 | |------|------| | intensity.png | 锁相振幅 | | phase.png | HSV 相位（亮度随振幅） | | phase_hue_uniform.png | 仅相位，饱和度/明度全图一致 | | time_delay.png / time_delay_map.png | 相对周期起点的时间延迟伪彩 | | cos_component.png / sin_component.png | 同频 cos/sin 分量 | | residual_lockin.mcap | 残差逐帧 JPEG（Foxglove CompressedImage） | | lockin.npz | 数值结果（体素过大时可能不含完整 residual 数组） | | meta.json | 参数与裁剪区域等元数据 |

锁相与残差计算 仅使用锁相起点（白线）之后的帧；为保持配准连续，解码仍会从首帧读到「起点 + 最大帧数」再截断。

项目结构

mcpRHEEDanalysics/
├── mcap_roi_viewer.py      # PyQt6 主界面：ROI、曲线、锁相触发
├── rheed_lockin_analysis.py # 逐像素锁相核心与批处理 API
├── rheed_viewer_common.py  # 帧加载、周期解析、ROI 控件等共用逻辑
├── viewer_pipeline.py      # 查看器数据管线
├── viewer_validation.py    # 参数校验
├── residual_ops.py         # 残差相关运算
├── tests/                  # 单元测试
├── pyproject.toml          # 依赖（Python 3.11）
├── 安装依赖.bat / 启动RHEED查看器.bat
└── 安装依赖_快速JPEG.bat   # 可选 TurboJPEG

运行测试

uv run python -m unittest discover -s tests -v

依赖摘要

• GUI：PyQt6、pyqtgraph
• 图像 / 视频：OpenCV、NumPy、Matplotlib
• MCAP：mcap、mcap-protobuf-support、foxglove-schemas-protobuf

完整版本见 pyproject.toml 与 uv.lock。

仓库

https://github.com/JMjimike/mcpRHEEDanalysics

许可

未指定开源许可证；使用前请与仓库维护者确认。