arkit-visionos-developer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ARKit visionOS Developer

ARKit visionOS 开发者指南

Description and Goals

说明与目标

This skill provides comprehensive guidance for implementing ARKit-powered features on visionOS. ARKit on visionOS uses

ARKitSession

with data providers to access world tracking, hand tracking, plane detection, scene reconstruction, and other spatial data, which can then be bridged into RealityKit content.

本技能为在visionOS上实现基于ARKit的功能提供全面指导。visionOS上的ARKit通过

ARKitSession

搭配数据提供器来获取世界跟踪、手部跟踪、平面检测、场景重建等空间数据，并可将这些数据与RealityKit内容进行桥接。

Goals

目标

Enable developers to set up and manage ARKitSession on visionOS
Guide proper authorization handling for ARKit data providers
Help developers choose and configure appropriate data providers
Support anchor processing and RealityKit integration
Ensure proper lifecycle management of ARKit sessions

帮助开发者在visionOS上设置和管理ARKitSession
指导正确处理ARKit数据提供器的授权
协助开发者选择和配置合适的数据提供器
支持锚点处理与RealityKit集成
确保ARKit会话的生命周期管理规范

What This Skill Should Do

本技能的适用场景

When implementing ARKit features on visionOS, this skill should:

Guide ARKitSession setup - Help you create and manage long-lived ARKitSession instances
Handle authorization - Show how to request and check authorization for required data types
Select data providers - Help you choose the right providers (world tracking, hand tracking, plane detection, etc.)
Process anchors - Demonstrate how to consume anchor updates and map them to RealityKit entities
Manage lifecycle - Ensure proper session start/stop and task cancellation
Bridge to RealityKit - Show how to integrate ARKit anchors with RealityKit content

Load the appropriate reference file from the tables below for detailed usage, code examples, and best practices.

在visionOS上实现ARKit功能时，本技能可用于：

指导ARKitSession设置 - 帮助你创建和管理长期存在的ARKitSession实例
处理授权 - 展示如何请求和检查所需数据类型的授权
选择数据提供器 - 协助你选择合适的提供器（世界跟踪、手部跟踪、平面检测等）
处理锚点 - 演示如何消费锚点更新并将其映射到RealityKit实体
管理生命周期 - 确保会话正确启动/停止以及任务取消
桥接到RealityKit - 展示如何将ARKit锚点与RealityKit内容集成

从下方表格中加载对应的参考文件，获取详细用法、代码示例和最佳实践。

Quick Start Workflow

快速开始工作流

Add

NSWorldSensingUsageDescription

and

NSHandsTrackingUsageDescription

Info.plist

as needed.

Ensure the experience runs in a Full Space (ARKit data is unavailable in Shared Space).
Create a long-lived
```
ARKitSession
```
and the data providers you need.
Request authorization for provider-required data types before running the session.
Run the session with your providers and observe
```
anchorUpdates
```
streams.
Map anchors to RealityKit entities and keep state in a model layer.
Observe
```
ARKitSession.events
```
for authorization changes and errors.
Stop the session and cancel tasks when leaving the immersive space.

根据需要在

Info.plist

中添加

NSWorldSensingUsageDescription

和

NSHandsTrackingUsageDescription

。

确保体验在Full Space中运行（Shared Space中无法获取ARKit数据）。
创建一个长期存在的
```
ARKitSession
```
以及所需的数据提供器。
在运行会话前，请求提供器所需数据类型的授权。
搭配提供器运行会话，并监听
```
anchorUpdates
```
流。
将锚点映射到RealityKit实体，并在模型层维护状态。
监听
```
ARKitSession.events
```
以获取授权变更和错误信息。
离开沉浸式空间时，停止会话并取消任务。

Information About the Skill

技能相关信息

Core Concepts

核心概念

ARKitSession Lifecycle

ARKitSession 生命周期

Keep a strong reference to the session; call
```
run(_:)
```
with providers, stop on teardown.
Sessions stop automatically on deinit, so maintain references throughout the immersive experience.

保持对会话的强引用；调用
```
run(_:)
```
方法并传入提供器，在销毁时停止会话。
会话会在销毁时自动停止，因此在整个沉浸式体验期间都要维持引用。

Authorization

授权

Use

requestAuthorization(for:)

queryAuthorization(for:)

and handle denied states gracefully.

Request authorization before running the session with providers that require it.

使用
```
requestAuthorization(for:)
```
或
```
queryAuthorization(for:)
```
，并优雅处理授权被拒绝的情况。
在运行带有需授权提供器的会话前，先请求授权。

Data Providers

数据提供器

Choose providers for world tracking, plane detection, scene reconstruction, and hand tracking based on the feature set.
Providers expose
```
anchorUpdates
```
streams that you consume to process anchors.

