search

gyroflow / gyroflow

Video stabilization using gyroscope data
https://gyroflow.xyz
GNU General Public License v3.0
6.22k stars 264 forks source link
fpv gopro gpu gpu-computing gyroscope insta360 rolling-shutter-undistortion rust sony-alpha-cameras stabilization video video-processing

readme

Gyroflow logo Gyroflow logo

Video stabilization using gyroscope data

Homepage • Download • Documentation • Discord • Report bug • Request feature

Downloads Contributors Issues License

About the project

Gyroflow is an application that can stabilize your video by using motion data from a gyroscope and optionally an accelerometer. Modern cameras record that data internally (GoPro, Sony, Insta360 etc), and this application stabilizes the captured footage precisely by using them. It can also use gyro data from an external source (eg. from Betaflight blackbox).

Trailer / results video

Screenshot

Features

Supported gyro sources

Info for cameras not on the list

Installation

Windows

MacOS

Linux

Nightly build

Latest development version is always available here: https://gyroflow.xyz/devbuild/.

Minimum system requirements:

Help and support

For general support and discussion, you can find the developers and other users on the Gyroflow Discord server.

For companies or people wishing to get in touch with the team privately for collaborative purposes: devteam@gyroflow.xyz.

Test data

You can download some clips with gyro data from here: https://drive.google.com/drive/folders/1sbZiLN5-sv_sGul1E_DUOluB5OMHfySh?usp=sharing

Roadmap

See the open issues for a list of proposed features and known issues. There's also a ton of TODO comments throughout the code.

Video editor plugins

Gyroflow OpenFX plugin is available here. OpenFX plugin was tested in DaVinci Resolve

Gyroflow Toolbox allows you to import Gyroflow Projects into a Final Cut Pro effect.

Adobe After Effects plugin is planned, but not ready yet

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributors are greatly appreciated.

Translations

Currently Gyroflow is available in:

Help us translate Gyroflow to your language! We use crowdin to manage translations and you can contribute there: https://crowdin.com/project/gyroflow

I want to contribute but I don't know Rust or QML

Development

Used languages and technologies

Gyroflow is written in Rust, with UI written in QML. It uses Qt, ffmpeg, OpenCV and mdk-sdk external dependencies for the main program, but the core library is written in pure Rust without any external dependencies.

OpenCV usage is kept to a minimum, used only for lens calibration and optical flow (src/core/calibration/mod.rs and src/core/synchronization/opencv.rs). Core algorithms and undistortion don't use OpenCV.

GPU stuff supports DirectX, OpenGL, Metal and Vulkan thanks to Qt RHI and wgpu. For GPU processing we use OpenCL or wgpu, with highly parallelized CPU implementation as a fallback.

Code structure

  1. Entire GUI is in the src/ui directory
  2. src/controller.rs is a bridge between UI and core, it takes all commands from QML and calls functions in core
  3. src/core contains the whole gyroflow engine and doesn't depend on Qt or ffmpeg, and OpenCV is optional
  4. src/rendering contains all FFmpeg related code for rendering final video and processing for synchronization
  5. src/core/gpu contains GPU implementations of the undistortion
  6. src/qt_gpu contains zero-copy GPU undistortion path, using Qt RHI and GLSL compute shader
  7. src/gyroflow.rs is the main entry point
  8. mod.rs or lib.rs in each directory act as a main entry of the module (directory name is the module name and mod.rs is kind of an entry point)

Dev environment

Visual Studio Code with rust-analyzer extension.

For working with QML I recommend to use Qt Creator and load all QML files there, as it has auto-complete and syntax highlighting. The project also supports UI live reload, it's a super quick way of working with the UI. Just change live_reload = true in gyroflow.rs and it should work right away. Now every time you change any QML file, the app should reload it immediately.

Building on Windows

  1. Prerequisites: git, 7z and working powershell. If you never ran powershell scripts before, run set-executionpolicy remotesigned in powershell as admin
  2. Get latest stable Rust language from: https://rustup.rs/
    • Please make sure to check the English language pack option when installing the C++ build tools from Visual Studio Installer
  3. Install Just by running cargo install --force just
  4. Clone the repo: git clone https://github.com/gyroflow/gyroflow.git
  5. Enter the project directory and:
    • Install dependencies: just install-deps
    • Compile and run: just run

Building on MacOS

  1. Prerequisites: git, brew
  2. Get latest stable Rust language from: https://rustup.rs/
  3. Install Just by running cargo install --force just
  4. Clone the repo: git clone https://github.com/gyroflow/gyroflow.git
  5. Enter the project directory and:
    • Install dependencies: just install-deps
    • Compile and run: just run
    • The first time you run it won't work, run just deploy once and then just run will work

Building on Linux

  1. Prerequisites: git, 7z, python, apt package manager (or adjust commands inside scripts if on different distro)
  2. Get latest stable Rust language from: https://rustup.rs/
  3. Install Just by running cargo install --force just
  4. Clone the repo: git clone https://github.com/gyroflow/gyroflow.git
  5. Enter the project directory and:
    • Install dependencies: just install-deps
    • Compile and run: just run

Building for Android

  1. Prerequisites: git, 7z, working powershell, Android SDK and NDK. Android is not well supported yet, but the app can be built and somewhat works. Building is supported only on Windows
  2. Get latest stable Rust language from: https://rustup.rs/
  3. Install Just by running cargo install --force just
  4. Clone the repo: git clone https://github.com/gyroflow/gyroflow.git
  5. Install Android SDK and NDK r23c and update paths in _scripts/android.just
  6. Enter the project directory and:
    • Install dependencies: just android install-deps
    • Compile the apk and install on device: just android deploy

Building for iOS

  1. Prerequisites: git, brew
  2. Get latest stable Rust language from: https://rustup.rs/
  3. Install Just by running cargo install --force just
  4. Clone the repo: git clone https://github.com/gyroflow/gyroflow.git
  5. Enter the project directory and:
    • Install dependencies: just ios install-deps
    • Update Team ID, signing keys and provisioning profiles in _scripts/ios.just
    • Compile and run on device: just ios run

Profiling on Windows

  1. Install and run Visual Studio Community Edition
  2. Compile and run Gyroflow with the profile profile: just profile
  3. In Visual Studio, go to Debug -> Performance Profiler...
    • Under Target, open Change Target and select Running Process..., select the running gyroflow.exe process

Profiling QML

  1. Uncomment config.define("QT_QML_DEBUG", None); in build.rs
  2. Comment cli::run() in gyroflow.rs
  3. Run in debug mode with QML debugger args: cargo run -- "-qmljsdebugger=port:1234,block,services:CanvasFrameRate,EngineControl,DebugMessages"
  4. In Qt Creator go to Analyze -> QML Profiler (Attach to Waiting Application) and enter port 1234

License

Distributed under the GPLv3 License with App Store Exception. See LICENSE for more information.

As additional permission under section 7, you are allowed to distribute gyroflow_core through an app store, even if that store has restrictive terms and conditions that are incompatible with the GPL, provided that the source is also available under the GPL with or without this permission through a channel without those restrictive terms and conditions.

Authors

Notable contributors

Acknowledgements