A view for displaying AR experiences that augment the camera view with 3D SceneKit content.
显示使用3D SceneKit内容增强相机视图的AR体验的视图。

Overview

The ARSCNView class provides the easiest way to create augmented reality experiences that blend virtual 3D content with a device camera view of the real world. When you run the view's provided ARSession object:

The view automatically renders the live video feed from the device camera as the scene background.

The world coordinate system of the view's SceneKit scene directly responds to the AR world coordinate system established by the session configuration.

The view automatically moves its SceneKit camera to match the real-world movement of the device.

Because ARKit automatically matches SceneKit space to the real world, placing a virtual object such that it appears to maintain a real-world position requires only setting that object's SceneKit position appropriately. (See Providing 3D Virtual Content with SceneKit.)

You don't necessarily need to use the ARAnchor class to track positions of objects you add to the scene, but by implementing ARSCNViewDelegate methods, you can add SceneKit content to any anchors that are automatically detected by ARKit.

概述

ARSCNView类提供了最简单的方法来创建增强现实体验，将虚拟3D内容与真实世界的设备相机视图融合在一起。当你运行视图的提供的ARSession对象时：

该视图自动将设备摄像机的实时视频馈送呈现为场景背景。

视图的SceneKit场景的世界坐标系直接响应由Session配置建立的AR世界坐标系。

该视图会自动移动其SceneKit相机以匹配设备的实际移动。

由于ARKit会自动将SceneKit空间与现实世界相匹配，因此放置虚拟对象以使其看起来保持真实世界的位置仅需要适当地设置该对象的SceneKit位置。 （请参阅使用SceneKit提供3D虚拟内容。）

您不一定需要使用ARAnchor类来跟踪添加到场景中的对象的位置，但通过实现ARSCNViewDelegate方法，可以将SceneKit内容添加到ARKit自动检测到的任何锚点。

                                   First Steps

Providing 3D Virtual Content with SceneKit
Use SceneKit to add realistic three-dimensional objects to your AR experience.
使用SceneKit为您的AR体验添加逼真的三维物体。

Overview

Because ARKit automatically matches SceneKit space to the real world, placing a virtual object so that it appears to maintain a real-world position requires that you set the object's SceneKit position appropriately. For example, in a default configuration, the following code places a 10-centimeter cube 20 centimeters in front of the camera's initial position:

概述

由于ARKit自动将SceneKit空间与现实世界相匹配，放置虚拟对象以使其看起来保持真实世界的位置，因此需要适当地设置对象的SceneKit位置。 例如，在默认配置下，以下代码在摄像机初始位置的前面放置一个距离摄像机20厘米20厘米的10厘米立方体：

The code above places an object directly in the view’s SceneKit scene. The object automatically appears to track a real-world position because ARKit matches SceneKit space to real-world space.

Alternatively, you can use the ARAnchor class to track real-world positions, either by creating anchors yourself and adding them to the session or by observing anchors that ARKit automatically creates. For example, when plane detection is enabled, ARKit adds and updates anchors for each detected plane. To add visual content for these anchors, implement ARSCNViewDelegate methods such as the following:

上面的代码将一个对象直接放置在视图的SceneKit场景中。 该对象自动显示为跟踪真实世界的位置，因为ARKit将SceneKit空间与实际空间相匹配。

或者，您可以使用ARAnchor类来跟踪真实世界的位置，既可以通过自己创建锚点并将其添加到会话中，也可以通过观察ARKit自动创建的锚点来实现。 例如，启用平面检测功能后，ARKit会为每个检测到的平面添加并更新锚点。 要为这些锚点添加可视内容，请实施ARSCNViewDelegate方法，如下所示：

Follow Best Practices for Designing 3D Assets 

Use the SceneKit physically based lighting model for materials for a more realistic appearance. (See the SCNMaterial class and the Badger: Advanced Rendering in SceneKit sample code project.)

Bake ambient occlusion shading so that objects appear properly lit in a wide variety of scene lighting conditions.

