混合现实空间数据包装程序文档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

混合现实空间数据包装器工具通过两步导出和导入过程将目标应用的空间数据从一台 PC 复制到另一台 PC。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. 在导入时锁定地图 (通过预览体验) 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 Administrator-Mode 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>    

从设备导出映射会生成两个 mapx 文件:获取 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>