360° 视频稳定

🌍 中文 | English

本仓库包含以下论文代码实现：

• 360° video stabilization (Kopf, 2016) 的代码复现
• 基于双圆柱投影与变形旋转网格的全景视频稳定(2026,未发布)，基于Kopf方法的框架上进行一些小改进

Warning

仓库仍在整理中。本仓库可能包含

• 大量 vibe coding （AI）产物
• camelCase、snake_case 混用
• 不太专业的实现

敬请谅解qwq

项目结构

├── config/
│   └── config.yml      # 运行配置文件
├── experiments/        # 实验数据和可视化脚本
│   ├── results/
│   └── *.py
├── src/                # 源代码目录
│   ├── core/           # 核心模块
│   │   ├── common.cpp    # 公共函数
│   │   ├── visualize_tracks.cpp    # 光流可视化工具
│   │   ├── cubemap_tracker.cpp    # 光流跟踪器
│   │   ├── deformed_optimizer.cpp # 变形优化器
│   │   ├── inner_frame_optimizer.cpp # 内帧优化器
│   │   └── pose_estimator.cpp     # 姿态估计器
│   ├── main.cpp        # 光流+位姿估计
│   ├── test_inner_frame_optimizer.cpp # 内帧优化
│   ├── test_deformed_optimizer.cpp # 变形优化
│   └── test_*.cpp # 其他辅助测试模块
├── .gitignore          # Git 忽略文件
├── CMakeLists.txt      # CMake 配置文件
└── README.MD           # 项目说明文档

核心功能模块

1. 光流跟踪器 (CubemapTracker)：负责将全景视频转换为立方体贴图或双圆柱投影，并进行特征点检测和光流跟踪。
2. 姿态估计器 (PoseEstimator)：基于跟踪的特征点估计相机姿态。
3. 内帧优化器 (InnerFrameOptimizer)：对关键帧之间的旋转进行平滑优化。
4. 变形优化器 (DeformedOptimizer)：使用变形旋转模型消除残余抖动，进一步提高视频稳定性。

使用方法

环境配置

• 项目使用 C++ 编写，本项目开发时使用 MSyS2 + Vscode 在 Windows 10 上进行开发
• 需安装以下依赖库：

  注：若使用Msys2 可使用 pacman 指令安装OpenCV、Ceres

  • OpenCV4 (用于图像处理和视频操作)
  • OpenGV (用于相机姿态估计)
  • Eigen3 (用于线性代数运算)
  • Ceres (用于优化问题求解)
• 确保安装FFmpeg工具:
  • 代码中会使用 FFmpeg 指令处理视频格式转换
  • 请修改 config/config.yml 中的 ffmpeg_path 为你的FFmpeg可执行文件路径

构建

• 使用 CMake 构建项目，请自行修改 CMakeLists.txt 中的配置

运行

1. 配置参数

• 在 config/config.yml 配置运行参数，主要配置项包括：
  • preset：预设配置，可选值：
    • 0: 自定义配置
    • 1：原版 Kopf 方法
    • 2：双圆柱投影 + 变形旋转网格方法
  • track_projection：跟踪投影方式，0 为立方体贴图，1 为圆柱投影
  • 更多配置选项见 config/config.yml 的注释

2. 光流跟踪 + 位姿估计

• CMD控制台运行：

  :: windows 可以运行这个防止中文乱码
  chcp 65001
  
  main.exe ./input/example.mp4

  程序会做下面的事情：
  1. 首先会将输入的ERP (Equirectangular Projection) 视频转为立方体贴图（或双圆柱投影），保存到输入视频目录下
  2. 弹出窗口，可调整初始方向（如果初始镜头歪斜），不调整则按Esc继续
  3. 开始光流跟踪和位姿估计
  4. 完成后，输入 y 生成光流视频；输入 n 不输出视频，直接弹出窗口查看
  5. 光流、位姿结果保存到 ./output/tracks/ 目录

3. 内帧纯旋转优化

• 控制台运行：

  :: 后面的 t 可选，表示生成稳定视频时，是否加回原始方向（默认消除所有方向）
  test_inner_frame_optimizer.exe ./input/example.mp4 t

  执行流程：
  1. 读取之前的光流和位姿信息
  2. 对视频进行内部帧旋转优化
  3. 可根据提示保存纯旋转优化视频

4. 残余抖动消除

• 控制台运行：

  :: 后面的 t 可选，表示生成稳定视频时，是否加回原始方向（默认消除所有方向）
  test_deformed_optimizer.exe ./input/example.mp4 t

  执行流程：
  1. 读取之前的优化结果
  2. 应用变形优化器消除残余抖动
  3. 输出最终稳定后的视频

配置说明

config/config.yml 文件包含以下主要配置项：

配置项	描述	默认值
ffmpeg_path	FFmpeg 可执行文件路径	"C:/msys64/ucrt64/bin/ffmpeg.exe"
track_projection	跟踪投影方式 (0: 立方体, 1: 双圆柱)	0
face_size	立方体贴图每个面的大小	256
cylinder_height	双圆柱投影，单个投影面高度	500
preset	预设配置 0 - 不适用预设 1 - 使用Kopf预设 2 - 双圆柱投影 + 变形旋转网格预设	2
keyframe_time_sec	强制关键帧间隔（秒）	1
min_keyframe_gap	最小关键帧间隔	2
use_grid	是否使用密集方形网格	1
grid_cols/grid_rows	网格行列数	8/6
...	更多配置详见config.yml注释

参考文献

1. 360° video stabilization (Kopf, 2016)
2. 基于双圆柱投影与变形旋转网格的全景视频稳定

许可证

本项目主体采用 MIT 许可证协议，仅部分文件使用其他许可协议，详情参见：

• LICENSE
• src/core/opengv_mod/FiveptKneipSacProblem.hpp