앱에 3D 모델 추가

적용 가능한 XR 기기
이 가이드는 이러한 유형의 XR 기기를 위한 환경을 빌드하는 데 도움이 됩니다.
XR 기기 유형 알아보기 →
XR 헤드셋
유선 XR 글라스
XR 기기 유형 알아보기 →

3D 모델을 사용할 때 Jetpack XR SDK는 glTF 2.0 개방형 표준을 지원합니다. Android XR이 Jetpack XR SDK로 빌드된 앱을 렌더링할 때 3D 모델은 glTF 2.0 표준에 지정된 물리 기반 렌더링(PBR) 기법(지원되는 확장 프로그램 포함)을 사용하여 렌더링됩니다. Autodesk Maya, Maxon ZBrush, Blender, Spline과 같은 대부분의 디지털 콘텐츠 제작 (dcc) 도구는 3D 모델을 glTF 형식 (.gltf 또는 .glb 파일)으로 내보낼 수 있습니다.

사용자 또는 앱에서 SpatialEnvironment 스카이박스를 지정한 경우 3D 모델은 환경 스카이박스에서 제공하는 조명 정보로 조명을 받습니다. 반사 재질과 반사 하이라이트도 환경 스카이박스를 반영합니다. 패스 스루가 사용 설정된 경우 조명, 반사, 반사 하이라이트는 단일 방향 조명이 있는 밝은 방을 기반으로 합니다.

지원되는 소재에 대한 간략한 개요는 Khronos 사이트의 glTF PBR 속성을 참고하세요. 이러한 속성 및 기타 속성으로 3D 모델을 맞춤설정하는 방법을 알아보려면 앱에서 3D 모델 맞춤설정을 참고하세요.

애셋 폴더에 glTF 파일 추가

glTF 파일이 있으면 다음 단계는 Android 스튜디오의 assets 디렉터리에 추가하는 것입니다. 애셋 유형을 더 잘 정리하려면 models 디렉터리를 만드는 것이 좋습니다.

/models 디렉터리에 애셋을 추가하는 예시

SpatialGltfModel을 사용하여 3D 객체 추가

Android XR은 3D 모델의 glTF 형식을 지원하며, 일반적으로 .glb 파일로 저장됩니다. 이러한 객체를 레이아웃에 추가하려면 SpatialGltfModel를 사용합니다. SpatialGltfModel는 glTF 형식의 3D 모델을 공간 레이아웃에 추가할 수 있는 하위 공간 컴포저블입니다. 이 API는 애셋을 로드하고 상태를 관리하는 프로세스를 간소화합니다.

모델을 표시하려면 먼저 rememberSpatialGltfModelState를 사용하여 소스와 상태를 정의합니다. 앱의 assets 폴더, URI 또는 raw data에서 모델을 로드할 수 있습니다.

val modelState = rememberSpatialGltfModelState(
    source = SpatialGltfModelSource.fromPath(
        Paths.get("models/model_name.glb")
    )
)

상태가 정의되면 SpatialGltfModel 컴포저블을 사용하여 하위 공간 내에서 렌더링합니다.

SpatialGltfModel(state = modelState, modifier = SubspaceModifier)

코드에 관한 핵심 사항

  • 비동기 로드: 모델이 비동기식으로 로드됩니다. 초기 컴포지션 중에 고유 크기가 0일 수 있습니다. 모델이 준비되면 레이아웃이 다시 측정됩니다.
  • 상태 제어: SpatialGltfModelState.status를 사용하여 로드 상태를 쿼리하거나 애니메이션을 제어합니다.
  • 크기 및 확장: 기본적으로 레이아웃 크기는 확장 소재의 경계 상자와 일치합니다. SubspaceModifier.size로 이를 재정의하여 지정된 경계 내에 맞도록 모델을 균일하게 확장할 수 있습니다.

Compose SceneCoreEntity를 사용하여 3D 모델 배치

SceneCoreEntity를 사용하여 3D 모델을 배치하려면 먼저 GltfModel.create()를 사용하여 glTF를 메모리에 로드해야 합니다. 그런 다음 3D 모델을 SceneCoreEntity에 배치하여 SceneCore 구성요소를 Compose for XR 레이아웃과 연결할 수 있습니다. SceneCoreEntity를 사용하여 레이아웃에 3D 객체 배치를 참고하세요.

Jetpack Scenecore를 사용하여 3D 모델 배치

glTF 모델을 로드하려면 GltfModel.create()를 호출합니다.

val gltfModel = GltfModel.create(session, Paths.get("models", "saturn_rings.glb"))

이 시점에서 모델은 메모리에 로드되지만 아직 렌더링되지 않습니다. 로드할 3D 모델이 많거나 모델이 큰 경우 미리 비동기식으로 로드하는 것이 좋습니다. 이렇게 하면 사용자가 모델이 메모리에 로드될 때까지 기다릴 필요가 없습니다.

ActivitySpace에 glTF를 추가합니다. GltfModelEntity.create를 호출하여 항목을 만들고 ActivitySpace에 배치합니다. 권장사항에 따라 앱이 공간 기능을 허용하는 상태인지 확인해야 합니다.

if (session.scene.spatialCapabilities.contains(SpatialCapability.SPATIAL_3D_CONTENT)) {
    val gltfEntity = GltfModelEntity.create(session, gltfModel)
}

이제 앱을 실행하면 로드된 3D 모델이 표시됩니다.

로드된 3D 모델의 예

Scene Viewer를 사용하여 3D 모델 로드

기본 상호작용 기능이 있는 3D 모델을 로드하는 가장 간단한 방법을 찾고 있다면 모바일에서와 같이 Scene Viewer를 사용할 수 있습니다. Android XR의 Scene Viewer와 모바일의 Scene Viewer의 주요 차이점은 Scene Viewer가 glTF 파일을 가리키는 파일 URI 매개변수만 지원하고 다른 모든 매개변수는 무시된다는 것입니다.

Scene Viewer는 인텐트를 사용하여 호출되고 전체 공간 모드에서 실행되는 별도의 앱입니다. 따라서 호출하면 앱이 더 이상 표시되지 않고 Scene Viewer에 포커스가 맞춰집니다. 변경한 환경이 사용자의 시스템 환경설정으로 재설정됩니다.

다음은 Android XR의 Scene Viewer에서 Intent를 사용하여 glTF 파일을 보는 예입니다.

val url =
    "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf"
val sceneViewerIntent = Intent(Intent.ACTION_VIEW)
val intentUri =
    Uri.parse("https://arvr.google.com/scene-viewer/1.2")
        .buildUpon()
        .appendQueryParameter("file", url)
        .build()
sceneViewerIntent.setData(intentUri)
try {
    startActivity(sceneViewerIntent)
} catch (e: ActivityNotFoundException) {
    // There is no activity that could handle the intent.
}

Scene Viewer의 상호작용 옵션에 관한 자세한 내용은 3D 모델 디자인 문서를 참고하세요.

glTF 확장 프로그램

Jetpack XR SDK는 3D 모델의 기능을 확장하는 여러 glTF 확장 프로그램을 지원합니다. 이러한 기능은 GltfModelEntity 및 Scene Viewer를 통해 사용할 수 있습니다.