Menyesuaikan model 3D di aplikasi Anda

Perangkat XR yang kompatibel
Panduan ini membantu Anda membangun pengalaman untuk jenis perangkat XR ini.
Mempelajari jenis perangkat XR →
Headset XR
Kacamata XR Berkabel
Mempelajari jenis perangkat XR →

Sebelum menyesuaikan model 3D, Anda harus menambahkannya ke aplikasi terlebih dahulu. Setelah menambahkan model 3D ke aplikasi, Anda dapat meningkatkan pengalaman visual dan interaktif dengan menyesuaikan tampilan dan pergerakan model 3D.

Misalnya, Anda dapat memutar dan mengontrol animasi glTF tersemat, mengakses dan memindahkan node yang membentuk model, atau bahkan memuat tekstur kustom dan menentukan properti materi untuk menggantikan mesh internal. Kemampuan ini memungkinkan Anda mengubah tampilan dan perilaku objek secara dinamis saat runtime.

Objek 3D di Android XR

Jetpack XR SDK mendukung standar terbuka glTF 2.0 dari Khronos Group untuk model 3D dan merender objek ini dengan teknik physically based rendering (PBR) yang ditentukan dalam standar glTF 2.0 (bersama dengan ekstensi yang didukung). glTF (Graphics Library Transmission Format) adalah format file standar untuk mengirim dan memuat adegan dan model 3D. Model glTF terdiri dari struktur hierarkis komponen internal.

Berikut komponen utama yang perlu dipahami:

  • Node: Node ini menentukan struktur dan hierarki model. Setiap node dapat memiliki posisi, rotasi, dan skala sendiri.
  • Mesh: Geometri 3D struktural yang membentuk objek 3D.
  • Material: Menentukan tampilan visual mesh, seperti warna, kekasaran, atau reaksinya terhadap pencahayaan.
  • Tekstur: Aset gambar, seperti file PNG, yang dapat Anda terapkan ke permukaan model 3D untuk membuat pola, warna, detail, atau efek visual lainnya yang disesuaikan.
  • Animasi: Ini adalah urutan atau jalur animasi yang telah ditentukan sebelumnya yang berisi perubahan pada node dan mesh individual untuk menciptakan tampilan pergerakan dari waktu ke waktu.

Di Jetpack Compose untuk XR, Anda merender file ini menggunakan SpatialGltfModel dan melacak status pemuatan dan animasinya menggunakan SpatialGltfModelState. Untuk mengetahui informasi selengkapnya, lihat Menambahkan model 3D ke aplikasi Anda.

Menganimasikan model 3D

Model 3D dapat memiliki animasi tersemat. Secara internal, animasi menggunakan sampler untuk menentukan waktu dan nilai gerakan, serta channel untuk menghubungkan gerakan tersebut ke masing-masing node dan mesh. Animasi kerangka dan animasi materi yang dibuat dengan KHR_animation_pointer ekstensi glTF didukung di Jetpack XR SDK.

Dengan menggunakan Compose untuk XR, untuk memutar animasi, tentukan nama jalur tertentu dari daftar animations. Gunakan animation.start() untuk mulai memutar. Secara opsional, Anda dapat menentukan kecepatan, waktu pencarian, dan apakah animasi harus diulang atau tidak menggunakan SpatialGltfModelAnimation:

val animation = modelState.animations.find { it.name == "Walk" }

animation?.animationState?.let { state ->
    LaunchedEffect(state) {
        Log.i("SpatialGltfModelAnimationSample", "Animation State: $state")
    }
}

DisposableEffect(animation) {
    animation?.loop()
    onDispose {
        animation?.stop()
    }
}

Memanipulasi Node: Pose dan Rotasi

Untuk memanipulasi bagian tertentu dari model dan mengubah propertinya seperti rotasi atau pose, Anda harus membuat kueri nodes internal model glTF menggunakan SpatialGltfModelState.

// Retrieve the list of nodes (individual components/meshes) defined within the glTF model.
val entityNodes = modelState.nodes

// Find a specific node by name to apply modifications, such as material overrides.
val node = entityNodes.find { it.name == "node_name" }

Setelah menemukan node yang benar, Anda dapat menyetel localPose untuk mengubah posisi dan rotasi 3D-nya relatif terhadap induk langsungnya GltfModelNode atau menggunakan modelPose untuk menyetel posisi relatif terhadap root GltfModelEntity. Demikian pula, Anda dapat menggunakan localScale/modelScale untuk mengubah skala model relatif terhadap induk atau root-nya.

LaunchedEffect(node, degrees) {
    val rotation = Quaternion.fromEulerAngles(degrees, 0f, degrees)
    node?.let {
        it.localPose = Pose(it.localPose.translation, rotation)
    }
}

Menyesuaikan properti materi model 3D Anda

