Mixed Reality Spatial Data Packager のドキュメント

  • [アーティクル]

Note

非推奨

2020 年 8 月 1 日の時点で、このツールは非推奨となり、どのプラットフォームでも機能しなくなりました。 代わりに、デバイス ポータルの Map Manager ツールを使用することをお勧めします。

このツールと操作は、現状のまま提供されます。 これは予告なしに変更される可能性があり、将来の Windows または Windows Mixed Reality HMD リリースと互換性を持たなくなる可能性があります。

ダウンロード

MixedRealitySpatialDataPackager をここからダウンロードします

デバイス サポート

機能 HoloLens (第 1 世代) HoloLens 2 イマーシブ ヘッドセット
Mixed Reality Spatial Data Packager ❌ ❌ ✔️

クイックスタート

Mixed Reality Spatial Data Packager ツールはターゲット アプリの空間データを、特定の PC から別の PC に 2 段階のエクスポートおよびインポート プロセスを使用してコピーします。 このツールは管理者特権で実行する必要があり、インポート時に既存の空間データが削除されます。 エクスポートの場合は、既存の空間データはそのまま残ります。

主要な要件と制限:

  1. ツールは管理者特権で実行する必要があります
  2. ツールの実行後に Mixed Reality ポータルが不安定になった場合、PC を再起動する必要が生じることがあります
  3. 空間データのバージョンに不一致または非互換が発生した場合、ツールは実行されません
  4. インポート時に、ツールによって既存の空間データが消去されます
  5. インポート プロセスが失敗した場合、以前のデータは、前もってエクスポートしてバックアップしていなければ復元することはできません
  6. インポート機能の品質は、空間マップ データの「読み取り専用」モードに依存します

マッピングのベスト プラクティス

  1. コントロール パネルから既存のマップをクリアする ([設定] -> [Mixed Reality] -> [環境] -> [環境データをクリアします])
  2. 適切な追跡を行うのに十分な照明を確保し、ロックされたマップ モードを実行している場合は、同じ照明を維持するよう試みる
  3. 可能な場合は、暗い影付き領域の横に生じる高照度の領域を避けて、照明のダイナミック レンジを低く保つ
  4. テクスチャのない空白の表面を最小限に抑える (例: 白い壁にさまざまなポスターを貼る)
  5. 動いている人など、シーン内に動的オブジェクトを含めずに空間をマップする
  6. インポート時にマップをロックする (Insider Preview で使用可能)
  7. 品質の低下を追跡するときや、環境に変化があるとき (照明やオブジェクト レイアウトの変更)、マップのロックを解除し、環境を再スキャンする

コンパニオン スクリプトを使用した Mixed Reality Spatial Data Packager の実行

マップ パッケージャー ツールを実行する MRSpatialPackagerHelperScript.ps1 を提供しています。

スクリプト パラメーターは次のように定義されています。

-AppName <String>
    On export: The spatial anchors from the app of interest
    On import: The target app that spatial anchors should be imported for
    Returns a list of apps containing the input string if a unique app is not found

-UserName <String>
    Target username, will return a list of users if a unique match is not found

-Mode <String>
    import or export

-MapxPath <String>
    On export: Directory to export your mapx files
    On import: Directory where import mapx are stored

-LockMap <Int32>
    0 to unlock map
    1 to lock map

-BinPath <String>
    Path to MixedRealitySpatialDataPackager.exe, default value is current directory

Powershell スクリプトの使用例と出力例

.\MRSpatialPackagerHelperScript.ps1 -AppName holoshell -UserName Administrator -Mode export -MapxPath D:\temp\ -LockMap 0

Package Family Name for holoshell: HoloShell_cw5n1h2txyewy
User SID for Administrator: S-1-5-21-1279937937-3984375698-1043392598-499
Lock map value successfully set to 0

Running: C:\bin\MixedRealitySpatialDataPackager.exe export D:\temp\ HoloShell_cw5n1h2txyewy S-1-5-21-1279937937-3984375698-1043392598-499

