Mixed Reality Toolkit V2.2.0 のリリースノートを整理した

# 先にARFoundation対応を紹介したかったので一部フライングしました

先日「[Mixed Reality Toolkit V2.2.0]」の中でもARFaoundation対応が試験的に入っていたのでそこを中心にQiitaで解説記事を書きました。

* [Mixed Reality Toolkit V2.2.0 の新しいCamera SystemおよびiOS/Android対応について]

今回は「HoloLens Advent Calendar 2019 」のトリとしてV2.2.0の残りの新機能などなどを紹介したいと思います。基本的には[ReleaseNote](https://microsoft.github.io/MixedRealityToolkit-Unity/version/releases/2.2.0/Documentation/ReleaseNotes.html)をベースにして整理しています。
新機能や既知の問題が多いのでそれぞれはかなり簡単な解説になります。

1. 環境/デバイス
2. V2.1.0からのアップグレード
3. 新機能  
 1. Camera Settings Providers
 2. Cursor resizing
 3. Directional Indicator Solver
 4. Fingertip cursor translation and alignment
 5. GridObjectCollection supports content alignment
 6. Fixing LayoutDirection in GridObjectCollection
 7. InteractableToggleCollection improvements
 8. Mixed Reality Capture setting (Experimental)
 9. Mobile AR (Android and iOS) support (Experimental)
 10. MSBuild for Unity
 11. New audio clips for HoloLens 2 style bounding boxes
 12. PressableButtonHoloLens2 icon lift on focus
 13. Pulse shaders for spatial mesh and hand mesh (Experimental)
 14. Hand mesh
 15. Scrolling Object Collection (Experimental)
 16. Search MRTK profiles for keywords
 17. Surface Magnetism Solver and Hand Ray example scene
 18. Support for hand and eye tracking remoting for Microsoft HoloLens 2
 19. Windows Mixed Reality Depth Reprojection Settings
4. 既知の問題
 1. Long paths
 2. Runtime profile swapping
 3. Unity 2018: .NET Backend and AR Foundation
 4. Hang when using Holographic Remoting
 5. Failed to get IHolographicCameraRenderingParameters from main camera for updating rendering parameter
 6. Assembly has reference to non-existent assembly 'Unity.XR.ARFoundation'
 7. Mixed Reality Capture settings (Experimental)
 8. MRTK Configurator dialog
 9. The type or namespace name 'TrackedPoseDriver' could not be found

以上をトピック的に整理。

## 1.環境/デバイス
### 1.1.対応デバイス

V2.2.0の対応デバイスは以下の通り。

* Microsoft HoloLens 2
* Microsoft HoloLens (1st gen)
* Windows Mixed Reality Immersive headsets
* OpenVR
* (Experimental) Mobile AR
 * Android
 * iOS
The following software is required.

### 1.2.開発環境

開発環境は以下の通り

* Microsoft Visual Studio (2017 or 2019) Community Edition or higher
* Windows 10 SDK 18362 or later (installed by the Visual Studio Installer)
* Unity 2018.4 LTS, 2019.1 or 2019.2
* NuGet for Unity 2.0.0 or newer(任意)

## 2.V2.1.0からのアップグレード方法

基本的には V2.1.0のモジュールを丸ごと入替える。ちなみにAPIとして変更になった個所は以下の2カ所。

### V2.1.0 ⇒ V2.2.0との差異
#### IMixedRealityBoundarySystem.Contains
引数の[boundaryType]の列挙体をUnity定義からMRTKで定義したものに変更（MRTK標準で今後の対応をできるように）

#### MixedRealityServiceProfileAttribute
MRTKで利用するProfileの挙動が変更。

* V2.1.0以前は1プロファイル = 1サービス
* V2.2.0からは1プロファイル = 多サービスが可能。また対象外サービスの定義も可能

### 移行手順

unitypakageとNugetでの対応方法。
スムーズに移行したかったら手順は守ってねということらしい。

#### unitypackage使ったパターン

1. アップグレードしたいプロジェクトをUnityで開いていたら閉じる
2. MixedRealityToolkitに関連するフォルダをエクスプローラ上で削除する  
注：追加したAsset等は、念のためバックアップ取っておく  
<font color=red><B>とても重要！！！MixedRealityToolkit.Generatedは絶対消しちゃダメ</B></font>  
 * MixedRealityToolkit
 * MixedRealityToolkit.Examples
 * MixedRealityToolkit.Extensions
 * MixedRealityToolkit.Providers
 * MixedRealityToolkit.SDK
 * MixedRealityToolkit.Services
 * MixedRealityToolkit.Tools
3. プロジェクトフォルダ内のLibraryフォルダを削除
4. Unityで再度プロジェクトを開く
5. 新しいMRTK V2.2.0のunity packagesを<B>以下の手順</B>でインポートする。  
補足：追加したAsset等は再インポートが必要になる場合がある  
 * Foundation - Import this package first
 * (Optional) Tools
 * (Optional) Extensions
 * (Optional) Examples
6. Unityを閉じてプロジェクトのLibraryフォルダを削除する. （AssetのデータベースやCustomProfileを強制的に読込ませるために実施）
7. Unityを開いて、プロジェクトの内の各シーンを開き以下の修正を行う。  
 * [hierarchy]に[MixedRealityToolkit]と[MixedRealityPlayspace]があれば削除する
 * メニューから[MixedRealityToolkit] > [Add to Scene and Configure]を選択(コンポーネントの再構成)
 * メニューから[MixedRealityToolkit] > [Utilities] > [Update] > [Controller Mapping Profiles]を選択 (一度だけ実行)  
この操作を行うことで、V2.2.0で修正されたカスタムコントローラーマッピングプロファイルが更新されます。なお、カスタム割当てした入力アクションはそのまま残ります。

#### NuGet for Unityでの更新

プロジェクトがNuget for Unityと使った[Mixed Reality Toolkit NuGet packages]をインポートしている場合は以下の手順で反映します。

1. メニューから[NuGet] > [Manage NuGet Packages]を選択
2. [Online]タブを選択し[Reflesh]ボタンを押します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/152548/97379857-d9c2-70b3-55d4-06c7e8f4d752.png)
3. [Installed]タブを選択
4. インストールしたパッケージ毎にUpdateボタンをクリック
 * Microsoft.MixedReality.Toolkit.Foundation
 * Microsoft.MixedReality.Toolkit.Tools
 * Microsoft.MixedReality.Toolkit.Extensions
 * Microsoft.MixedReality.Toolkit.Examples
