混合現實空間資料封裝工具檔Mixed Reality Spatial Data Packager Documentation

注意

已淘汰DEPRECATED

從8/1/2020 開始,這項工具現在已淘汰,且在任何平臺上都不再有作用。As of 8/1/2020 this tool is now deprecated and no longer functions on any platform. 建議您改為使用裝置入口網站中的 對應管理員 工具。We recommend using the Map Manager tool in the Device Portal instead.

此工具和其作業會依原樣提供。This tool and its operation are offered as-is. 這項變更可能會隨時變更,恕不另行通知,且可能與未來的 Windows 或 Windows Mixed Reality HMD 版本不相容。It is subject to change without any notice and may not be compatible with future Windows or Windows Mixed Reality HMD releases.

下載Download

在這裡下載 MixedRealitySpatialDataPackagerDownload MixedRealitySpatialDataPackager here

裝置支援Device support

功能Feature HoloLens (第 1 代)HoloLens (1st gen) HoloLens 2HoloLens 2 沉浸式頭戴裝置Immersive headsets
混合現實空間資料封裝工具Mixed Reality Spatial Data Packager ✔️✔️

快速入門Quickstart

混合現實空間資料封裝工具會透過兩個步驟的匯出和匯入程式,將目標應用程式的空間資料從一部電腦複製到另一台電腦。The Mixed Reality Spatial Data Packager tool copies the spatial data of a target app from one PC to another through a two step export and import process. 此工具必須以系統管理員許可權執行,並在匯入時刪除現有的空間資料。The tool must be run with administrator privileges and deletes the existing spatial data on import. 匯出會讓現有的空間資料保持不變。Export leaves the existing spatial data intact.

重要需求和限制:Key requirements and limitations:

  1. 工具必須以系統管理員許可權執行Tool must be run with administrator privileges
  2. 如果在執行此工具之後混合實境入口不穩定,您可能必須重新開機電腦You may have to restart PC if Mixed Reality Portal is unstable after running the tool
  3. 當遇到空間資料版本不符或不相容時,工具將不會執行Tool will not run when encountering spatial data version mismatches or incompatibilities
  4. 工具會在匯入時清除現有的空間資料Tool will erase existing spatial data on import
  5. 如果匯入程式失敗,則無法還原先前的資料,除非之前匯出之前的資料已備份If import process fails previous data cannot be restored unless it has been backed up by exporting previously
  6. 空間對應資料的「唯讀」模式上的匯入功能品質Quality of import functionality contingent on “Read-Only” mode for spatial map data

對應最佳作法Mapping Best Practices

  1. 清除主控台 (設定中的現有對應-> 混合現實-> 環境-> 清除環境資料) Clear existing maps from the Control Panel (Settings -> Mixed Reality -> Environment -> Clear environment data)
  2. 確定有足夠的光源可進行良好的追蹤,而且如果執行鎖定的地圖模式嘗試維持相同的光源Ensure sufficient lighting for good tracking and if running locked map mode try to maintain the same lighting
  3. 可能的話,請避免深色、陰影區域旁邊的高照明區域,讓燈光動態範圍減少When possible keep the lighting dynamic range low by avoiding areas of high illumination next to dark, shadowed areas
  4. 將空白、textureless 的表面最小化,例如在白色牆上放置不同海報的範圍Minimize blank, textureless surfaces e.g. place a range of different posters on white walls
  5. 對應場景中不含動態物件的空間,例如移動人員Map the space without dynamic objects in the scene such as moving people
  6. 透過 Insider Preview (可取得的匯入鎖定地圖) Lock the map on import (available via Insider Preview)
  7. 當追蹤品質降低,並(或)環境中有變更 (光源或物件配置中的變更時,請解除鎖定地圖並重新掃描環境) * * Unlock the map and rescan the environment when tracking quality degrades and/or there are changes in the environment (lighting or changes in object layout) **

使用隨附腳本執行混合現實空間資料封裝程式Running Mixed Reality Spatial Data Packager with Companion Script

我們已提供執行地圖封裝工具的 MRSpatialPackagerHelperScript.ps1。We have provided MRSpatialPackagerHelperScript.ps1 that runs the map packager the tools.

腳本參數定義如下:The script parameters are defined below:

-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 腳本範例使用方式和輸出Powershell Script Example Usage and Output

.\MRSpatialPackagerHelperScript.ps1-AppName holoshell-UserName 系統管理員-Mode export-MapxPath D:\temp-LockMap 0.\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 匯出How to Export using MixedRealitySpatialDataPackager.exe

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

將 maps 匯出裝置會產生兩個 mapx 檔案,het. mapx 和 mapx。Exporting maps off device generates two mapx files, het.mapx and sa.mapx. 在匯出過程中,除了指定的應用程式和使用者建立的界限 ((如果存在) )之外,也會移除所有空間錨點。During the export process all spatial anchors are removed except for the specified app and the user-created boundary (if it exists). 來源套件系列名稱必須符合現有已安裝的應用程式,否則 exe 將會失敗。The source package family name must match an existing installed app or the exe will fail.

如何使用 MixedRealitySpatialDataPackager.exe 匯入How to Import using MixedRealitySpatialDataPackager.exe

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

匯入會刪除現有的空間資料,並將其取代為指定之目錄中的資料。Import deletes the existing spatial data and replaces it with the data from the specified directory. 應用程式名稱輸入會指定應匯入空間錨點的目標應用程式套件名稱,而目標使用者 SID 會指定應該具有已匯入空間錨點存取權的使用者。The app name input specifies the package name of the target app that like the spatial anchors should be imported for and the target user SID specifies the user that should have access to the imported spatial anchors. 目標套件系列名稱和使用者 Sid 必須符合電腦上現有的值,否則 exe 將會失敗。The target package family name and user SIDs must match existing values on the PC or the exe will fail.

****

錯誤訊息Error Messages

此外,下列錯誤訊息也會伴隨 HRESULTIn addition the error messages below failures will also be accompanied with an HRESULT

如果有錯誤的引數無效If there was an error invalid arguments

Invalid command line parameters

如果可執行檔未以系統管理員模式執行If the executable was not run in administrator mode

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

如果啟用或停用驅動程式時發生錯誤If there was an error enabling or disabling the driver

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

如果驗證空間資料庫版本時發生錯誤If there was an error validating the spatial database version

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.

如果在驗證為目標匯入/匯出應用程式提供的套件系列名稱時發生錯誤If there was an error validating the package family name provided for target import/export app

The package family name does not correspond to an installed app

如果驗證使用者 SID 時發生錯誤If there was an error validating the user 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>