Anda dapat menyesuaikan atribut materi selama runtime untuk mengubah tampilan objek secara dinamis berdasarkan input pengguna atau status aplikasi saat ini.

Di Jetpack XR, class KhronosPbrMaterial dan KhronosUnlitMaterial digunakan untuk membuat dan memanipulasi materi ini. Seperti namanya, KhronosUnlitMaterials tidak menyala dan tidak terpengaruh oleh pencahayaan adegan. KhronosPbrMaterial memungkinkan Anda menyesuaikan berbagai properti, seperti warna kilau, seberapa metalik atau kasar suatu objek, dan apakah objek tersebut memancarkan cahaya.

Untuk mengetahui informasi selengkapnya tentang setiap properti yang didukung dan parameter yang dapat disesuaikan di Android XR, lihat dokumentasi referensi kami. Untuk lebih memahami properti ini, lihat glosarium Khronos.

Gambar 1. Contoh mengubah warna dasar pada model 3D.

Untuk menyesuaikan properti materi model 3D, pertama-tama Anda akan membuat materi baru menggunakan KhronosPbrMaterial. Anda harus menyetel AlphaMode yang sesuai untuk tampilan visual yang ingin Anda capai:

Selanjutnya, tentukan properti yang ingin Anda ubah. Contoh ini menggunakan setBaseColorFactor untuk mengubah warna dasar mesh menjadi ungu. Metode ini memerlukan Vector4, dengan komponen x, y, z, dan w masing-masing sesuai dengan nilai RGBA (Merah, Hijau, Biru, dan Alfa):

// Maintain a reference to the custom material to avoid re-creating it on every recomposition.
var pbrMaterial by remember { mutableStateOf<KhronosPbrMaterial?>(null) }

// Create and apply the custom material once the session is ready and the target node is available.
LaunchedEffect(node) {
    val material = KhronosPbrMaterial.create(
        session = xrSession,
        alphaMode = AlphaMode.OPAQUE
    ).also {
        pbrMaterial = it
        // Apply a base color factor (RGBA) to change the color of the model.
        it.setBaseColorFactor(
            Vector4(
                x = 0.5f,
                y = 0.0f,
                z = 0.5f,
                w = 1.0f
            )
        )
    }

Memuat tekstur kustom untuk model 3D Anda

Texture adalah aset gambar yang dapat Anda terapkan ke permukaan model 3D untuk memberikan warna, detail, atau informasi permukaan lainnya. Jetpack XR Texture API memungkinkan Anda memuat data gambar, seperti file PNG, dari folder /assets/ aplikasi Anda secara asinkron.

Saat memuat tekstur, Anda dapat menentukan TextureSampler, yang mengontrol cara tekstur dirender. Sampler menentukan properti pemfilteran (saat tekstur tampak lebih kecil atau lebih besar dari ukuran aslinya) dan mode pembungkusan (untuk menangani koordinat di luar rentang [0, 1] standar). Texture harus ditetapkan ke KhronosPbrMaterial agar memiliki efek visual pada model 3D.

Gambar 2. Contoh mengubah tekstur pada model 3D.

Untuk memuat tekstur kustom, pertama-tama Anda harus menyimpan file gambar ke folder /assets/. Sebagai praktik terbaik, sebaiknya Anda membuat subdirektori textures di folder tersebut juga.

Setelah Anda menyimpan file di direktori yang sesuai, buat tekstur dengan API Texture. Di sini juga Anda akan menerapkan TextureSampler opsional jika diperlukan.

Contoh ini menerapkan tekstur oklusi dan menetapkan kekuatan oklusi:

LaunchedEffect(node) {
    val material = KhronosPbrMaterial.create(
        session = xrSession,
        alphaMode = AlphaMode.OPAQUE
    ).also {
        pbrMaterial = it

        // Load a texture
        val texture = Texture.create(
            session = xrSession,
            path = Path("textures/texture_name.png")
        )

        // Set the texture and configure occlusion to define how the material surface handles ambient lighting.
        it.setOcclusionTexture(
            texture = texture,
            strength = 1.0f
        )
    }
    node?.setMaterialOverride(
        material = material
    )
}

Menerapkan material dan tekstur ke objek 3D

Untuk menerapkan material atau tekstur baru, ganti material yang ada untuk node tertentu di node glTF Anda. Lakukan hal ini dengan memanggil setMaterialOverride:

node?.setMaterialOverride(
    material = material
)

Untuk menghapus materi yang baru dibuat, panggil clearMaterialOverride di node yang sebelumnya diganti. Tindakan ini akan mengembalikan Model 3D Anda ke status default-nya:

if (removeMaterial) {
    node?.clearMaterialOverride()
}

glTF dan logo glTF adalah merek dagang Khronos Group Inc.