ARKit文档翻译 -- World Tracking(1)

Building Your First AR Experience

构建第一个AR体验

Create an app that runs an AR session and uses plane detection to place 3D content using SceneKit.

创建一个APP运行一个AR会话，使用平面检测来放置3dD内容使用SceneKit场景

Overview 概述

This sample app runs an ARKit world tracking session with content displayed in a SceneKit view. To demonstrate plane detection, the app visualizes both the estimated shape of and a bounding rectangle for each detected ARPlaneAnchor object. On supported devices, ARKit can recognize many types of real-world surfaces, so the app also labels each detected plane with identifying text.

这个app运行一个AR世界跟踪会话其中内容显示在SceneKit view中。为了演示平面检测，该应用程序为每个被检测到的ARPlaneAnchor对象可视化了估计形状和一个边框。在支持的设备上，ARKit可以识别许多类型的真实世界表面，因此该应用程序还用识别文本为每个检测到的平面贴上标签。

Configure and Run the AR Session 配置和运行AR会话

The ARSCNView class is a SceneKit view that includes an ARSession object that manages the motion tracking and image processing required to create an augmented reality (AR) experience. However, to run a session you must provide a session configuration.

ARSCNView类是一个SceneKit视图，它包含一个ARSession对象，用于管理创建增强现实(AR)体验所需的运动跟踪和图像处理。但是，要运行会话，必须提供会话配置。

645fa6d5-2d0c-4a8b-9c7a-3cf10c0d780b.png

The ARWorldTrackingConfiguration class provides high-precision motion tracking and enables features to help you place virtual content in relation to real-world surfaces. To start an AR session, create a session configuration object with the options you want (such as plane detection), then call the runWithConfiguration:options: method on the session object of your ARSCNView instance:

ARWorldTrackingConfiguration类提供了高精度的运动跟踪，并使功能能够帮助您将虚拟内容与真实世界的表面相关联。要启动一个AR会话，使用您想要的选项(例如平面检测)创建一个会话配置对象，然后在ARSCNView实例的会话对象上调用runWithConfiguration:options: method:

let configuration = ARWorldTrackingConfiguration()
/**
平面检测
没这句话不走 func renderer(_ renderer: SCNSceneRenderer, didAdd node: SCNNode, for anchor: ARAnchor);代理
*/
configuration.planeDetection = [.horizontal, .vertical]
sceneView.session.run(configuration)

Run your session only when the view that will display it is onscreen.
只有当将显示会话的视图在屏幕上时，才运行会话。

Important
If your app requires ARKit for its core functionality, use the arkit key in the UIRequiredDeviceCapabilities section of your app’s Info.plist file to make your app available only on devices that support ARKit. If AR is a secondary feature of your app, use the isSupported property to determine whether to offer AR-based features.

重要
如果您的应用程序的核心功能需要ARKit，请使用应用程序info.plist文件UIRequiredDeviceCapabilities部分中的ARKit键，使您的应用程序仅在支持ARKit的设备上可用。如果AR是应用程序的次要特性，请使用isSupported属性确定是否提供基于AR的特性。

Place 3D Content for Detected Planes 放置3D内容到检测到的平面上

After you’ve set up your AR session, you can use SceneKit to place virtual content in the view.

When plane detection is enabled, ARKit adds and updates anchors for each detected plane. By default, the ARSCNView class adds an SCNNode object to the SceneKit scene for each anchor. Your view’s delegate can implement the renderer:didAddNode:forAnchor: method to add content to the scene. When you add content as a child of the node corresponding to the anchor, the ARSCNView class automatically moves that content as ARKit refines its estimate of the plane’s position.

设置AR会话之后，可以使用SceneKit在视图中放置虚拟内容。
当启用平面检测时，ARKit为每个检测到的平面添加和更新锚点。默认情况下，ARSCNView类为每个锚点向SceneKit场景添加一个SCNNode对象。视图可实现代理方法renderer:didAddNode:forAnchor:来向场景添加内容。当您将内容作为与锚对应的节点的一个子节点添加时，ARSCNView类会自动移动该内容，因为ARKit会改进它对平面位置的估计。

