Detect known 2D images in the user’s environment, and use their positions to place AR content.

檢測用戶環(huán)境中的已知2D圖像，并使用它們的位置放置AR內容。

Overview

Many AR experiences can be enhanced by using known features of the user’s environment to trigger the appearance of virtual content. For example, a museum app might show a virtual curator when the user points their device at a painting, or a board game might place virtual pieces when the player points their device at a game board. In iOS 11.3 and later, you can add such features to your AR experience by enabling image recognition in ARKit: Your app provides known 2D images, and ARKit tells you when and where those images are detected during an AR session.

This example app looks for any of the several reference images included in the app’s asset catalog. When ARKit detects one of those images, the app shows a message identifying the detected image and a brief animation showing its position in the scene.

概述

通過使用用戶環(huán)境的已知特征來觸發(fā)虛擬內容的出現(xiàn)，可以增強許多AR體驗。 例如，當用戶將他們的設備指向繪畫時，博物館應用可以顯示虛擬館長，或者當玩家將他們的設備指向游戲板時，棋盤游戲可以放置虛擬件。 在iOS 11.3和更高版本中，您可以通過在ARKit中啟用圖像識別功能將這些功能添加到AR體驗中：您的應用程序提供已知的2D圖像，ARKit會告訴您在AR會話期間何時何地檢測到這些圖像。

此示例應用程序查找應用程序資產目錄中包含的任意幾個參考圖像。 當ARKit檢測到其中一個圖像時，該應用程序會顯示一條消息，標識檢測到的圖像以及顯示其在場景中的位置的簡短動畫。

Important

The images included with this sample are designed to fit the screen sizes of various Apple devices. To try the app using these images, choose an image that fits any spare device you have, and display the image full screen on that device. Then run the sample code project on a different device, and point its camera at the device displaying the image. Alternatively, you can add your own images; see the steps in Provide Your Own Reference Images, below.

重要

此示例中包含的圖像旨在適合各種Apple設備的屏幕尺寸。 要嘗試使用這些圖像的應用程序，請選擇適合您的任何備用設備的圖像，并在該設備上全屏顯示圖像。 然后在其他設備上運行示例代碼項目，并將其相機指向顯示圖像的設備。 或者，您可以添加自己的圖像; 請參閱下面提供您自己的參考圖片中的步驟。

Enable Image Detection

Image recognition is an add-on feature for world-tracking AR sessions. (For more details on world tracking, see?Building Your First AR Experience.)

To enable image detection:

1.Load one or more?ARReferenceImage?resources from your app’s asset catalog.

2.Create a world-tracking configuration and pass those reference images to its?detectionImages?property.

3.Use the?runWithConfiguration:options:?method to run a session with your configuration.

The code below shows how the sample app performs these steps when starting or restarting the AR experience.

啟用圖像檢測

圖像識別是世界追蹤AR Session的附加功能。 （有關世界追蹤的更多詳情，請參閱創(chuàng)建您的第一次AR體驗。）

要啟用圖像檢測：

1.從應用的Asset目錄中加載一個或多個ARReferenceImage資源。

2.創(chuàng)建一個世界跟蹤配置，并將這些參考圖像傳遞給它的detectionImages屬性。

3.使用runWithConfiguration：options：方法與您的配置一起運行Session。

下面的代碼顯示了示例應用程序在啟動或重新啟動AR體驗時如何執(zhí)行這些步驟。

Visualize Image Detection Results

When ARKit detects one of your reference images, the session automatically adds a corresponding?ARImageAnchor?to its list of anchors. To respond to an image being recognized, implement an appropriate?ARSessionDelegate,?ARSKViewDelegate, or?ARSCNViewDelegate?method that reports the new anchor being added to the session. (This example app uses the?renderer:didAddNode:forAnchor:?method for the code shown below.)

To use the detected image as a trigger for AR content, you’ll need to know its position and orientation, its size, and which reference image it is. The anchor’s inherited?transformproperty provides position and orientation, and its?referenceImage?property tells you which?ARReferenceImage?object was detected. If your AR content depends on the extent of the image in the scene, you can then use the reference image’s?physicalSize?to set up your content, as shown in the code below.

