Jetpack XR용 ARCore 사용

Jetpack XR용 ARCore를 사용하면 앱이 하위 수준 장면 이해 프리미티브와 모션 추적을 사용하여 증강 현실 (AR)의 기본 개념을 사용할 수 있습니다. AR 환경을 빌드할 때 평면 데이터를 사용하거나 콘텐츠를 공간의 고정된 위치에 고정해야 하는 경우 Jetpack XR용 ARCore를 사용하세요.

세션의 수명 주기 이해

Jetpack XR용 ARCore에서 추적하는 모든 객체는 세션을 통해 액세스해야 합니다. Activity의 수명 주기와 마찬가지로 세션 객체에도 앱에서 세션 객체의 기능을 사용하는 방식에 따라 유지해야 하는 수명 주기가 있습니다. 앱에 XR 지원 활동이 하나만 포함된 경우 수명 주기 인식 구성요소를 사용하여 세션의 수명 주기를 처리하는 것이 좋습니다.

세션 만들기

세션을 사용하려면 먼저 만들어야 합니다. 세션을 만들려면 사용자가 앱에 android.permission.SCENE_UNDERSTANDING 권한을 부여해야 합니다.

세션을 만들려면 다음 단계를 따르세요.

when (val result = Session.create(owner)) {
  is SessionCreateSuccess -> {
    session = result.session
  }
  is SessionCreatePermissionsNotGranted -> {
   // Request android.permission.SCENE_UNDERSTANDING.
  }
}

세션을 만들 수 없는 이유에 관한 자세한 내용은 SessionCreateResult를 참고하세요.

세션 재개

세션을 재개하는 작업은 앱이 Jetpack XR용 ARCore의 상태 변경을 처리할 준비가 되었을 때 실행해야 합니다. 대부분의 경우 Activity의 onResume() 콜백에서 실행되지만 앱은 사용자 상호작용 시까지 처리를 지연할 수 있습니다.

다음 코드 스니펫은 세션을 재개하는 예를 보여줍니다.

