Plane AR tracker exception handling

This article explains how to handle exceptions for WeChat's plane AR tracker by registering callbacks.

Before you begin

• Understand through the MegaTracker workflow:

  • The plane AR tracker in xr-frame is essentially a wrapper for VisionKit's 6DoF-plane capability.
  • How MegaTracker works on xr-frame.

• Understand AR session concepts and workflow

Why plane detection exceptions occur

Under specific circumstances (such as large white walls in the frame, prolonged camera occlusion, etc.), WeChat's plane AR tracker may enter an abnormal state.

In this case, the plane AR tracker cannot output the camera pose (i.e., 6DoF data) per frame normally, causing MegaTracker to fail.

When the scene returns to normal (rich textures, unobstructed camera) for a period, the plane AR tracker will resume operation, and MegaTracker will also recover.

Setting behavior during plane detection exceptions

Register an exception handling callback via setPlaneDetectionErrorBehavior(behavior). When an exception is detected, this callback will be triggered, allowing developers to implement custom prompts, hide 3D content, or other processing logic.

session.setPlaneDetectionErrorBehavior(() => {
    wx.showToast({
        icon: 'none',
        title: `WeChat plane detection is abnormal. Point the camera at a plane and move it back and forth to restore tracking`,
        duration: 2000,
    });
});

This example uses the session's setPlaneDetectionErrorBehavior(behavior) interface to register a callback that pops up a Toast window when plane detection is abnormal.