可視化圖像檢測結果

當ARKit檢測到一個參考圖像時，Session會自動將相應的ARImageAnchor添加到其錨點列表中。 要響應正在識別的圖像，請實施適當?shù)腁RSessionDelegate，ARSKViewDelegate或ARSCNViewDelegate方法，以報告添加到Session中的新錨點。 （這個示例應用程序對下面顯示的代碼使用渲染器：didAddNode：forAnchor：方法。）

要將檢測到的圖像用作AR內容的觸發(fā)器，您需要知道它的位置和方向，大小以及它是哪個參考圖像。 該錨點的繼承transformproperty提供了位置和方向，其referenceImage屬性告訴你哪個ARReferenceImage對象被檢測到。 如果您的AR內容取決于場景中圖像的范圍，則可以使用參考圖像的physicalSize設置您的內容，如下面的代碼所示。

Provide Your Own Reference Images

To use your own images for detection (in this sample or in your own project), you’ll need to add them to your asset catalog in Xcode.

Open your project’s asset catalog, then use the Add button (+) to add a new AR resource group.

Drag image files from the Finder into the newly created resource group.

For each image, use the inspector to describe the physical size of the image as you’d expect to find it in the user’s real-world environment, and optionally include a descriptive name for your own use.

提供您自己的參考圖像

要使用自己的圖像進行檢測（在本示例中或在您自己的項目中），您需要將它們添加到Xcode中的Asset目錄中。

打開項目的Asset目錄，然后使用添加按鈕（+）添加新的AR資源組。

將Finder中的圖像文件拖到新創(chuàng)建的資源組中。

對于每幅圖像，請使用檢查員來描述圖像的物理尺寸，正如您期望在用戶的真實環(huán)境中找到它的一樣，并且可以選擇包含一個供您自己使用的描述性名稱。

Note

Put all the images you want to look for in the same session into a resource group. Use separate resource groups to hold sets of images for use in separate sessions. For example, an art museum app might use separate sessions (and thus separate resource groups) for recognizing paintings in different wings of the museum.

注意

將您想要在同一個會話中查找的所有圖像放入資源組中。 使用單獨的資源組來保存各組圖像以便在單獨的會話中使用。 例如，美術館的應用程序可能會使用單獨的Session（并因此分開資源組）來識別博物館不同側翼的繪畫。

Be aware of image detection capabilities.?Choose, design, and configure reference images for optimal reliability and performance:

Enter the physical size of the image in Xcode as accurately as possible. ARKit relies on this information to determine the distance of the image from the camera. Entering an incorrect physical size will result in an?ARImageAnchor?that’s the wrong distance from the camera.

When you add reference images to your asset catalog in Xcode, pay attention to the quality estimation warnings Xcode provides. Images with high contrast work best for image detection.

Use only images on flat surfaces for detection. If an image to be detected is on a nonplanar surface, like a label on a wine bottle, ARKit might not recognize it at all, or might create an image anchor at the wrong location.

Consider how your image appears under different lighting conditions. If an image is printed on glossy paper or displayed on a device screen, reflections on those surfaces can interfere with detection.

了解圖像檢測功能。選擇，設計和配置參考圖像以獲得最佳的可靠性和性能：

盡可能準確地在Xcode中輸入圖像的物理尺寸。 ARKit依靠此信息來確定圖像距相機的距離。輸入不正確的物理尺寸將導致ARImageAnchor與相機距離不正確。

將參考圖像添加到Xcode中的Asset目錄時，請注意Xcode提供的質量估算警告。具有高對比度的圖像最適合圖像檢測。

只使用平面上的圖像進行檢測。如果要檢測的圖像位于非平面表面上，例如酒瓶上的標簽，則ARKit可能根本無法識別它，或者可能會在錯誤的位置創(chuàng)建圖像定位點。

考慮你的圖像在不同的照明條件下如何顯示。如果圖像打印在光面紙上或顯示在設備屏幕上，那么這些表面上的反射會干擾檢測。