5. Unityプロジェクトを再度開きなおす


## 3.新機能  

とても多いので一言的に整理します。サンプル等は[リリースノート](https://microsoft.github.io/MixedRealityToolkit-Unity/version/releases/2.2.0/Documentation/ReleaseNotes.html#whats-new-in-220)のサイトを見るとGIFで動きも見れますので一度見てみるといいかもしれません。

### 3.1.Camera Settings Providers
Camera Systemをマルチプラットフォーム向けに対応するためにProviderで制御する方式に変更。
この件については別途整理

* [Mixed Reality Toolkit V2.2.0 の新しいCamera SystemおよびiOS/Android対応について](https://qiita.com/miyaura/items/3a1e605a27d49f2caa68)

### 3.2.Cursor resizing

DefaultCursorプレハブの挙動を各デバイスに合わせて調整するように更新。
* 距離に基づいて動的にサイズ変更
* 角度の情報を使用

### 3.3.Directional Indicator Solver

物体が視野外にある時、方向を示す矢印を制御する新しいSolverです。これは便利。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/152548/08ea3987-ed0c-840e-094d-c2bedf983af2.png)

### 3.4.Fingertip cursor translation and alignment
The fingertip cursor's translation and alignment have been updated to better match the HoloLens 2 shell behavior.

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/152548/84363328-0083-ec5f-767e-1c5ce0a9516d.png)

### 3.5.GridObjectCollection supports content alignment

GridObjectCollection UX controlの配置を以下の組合せで配置できるようになりました。
よくパワポなどで文字の位置を９方向で調整できると思うんですがあれと同じものをGridObjectCollectionで実現しています。

* Left
* Center
* Right

と

* Top
* Middle
* Bottom

### 3.6.Fixing LayoutDirection in GridObjectCollection

GridObjectCollectionはCollection内のオブジェクトを整列するための設定に[RowsThenColumns],[ColumnsThenRows]があるのですが、V2.1.0ではこの設定に関係なく縦方向⇒横方向の順でオブジェクトが整列されていました。V2.2.0からは上記の設定を利用した配置になります。[RowsThenColumns]はV2.1.0と変わらないですが<font color="red">[ColumnsThenRows]の場合は横方向⇒縦方向となるためオブジェクトの配置が換わります</font>