If you create a virtual object that you intend to place on a real-world flat surface in AR, include a transparent plane with a soft shadow texture below the object in your 3D asset.

遵循设计3D Asset的最佳实践

将SceneKit基于物理的照明模型用于材料以获得更逼真的外观。 （请参阅SceneKit示例代码项目中的SCNMaterial类和Badger：高级渲染。）

烘烤环境遮挡阴影，使物体在各种场景照明条件下正常点亮。

如果您创建了一个虚拟对象，您打算将其放置在AR中的真实世界平面上，请在3D素材资源中的对象下方包含一个透明平面，并在其中包含柔和阴影纹理。

session
The AR session that manages motion tracking and camera image processing for the view's contents.
AR Session管理视图内容的运动跟踪和摄像头图像处理。

Discussion

A view creates its own session object; use this property to access and configure the view's session.

讨论

视图创建自己的Session对象; 使用此属性来访问和配置视图的Session。

scene
The SceneKit scene to be displayed in the view.
SceneKit场景将显示在视图中。

Discussion

Note

Unlike the parent SCNView class, an ARSCNView object requires a non-nil scene to display.

讨论

注意

与父SCNView类不同，ARSCNView对象需要显示非零场景。

                      Responding to AR Updates

delegate
An object you provide to mediate synchronization of the view's AR scene information with SceneKit content.
您提供的一个对象，用于调解视图的AR场景信息与SceneKit内容的同步

ARSCNViewDelegate
Methods you can implement to mediate the automatic synchronization of SceneKit content with an AR session.
您可以实现的方法来调解SceneKit内容与AR Session的自动同步。

Overview

Implement this protocol to provide SceneKit content corresponding to ARAnchor objects tracked by the view's AR session, or to manage the view's automatic updating of such content.

This protocol extends the ARSessionObserver protocol, so your session delegate can also implement those methods to respond to changes in session status.

概述

实现此协议以提供与由视图的ARSession跟踪的ARAnchor对象相对应的SceneKit内容，或管理视图对此类内容的自动更新。

这个协议扩展了ARSessionObserver协议，所以你的会话委托也可以实现这些方法来响应会话状态的变化。

Handling Content Updates

renderer:nodeForAnchor:
Asks the delegate to provide a SceneKit node corresponding to a newly added anchor.
渲染：nodeForAnchor：请求委托提供与新添加的锚相对应的SceneKit节点。

Parameters

renderer
The ARSCNView object rendering the scene.
ARSCNView对象呈现场景。

anchor
The anchor for which a node is requested.
请求节点的锚点。

Return Value

A new SceneKit node, which ARKit will add to the scene and update to follow its corresponding AR anchor.

一个新的SceneKit节点，ARKit将添加到场景并更新以跟随其相应的AR定位点。

Discussion

Depending on the session configuration, ARKit may automatically add anchors to a session. ARKit also calls this method to provide visual content for any ARAnchor objects you manually add using the session's addAnchor: method.

You can implement this method to provide a new SCNNode object (or instance of an SCNNodesubclass) containing any attachments you plan to use as a visual representation of the anchor. Note that ARKit controls the node's visibility and its transform property, so you may find it useful to add child nodes or adjust the node's pivot property to maintain any changes to position or orientation that you make.

If you return nil from this method, no node is added to the scene.

Alternatively, if you do not implement this method, ARKit creates an empty node, and you can implement the renderer:didAddNode:forAnchor: method instead to provide visual content by attaching it to that node.

讨论

根据Session配置的不同，ARKit可能会自动将锚定添加到Session中。 ARKit还调用此方法为使用Session的addAnchor：方法手动添加的任何ARAnchor对象提供可视内容。

您可以实现此方法来提供一个新的SCNNode对象（或SCNNode子类的实例），其中包含您打算用作锚的可视表示的附件。 请注意，ARKit控制节点的可见性及其变换属性，所以您可能会发现添加子节点或调整节点的透视属性以保持对所做位置或方向的任何更改很有用。

