Video stabilization using gyroscope data
Homepage •
Download •
Documentation •
Discord •
Report bug •
Request feature
## 关于本项目
Gyroflow 是一款通过使用陀螺仪（以及可选的加速度计）的运动数据来稳定视频的应用程序。现代相机在内部记录这些数据（GoPro、Sony、Insta360 等），本应用程序通过利用这些数据，能够精准地对拍摄的视频画面进行增稳。它也可以使用来自外部源的陀螺仪数据（例如来自 Betaflight 黑盒日志）。
[预告片 / 效果视频](https://www.youtube.com/watch?v=QR-SINyvNyI)
## 功能
- 实时预览、参数调整及所有计算
- GPU 处理与渲染，所有算法完全多线程化
- 果冻效应（Rolling shutter）校正
- [视频编辑器插件](https://github.com/gyroflow/gyroflow-plugins)（Adobe Premiere/Ae、DaVinci Resolve、Final Cut Pro 等），允许你直接在视频编辑器中应用增稳效果而无需重新编码
- 支持完整的 Sony 元数据（录制参数、自动镜头、支持 IBIS、OIS、EIS - 你可以在相机中开启 IBIS 并同时在其基础上应用 Gyroflow）
- 支持已增稳的 GoPro 视频（在开启 Hypersmooth 的情况下拍摄）（Hero 8 及更高版本）
- 支持并渲染 10-bit 视频（常规编解码器最高支持 16-bit 4:4:4:4，OpenEXR 最高支持 32-bit 浮点 - 直接在 YUV 数据上工作以保持最高画质）
- 可自定义的镜头畸变校正强度
- 渲染队列
- 关键帧
- 能够创建自定义设置预设
- 包含陀螺仪数据的可视化图表（显示陀螺仪、加速度计、磁力计和四元数，包括平滑后的四元数）
- 支持水下镜头（校正水下画面畸变）
- 现代化且自适应的用户界面，包含深色和浅色主题
- 自适应缩放（动态裁剪）
- 缩放限制
- 支持图像序列（PNG、OpenEXR、CinemaDNG）
- 基于 [telemetry-parser](https://github.com/AdrianEddy/telemetry-parser) - 开箱即支持所有陀螺仪数据源
- 陀螺仪低通滤波器、任意旋转（俯仰、横滚、偏航角）及方向调整
- 用于姿态确定的多种陀螺仪积分方法
- 多种视频姿态平滑算法，包括地平线校平及按轴向调节平滑度。
- 跨平台 - 可在 Windows/Linux/Mac/Android/iOS 上运行
- 多种用户界面语言
- 支持可变帧率和高帧率视频 - 所有计算均基于时间戳进行
- H.264/AVC、H.265/HEVC、ProRes、DNxHD、CineForm、PNG 和 OpenEXR 输出，其中 H.264 和 H.265 完全由 GPU 加速（在 Apple Silicon 上 ProRes 同样获得加速）
- 简单的镜头标定流程
- 完全零拷贝的 GPU 预览渲染
- 核心引擎是一个没有外部依赖的独立库（无需 Qt、ffmpeg 或 OpenCV），可用于创建 OpenFX 和 Adobe 插件（已在待办事项列表中）
- 镜头配置文件数据库的自动更新
- 内置 GoPro HERO 6-13；Sony；DJI；Insta360 运动相机；RunCam：Thumb 系列，5 Orange 的官方镜头配置文件
- 可在应用程序内轻松管理视频编辑器插件
- 能够添加额外的 3D 旋转（适用于竖屏视频的构图调整）
## 支持的陀螺仪数据源
- [x] GoPro (HERO 5 及更高版本)
- [x] Sony (a1, a7c, a7r V, a7 IV, a7s III, a9 II, a9 III, FX3, FX6, FX9, RX0 II, RX100 VII, ZV1, ZV-E10, ZV-E10 II, ZV-E1, a6700)
- [x] Insta360 (OneR, OneRS, SMO 4k, Go, GO2, GO3, GO3S, GOUltra, Caddx Peanut, Ace, Ace Pro)
- [x] DJI (Avata, Avata 2, O3/O4 Air Unit, Action 2/4/5/6/Nano, Neo, Neo2)
- [x] XTRA (Edge, Edge Pro)
- [x] Blackmagic RAW (*.braw)
- [x] RED RAW (V-Raptor, KOMODO) (*.r3d)
- [x] Canon (C50, C80, C400, R6 Mk3, R5 Mk2) (*.mp4, *.mov, *.mxf)
- [x] Freefly (Ember)
- [x] Betaflight 黑盒 (*.bfl, *.bbl, *.csv)
- [x] ArduPilot 日志 (*.bin, *.log)
- [x] Gyroflow [.gcsv 日志](https://docs.gyroflow.xyz/app/technical-details/gcsv-format)
- [x] iOS 应用: [`Sensor Logger`](https://apps.apple.com/us/app/sensor-logger/id1531582925), [`G-Field Recorder`](https://apps.apple.com/at/app/g-field-recorder/id1154585693), [`Gyro`](https://apps.apple.com/us/app/gyro-record-device-motion-data/id1161532981)
- [x] Android 应用: [`Sensor Logger`](https://play.google.com/store/apps/details?id=com.kelvin.sensorapp&hl=de_AT&gl=US), [`Sensor Record`](https://play.google.com/store/apps/details?id=de.martingolpashin.sensor_record), [`OpenCamera Sensors`](https://github.com/MobileRoboticsSkoltech/OpenCamera-Sensors), [`MotionCam Pro`](https://play.google.com/store/apps/details?id=com.motioncam.pro)
- [x] Runcam CSV (Runcam 5 Orange, iFlight GOCam GR, Runcam Thumb, Mobius Maxi 4K)
- [x] Hawkeye Firefly X Lite CSV
- [x] XTU (S2Pro, S3Pro)
- [x] WitMotion (WT901SDCL binary 和 *.txt)
- [x] Vuze (VuzeXR)
- [x] KanDao (Obisidian Pro, Qoocam EGO)
- [x] [CAMM 格式](https://developers.google.com/streetview/publish/camm-spec)
### 不在列表中的相机信息
- 对于内置陀螺仪的相机，请联系我们，我们将实现对相机的支持。有关陀螺仪记录过程的信息，请参阅[文档](https://docs.gyroflow.xyz)。
- 对于没有内置陀螺仪的相机，你可以使用任何其他记录陀螺仪数据的设备。它可以是手机、运动相机，或者像 Betaflight FC、[flowshutter](https://github.com/gyroflow/flowshutter)、[esp-gyrologger](https://github.com/VladimirP1/esp-gyrologger)（例如在 [AtomS3](https://shop.m5stack.com/products/atoms3-dev-kit-w-0-85-inch-screen) 上）这样的外部设备。你只需要将它安装在你的主相机上即可。
## 安装
### Windows - [Microsoft Store](https://apps.microsoft.com/store/detail/gyroflow/9NZG7T0JCG9H) 或：
- 从 [Releases](https://github.com/gyroflow/gyroflow/releases) 页面下载 `Gyroflow-windows64.zip`，将文件解压到任意位置并运行 `Gyroflow.exe`
- 如果显示关于 `VCRUNTIME140.dll` 或 `0xc0000142` 的错误，请[安装 VC redist](https://aka.ms/vs/17/release/vc_redist.x64.exe)
### MacOS - [App Store](https://apps.apple.com/us/app/gyroflow/id6447994244) 或：
- 从 [Releases](https://github.com/gyroflow/gyroflow/releases) 页面下载 `Gyroflow-mac-universal.dmg`，运行下载的文件，并将 `Gyroflow` 应用拖放到“应用程序”文件夹（或任何你想要的位置，如桌面）
- 你也可以使用 brew 安装：`brew install gyroflow`。要升级 Gyroflow，请运行 `brew update`，然后运行 `brew upgrade gyroflow`
### Linux
- 从 [Releases](https://github.com/gyroflow/gyroflow/releases) 页面下载 `Gyroflow-linux64.tar.gz`，将文件解压到任意位置并在终端中运行 `./Gyroflow`。
- 如果上述方法无效，你可以尝试 `Gyroflow-linux64.AppImage`，但首选 .tar.gz 版本。
- 确保你安装了最新的显卡驱动程序
- 可能需要安装的软件包：`sudo apt install libva2 libvdpau1 libasound2 libxkbcommon0 libpulse0 libc++-dev libvulkan1`
- 特定 GPU 的软件包：
- NVIDIA: `nvidia-opencl-icd nvidia-vaapi-driver nvidia-vdpau-driver nvidia-egl-icd nvidia-vulkan-icd libnvcuvid1 libnvidia-encode1`
- Intel: `intel-media-va-driver i965-va-driver beignet-opencl-icd intel-opencl-icd`
- AMD: `mesa-vdpau-drivers mesa-va-drivers mesa-opencl-icd libegl-mesa0 mesa-vulkan-drivers`
### Android
- [Google Play](https://play.google.com/store/apps/details?id=xyz.gyroflow)
### iOS
- [App Store](https://apps.apple.com/us/app/gyroflow/id6447994244)
### 每日构建版
最新开发版本始终可在此处获取：https://gyroflow.xyz/devbuild/
## 最低系统要求：
- Windows 10 64 位（1809 或更高版本）
- 如果你安装的是 Windows "N" 版本，请转到 `设置` -> `应用` -> `可选功能` -> `添加功能` -> 启用 `Media Feature Pack`
- macOS 10.15 或更高版本（原生支持 Intel 和 Apple Silicon）
- Linux:
- `.tar.gz` 包（推荐）：Debian 10+、Ubuntu 18.10+、CentOS 8.2+、openSUSE 15.3+。其他发行版需要 glibc 2.28+（使用 `ldd --version` 进行检查）
- `.AppImage` 应该可以在所有地方运行
- Android 6+
- iOS 14+
## 帮助与支持
如需一般支持和讨论，你可以在 [Gyroflow Discord 服务器](https://discord.gg/YaUtNpWTUh) 上找到开发人员和其他用户。
对于希望以私人方式联系团队进行合作的公司或个人：devteam@gyroflow.xyz。
## 测试数据
你可以从这里下载一些带有陀螺仪数据的剪辑片段：https://drive.google.com/drive/folders/1sbZiLN5-sv_sGul1E_DUOluB5OMHfySh?usp=sharing
## 路线图
请查看 [未解决的问题](https://github.com/gyroflow/gyroflow/issues) 以获取建议功能和已知问题的列表。
在整个代码中还有大量的 TODO 注释。
### 视频编辑器插件
Gyroflow OpenFX 插件可在[此处](https://github.com/gyroflow/gyroflow-plugins)获取。OpenFX 插件已在 DaVinci Resolve 中经过测试。
Adobe Premiere 和 After Effects 插件可在[此处](https://github.com/gyroflow/gyroflow-plugins)获取。
Final Cut Pro 插件以 [Gyroflow Toolbox](https://gyroflowtoolbox.io) 的形式提供。
## 贡献
开源社区之所以能成为一个令人惊叹的学习、启发和创造之地，正是因为有了各种贡献。我们对任何贡献者都**表示衷心的感谢**。
* 如果你对添加或删除功能有建议，请随时[提出问题](https://github.com/gyroflow/gyroflow/issues/new)进行讨论。
* 如果你想实现某项功能，可以复刻该项目，编写你的代码并提交拉取请求。
### 翻译
目前 *Gyroflow* 提供以下语言版本：
* **英语**（基础语言）
* **简体中文**（由 [DusKing1](https://github.com/DusKing1) 翻译）
* **繁体中文**（由 [DusKing1](https://github.com/DusKing1) 翻译）
* **捷克语**（由 Jakub Ešpandr, VitroidFPV, davidazarian, Michael Kmoch 翻译）
* **丹麦语**（由 [ElvinC](https://github.com/ElvinC) 翻译）
* **芬兰语**（由 Jesse Julkunen 翻译）
* **法语**（由 KennyDorion 翻译）
* **加利西亚语**（由 Martín Costas 翻译）
* **德语**（由 [Grommi](https://github.com/Gro2mi) 和 [Nicecrash](https://github.com/B-nutze-RR) 翻译）
* **希腊语**（由 [Stamatis Galiatsatos](https://github.com/Logicenios) 翻译）
* **印度尼西亚语**（由 Aloysius Puspandono 翻译）
* **意大利语**（由 Rosario Casciello 翻译）
* **日语**（由 井上康 翻译）
* **韩语**（由 EP45 翻译）
* **挪威语**（由 [MiniGod](https://github.com/MiniGod) 和 [alexagv](https://github.com/alexagv) 翻译）
* **波兰语**（由 [AdrianEddy](https://github.com/AdrianEddy) 翻译）
* **巴西葡萄牙语**（由 KallelGaNewk 翻译）
* **葡萄牙语**（由 Ricardo Pimentel 翻译）
* **俄语**（由 Андрей Гурьянов, redstar01 和 lukdut 翻译）
* **斯洛伐克语**（由 Radovan Leitman 和 Eduard Petrovsky 翻译）
* **西班牙语**（由 Pelado-Mat翻译）
* **土耳其语**（由 [Metin Oktay Yılmaz](https://github.com/mettinoktay) 翻译）
* **乌克兰语**（由 Artem Alexandrov 翻译）
帮助我们翻译 *Gyroflow* 为你的语言吧！我们使用 *crowdin* 来管理翻译，你可以在此处贡献翻译：https://crowdin.com/project/gyroflow
#### 我想贡献但我不会 Rust 或 QML
* 《Rust 程序设计语言》是入门 Rust 的绝佳途径：https://doc.rust-lang.org/book/
* 其他有用的 Rust 资源：https://quickref.me/rust 和 https://cheats.rs/
* 关于 UI 内容，The Qt Company 出品了一本不错的 QML 书籍：https://www.qt.io/product/qt6/qml-book
## 开发
### 使用的语言和技术
*Gyroflow* 使用 [Rust](https://www.rust-lang.org/) 编写，UI 使用 [QML](https://doc.qt.io/qt-6/qmlfirststeps.html) 编写。主程序使用了 *Qt*、*ffmpeg*、*OpenCV* 和 *mdk-sdk* 外部依赖，但核心库使用纯 Rust 编写，没有任何外部依赖。
OpenCV 的使用被保持在最低限度，仅用于镜头标定和光流法（`src/core/calibration/mod.rs` 和 `src/core/synchronization/opencv.rs`）。核心算法和畸变校正不使用 OpenCV。
借助 *Qt RHI* 和 *wgpu*，GPU 相关内容支持 *DirectX*、*OpenGL*、*Metal* 和 *Vulkan*。
对于 GPU 处理，我们使用 *OpenCL* 或 *wgpu*，并以高度并行化的 CPU 实现作为后备方案。
Gyroflow 二进制文件链接到 mdk-sdk，该 SDK 是闭源的，且未在 GNU GPL 下授权。
Gyroflow 在 GPLv3 下授权，并带有允许与 mdk-sdk 链接的附加许可。mdk-sdk 在其自身的许可证下分发。
### 代码结构
1. 整个 GUI 位于 `src/ui` 目录中
2. `src/controller.rs` 是 UI 和核心之间的桥梁，它接收来自 QML 的所有命令并调用核心中的函数
3. `src/core` 包含整个 gyroflow 引擎，并且不依赖于 *Qt* 或 *ffmpeg*。*OpenCV* 是可选的
4. `src/rendering` 包含用于渲染最终视频和同步处理的所有 FFmpeg 相关代码
5. `src/core/gpu` 包含畸变校正的 GPU 实现
6. `src/qt_gpu` 包含使用 Qt RHI 和 GLSL 计算着色器的零拷贝 GPU 畸变校正路径
7. `src/gyroflow.rs` 是主入口点
8. 每个目录中的 `mod.rs` 或 `lib.rs` 充当该模块的主入口（目录名是模块名，而 `mod.rs` 相当于入口点）
### 开发环境
带有 `rust-analyzer` 扩展的 `Visual Studio Code`。
为了处理 QML，我建议使用 Qt Creator 并在那里加载所有 QML 文件，因为它具有自动补全和语法高亮功能。
该项目还支持 UI 热重载，这是一种处理 UI 的非常快捷的方式。只需在 `gyroflow.rs` 中更改 `live_reload = true`，它就应该立即生效。现在，每当你修改任何 QML 文件时，应用程序都会立即重新加载它。
### 在 Windows 上构建
0. 前置条件：`git`、`7z` 和可正常运行的 `powershell`。如果你之前从未运行过 powershell 脚本，请以管理员身份在 powershell 中运行 `set-executionpolicy remotesigned`
1. 从以下网址获取最新稳定版的 Rust 语言：https://rustup.rs/
- 请务必在从 Visual Studio Installer 安装 C++ 生成工具时勾选英语语言包选项
2. 通过运行 `cargo install --force just` 来安装 `Just`
3. 克隆仓库：`git clone https://github.com/gyroflow/gyroflow.git`
4. 进入项目目录并执行：
- 安装依赖项：`just install-deps`
- 编译并运行：`just run`
### 在 MacOS 上构建
0. 前置条件：`git`、`brew`
1. 从以下网址获取最新稳定版的 Rust 语言：https://rustup.rs/
2. 通过运行 `cargo install --force just` 来安装 `Just`
3. 克隆仓库：`git clone https://github.com/gyroflow/gyroflow.git`
4. 进入项目目录并执行：
- 安装依赖项：`just install-deps`
- 编译并运行：`just run`
- 首次运行将无法正常工作，请先运行一次 `just deploy`，之后 `just run` 即可正常工作
### 在 Linux 上构建
0. 前置条件：`git`、`7z`、`python`、`apt` 包管理器（如果使用不同的发行版，请调整脚本内的命令）
1. 从以下网址获取最新稳定版的 Rust 语言：https://rustup.rs/
2. 通过运行 `cargo install --force just` 来安装 `Just`
3. 克隆仓库：`git clone https://github.com/gyroflow/gyroflow.git`
4. 进入项目目录并执行：
- 安装依赖项：`just install-deps`
- 编译并运行：`just run`
### 为 Android 构建
0. 前置条件：`git`、`7z`、可正常运行的 `powershell`、Android SDK 和 NDK。仅支持在 Windows 上进行构建
1. 从以下网址获取最新稳定版的 Rust 语言：https://rustup.rs/
2. 通过运行 `cargo install --force just` 来安装 `Just`
3. 克隆仓库：`git clone https://github.com/gyroflow/gyroflow.git`
4. 安装 Android SDK 和 NDK r23c，并更新 `_scripts/android.just` 中的路径
5. 进入项目目录并执行：
- 安装依赖项：`just android install-deps`
- 编译 apk 并安装到设备：`just android deploy`
### 为 iOS 构建
0. 前置条件：`git`、`brew`
1. 从以下网址获取最新稳定版的 Rust 语言：https://rustup.rs/
2. 通过运行 `cargo install --force just` 来安装 `Just`
3. 克隆仓库：`git clone https://github.com/gyroflow/gyroflow.git`
4. 进入项目目录并执行：
- 安装依赖项：`just ios install-deps`
- 更新 `_scripts/ios.just` 中的 Team ID、签名密钥和预置描述文件
- 编译并在设备上运行：`just ios run`
### 在 Windows 上进行性能分析
1. 安装并运行 `Visual Studio Community Edition`
2. 使用 `profile` 配置编译并运行 Gyroflow：`just profile`
3. 在 Visual Studio 中，转到 `调试 -> 性能探查器...`
- 在 `目标` 下，打开 `更改目标` 并选择 `运行中的进程...`，选择正在运行的 `gyroflow.exe` 进程
### 分析 QML 性能
1. 在 `build.rs` 中取消注释 `config.define("QT_QML_DEBUG", None);`
2. 在 `gyroflow.rs` 中注释掉 `cli::run()`
3. 使用 QML 调试器参数在调试模式下运行：`cargo run -- "-qmljsdebugger=port:1234,block,services:CanvasFrameRate,EngineControl,DebugMessages"`
4. 在 Qt Creator 中，转到 `分析` -> `QML Profiler (附加到等待的应用程序)` 并输入端口 1234
## 许可证
在带有 App Store 例外的 GPLv3 许可证下分发。有关更多信息，请参见 [LICENSE](https://github.com/gyroflow/gyroflow/blob/main/LICENSE)。
作为第 7 节下的附加许可，允许你通过应用商店分发 [`gyroflow_core`](https://github.com/gyroflow/gyroflow/tree/master/src/core)，即使该应用商店具有与 GPL 不兼容的限制性条款和条件，前提是源代码也可以在不包含这些限制性条款和条件的渠道下，带有或不带有此许可的 GPL 许可证下获取。
Gyroflow 二进制文件链接到 mdk-sdk，该 SDK 是闭源的，且未在 GNU GPL 下授权。
授予了允许与 mdk-sdk 链接的附加许可。mdk-sdk 在其自身的许可证下分发。
## 作者
* [AdrianEddy](https://github.com/AdrianEddy/) - *Rust 实现（本仓库中的代码）的作者，UI、GPU 处理、果冻效应校正、高级渲染功能以及 Adobe 插件的作者*
* [Elvin Chen](https://github.com/ElvinC/) - *首个 Python 版本的作者，为使这一切成为可能奠定了基础*
### 杰出贡献者
* [Maik Menz](https://github.com/mycosd/) - *在修复和改进方面对 Gyroflow 的所有领域做出了贡献*
* [Aphobius](https://github.com/Aphobius/) - *速度阻尼平滑算法的作者*
* [Marc Roeschlin](https://github.com/marcroe/) - *自适应缩放算法的作者*
* [Ilya Epifanov](https://github.com/ilya-epifanov/) - *OpenFX 插件的作者*
* [Vladimir Pinchuk](https://github.com/VladimirP1/) - *鲁棒的陀螺仪到视频同步算法以及 Sony 镜头/IBIS 数据的作者*
* [Chris Hocking](https://github.com/latenitefilms) - *[Gyroflow Toolbox](https://gyroflowtoolbox.io) Final Cut Pro 插件的作者*
## 致谢
* [Gyroflow Python 版本（旧版代码）](https://github.com/ElvinC/gyroflow)
* [telemetry-parser](https://github.com/AdrianEddy/telemetry-parser)