Apply Best Practices

This example app simply visualizes where ARKit detects each reference image in the user’s environment, but your app can do much more. Follow the tips below to design AR experiences that use image detection well.

Use detected images to set a frame of reference for the AR scene.?Instead of requiring the user to choose a place for virtual content, or arbitrarily placing content in the user’s environment, use detected images to anchor the virtual scene. You can even use multiple detected images. For example, an app for a retail store could make a virtual character appear to emerge from a store’s front door by recognizing posters placed on either side of the door and then calculating a position for the character directly between the posters.

應用最佳實踐

這個示例應用程序簡單地可視化ARKit在用戶環(huán)境中檢測每個參考圖像的位置，但您的應用程序可以做更多。 請按照以下提示設計良好地使用圖像檢測的AR體驗。

使用檢測到的圖像為AR場景設置參考框架。 而不是要求用戶選擇虛擬內容的地方，或任意放置內容在用戶的環(huán)境中，使用檢測到的圖像來錨定虛擬場景。 你甚至可以使用多個檢測到的圖像。 例如，一家零售商店的應用程序可以通過識別放置在門兩側的海報，然后直接在海報之間計算角色的位置，使商店的前門出現(xiàn)虛擬角色。

Note

Use the?ARSession?setWorldOrigin:?method to redefine the world coordinate system so that you can place all anchors and other content relative to the reference point you choose.

注意

使用ARSession setWorldOrigin：方法重新定義世界坐標系，以便您可以將所有錨點和其他內容相對于您選擇的參考點放置。

Design your AR experience to use detected images as a starting point for virtual content.ARKit doesn’t track changes to the position or orientation of each detected image. If you try to place virtual content that stays attached to a detected image, that content may not appear to stay in place correctly. Instead, use detected images as a frame of reference for starting a dynamic scene. For example, your app might recognize theater posters for a sci-fi film and then have virtual spaceships appear to emerge from the posters and fly around the environment.

Consider when to allow detection of each image to trigger (or repeat) AR interactions.?ARKit adds an image anchor to a session exactly once for each reference image in the session configuration’s?detectionImages?array. If your AR experience adds virtual content to the scene when an image is detected, that action will by default happen only once. To allow the user to experience that content again without restarting your app, call the session’s?removeAnchor:?method to remove the corresponding?ARImageAnchor. After the anchor is removed, ARKit will add a new anchor the next time it detects the image.

For example, in the case described above, where spaceships appear to fly out of a movie poster, you might not want an extra copy of that animation to appear while the first one is still playing. Wait until the animation ends to remove the anchor, so that the user can trigger it again by pointing their device at the image.

設計您的AR體驗，將檢測到的圖像用作虛擬內容的起點。 ARKit不會跟蹤每個檢測圖像的位置或方向的更改。如果您嘗試放置保留附加到檢測到的圖像的虛擬內容，該內容可能無法正確保留。相反，使用檢測到的圖像作為開始動態(tài)場景的參考框架。例如，您的應用可能會為科幻電影識別影院海報，然后虛擬宇宙飛船似乎會從海報中浮現(xiàn)出來并在環(huán)境中飛行。

考慮何時允許檢測每個圖像以觸發(fā)（或重復）AR交互。 ARKit為Session配置的detectionImages數(shù)組中的每個參考圖像精確地添加一次圖像定位點。如果您的AR體驗在檢測到圖像時將虛擬內容添加到場景中，則該操作默認只會發(fā)生一次。要允許用戶在不重新啟動應用程序的情況下再次體驗該內容，請調用會話的removeAnchor：方法來刪除相應的ARImageAnchor。錨點被移除后，ARKit會在下一次檢測到圖像時添加新的錨點。

例如，在上面描述的情況下，當飛船出現(xiàn)在電影海報中時，您可能不希望在第一個播放時播放該動畫的額外副本。等待動畫結束以移除錨點，以便用戶可以通過將其設備指向圖像來再次觸發(fā)它。