如果您从此方法返回nil，则不会将节点添加到场景中。

或者，如果您未实现此方法，ARKit将创建一个空节点，并且您可以实现渲染器：didAddNode：forAnchor：方法，以通过将其附加到该节点来提供可视内容。

renderer:didAddNode:forAnchor:
Tells the delegate that a SceneKit node corresponding to a new AR anchor has been added to the scene.
告诉委托人已将与新的AR锚相对应的SceneKit节点添加到场景中。

Parameters

renderer
The ARSCNView object rendering the scene.
ARSCNView对象呈现场景。

node
The newly added SceneKit node.
新添加的SceneKit节点。

anchor
The AR anchor corresponding to the node.
AR节点对应的AR节点。

Discussion

Depending on the session configuration, ARKit may automatically add anchors to a session. The view calls this method once for each new anchor. ARKit also calls this method to provide visual content for any ARAnchor objects you manually add using the session's addAnchor: method.

You can provide visual content for the anchor by attaching geometry (or other SceneKit features) to this node or by adding child nodes.

Alternatively, you can implement the renderer:nodeForAnchor: method to create your own node (or instance of an SCNNode subclass) for an anchor.

讨论

根据Session配置的不同，ARKit可能会自动将锚定添加到Sessopm中。 该视图为每个新的锚点调用一次该方法。 ARKit还调用此方法为使用Session的addAnchor：方法手动添加的任何ARAnchor对象提供可视内容。

您可以通过将几何图元（或其他SceneKit特征）附加到此节点或通过添加子节点来为锚点提供可视内容。

或者，您可以实现渲染器：nodeForAnchor：方法为锚点创建自己的节点（或SCNNode子类的实例）。

renderer:willUpdateNode:forAnchor:
Tells the delegate that a SceneKit node's properties will be updated to match the current state of its corresponding anchor.
告诉委托人SceneKit节点的属性将被更新以匹配其相应锚的当前状态。Parameters

Parameters

renderer
TheARSCNViewobject rendering the scene.
ARSCNView对象呈现场景。

node
The newly added SceneKit node.
新添加的SceneKit节点。

anchor
The AR anchor corresponding to the node.
AR节点对应的AR节点

Discussion

Depending on the session configuration, ARKit may automatically update anchors in a session. The view calls this method once for each updated anchor.

讨论

根据Session配置的不同，ARKit可能会自动更新会话中的锚点。 该视图为每个更新的锚点调用一次该方法。

renderer:didUpdateNode:forAnchor:
Tells the delegate that a SceneKit node's properties have been updated to match the current state of its corresponding anchor.
告诉委托人SceneKit节点的属性已更新以匹配其相应锚的当前状态。

Parameters

renderer
TheARSCNViewobject rendering the scene.
ARSCNView对象呈现场景。

node
The newly added SceneKit node.
新添加的SceneKit节点。

anchor
The AR anchor corresponding to the node.
AR节点对应的AR节点

Discussion

Depending on the session configuration, ARKit may automatically update anchors in a session. The view calls this method once for each updated anchor.

讨论

根据Session配置的不同，ARKit可能会自动更新Session中的锚点。 该视图为每个更新的锚点调用一次该方法。

renderer:didRemoveNode:forAnchor:
Tells the delegate that the SceneKit node corresponding to a removed AR anchor has been removed from the scene.
告诉委托人已经从场景中移除了与已移除的AR锚点对应的SceneKit节点。

Parameters

renderer
TheARSCNViewobject rendering the scene.
ARSCNView对象呈现场景。

node
The newly added SceneKit node.
新添加的SceneKit节点。

anchor
The AR anchor corresponding to the node.
AR节点对应的AR节点

Discussion

Depending on the session configuration, ARKit may automatically remove anchors from a session. The view calls this method once for each removed anchor.

讨论

根据Session配置的不同，ARKit可能会自动从Session中删除锚点。 该视图为每个已移除的锚点调用一次该方法。

