Руководство для разработчиков Instant Placement для Android

Learn how to use the Instant Placement API in your own apps.

Предварительные требования

Прежде чем продолжить, убедитесь, что вы понимаете основные концепции дополненной реальности и как настроить сессию ARCore .

Настройте новую сессию с помощью функции мгновенного размещения.

In a new ARCore session, enable Instant Placement mode .

Java

// Create the ARCore session.
public void createSession() {
  session = new Session(applicationContext);
  Config config = new Config(session);
  // Set the Instant Placement mode.
  config.setInstantPlacementMode(InstantPlacementMode.LOCAL_Y_UP);
  session.configure(config);
}

Котлин

// Create the ARCore session.
fun createSession() {
  session = Session(applicationContext);
  val config = Config(session)
  // Set the Instant Placement mode.
  config.instantPlacementMode = Config.InstantPlacementMode.LOCAL_Y_UP
  session.configure(config)
}

Поместите предмет

Используйте Frame.hitTestInstantPlacement() для создания отслеживаемой точки мгновенного размещения по положению касания экрана. Получите текущую позу с помощью метода getPose() .

Java

private placementIsDone = false;

public void onDrawFrame(GL10 gl) {
  Frame frame = session.update();

  // Place an object on tap.
  if (!placementIsDone && didUserTap()) {
    // Use estimated distance from the user's device to the real world, based
    // on expected user interaction and behavior.
    float approximateDistanceMeters = 2.0f;
    // Performs a ray cast given a screen tap position.
    List<HitResult> results =
      frame.hitTestInstantPlacement(tapX, tapY, approximateDistanceMeters);
    if (!results.isEmpty()) {
      InstantPlacementPoint point = (InstantPlacementPoint) results.get(0).getTrackable();
      // Create an Anchor from the point's pose.
      Anchor anchor = point.createAnchor(point.getPose());
      placementIsDone = true;
      disableInstantPlacement();
    }
  }
}

Котлин

var placementIsDone = false;

fun onDrawFrame(gl: GL10) {
  val frame = session.update();

  // Place an object on tap.
  if (!placementIsDone && didUserTap()) {
    // Use estimated distance from the user's device to the real world, based
    // on expected user interaction and behavior.
    val approximateDistanceMeters = 2.0f;
    // Performs a ray cast given a screen tap position.
    val results = frame.hitTestInstantPlacement(tapX, tapY, approximateDistanceMeters)
    if (results.isNotEmpty()) {
      val point = results[0].trackable as InstantPlacementPoint
      // Create an Anchor from the point's pose.
      val anchor = point.createAnchor(point.pose)
      placementIsDone = true
      disableInstantPlacement()
    }
  }
}

Функция Instant Placement поддерживает отслеживание в экранном пространстве с приблизительным расстоянием , автоматически переключаясь на полное отслеживание, как только точка Instant Placement будет зафиксирована в реальном мире. Текущую позу можно получить с помощью getPose() . Текущий метод отслеживания можно получить с помощью getTrackingMethod() .

Хотя ARCore может выполнять мгновенные проверки попадания по поверхностям любой ориентации, результаты проверки попадания всегда будут возвращать позу с направлением +Y вверх, против направления силы тяжести. На горизонтальных поверхностях проверки попадания дают точные координаты гораздо быстрее.

Smooth the tracking method transition

Когда станет доступна истинная глубина, ARCore изменит метод отслеживания объекта InstantPlacementPoint с SCREENSPACE_WITH_APPROXIMATE_DISTANCE на FULL_TRACKING . Положение точки также изменится, отражая истинную глубину. Это может привести к тому, что объект будет казаться внезапно увеличивающимся или уменьшающимся. Чтобы избежать этого внезапного изменения, добавьте обертку InstantPlacementPoint .

Java

// Wrapper class to track state to reduce sudden visual changes in object size
class WrappedInstantPlacement {
  public InstantPlacementPoint point;
  public InstantPlacementPoint.TrackingMethod previousTrackingMethod;
  public float previousDistanceToCamera;
  public float scaleFactor = 1.0f;

  public WrappedInstantPlacement(
      InstantPlacementPoint point,
      InstantPlacementPoint.TrackingMethod previousTrackingMethod,
      float previousDistanceToCamera) {
    this.point = point;
    this.previousTrackingMethod = previousTrackingMethod;
    this.previousDistanceToCamera = previousDistanceToCamera;
  }
}

Котлин

// Wrapper class to track state to reduce sudden visual changes in object size
class WrappedInstantPlacement(
  var point: InstantPlacementPoint,
  var previousTrackingMethod: InstantPlacementPoint.TrackingMethod,
  var previousDistanceToCamera: Float,
  var scaleFactor: Float = 1.0f
)

Then, add the following to your activity.

Java

List<WrappedInstantPlacement> wrappedPoints = new ArrayList<>();

