ワールド ロック ツールの初期セットアップ

可能な限り最も小さいセットアップ

このチュートリアルでは、最小限のセットアップを実行して、アプリケーション内のワールド ロックされているすべてのものを起動して実行します。それ以上のアクション (空間アンカーなど) は必要ありません。 これは、このレポートの兄弟のサンプル レポートに含まれています。

クイック スタート ガイド

WLT をプロジェクトに統合するための、概念的に詳細ではない、より実用的なアプローチがここに記載されています。 必要に応じて、より詳細なページを参照します。 どちらのアプローチがより適切かは実際には個人的な好みの問題ですが、「作業を開始する前に」のページをざっと読むと、このドキュメントのどこにエネルギーを注ぐかについて考える時間を節約できます。

サポートされる環境

現在、Unity 用のワールド ロック ツールは、HoloLens デバイス ファミリの UWP アプリケーションを対象としています。 元のHoloLens (x86) と HoloLens 2 (ARM64) の両方がサポートされています。

他のプラットフォームの試験的なサポートは、Unity の AR サブシステムを通じて利用できます。

ワールド ロック ツールの継続的インテグレーション (CI) ビルドは、Unity 2018.4.6f1 と Visual Studio 2017 を使用して検証されます。 ただし、広範な WLT の開発は、Unity2018 バージョンの全範囲と Unity2019 の広い範囲も使用して実行されています。 Visual Studio 2017 と Visual Studio 2019 の両方がツールの開発に使用されています。

他のバージョンの Unity や Visual Studio との互換性の問題が発生した場合は、その問題についてお知らせいただけると幸いです。 問題を報告する最善の方法は、GitHub の問題ポータルを使用することです。

想定される背景

ワールド ロック ツール ソリューションをプロジェクトに統合しようとしているユーザーは、HoloLens ファミリ デバイス用のアプリケーションの構築とデプロイの基本について既に理解している必要があります。 そうではない場合は、この記事の最後に記載されているいくつかの役に立つ参考資料を参照してください。

ワールド ロック ツールのレイヤー

ワールド ロック ツールは 4 つのレイヤーに分割されます。 依存するレイヤーを指す矢印を使用すると、単純な依存関係の図は次のように表示されます。

破線は、オプションの依存関係を示します。

Examples レイヤーでは MixedRealityToolkit (MRTK) を使用しますが、他のレイヤーには外部依存関係がありません。また、MRTK と互換性がある完全な機能を使用できますが、それらは MRTK とは独立しています。

アプリケーションの依存関係に関するその他の注意事項を以下に示します。

レイヤーは次のようにまとめられる場合があります。

プラグイン

エンジン DLL との直接通信を可能にする命令型インターフェイス。 ここでは、引数のマーシャリングなどの一般的な問題を解決し、複合ディレクティブと組み合わせて頻繁に使用される複数の関数の構成をいくつか行います。 引き続き、基になる C++ DLL への低レベルの C# インターフェイスになります。 直接の使用は可能ですが、必須ではなく、推奨されません。

コア

Core は、ワールド ロック ツールの安定したワールド ロック空間のメリットを得るために必要なすべての手順をカプセル化したものであり、宣言型インターフェイスにパッケージ化されています。 動作するアプリケーションは、Core の機能のみを使用して出荷される予定です。

ツール

Tools は、主に診断機能です。 ワールド ロック ツールのプロセスの視覚化は、ワールド ロック ツールを使用する任意のプロジェクトに簡単に追加できるフォームに含まれています。

その他の便利なユーティリティが含まれていますが、それらは、Core が提供するような最終的なソリューションではなく、カスタム ソリューションのコーディングを開始する際に役立つことが想定されます。

例

Examples レイヤーでは、ワールド ロック ツールを使用する場合の一般的なシナリオの設定のサンプルと、さまざまなシナリオへのワールド ロック ツールの統合に関するベスト プラクティスを提供します。

UX とオブジェクト操作に必要な MRTK の依存関係は、Examples レイヤーのスクリプトとプレハブに制限されます。 これにより、下位レイヤーは外部の依存関係から解放されます。

Examples レイヤーのスクリプトと資産は、出荷製品に直接統合される予定はありませんが、これに対する禁止事項はありません。 むしろ、それらの構造では、再利用性と効率性よりも単純さと明快さが優先されます。

Application

一般に、Application は、ワールド ロック ツールのみへの依存を必要とします。