Inherits From ARSessionObserver,  SCNSceneRendererDelegate

                 Hit Testing for Real-World Surfaces

- hitTest:types:
Searches for real-world objects or AR anchors in the captured camera image corresponding to a point in the SceneKit view.
在捕获的摄像机图像中搜索与SceneKit视图中的点相对应的真实世界对象或AR锚。

Parameters

point
A point in the 2D coordinate system of the view.
视图2D坐标系中的一个点。

types
The types of hit-test result to search for.
要搜索的命中测试结果的类型。

Return Value

A list of results, sorted from nearest to farthest (in distance from the camera).

返回值

结果列表，从最近到最远（与相机的距离）排序。

Discussion

Hit testing searches for real-world objects or surfaces detected through the AR session's processing of the camera image. A 2D point in the view's coordinate system can refer to any point along a 3D line that starts at the device camera and extends in a direction determined by the device orientation and camera projection. This method searches along that line, returning all objects that intersect it in order of distance from the camera.

讨论

命中测试搜索通过ARSession处理相机图像检测到的真实世界对象或表面。 视图坐标系中的二维点可以指沿着三维线上的任意点，该三维线始于设备相机，并沿着由设备方向和相机投影确定的方向延伸。 该方法沿着该线搜索，按距离相机的顺序返回与其相交的所有对象。

Note

This method searches for AR anchors and real-world objects detected by the AR session, not SceneKit content displayed in the view. To search for SceneKit objects, use the view's hitTest:options: method instead.

注意

此方法搜索由ARSession检测到的AR锚点和真实世界对象，而不是视图中显示的SceneKit内容。 要搜索SceneKit对象，请改为使用视图的hitTest：options：方法。

             Mapping Content to Real-World Positions

- anchorForNode:
Returns the AR anchor associated with the specified SceneKit node, if any.
返回与指定的SceneKit节点关联的AR定位点（如果有）。

Parameters

node
A SceneKit node in the view's scene.
场景中的SceneKit节点。

Return Value

The ARAnchor object tracking the node, or nil if the node is not associated with an anchor or not in the view's scene.

返回值

ARAnchor对象跟踪节点，或者如果节点未与视图的场景中的锚点关联，则为零。

- nodeForAnchor:
Returns the SceneKit node associated with the specified AR anchor, if any.
返回与指定的AR锚点相关的SceneKit节点（如果有的话）。

Parameters

anchor
An anchor in the view's AR session.
视图的ARSession中的一个锚点。

Return Value

The node whose position in the AR scene the anchor tracks, or nil if the anchor has no associated node or is not in the view's AR session.

返回值

在AR场景中锚点跟踪的节点，或者如果锚点没有关联节点或不在视图的ARSession中，则为零。

                       Managing Scene Lighting

automaticallyUpdatesLighting
A Boolean value that specifies whether ARKit creates and updates SceneKit lights in the view's scene.
一个布尔值，指定ARKit是否在视图的场景中创建并更新SceneKit指示灯。

Discussion

If this value is YES (the default), the view automatically creates one or more SCNLight objects, adds them to the scene, and updates their properties to reflect estimated lighting information from the camera scene. Set this value to NO if you want to directly control all lighting in the SceneKit scene.

讨论

如果此值为YES（默认值），视图会自动创建一个或多个SCNLight对象，将它们添加到场景中，并更新其属性以反映来自相机场景的估计光照信息。 如果要直接控制SceneKit场景中的所有照明，请将此值设置为NO。

                              Debugging AR Display

ARSCNDebugOptions
Options for drawing overlay content to aid debugging of AR tracking in a SceneKit view.
用于绘制叠加内容的选项，以帮助在SceneKit视图中调试AR追踪。

Discussion

To use these debugging overlays, add them to the option set in the view's debugOptionsproperty (inherited from the SCNView class).

讨论

要使用这些调试覆盖图，请将它们添加到视图的debugOptions属性中的选项集（从SCNView类继承）。

Inherits From  SCNView