根据功能需求选择世界跟踪、平面检测、场景重建、手部跟踪等提供器。
提供器会暴露
```
anchorUpdates
```
流，你可以消费该流来处理锚点。

Anchors and Updates

锚点与更新

Consume provider
```
anchorUpdates
```
and reconcile added, updated, and removed anchors.
Normalize anchor IDs to your own state model for reliable entity updates.

消费提供器的
```
anchorUpdates
```
流，处理锚点的添加、更新和移除操作。
将锚点ID标准化到你自己的状态模型中，以实现可靠的实体更新。

RealityKit Bridge

RealityKit 桥接

Use
```
ARKitAnchorComponent
```
to inspect backing ARKit data on entities when needed.
Treat ARKit streams as authoritative and keep rendering logic in RealityKit.

必要时使用
```
ARKitAnchorComponent
```
检查实体背后的ARKit数据。
将ARKit流视为权威数据源，渲染逻辑保留在RealityKit中。

Implementation Patterns

实现模式

Prefer one session per immersive experience and reuse providers when possible.
Normalize anchor IDs to your own state model for reliable entity updates.
Treat ARKit streams as authoritative and keep rendering logic in RealityKit.

每个沉浸式体验优先使用一个会话，并尽可能复用提供器。
将锚点ID标准化到你自己的状态模型中，以实现可靠的实体更新。
将ARKit流视为权威数据源，渲染逻辑保留在RealityKit中。

Provider References

提供器参考

Provider	When to Use
`WorldTrackingProvider`	When tracking device position and orientation in 3D space.
`HandTrackingProvider`	When tracking hand poses and gestures for interaction.
`PlaneDetectionProvider`	When detecting horizontal and vertical surfaces (floors, walls, tables).
`SceneReconstructionProvider`	When creating detailed 3D mesh reconstructions of the environment.
`ImageTrackingProvider`	When tracking known images or reference objects.
`ObjectTrackingProvider`	When tracking 3D objects in the environment.
`RoomTrackingProvider`	When tracking room boundaries and room-scale experiences.
`AccessoryTrackingProvider`	When tracking Apple Vision Pro accessories.
`BarcodeDetectionProvider`	When detecting and reading barcodes in the environment.
`CameraFrameProvider`	When accessing raw camera frames for custom processing.
`CameraRegionProvider`	When accessing camera frames from specific regions.
`EnvironmentLightEstimationProvider`	When estimating ambient lighting conditions.
`SharedCoordinateSpaceProvider`	When sharing coordinate spaces across multiple sessions.
`StereoPropertiesProvider`	When accessing stereo camera properties.

提供器	使用场景
`WorldTrackingProvider`	需在3D空间中跟踪设备位置和姿态时使用。
`HandTrackingProvider`	需跟踪手部姿态和手势以实现交互时使用。
`PlaneDetectionProvider`	需检测水平和垂直表面（地面、墙壁、桌子）时使用。
`SceneReconstructionProvider`	需创建环境的精细3D网格重建时使用。
`ImageTrackingProvider`	需跟踪已知图像或参考对象时使用。
`ObjectTrackingProvider`	需跟踪环境中的3D对象时使用。
`RoomTrackingProvider`	需跟踪房间边界和实现房间尺度体验时使用。
`AccessoryTrackingProvider`	需跟踪Apple Vision Pro配件时使用。
`BarcodeDetectionProvider`	需检测和读取环境中的条形码时使用。
`CameraFrameProvider`	需访问原始相机帧以进行自定义处理时使用。
`CameraRegionProvider`	需访问特定区域的相机帧时使用。
`EnvironmentLightEstimationProvider`	需估算环境光照条件时使用。
`SharedCoordinateSpaceProvider`	需在多个会话之间共享坐标空间时使用。
`StereoPropertiesProvider`	需访问立体相机属性时使用。

General ARKit Patterns

通用ARKit模式

Reference	When to Use
`REFERENCE.md`	When implementing ARKit session setup, authorization, and general provider patterns.

参考文档	使用场景
`REFERENCE.md`	需实现ARKit会话设置、授权和通用提供器模式时使用。

Pitfalls and Checks

常见陷阱与检查项

Do not use
```
ARView
```
on visionOS; use
```
RealityView
```
and
```
ARKitSession
```
instead.
Do not expect ARKit data in Shared Space; use Full Space only.
Do not block the main actor while awaiting provider updates.
Do not drop session references; ARKit stops sessions on deinit.

不要在visionOS上使用
```
ARView
```
；请改用
```
RealityView
```
和
```
ARKitSession
```
。
不要期望在Shared Space中获取ARKit数据；仅在Full Space中使用。
等待提供器更新时不要阻塞主actor。
不要丢弃会话引用；ARKit会在会话销毁时停止它。