混合现实空间数据打包器文档

  • 项目

注意

已弃用

从 2020/8/1 开始，此工具已弃用，不再在任何平台上运行。 建议改为使用设备门户中的映射管理器工具。

此工具及其操作按原样提供。 它有可能发生更改，且不会另行通知，并且可能与将来的 Windows 或 Windows Mixed Reality HMD 不兼容。

下载

在此处下载 MixedRealitySpatialDataPackager

设备支持

功能 HoloLens（第一代） HoloLens 2 沉浸式头戴显示设备
混合现实空间数据打包器 ❌ ❌ ✔

快速入门

混合现实空间数据打包器工具通过两步的导出和导入过程，将目标应用的空间数据从一台电脑复制到另一台电脑。 该工具需要使用管理员权限运行，并会在导入时删除现有空间数据。 导出操作不会改变现有空间数据。

关键要求和限制：

  1. 工具需要使用管理员权限运行
  2. 如果在运行该工具后混合现实门户不稳定，可能需要重启电脑
  3. 如果遇到空间数据版本不匹配或不兼容的情况时，工具不会运行
  4. 工具将在导入时擦除现有空间数据
  5. 如果导入过程失败，将无法还原以前的数据，除非之前通过导出进行了备份
  6. 导入功能的质量取决于空间映射数据的“只读”模式

映射最佳做法

  1. 从控制面板清除现有映射（“设置”->“混合现实”->“环境”->“清除环境数据”）
  2. 确保有足够的照明来进行良好的追踪，如果运行锁定映射模式，请尽量维持相同的照明
  3. 如果可能，请避免深色阴影区域旁边出现高照明区域，保持较小的照明动态范围
  4. 最小化空白无纹理表面，例如，将一系列不同的海报放置在白色墙上
  5. 映射场景中那些不存在动态对象（例如移动人员）的空间
  6. 导入时锁定映射（通过 Insider Preview 实现）
  7. 当追踪质量下降和/或环境发生变化（照明或对象布局变化）时，解锁映射并重新扫描环境

使用助手脚本运行混合现实空间数据打包器

我们提供了运行映射打包器工具的 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>

从设备导出映射时会生成两个 mapx 文件：het.mapx 和 sa.mapx。 在导出过程中，除指定应用和用户创建的边界（如果存在）的空间定位点外，所有其他空间定位点都将被删除。 源包系列名称必须与现有的已安装应用匹配，否则 exe 将失败。

如何使用 MixedRealitySpatialDataPackager.exe 导入

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

导入会删除现有空间数据，并将其替换为指定目录中的数据。 输入的应用名称将指定（比如）应为其导入空间定位点的目标应用的包名称，目标用户 SID 则指定应有权访问导入的空间定位点的用户。 目标包系列名称和用户 ID 必须与电脑上的现有值匹配，否则 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>