Guide du développeur sur l'emplacement instantané pour Android

Découvrez comment utiliser l'API Instant Placement dans vos propres applications.

Prérequis

Avant de continuer, assurez-vous de bien comprendre les concepts fondamentaux de la RA et de savoir comment configurer une session ARCore.

Configurer une nouvelle session avec Instant Placement

Dans une nouvelle session ARCore, activez le mode Instant Placement.

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);
}

Kotlin

// 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)
}

Placer un objet

Utilisez Frame.hitTestInstantPlacement() pour créer un point Instant Placement pouvant être suivi à partir d'une position de pression sur l'écran. Récupérez la pose actuelle avec la getPose() méthode.

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();
    }
  }
}

Kotlin

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 est compatible avec le suivi de l'espace à l'écran avec une distance approximative, Il passe automatiquement au suivi complet une fois que le point Instant Placement est ancré dans le monde réel. Récupérez la pose actuelle avec getPose(). Obtenez la méthode de suivi actuelle avec getTrackingMethod().

Bien qu'ARCore puisse effectuer des tests de détection Instant Placement sur des surfaces de n'importe quelle orientation, les résultats de détection renvoient toujours une pose avec +Y vers le haut, dans le sens opposé à la gravité. Sur les surfaces horizontales, les tests de détection renvoient des positions précises beaucoup plus rapidement.

Lisser la transition de la méthode de suivi

Lorsque la profondeur réelle devient disponible, ARCore remplace la méthode de suivi d'un InstantPlacementPoint's tracking method de SCREENSPACE_WITH_APPROXIMATE_DISTANCE par FULL_TRACKING. La pose du point change également pour refléter la profondeur réelle. L'objet peut alors sembler soudainement grandir ou rétrécir. Pour éviter ce changement soudain, ajoutez un wrapper 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;
  }
}

Kotlin

// 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
)

Ajoutez ensuite les éléments suivants à votre activité.

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));
}

Kotlin

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)
)

Améliorer l'efficacité après le placement d'un objet

Désactivez Instant Placement lorsque l'objet est correctement placé pour économiser des cycles de processeur et de l'énergie.

Java

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

Kotlin

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