開発中には、予期しない動作を理解するための多くの視覚化や他のヘルパーを Tools レイヤーで使用できます。 完成したアプリケーションでは、これらのヘルパーを削除するか、少なくとも無効にするのが理想的です。 もちろん、現在の形式または変更された形式で、他の用途でも無料で使用できます。 詳細については、ライセンスに関するページを参照してください。

高度な使用方法や、ワールド ロック ツールの完全な機能の実験のために、Plugin レイヤーはエンジン DLL への低レベルの命令型アクセスを提供します。

Plugin レイヤーへのアクセスが必要になった場合は、Core レイヤーで提供される API サーフェスの欠陥を示している可能性があります。 ワールド ロック チームは、このようなギャップを埋めることを常に目指しています。 そのような分析情報をチームに提供することを検討してください。 寄与に関するページを参照してください。

インストール パスの長さに関する警告メモ

MRTK の一部のバージョンには、長いインストール パスに問題があります。 MRTK のインストールでの深いサブフォルダーの完全パスの長さは、Windows のパスの上限 (260 文字) を超える可能性があります。 次の形式のビルド エラーが表示される場合があります。

DirectoryNotFoundException: Could not find a part of the path "D:\MyOverTwentyEightCharacterLongLengthInstallPath\MixedReality-WorldLockingTools-Unity\Assets\MRTK\MixedRealityToolkit.Providers\WindowsMixedReality\DotNetAdapter\Plugins\net46\Microsoft.Windows.MixedReality.DotNetWinRT\Editor\Microsoft.Windows.MixedReality.DotNetWinRT.Editor.asmdef"

ただし、ファイルは実際にはドライブ上にあるので、問題はパスの長さである可能性があります。 MRTK チームはこれを認識し、改善に取り組んでいます (注: これについては大幅な改善が行われ、問題ではなくなったと思われます)。 その間の回避策として、次方法の組み合わせでパス プレフィックスを短縮します。

1. Unity プロジェクトを短い長さのパス ルート (例: "D:\Proj") にインストールします。
2. リポジトリを複製する場合は、ワールド ロック ツールのルートを既定の "\MixedReality-WorldLockingTools-Unity" よりも短いものに複製します。次に例を示します。

git clone https://github.com/microsoft/MixedReality-WorldLockingTools-Unity.git d:\MyGit\wlt

このパスの制限は、一般的に、ワールド ロック ツール自体に関する問題ではありません。これは、それらはこのような深いフォルダー構造を利用しないためです。

Unity プロジェクトへのワールド ロック ツールの追加

ワールド ロック ツールは、基になる Frozen World Engine をインストールするために nuget に依存します。

既存のプロジェクトにワールド ロック ツールを追加する場合は、ビルドして HoloLens デバイスにデプロイできることが検証されてているプロジェクトから始める必要があります。 これは、HoloLens で最初にアプリを実行する際の問題 (複雑になる可能性があります) と、ワールド ロック ツールの問題を分離するのに役立ちます。 次に、以下の「FrozenWorld Engine のインストール」と「「ワールド ロック ツールの資産」のセクションに進みます。

FrozenWorld エンジンのインストール

FrozenWorld Engine DLL は、優れた NuGet For Unity ユーティリティを使用して、または手動で NuGet から取得できます。

NuGet For Unity を使用する

nuget.org フィードがソースにあることを確認します。 [Unity] > [Edit]\(編集\) > [Preferences]\(基本設定\) > [NuGet for Unity] でこれを確認します。 ない場合は、次のいずれかを行います。

Unity >[Edit]\(編集\) > [Preferences]\(基本設定\) > [NuGet For Unity] の [Add New Source]\(新規ソースの追加\) GUI を使用して、同じ共有を追加します。

• "新規ソース" は、選択した名前 ("NuGet" など) に置き換えてください。
• "source_path" を "http://www.nuget.org/api/v2/"" に置き換えてください。

[Unity] > [NuGet] > [NuGet パッケージの管理] で nuget.org フィードを確認した後で、Microsoft.MixedReality.FrozenWorld.Engine の最新バージョンを見つけてインストールします ("FrozenWorld" を検索します)。

新しいバージョンに更新するには、[Unity] > [NuGet] > [NuGet パッケージの管理] を再度開き、FrozenWorld.Engine パッケージを見つけて [更新] を選択します。 注: 必要なバージョンを見つけるには、[更新] タブが必要な場合があります。

Frozen World Engine DLL の手動インストール

テキスト エディターを使用して Assets/NuGet.config に packageSources 行を追加します。次に例を示します。

  <packageSources>
    <add key="NuGet" value="http://www.nuget.org/api/v2/" />
  </packageSources>