### 3.7.InteractableToggleCollection improvements

MRTKではラジオボタン相当の動きをするUIが提供されているのですが、InteractableToggleCollectionを活用すると、Status値をInteractableコンポーネントの機能を介してオブジェクトのプロパティ変更に利用できるようになります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/152548/cac82aac-ddcc-0956-2905-c9410ab4d37d.png)

### 3.8.Mixed Reality Capture setting (Experimental)

試験的な機能ですが、動作撮影のずれを補正する機能です。
HoloLens/HoloLens 2にはMixed Reality Captureという機能で現実空間と実際のデジタルの描画を結像して撮影する機能があります。ただ、ハードの仕様上、合成する現実空間は実際の目線より上にあるRGBカメラで撮影するため単純に合成するとずれるという状況がありました。この試験的な機能はその描画を調整してずれをなくすことができます。
この機能を利用するには、Unityのバージョンが<font color="red">2018.4 (.13f1以降)</font>か<font color="red">2019.3 (.0f1以降)</font>である必要があります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/152548/d0296638-b670-61a2-f5fb-8913e3ddf135.png)

### 3.9.Mobile AR (Android and iOS) support (Experimental)

これも試験的な機能
ARFoundationを利用してMRTK V2.2.0をAndroid/iOS対応にするもの。
モジュールは[Microsoft.MixedReality.Providers.UnityAR]として別に構成されているので追加が必要です。

この件の詳細は以下のサイトを参照

* [Mixed Reality Toolkit V2.2.0 の新しいCamera SystemおよびiOS/Android対応について](https://qiita.com/miyaura/items/3a1e605a27d49f2caa68)

### 3.10.MSBuild for Unity

MSBuild for Unityをサポートすることで、NuGetで発生する依存関係の自動取得が可能になりました。
この機能はメニューの[Mixed Reality Toolkit] > [Utilities] > [Configure Unity Project]から利用でき、プロジェクトのロード時に実行できます。
ちなみに、MRTKのいくつかの機能（HoloLens 2のハンドトラッキング、アイトラッキングのリモート等）はこの機能が必須となっています。

### 3.11.New audio clips for HoloLens 2 style bounding boxes

HoloLens 2形式のbounding box UX controlの操作時のオーディオクリップ等を利用することでUXのをより向上。
実はあまり知られていないのですが、この辺りの機能はMRTKがかなり優れている要素の1つです。
Mixed Reality（だけじゃないXR全般ですが）の世界ではデジタル情報を直接操作できるといっても現実に物体があるわけではないので質量感や、触れるといった感覚的なものを得ることができません。このため、MRTKでは物体を操作するときにほかの表現に置換しているものが多くあります。例えば、物体を手で触れるときに表面が手の動きに沿って光ったり、今回追加されているような音でリアクションを返すなどです。

### 3.12.PressableButtonHoloLens2 icon lift on focus

PressableButtonHoloLens2ボタンの表面等の表現方法がHoloLens用のものと同等の表現になりました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/152548/365c0203-175f-1322-df12-43e979d447b3.png)


### 3.13.Pulse shaders for spatial mesh and hand mesh (Experimental)

試験的な機能。空間マッピングとハンドトラッキングで使用するメッシュ用のシェーダーが提供されました。使うとわかりますがいわゆる中心から遠方にかけて広がっていく表現です。最もわかりやすい例がHoloLens/HoloLens 2で空間のどこかをタップした時に、空間マッピングのメッシュがGazeポインターを中心として光が広がっていく表現があると思いますが、あれと同じ表現が可能になります。
ハンドトラッキングの場合は手首側から指先にパルスが出る感じになります。

### 3.15.Scrolling Object Collection (Experimental)

スクロールが可能なObjectCollectionコントロール（試験的）
ハンドトラッキング等で上下にオブジェクトを撫でるように操作することでスクロールできるオブジェクト。

### 3.16.Search MRTK profiles for keywords

MRTK内で利用するProfileのキーワード検索が可能に。MRTK V2からはProfileを利用した設定が中心となっていますが、
利用する機能毎に用意する必要があります。たくさんProfileが出てくるのでそれを検索するために追加してくれました。

