【Unity × 機械学習】Barracuda をインストール → スタイル変換（学習済みモデル）する方法

どーも、ぐるたか@guru_takaです。

Unity ステーションで、Barracuda という Unity Technologies 製の推論エンジン（ライブラリ）が取り扱われました。

Barracuda を使えば、学習済みモデルを Unity 上で良い感じに使えるとのこと。早速、スタイル変換の学習済みモデルと Barracuda を使い、Unity 上でレナ嬢をスタイル変換しました！以下記事を参考にしています。
参考 Unity Technologies製推論エンジン Barracudaがスゴイという話Qiita

本記事では Barracuda の導入方法や基本的な使い方、また詰まった点を、備忘録としてまとめます。Barracuda × Unity が気になる方の参考になれば幸いです！

実行環境

・Unity：2020.3.2f1
・Visual Effect Graph：10.4.0

スポンサードリンク

Barracuda とは？
ONNX フォーマットの学習済みモデル
Barracuda のインストール
Barracuda でスタイル変換する流れ
全体のコード
ヒエラルキーの中身
最後に
参考リンク

Barracuda とは？

Barracuda とは、Unity 用のニューラルネットワークの軽量な Unity Technologies 製の推論ライブラリです。

Unity Barracuda is a lightweight cross-platform Neural Networks inference library for Unity.
Barracuda can run Neural Networks both on GPU and CPU.
引用：Unity-Technologies/barracuda-release | GitHub

CPU はもちろん、GPU でも動かすことが可能。さらに、パフォーマンスの最適化もされています！

参考 Real-time style transfer in Unity using deep neural networksUnity 公式ブログ

Barracuda は推論ライブラリのため、予め学習済みモデルが必要です。また、モデルのフォーマットは ONNX（Open Neural Network eXchange）になります。ONNX（読み方：オニキス）とは、様々な機械学習用のフレームワークに対応できるフォーマットです。

PyTorch や TensorFlow など様々な機械学習用のフレームワークがありますが、最終的に ONNX でモデルを出力すれば、Barracuda でも使えるわけです。

ONNX フォーマットの学習済みモデル

ONNX の学習済みモデルは、何と GitHub 上に無料で公開されています!そのため、ゼロから学習済みモデルを構築しなくても、有名どころのモデルであれば、無料でダウンロードできます。

参考 onnx/models: A collection of pre-trained, state-of-the-art models in the ONNX formatGitHub

本記事では Fast Neural Style Transfer の Mosaic を拝借して、スタイル変換を行います！

出典：models/vision/style_transfer/fast_neural_style at master · onnx/models

注意

onnx/models リポジトリをクローンしてから、モデルを使用すると、以下のようなエラーが出力されました。

InvalidProtocolBufferException: Protocol message contained a tag with an invalid wire type.

同じような現象を報告している Issue があり、モデルが壊れていることが原因とのこと。再ダウンロードすれば解決すると紹介されています。上述した方法でモデルを再ダウンロードすると、上記のようなエラーは出力されませんでした！

参考 'InvalidProtocolBufferException' occurs when importing Tiny-YOLO v2 assets · Issue #143 · Unity-Technologies/barracuda-releaseGitHub

Barracuda のインストール

最初に Barracuda を Unity のプロジェクトにインストールしましょう。Unity のバージョンが 2020.3 以上の場合は、デフォルトで Package Manager にインストールされていません。

そのため、GitHub のリポジトリ経由で、Package Manager に Barracuda を追加します。

STEP.1

Window → Package Manager

STEP.2

Package Manager に Barracuda を追加

STEP.3

GitHub のリポジトリ URL をコピペ

下図のように Barracuda が追加されれば成功です！

参考 barracuda-release/Installing.md at release/1.4.0 · Unity-Technologies/barracuda-releaseGitHub

Barracuda でスタイル変換する流れ

Barracuda でスタイル変換する流れは以下の通りです。

STEP.1

学習済みモデルの読み込み

STEP.2

推論エンジンの生成

STEP.3

推論の実行

入力の RenderTexture を Tensor に変換する必要あり。

STEP.4

結果の取得

得られた Tensor の結果を、RenderTexture に変換

全体のコード

スタイル変換する C# スクリプトは以下の通りです。コメントで解説しています。以下リポジトリを参考にしました！

参考 highnoRQ/BarracudaTestGitHub

StyleChange.cs

using UnityEngine;
using Unity.Barracuda;  // import 必須

public class StyleChange : MonoBehaviour
{
    //  Barracuda 推論用
    public NNModel modelAsset;
    private Model m_RuntimeModel;
    private IWorker m_worker;

    public RenderTexture inputTexture;
    public RenderTexture outputTexture;

    // Start is called before the first frame update
    void Start()
    {
        // 学習済みモデルの読み込み
        m_RuntimeModel = ModelLoader.Load(modelAsset);

        // GPU 実行
        var workerType = WorkerFactory.Type.Compute;
        // CPU 実行
        // var workerType = WorkerFactory.Type.CSharp;

        // 推論エンジンの生成
        m_worker = WorkerFactory.CreateWorker(workerType, m_RuntimeModel);
    }

    private void Update()
    {
        // RenderTexture → Tensor に変換
        Tensor input = new Tensor(inputTexture);
        // 推論の実行
        m_worker.Execute(input);
        // 出力結果を取得
        Tensor output = m_worker.PeekOutput();
        // 出力結果（Tensor）を RenderTexture に保存
        // バッチサイズは 1 なので、第 2 引数は 0
        // チャンネル数は 3 なので、第 ３ 引数は 0 or 1 or 2
        // 0~255 → 0～1 にスケーリングするため、第 ４ 引数 は 1/255f、
        // 第 5 引数 のバイアスで、色味調整が可能。今回は 0 とする
        output.ToRenderTexture(outputTexture, 0, 0, 1 / 255f, 0, null);
        // メモリリークを回避のため、各ステップごとに Tensor は破棄
        // ※ PeekOutput で得られた Tensor の破棄は除く
        input.Dispose();
    }

    private void OnDestroy()
    {
        //終了時に 推論エンジン は破棄
        m_worker.Dispose();
    }

}

ポイントは以下３つです！

最初に、学習済みモデルの読み込み → GPU or CPU の選択 → 推論エンジンの生成を行う
Tensor のインスタンス化と、ToRenderTexture メソッドで簡単に Tensor ↔ RenderTexture への変換が可能！
メモリリークを防ぐため、Tensor と推論エンジンは破棄する必要あり（PeekOutput メソッドで得られた Tensor は除く）

Unity の公式にも基本的な流れが解説されているので、併せてチェックしてみてください！

参考 Memory management | Barracuda | 1.4.0-previewUnity 公式参考 Getting started with Barracuda | Barracuda | 1.4.0-previewUnity 公式

MEMO

学習済みモデルによって、前処理が必要なケースがあります。使用する学習済みモデルで必要な前処理を予め確認しておきましょう！