Assets/NuGet.config ファイルをまだ持っていない場合は、ワールド ロック ツール github リポジトリからコピーできます。

テキスト エディターを使用して、Assets/packages.config に Frozen World Engine DLL パッケージを追加します。次に例を示します。

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="Microsoft.MixedReality.Unity.FrozenWorld.Engine" version="1.0.0" />
</packages>

ここでも、Assets/packages.config ファイルをまだ持ってない場合は、ワールド ロック ツール github リポジトリからファイルを取得するか、上記を "Assets/packages.config" というテキスト ファイルにコピーします。

次の方法で、NuGet.config と packages.config をインストールします。

1. NuGet ダウンロードから最新の nuget.exe を取得します。
2. パスに nuget.exe があることを確認します (ここでは、Assets にコピーされたと仮定します)。
3. PowerShell コマンド ウィンドウを開き、ディレクトリを Assets フォルダーに変更します。
4. 次のコマンドを実行します。

.\nuget.exe restore

新しいバージョンにアップグレードするには:

1. 上記の packages.config ファイルの FrozenWorld.Engine バージョン番号を目的のバージョンに更新します (たとえば、version="1.0.0" は version="1.0.1" になります)。
2. Assets/Packages フォルダー内で "Microsoft.MixedReality.Unity.FrozenWorld.Engine" で始まるものをすべて削除します。
3. 上記のように nuget.exe を再実行します。

ワールド ロック ツールの資産

必要なワールド ロック ツールの .unitypackage ファイルをプロジェクトにインポートするか (推奨される方法)、コピーします。 これらはアプリケーション開発の邪魔にならないように、Assets 内のサブフォルダーに移動されている場合があります。

最新の安定した .unitypackage ファイルは、Unity 用のワールド ロック ツールのリリースから入手できます。

WorldLocking.Core レイヤーと Engine レイヤーは必ず必要になるので、最小限のインストール パッケージは WorldLockingCoreEngine.unitypackage になります。

他にどのようなレイヤーが必要かを判断するには、上記のワールド ロック ツール レイヤーとその依存関係に関する説明を参照してください。 各レイヤーは、1 つの Unity パッケージに含まれています。

一部のワールド ロック ツールの例では MRTK の機能が使用されているので、互換性のある MRTK スナップショットが、例 unitypackage に含まれています。 MRTK の最新リリースについては、こちらを参照してください。

Unity シーンにワールド ロック ツールを追加する

FrozenWorld エンジン (nuget.org から) を含む Unity プロジェクト内で、必要な World Locking Tools Assets レイヤー (ただし、少なくとも WorldLocking.Core) と、必要に応じて MRTK をインポートします。 次に、新しいシーンを作成します (または、既存のシーンを開きます)。

コア エクスペリエンス

WorldLockingManager プレハブを Assets/WorldLocking.Core/Prefabs からシーンにドラッグします。 シーン内の場所は関係ありませんが、カメラ ツリーに配置しないようにする必要があります。 推奨される構成については、サンプル シーンを参照してください。

WorldLockingManager プレハブには使用可能な設定がありますが、開始するときには既定値のままにすることをお勧めします。

表示されるオプションの説明については、「ワールド ロック ツールのコンテキスト」を参照してください。

[省略可能] MRTK

ワールド ロック ツールと MRTK は補完的ですが、相互に独立しています。 ワールド ロック ツールとともに MRTK を使用することは、完全に任意です。

とは言え、ワールド ロック ツールのサンプルは MRTK を使用して構築されており、一般的に、ワールド ロック ツールから最も多くのメリットを得られる MR アプリケーションの種類を開発する上で、MRTK は非常に重要です。

MRTK を使用する場合は、例に含まれているスナップショットを使用するのではなく、少なくとも次のパッケージの最新バージョンを追加することをお勧めします。

• MixedReality.Toolkit
• MixedReality.Toolkit.Providers
• MixedReality.Toolkit.Services
• MixedReality.Toolkit.SDK

[省略可能] spongy とワールド ロック アンカーの視覚化

これには、WorldLocking.Tools をプロジェクトの資産に追加する必要があります。

アンカーを視覚化する場合は、AnchorGraphVisual プレハブを Assets/WorldLocking.Tools/Prefabs からシーンにドラッグします。 インスペクターで視覚化の側面を切り替えるチェック ボックスは、WorldLockingManager にあります。

WorldLocking.Tools の視覚化はあまり最適化されていないので、診断すると、コアのワールド ロック ツールの処理時間が適切になるかなり前にパフォーマンスが低下します。