### 3.17.Surface Magnetism Solver and Hand Ray example scene

ハンドレイで動作する表面に沿うSolverのサンプルが追加。
たぶん動きをみるとわかりやすいのですが、HoloLens 2やモーションコントローラで例を飛ばした先の境界面の表面に沿って移動するオブジェクトを生成できます。サンプルの映像見るとすごい既視感があるんですよね。。。

### 3.18.Support for hand and eye tracking remoting for Microsoft HoloLens 2
HoloLens 2のでHolographic Remoting上でハンドトラッキングとアイトラッキングをサポート。
これでかなりデバッグがはかどりますね！
多少手順が必要なので必ず[設定方法](https://microsoft.github.io/MixedRealityToolkit-Unity/version/releases/2.2.0/Documentation/Tools/HolographicRemoting.html)を確認しましょう。
この機能は[MSBuild for Unity]のインストールが必須で、MSBuildを経由してNugetからMicrosoft.Windows.MixedReality.DotNetWinRTをインストールする形になります。

### 3.19.Windows Mixed Reality Depth Reprojection Settings

開発者は、Microsoft HoloLens 2アプリケーションに必要な深度再投影方法を指定できるようになりました。次の図に示すように、Windows Mixed Reality Camera Settingsで、Depth ReprojectionまたはAuto Planarを選択します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/152548/dff876f2-de50-789f-31b7-db97761b08f9.png)

## 4.既知の問題
すでにわかっている問題は以下の通りです。
### 4.1.Long paths

プロジェクトの開始パスが長いと一部のパスが長すぎて処理できなくなります。
（これ自体は別にMRTK関係なく良くある話ですが・・・）

### 4.2.Runtime profile swapping

現状、Profileの動的変更には対応していません。Profileは静的な設定となっています。ただ、現状はそこまで困らないと思います。ProfileはマルチデバイスようにProviderを複数デバイスごとに割り当てて定義できるなどかなりの配慮がすでにありますし。
ただ、動的変更をやりたいと思ったときは現状できないことを理解しておきましょう。

### 4.3.Unity 2018: .NET Backend and AR Foundation

Unity 2018で.NET scripting Backendを使ってUWPをビルドしようとするとAR Foundationのインストールに失敗します。
これを回避するには以下の2つのいずれかの対応が必要。