public void onDrawFrame(GL10 gl) {
  Frame frame = session.update();
  Camera camera = frame.getCamera();

  // Place an object on tap.
  if (didUserTap()) {
    // Instant Placement should only be applied if no results are available through hitTest.
    List<HitResult> results = frame.hitTest(tapX, tapY);
    if (results.isEmpty()) {
      // Use the estimated distance from the user's device to the closest
      // available surface, based on expected user interaction and behavior.
      float approximateDistanceMeters = 2.0f;

      // Returns a single result if the hit test was successful.
      results =
          frame.hitTestInstantPlacement(tapX, tapY, approximateDistanceMeters);
      if (!results.isEmpty()) {
        // Instant placement was successful.
        InstantPlacementPoint point = (InstantPlacementPoint) results.get(0).getTrackable();
        wrappedPoints.add(new WrappedInstantPlacement(point, point.getTrackingMethod(),
          distance(camera.getPose(), point.getPose())));
      }
    } else {
      // results contain valid hit tests which can be used directly, so instant placement is not required.
    }
  }

  for (WrappedInstantPlacement wrappedPoint : wrappedPoints) {
    InstantPlacementPoint point = wrappedPoint.point;
    if (point.getTrackingState() == TrackingState.STOPPED) {
      wrappedPoints.remove(wrappedPoint);
      continue;
    }
    if (point.getTrackingState() == TrackingState.PAUSED) {
      continue;
    }

    if (point.getTrackingMethod() == TrackingMethod.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.
       wrappedPoint.previousDistanceToCamera = distance(point.getPose(), camera.getPose());
    }
    else if (point.getTrackingMethod() == TrackingMethod.FULL_TRACKING) {
      if (wrappedPoint.previousTrackingMethod == TrackingMethod.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.
        wrappedPoint.scaleFactor = distance(point.getPose(), camera.getPose()) /
            wrappedPoint.previousDistanceToCamera;
        // Apply the scale factor to the model.
        // ...
        wrappedPoint.previousTrackingMethod = TrackingMethod.FULL_TRACKING;
      }
    }
  }
}

float distance(Pose p, Pose q) {
  return Math.sqrt(Math.pow(p.tx() - q.tx(), 2) + Math.pow(p.ty() - q.ty(), 2) + Math.pow(p.tz() - q.tz(), 2));
}

Котлин

var wrappedPoints = mutableListOf<WrappedInstantPlacement>()

fun onDrawFrame(gl: GL10?) {
  val frame = session.update()
  val camera = frame.camera

  // Place an object on tap.
  if (didUserTap()) {
    // Instant Placement should only be applied if no results are available through hitTest.
    var results = frame.hitTest(tapX, tapY);
    if (results.isEmpty()) {
      // Use the estimated distance from the user's device to the closest
      // available surface, based on expected user interaction and behavior.
      val approximateDistanceMeters = 2.0f;

      // Returns a single result if the hit test was successful.
      results = frame.hitTestInstantPlacement(tapX, tapY, approximateDistanceMeters);
      if (results.isNotEmpty()) {
        // Instant placement was successful.
        val point = results[0].trackable as InstantPlacementPoint
        val wrapped = WrappedInstantPlacement(point, point.trackingMethod, point.pose.distance(camera.pose))
        wrappedPoints.add(wrapped)
      }
    } else {
      // Results contain valid hit tests which can be used directly, so Instant Placement 
      // is not required.
    }
  }

  loop@ for (wrappedPoint in wrappedPoints) {
    val point = wrappedPoint.point
    when {
      point.trackingState == TrackingState.STOPPED -> {
        wrappedPoints.remove(wrappedPoint)
        continue@loop
      }
      point.trackingState == TrackingState.PAUSED -> continue@loop
      point.trackingMethod == TrackingMethod.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.
        wrappedPoint.previousDistanceToCamera = point.pose.distance(camera.pose)
      }
      wrappedPoint.previousTrackingMethod == TrackingMethod.SCREENSPACE_WITH_APPROXIMATE_DISTANCE &&
      point.trackingMethod == TrackingMethod.FULL_TRACKING -> {
        // Change from the estimated pose to the accurate pose. Adjust the
        // object scale to counteract the apparent change due to pose jump.
        wrappedPoint.scaleFactor =
          point.pose.distance(camera.pose) / wrappedPoint.previousDistanceToCamera
        // Apply the scale factor to the model.
        // ...
        wrappedPoint.previousTrackingMethod = TrackingMethod.FULL_TRACKING
      }
    }
  }
}

fun Pose.distance(other: Pose) = sqrt(
  (tx() - other.tx()).pow(2.0f) + (ty() - other.ty()).pow(2.0f) + (tz() - other.tz()).pow(2.0f)
)

Повышение эффективности после размещения объекта

Отключите мгновенное размещение объекта после его правильного размещения, чтобы сэкономить ресурсы процессора и энергию.

Java

void disableInstantPlacement() {
  Config config = new Config(session);
  config.setInstantPlacementMode(Config.InstantPlacementMode.DISABLED);
  session.configure(config);
}

Котлин

fun disableInstantPlacement() {
  val config = Config(session)
  // Set the Instant Placement mode.
  config.instantPlacementMode = Config.InstantPlacementMode.DISABLED
  session.configure(config)
}