when (val result = session.resume()) {
  is SessionResumeSuccess -> {
    // Session has been created successfully.
    // Attach any successful handlers here.
  }
  is SessionResumePermissionsNotGranted -> {
    // Request android.permission.SCENE_UNDERSTANDING.
}

세션을 다시 시작할 수 없는 이유에 관한 자세한 내용은 SessionResumeResult를 참고하세요.

세션 일시중지

활동이 백그라운드로 전환되면 Session.pause()를 사용하여 세션을 일시중지합니다. 세션을 일시중지하면 세션이 재개될 때까지 추적이 일시적으로 중지되어 인식 시스템의 상태가 유지됩니다.

세션 소멸

세션을 영구적으로 폐기하려면 Session.destroy()를 사용하세요. 이렇게 하면 세션에서 사용 중인 리소스가 해제되고 모든 세션 상태가 소멸됩니다.

인식된 평면의 상태를 가져옵니다.

Jetpack XR용 ARCore는 평면 상태를 내보내는 StateFlow를 통해 평면 상태를 제공합니다. 세션에서 평면을 구독하면 평면이 추가, 업데이트 또는 삭제될 때 앱에 알림이 전송됩니다.

Plane.subscribe(session).collect { planes ->
 // Planes have changed; update plane rendering
}

평면에는 다음과 같은 속성이 있습니다.

  • label: 지정된 Plane의 시맨틱 설명입니다. Wall, Floor, Ceiling 또는 Table일 수 있습니다.
  • centerPose: 감지된 평면 중심의 포즈입니다.
  • extents: 감지된 평면의 크기(단위: 미터)입니다.
  • vertices: 평면을 근사하는 볼록 다각형의 정점 목록입니다.

평면에 대한 히트 테스트 실행

히트 테스트는 세션에서 추적하는 객체와 광선의 교차를 계산하는 방법입니다. 히트 테스트의 일반적인 적용은 표를 가리키고 해당 위치에 객체를 배치하는 것입니다. 히트 테스트를 실행하면 히트 객체 목록이 생성됩니다. 즉, 첫 번째 객체에서 히트 테스트가 중지되지 않습니다. 그러나 특정 유형의 첫 번째 히트 객체에만 관심이 있는 경우가 많습니다.

히트 테스트를 실행하려면 Interaction.hitTest()에 Ray을 사용합니다.

val results = Interaction.hitTest(session, ray)
// When interested in the first Table hit:
val tableHit = results.firstOrNull {
  val trackable = it.trackable
  trackable is Plane && trackable.state.value.label == Plane.Label.Table
}

공간의 고정된 위치에 콘텐츠 고정

가상 객체에 실제 위치를 지정하려면 Anchor를 사용하세요. 앵커 객체는 앱이 실제 공간에서 고정된 위치를 추적하는 데 도움이 됩니다.

앵커는 Pose를 사용하여 생성되며, 이는 기존 Trackable를 기준으로 해석될 수도 있고 그렇지 않을 수도 있습니다.

추적 가능한 항목을 기준으로 앵커 만들기

Plane과 같은 Trackable를 기준으로 앵커가 생성되면 앵커가 공간을 이동할 때 연결된 Trackable를 따라 이동합니다.

val anchor = trackable.createAnchor(pose)

추적 가능한 항목 없이 앵커 만들기

Trackable에 연결되지 않은 앵커를 만들려면 다음 단계를 따르세요.

when (val result = Anchor.create(session, pose)) {
  is AnchorCreateSuccess -> // ...
  else -> // handle failure
}

앵커에 항목 연결

이 위치에 모델을 렌더링하려면 GltfModel를 만들고 포즈를 앵커의 포즈로 설정합니다. 앵커의 TrackingState가 Stopped일 때 모델이 숨겨지는지 확인합니다.

// renderSession is androidx.xr.core.Session
anchor.state.collect { state ->
  if (state.trackingState == TrackingState.Tracking) {
    gltfEntity.setPose(
      renderSession.perceptionSpace.transformPoseTo(state.pose, renderSession.activitySpace)
    )
  } else if (state.trackingState == TrackingState.Stopped) {
    entity.setHidden(true)
  }
}

TrackingState 이해

각 Trackable에는 사용하기 전에 확인해야 하는 TrackingState가 있습니다. TrackableState이 Tracking인 Trackable의 경우 시스템에서 Pose를 적극적으로 업데이트합니다. Paused인 Trackable는 향후 Tracking이 될 수 있지만 Stopped인 Trackable는 Tracking이 될 수 없습니다.

세션 전반에서 앵커 유지

유지되지 않는 앵커는 세션이 소멸된 후 사라집니다. 앵커를 유지하면 앱은 비공개 앱 데이터에서 앵커의 위치를 기억합니다. 이 앵커는 후속 세션에서 검색할 수 있으며 지구상의 동일한 위치에 고정됩니다.

앵커를 유지하려면 다음과 같이 anchor.persist()를 사용합니다.

val uuid = anchor.persist()

앱은 향후 세션에서 UUID를 사용하여 앵커를 검색할 수 있습니다.

when (val result = Anchor.load(session, uuid)) {
  is AnchorCreateSuccess -> // Loading was successful. The anchor is stored in result.anchor.
  else -> // handle failure
}

더 이상 앵커가 필요하지 않으면 unpersist()를 호출합니다. 이렇게 하면 앱의 저장소에서 앵커가 삭제되고 Anchor.load() 호출 시 지정된 UUID를 검색할 수 없게 됩니다.

Anchor.unpersist(session, uuid)

앱은 여전히 앱의 저장소에 있는 모든 지속된 앵커의 목록을 요청할 수도 있습니다.

val uuids = Anchor.getPersistedAnchorUuids(session)