[省略可能] Mixed Reality 内のパラメーター コントロール用の単純なダッシュボード

単純な HUD を使用できます。これは、実行時に MR 内から WorldLockingManager をコントロールするために使用できます。 これらは、サンプル パッケージで提供されます。 これらは、そのまま使用できますが、アプリケーション独自の表示システムと UX に類似した機能を組み込むときのパターンとして使用することを目的としています。

WorldLocking.Examples/Prefabs/Dashboard プレハブ内をドラッグし、そのアンカー ビジュアライザー フィールドで前のセクションのビジュアライザーをポイントします。

既存のシーンをワールド ロック ツールに移行する

ワールド ロック ツールに移行する際の最大の変更点は、ワールド ロック仮想オブジェクトに対する空間アンカーを使用する必要がなくなった点です。

従来、空間アンカーは、従来、個々のオブジェクトをワールド ロックするために使用できる唯一のツールでした。 しかし、ワールド ロック ツールを使用する場合、これらの仮想オブジェクトが存在する座標空間は既にワールド ロックされています。 それ以上ロックする必要はありません。

空間アンカーは不要であるだけでなく、カメラ階層の追加の変換 (MRTK "Playspace" 変換など) を考慮できないので、正しく機能しません。

そのため、すべての空間アンカーをシーンから削除する必要があります。また、空間アンカーを追加するすべてのスクリプトは、その処理を停止する必要があります。 空間アンカーを何かに置き換える必要はありません。ワールド ロック ツールは、それらのターゲットを現実世界に固定します。

ワールド ロック ツールを使用する場合と使用しない場合のワールド ロックを比較することが望ましい場合は、WorldAnchors を削除する代わりに、WorldLocking.Tools で提供されている ToggleWorldAnchor に置き換えることができます。

ToggleWorldAnchor は WorldAnchor とまったく同じように動作しますが、これは、ワールド ロック ツール マネージャーが有効なときに、それ自体が簡単に無効になって邪魔にならないようにするという重要な違いがあります。 ワールド ロック ツール マネージャーを無効にすると、通常の WorldAnchor として動作します。

他の理由で WorldAnchors がシーンで引き続き必要な場合 (ネットワーク共有の場合など)、WorldAnchorAdapter として提供されるアダプターとともに使用できます。

WorldAnchorAdapter は、WorldAnchor によって配置された GameObject の生の位置を、ワールド ロックされた Unity グローバル空間に変換してから、ターゲット オブジェクトに変換を適用します。 それを使用するには、WorldAnchor をオブジェクトに直接追加するのではなく、WorldAnchor をプロキシ オブジェクト (通常は空になっている GameObject) に適用してから、Update() で WorldAnchorAdapter が WorldAnchor のポーズを読み取り、正しく変換してターゲットに適用する必要があります。

セットアップの完了

上記の手順に従った後、デバイスにデプロイされたプロジェクトは、最適な安定したワールド ロック空間を維持するように、ワールド ロック ツールによって調整されて実行されます。 シーンに配置された固定オブジェクトは、互いに相対的に視覚的な一貫性を維持し、さらに物理的な世界とも一貫性を維持します。

使用可能なアプリケーションの例

スクリプトと資産の両方を含むサンプル シーンが、ワールド ロック ツールの機能のより複雑な使用方法を示すために提供されています。

たとえば、WorldLockedPhysicsSample は、物理的にシミュレートされたオブジェクトを作成および削除し、相互に対話したり、環境と対話したり (空間マッピング) できる単純な環境を提供します。

スペース ピン機能の詳細を知るために、SpacePin は、大規模な仮想オブジェクトを現実世界の特徴に位置合わせする簡単な例を提供します。

RayPins は、SpacePin の例で導入された機能を拡張し、空間メッシュに対するレイ テストを使用して仮想世界を物理世界にピン留めできます。

開始のためのリファレンス

AR アプリの作成、構築、HoloLens ファミリのデバイスへの展開の基本について詳しく知らない場合のために、作業の開始に役立ついくつかの参考資料を次に示します。

Unity 開発の概要 - MR/AR 開発用の Unity。

MR の基礎 100 - HoloLens 用の開発を開始する手順。

HoloLens 2 チュートリアル - HoloLens 2 用の開発を開始する手順。

座標系 AR 開発における空間への影響を調整する。

• ワールド ロック ツールによって、ここに記載されている問題が解決されます。

問題が生じた場合は、

トラブルシューティング ガイドを参照してください。