了解如何在您的应用中使用 Instant Placement API。
前提条件
确保您了解基本 AR 概念以及如何配置 ARCore 会话，然后再继续。
使用即时展示位置配置新会话
在新的 ARCore 会话中，启用即时放置模式。
// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);
// Enable Instant Placement mode.
ArConfig_setInstantPlacementMode(ar_session, ar_config,
AR_INSTANT_PLACEMENT_MODE_LOCAL_Y_UP);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);
// Release config resources.
ArConfig_destroy(ar_config);
放置对象
在新的 ARCore 会话中，使用 ArFrame_hitTestInstantPlacement 执行即时展示位置点击测试。然后，使用命中结果的 ARTrackable 中的 ArInstantPlacementPoint 姿势创建新的 ArAnchor。
ArFrame* ar_frame = NULL;
if (ArSession_update(ar_session, ar_frame) != AR_SUCCESS) {
// Get the latest frame.
LOGE("ArSession_update error");
return;
}
// Place an object on tap.
// Use the estimated distance from the user's device to the closest
// available surface, based on expected user interaction and behavior.
float approximate_distance_meters = 2.0f;
ArHitResultList* hit_result_list = NULL;
ArHitResultList_create(ar_session, &hit_result_list);
CHECK(hit_result_list);
// Returns a single result if the hit test was successful.
ArFrame_hitTestInstantPlacement(ar_session, ar_frame, x, y,
approximate_distance_meters, hit_result_list);
int32_t hit_result_list_size = 0;
ArHitResultList_getSize(ar_session, hit_result_list, &hit_result_list_size);
if (hit_result_list_size > 0) {
ArHitResult* ar_hit_result = NULL;
ArHitResult_create(ar_session, &ar_hit_result);
CHECK(ar_hit_result);
ArHitResultList_getItem(ar_session, hit_result_list, 0, ar_hit_result);
if (ar_hit_result == NULL) {
LOGE("ArHitResultList_getItem error");
return;
}
ArTrackable* ar_trackable = NULL;
ArHitResult_acquireTrackable(ar_session, ar_hit_result, &ar_trackable);
if (ar_trackable == NULL) {
LOGE("ArHitResultList_acquireTrackable error");
return;
}
ArTrackableType ar_trackable_type = AR_TRACKABLE_NOT_VALID;
ArTrackable_getType(ar_session, ar_trackable, &ar_trackable_type);
if (ar_trackable_type == AR_TRACKABLE_INSTANT_PLACEMENT_POINT) {
ArInstantPlacementPoint* point = (ArInstantPlacementPoint*)ar_trackable;
// Gets the pose of the Instant Placement point.
ArPose* ar_pose = NULL;
ArPose_create(ar_session, NULL, &ar_pose);
CHECK(ar_pose);
ArInstantPlacementPoint_getPose(ar_session, point, ar_pose);
// Attaches an anchor to the Instant Placement point.
ArAnchor* anchor = NULL;
ArStatus status = ArTrackable_acquireNewAnchor(ar_session, ar_trackable,
ar_pose, &anchor);
ArPose_destroy(ar_pose);
// Render content at the anchor.
// ...
}
ArTrackable_release(ar_trackable);
}
即时放置支持通过大致距离跟踪屏幕空间，一旦即时放置位置点锚定在现实世界中，它就会自动切换到完整跟踪。使用 ArInstantPlacementPoint_getPose() 检索当前姿势。使用 ArInstantPlacementPoint_getTrackingMethod() 获取当前的跟踪方法。
虽然 ARCore 可以针对任何方向的表面执行即时放置命中测试，但命中结果始终会返回针对重力方向 +Y 向上的姿势。在水平表面，点击测试可以更快地返回准确位置。
监控即时展示位置点跟踪方法
如果 ARCore 可以针对 ArFrame_hitTestInstantPlacement 返回的 ArInstantPlacementPoint 提供准确的 3D 姿势，则从跟踪方法 AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_FULL_TRACKING 开始。否则，它将从跟踪方法 AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_SCREENSPACE_WITH_APPROXIMATE_DISTANCE 开始，并在 ARCore 获得准确的 3D 姿势后过渡到 AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_FULL_TRACKING。一旦跟踪方法处于 AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_FULL_TRACKING 状态，它便不会还原为 AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_SCREENSPACE_WITH_APPROXIMATE_DISTANCE。
平滑跟踪方法转换
当跟踪方法从一帧中的 AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_SCREENSPACE_WITH_APPROXIMATE_DISTANCE 更改为下一帧中的 AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_FULL_TRACKING 时，姿势会根据提供的大致距离，从其初始位置跳到精确距离的新位置。姿态的这种瞬时变化会改变锚定到 ArInstantPlacementPoint 的任何对象的表观比例。也就是说，某个对象突然显示大于或小于上一帧。
请按照以下步骤操作，以避免因表观对象比例突然变化而导致的视觉跳跃：
- 跟踪每一帧中
ArInstantPlacementPoint的姿势和跟踪方法。 - 等待跟踪方法更改为
AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_FULL_TRACKING。 - 使用上一帧中的姿势和当前帧中的姿势来确定两个帧中对象与设备的距离。
- 计算由于与镜头距离的变化而导致的尺度变化。
- 调整对象的缩放比例以抵消感知的缩放比例变化，这样对象在视觉上不会显得尺寸变化。
- （可选）在数帧上平滑地将对象的缩放比例调整回其原始值。
class WrappedInstantPlacement {
ArInstantPlacementPoint* point;
ArInstantPlacementPointTrackingMethod previous_tracking_method;
float previous_distance_to_camera;
float scale_factor = 1.0f;
public:
WrappedInstantPlacement(ArInstantPlacementPoint* point,
TrackingMethod previous_tracking_method,
float previous_distance_to_camera) {
this.point = point;
this.previous_tracking_method = previous_tracking_method;
this.previous_distance_to_camera = previous_distance_to_camera;
}
};
std::vector<WrappedInstantPlacement> wrapped_points_;
创建即时展示位置后，修改 OnTouched() 以对其进行封装。
if (ar_trackable_type == AR_TRACKABLE_INSTANT_PLACEMENT_POINT) {
ArInstantPlacementPoint* point = (ArInstantPlacementPoint*)ar_trackable;
ArInstantPlacementPointTrackingMethod tracking_method;
ArInstantPlacementPoint_getTrackingMethod(ar_session, point,
&tracking_method);
ArCamera* ar_camera = nullptr;
ArFrame_acquireCamera(ar_session, ar_frame, &ar_camera);
CHECK(ar_camera);
wrapped_points_.push_back(WrappedInstantPlacement(
point, tracking_method, Distance(point, ar_camera)));
}
当即时展示位置点的跟踪方法从 AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_SCREENSPACE_WITH_APPROXIMATE_DISTANCE 转换为 AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_FULL_TRACKING 时，使用保存的距离抵消明显的比例变化。
void OnUpdate() {
for (auto& wrapped_point : wrapped_points_) {
ArInstantPlacementPoint* point = wrapped_point.point;
ArTrackingState tracking_state = AR_TRACKING_STATE_STOPPED;
ArTrackable_getTrackingState(ar_session, (ArTrackable)point,
&tracking_state);
if (tracking_state == AR_TRACKING_STATE_STOPPED) {
wrapped_points_.remove(wrapped_point);
continue;
}
if (tracking_state == AR_TRACKING_STATE_PAUSED) {
continue;
}
ArInstantPlacementPointTrackingMethod tracking_method;
ArInstantPlacementPoint_getTrackingMethod(ar_session, point,
&tracking_method);
ArCamera* ar_camera = nullptr;
ArFrame_acquireCamera(ar_session, ar_frame, &ar_camera);
CHECK(ar_camera);
const float distance_to_camera = Distance(point, ar_camera);
if (tracking_method ==
AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_SCREENSPACE_WITH_APPROXIMATE_DISTANCE) {
// Continue to use the estimated depth and pose. Record the distance to
// the camera for use in the next frame if the transition to full
// tracking happens.
wrapped_point.previous_distance_to_camera = distance_to_camera;
} else if (
tracking_method ==
AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_FULL_TRACKING &&
wrapped_point.previous_tracking_method ==
AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_SCREENSPACE_WITH_APPROXIMATE_DISTANCE) {
// Change from the estimated pose to the accurate pose. Adjust the
// object scale to counteract the apparent change due to pose jump.
wrapped_point.scale_factor =
distance_to_camera / wrapped_point.previous_distance_to_camera;
// Apply the scale factor to the model.
// ...
previous_tracking_method =
AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_FULL_TRACKING;
}
}
}
性能考虑因素
启用 Instant Placement 后，ARCore 将消耗额外的 CPU 周期。如果担心性能问题，请考虑在用户成功放置对象且所有 Instant Placement 点的跟踪方法都更改为 AR_INSTANT_PLACEMENT_POINT_TRACKING_METHOD_FULL_TRACKING 后停用 Instant Placement。
停用即时展示位置后，请使用 ArFrame_hitTest 而非 ArFrame_hitTestInstantPlacement。
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);
// Disable Instant Placement.
ArConfig_setInstantPlacementMode(ar_session, ar_config,
AR_INSTANT_PLACEMENT_MODE_DISABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);
ArConfig_destroy(ar_config);