func renderer(_ renderer: SCNSceneRenderer, didAdd node: SCNNode, for anchor: ARAnchor) {
    // Place content only for anchors found by plane detection.
    guard let planeAnchor = anchor as? ARPlaneAnchor else { return }
    
    // Create a custom object to visualize the plane geometry and extent.
    let plane = Plane(anchor: planeAnchor, in: sceneView)
    
    // Add the visualization to the ARKit-managed node so that it tracks
    // changes in the plane anchor as plane estimation continues.
    node.addChildNode(plane)
}

ARKit offers two ways to track the area of an estimated plane. A plane anchor’s geometry describes a convex polygon tightly enclosing all points that ARKit currently estimates to be part of the same plane (easily visualized using ARSCNPlaneGeometry). ARKit also provides a simpler estimate in a plane anchor’s extent and center, which together describe a rectangular boundary (easily visualized using SCNPlane).

ARKit提供两种跟踪估计平面区域的方法。平面锚的几何形状描述了一个凸多边形，它紧密地包围了ARKit目前估计属于同一平面的所有点(使用ARSCNPlaneGeometry可以很容易地可视化)。ARKit还提供了对平面锚的范围和中心的更简单的估计，它们共同描述了一个矩形边界(使用SCNPlane很容易可视化)。

// Create a mesh to visualize the estimated shape of the plane.
guard let meshGeometry = ARSCNPlaneGeometry(device: sceneView.device!)
    else { fatalError("Can't create plane geometry") }
meshGeometry.update(from: anchor.geometry)
meshNode = SCNNode(geometry: meshGeometry)

// Create a node to visualize the plane's bounding rectangle.
let extentPlane: SCNPlane = SCNPlane(width: CGFloat(anchor.extent.x), height: CGFloat(anchor.extent.z))
extentNode = SCNNode(geometry: extentPlane)
extentNode.simdPosition = anchor.center

// `SCNPlane` is vertically oriented in its local coordinate space, so
// rotate it to match the orientation of `ARPlaneAnchor`.
extentNode.eulerAngles.x = -.pi / 2

ARKit continually updates its estimates of each detected plane’s shape and extent. To show the current estimated shape for each plane, this sample app also implements the renderer:didUpdateNode:forAnchor: method, updating the ARSCNPlaneGeometry and SCNPlane objects to reflect the latest information from ARKit.
ARKit不断更新其对每个检测到的平面形状和范围的估计。为了显示每个平面的当前估计形状，这个示例应用程序还实现了renderer:didUpdateNode:forAnchor:方法，更新了ARSCNPlaneGeometry和SCNPlane对象，以反映来自ARKit的最新信息。

func renderer(_ renderer: SCNSceneRenderer, didUpdate node: SCNNode, for anchor: ARAnchor) {
    // Update only anchors and nodes set up by `renderer(_:didAdd:for:)`.
    guard let planeAnchor = anchor as? ARPlaneAnchor,
        let plane = node.childNodes.first as? Plane
        else { return }
    
    // Update ARSCNPlaneGeometry to the anchor's new estimated shape.
    if let planeGeometry = plane.meshNode.geometry as? ARSCNPlaneGeometry {
        planeGeometry.update(from: planeAnchor.geometry)
    }

    // Update extent visualization to the anchor's new bounding rectangle.
    if let extentGeometry = plane.extentNode.geometry as? SCNPlane {
        extentGeometry.width = CGFloat(planeAnchor.extent.x)
        extentGeometry.height = CGFloat(planeAnchor.extent.z)
        plane.extentNode.simdPosition = planeAnchor.center
    }
    
    // Update the plane's classification and the text position
    if #available(iOS 12.0, *),
        let classificationNode = plane.classificationNode,
        let classificationGeometry = classificationNode.geometry as? SCNText {
        let currentClassification = planeAnchor.classification.description
        if let oldClassification = classificationGeometry.string as? String, oldClassification != currentClassification {
            classificationGeometry.string = currentClassification
            classificationNode.centerAlign()
        }
    }
    
}

在iPhone XS、iPhone XS Max和iPhone XR上，ARKit还可以对检测到的平面进行分类，报告该平面代表哪种常见的现实世界表面(例如，桌子、地板或墙壁)。在本例中，renderer:didUpdateNode:forAnchor:方法还显示和更新一个文本标签来显示该信息。