* IL2CPPでビルドする
* [Build Settings]内の設定で[Unity C# Projects]のチェックを外す

要はVisual Studio上のUnityのコード（CSharp-Assemblyプロジェクト）をビルドしない状況を作ればいいということです。
まぁ、これはUWPではAR Foundationが不要とはいえ、仕組み上はライブラリをリンクするからモバイル用のライブラリをUWPでは
使えないでしょ？と言われたら、さほど違和感はないんですが。。。

### 4.4.Hang when using Holographic Remoting

Unityの一部のバージョンで発生する。
Holographic Remoting中に再生モードに入るとハングすることがあるそうです。
プロジェクト読み込み時にウィンドウが開いていると発生しやすいようです。
プロジェクトを閉じたり、再オープンするときにHolographicダイアログを閉じてからするように注意。

### 4.5.Failed to get IHolographicCameraRenderingParameters from main camera for updating rendering parameter

リモーティングを利用中にコンソールに「Failed to get IHolographicCameraRenderingParameters from main camera for updating rendering parameter」のエラーが表示されることがある。
ハンドトラッキング中にこの現象が発生することはあるが動作には支障はない。
Githubで追跡調査対象。

### 4.6.Assembly has reference to non-existent assembly 'Unity.XR.ARFoundation'

AR Foundationを利用するためのプロジェクトをインポートした状態でUnity.XR.ARFoundationが存在しないエラーが
出る場合はパッケージのインポートを忘れている場合がある。iOS/AndroidのAR Foundationの設定を確認して
手順通り設定すること。

* [Mixed Reality Toolkit V2.2.0 の新しいCamera SystemおよびiOS/Android対応について]

### 4.7.Mixed Reality Capture settings (Experimental)
Windows Mixed Reality Captureに関する試験的な機能は、デフォルトでは無効です。
必要に応じて自分で有効にする必要がありますが、これは一部のUnityのバージョンではこの機能をサポートできていないため。
この機能を使いたい場合は以下のUnityバージョンで実行する。

* 2018.4（.13f1以降）
* 2019.3.0f1以降

Unityの他のバージョンでこの機能を有効にすると、デジタルコンテンツの表示が不安定になる。

### 4.8.MRTK Configurator dialog

MRTKが含まれるプロジェクトをロードすると、MRTK Configuratorダイアログが複数回表示される場合がある。
さして実害があるわけじゃないですが、読み込み時の負荷度合いによって発生するそうです。
この問題は、MRTKの将来のバージョンで調査および対処される予定です。

### 4.9.The type or namespace name 'TrackedPoseDriver' could not be found

Unity 2019.2以降で今回追加されたUnityARパッケージを利用する場合は、 [Microsoft.MixedReality.Toolkit.Providers.UnityAR.asmdef]で示される参照定義に中に[UnityEngine.SpatialTracking]を含めておく必要があります。これに関しても手順がすでにあるので確認してください。

 * [Mixed Reality Toolkit V2.2.0 の新しいCamera SystemおよびiOS/Android対応について]

## まとめ

ということで、MRTK V2.2.0のリリースノートを読み解いてみました。
新しい機能の中でもAR Foundationは自分もサンプルコードを提供するなどいろいろ協力することで実現してもらえたのがよかったです。
Android/iOS対応はこれから必要になりそうな要素なのでそれがクロスプラットフォームで実現できるのはMRTKの活用の場が広がるのでうれしいです。
その他の便利な機能も続々と追加されてきていますので、これからもHoloLens以外のデバイスでも活用方法を検討してどんどん利用する方向になるのかなと個人的には思っています。

## おまけ

MRDLというMixed RealityのUXを実験的に取り組んでいるプロジェクトにとても素敵なサンプルが追加されています。
<blockquote class="twitter-tweet"><p lang="en" dir="ltr">Check out our new experimental sample app for <a href="https://twitter.com/hashtag/HoloLens2?src=hash&amp;ref_src=twsrc%5Etfw">#HoloLens2</a> &#39;Surfaces&#39; <a href="https://twitter.com/hashtag/MadeWithMRTK?src=hash&amp;ref_src=twsrc%5Etfw">#MadeWithMRTK</a> It explores how we can create a tactile sensation with visual, audio, and fully articulated hand-tracking <a href="https://t.co/A2H3POwCL5">https://t.co/A2H3POwCL5</a> <a href="https://twitter.com/hashtag/MRTK?src=hash&amp;ref_src=twsrc%5Etfw">#MRTK</a> <a href="https://twitter.com/HoloLens?ref_src=twsrc%5Etfw">@HoloLens</a> <a href="https://twitter.com/hashtag/MixedReality?src=hash&amp;ref_src=twsrc%5Etfw">#MixedReality</a> <a href="https://twitter.com/hashtag/AugmentedReality?src=hash&amp;ref_src=twsrc%5Etfw">#AugmentedReality</a> <a href="https://twitter.com/hashtag/VirtualReality?src=hash&amp;ref_src=twsrc%5Etfw">#VirtualReality</a> <a href="https://twitter.com/hashtag/AR?src=hash&amp;ref_src=twsrc%5Etfw">#AR</a> <a href="https://t.co/8KzTbZpuj7">pic.twitter.com/8KzTbZpuj7</a></p>&mdash; Yoon Park (박동윤) (@cre8ivepark) <a href="https://twitter.com/cre8ivepark/status/1208113136131117056?ref_src=twsrc%5Etfw">December 20, 2019</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script> 
HoloLens 2のデモとしてもわかりやすいハンドトラッキング系のサンプルなので手に入れたらぜひ試してみましょう。
https://github.com/microsoft/MRDL_Unity_Surfaces




[Mixed Reality Toolkit V2.2.0]: https://github.com/microsoft/MixedRealityToolkit-Unity/releases/tag/v2.2.0 "Mixed Reality Toolkit V2.2.0"
 [Mixed Reality Toolkit V2.2.0 の新しいCamera SystemおよびiOS/Android対応について]:https://qiita.com/miyaura/items/3a1e605a27d49f2caa68 "Mixed Reality Toolkit V2.2.0 の新しいCamera SystemおよびiOS/Android対応について"