Attempting to disable Windows MR driver
Driver disabled
Validating spatial data version information...
Device spatial data version OK
External spatial data version OK
Importing spatial anchors for user account phguan
Stopping SPECTRUM
Stopped SPECTRUM
Stopping SHAREDREALITYSVC
Stopped SHAREDREALITYSVC
Space ID is {00000000-4321-0000-0000-000000000000}
SUCCESS: Unpacked Space from D:\temp\map\het.mapx to
C:\ProgramData\WindowsHolographicDevices\SpatialStore\HoloLensSensors\{00000000-4321-0000-0000-000000000000}\
Space ID is {78FA06B5-4416-4815-BB00-B3CB5C983B7D}
SUCCESS: Unpacked Space from D:\temp\map\sa.mapx to
C:\ProgramData\Microsoft\Spectrum\PersistedSpatialAnchors\
Attempting to enable Windows MR driver
Driver enabled
Starting SHAREDREALITYSVC
Started SHAREDREALITYSVC
Starting SPECTRUM
Started SPECTRUM
IMPORT SUCCESS

MixedRealitySpatialDataPackager.exe を使用したエクスポート方法

MixedRealitySpatialDataPackager.exe export <folderpath to mapx files> <source package family name>

デバイスからマップをエクスポートすると、2 つの mapx ファイル het.mapx と sa.mapx が生成されます。 エクスポート プロセス中に、指定されたアプリとユーザーが作成した境界 (存在する場合) を除く、すべての空間アンカーが削除されます。 ソース パッケージ ファミリ名は、インストールされている既存のアプリと一致する必要があります。一致しない場合、exe は失敗します。

MixedRealitySpatialDataPackager.exe を使用したインポート方法

MixedRealitySpatialDataPackager.exe import <folderpath to mapx files> <target package family name> <user SID>

インポートによって既存の空間データが削除され、指定されたディレクトリからのデータに置き換えられます。 アプリ名を入力すると、(空間アンカーなどの) インポートする必要があるターゲット アプリのパッケージ名が指定され、ターゲット ユーザー SID によって、インポートされた空間アンカーにアクセスする必要のあるユーザーが指定されます。 ターゲット パッケージのファミリ名とユーザーの SID が PC 上の既存の値と一致している必要があります。一致しない場合、exe は失敗します。

エラー メッセージ

以下のエラー メッセージのほかに、失敗によって HRESULT も返されます。

無効な引数エラーが発生した場合

Invalid command line parameters

実行可能ファイルが管理者モードで実行されていなかった場合

1. Unable to determine elevation privileges 
2. Please run with administrator privileges

ドライバーの有効化または無効化でエラーが発生した場合

1. Could not find the specified driver with class GUID {d612553d-06b1-49ca-8938-e39ef80eb16f}
2. Could not find the device instance ID for specified driver with class GUID {d612553d-06b1-49ca-8938-e39ef80eb16f}
3. Could not find the specified driver with device instance ID <INSTANCE ID>
4. Failed to enable/disable driver

空間データベースのバージョンの検証中にエラーが発生した場合

1. Could not read database version
2. This tool is not compatible with the current driver version of Windows Mixed Reality and/or the spatial data provided to replace the existing spatial data is an invalid version.
3. No spatial data is present on the current device please connect your Mixed Reality device to initialize spatial data. If the problem persists please restart your PC.

ターゲットのインポート/エクスポート アプリに指定されたパッケージ ファミリ名の検証中にエラーが発生した場合

The package family name does not correspond to an installed app

ユーザー SID の検証中にエラーが発生した場合

Failed to find local user for passed in user SID

1. Folder path to space store files doesn't exist 
2. het.mapx or sa.mapx file doesn't exist in <PATH> for import
3. Unable to create directory at <PATH> for export

1. Unable to open service manager <SERVICE>
2. Timed out trying to start/stop <SERVICE>