افزودن مدل‌های سه‌بعدی به برنامه

دستگاه‌های XR واجدشرایط
این راهنمایی به شما کمک می‌کند برای این نوع دستگاه‌های واقعیت گسترده تجربه بسازید.
آشنایی با انواع دستگاه‌های XR →
هدست‌های واقعیت گسترده
عینک واقعیت گسترده سیمی
آشنایی با انواع دستگاه‌های XR →

هنگام کار با مدل‌های سه‌بعدی، Jetpack XR SDK از استاندارد باز glTF 2.0 پشتیبانی می‌کند. وقتی Android XR برنامه‌های ساخته‌شده با Jetpack XR SDK را رندر می‌کند، مدل‌های سه‌بعدی با تکنیک‌های رندرینگ مبتنی بر فیزیک(PBR) مشخص‌شده در استاندارد glTF 2.0 (همراه با افزونه‌های پشتیبانی‌شده) رندر خواهند شد. اکثر ابزارهای ایجاد محتوای دیجیتال (dcc)، مانند Autodesk Maya،‏ Maxon ZBrush،‏ Blender، و Spline می‌توانند مدل‌های سه‌بعدی را به قالب glTF (فایل‌های .gltf یا .glb) صادر کنند.

اگر کاربر یا برنامه‌تان SpatialEnvironment skybox را مشخص کرده باشد، مدل‌های سه‌بعدی با اطلاعات نورپردازی ارائه‌شده توسط محیط skybox روشن خواهند شد. مواد بازتابنده و نواحی پرنور و درخشان نیز جعبه آسمان محیط را بازتاب خواهند داد. اگر حالت گذرا فعال شده باشد، نورپردازی، بازتاب‌ها، و برجستگی‌های آینه‌ای براساس اتاقی روشن با یک منبع نور جهت‌دار خواهد بود.

برای نمای کلی سریع از مواد پشتیبانی‌شده، به ویژگی‌های glTF PBR در سایت Khronos مراجعه کنید. برای آشنایی با نحوه سفارشی‌سازی کردن مدل‌های سه‌بعدی با این ویژگی‌ها و ویژگی‌های دیگر، به سفارشی‌سازی کردن مدل‌های سه‌بعدی در برنامه مراجعه کنید

افزودن فایل glTF به پوشه دارایی‌ها

وقتی فایل glTF را دریافت کردید، مرحله بعدی این است که آن را به پوشه دارایی‌ها در «استودیو Android» اضافه کنید. توصیه می‌کنیم برای سازمان‌دهی بهتر انواع دارایی‌هایتان، یک دایرکتوری models ایجاد کنید.

نمونه‌ای از افزودن دارایی‌ها به فهرست راهنمای models/

افزودن شیء سه‌بعدی بااستفاده از SpatialGltfModel

Android XR از قالب glTF برای مدل‌های سه‌بعدی پشتیبانی می‌کند که معمولاً به‌صورت فایل‌های .glb ذخیره می‌شوند. برای افزودن این اشیاء به چیدمانتان، از SpatialGltfModel استفاده کنید. SpatialGltfModel یک ترکیب‌پذیر زیرفضا است که به شما امکان می‌دهد مدل‌های سه‌بعدی را در قالب glTF به چیدمان فضایی خود اضافه کنید. این میانای برنامه‌سازی کاربردی فرایند بار کردن دارایی‌ها و مدیریت وضعیت آن‌ها را ساده می‌کند.

برای نمایش مدل، ابتدا منبع و وضعیت آن را بااستفاده از rememberSpatialGltfModelState تعریف کنید. می‌توانید مدل‌ها را از پوشه assets برنامه‌تان، URI، یا raw data بار کنید.

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

پس‌از تعریف وضعیت، از ترکیب‌پذیر SpatialGltfModel برای رندر کردن آن در یک زیرفضا استفاده کنید:

SpatialGltfModel(state = modelState, modifier = SubspaceModifier)

نکات کلیدی درباره کد

  • بار کردن ناهمگام: مدل به‌صورت ناهمگام بار می‌شود. درطول ترکیب‌بندی اولیه، اندازه ذاتی آن ممکن است صفر باشد؛ وقتی مدل آماده شد، چیدمان دوباره اندازه‌گیری می‌شود.
  • کنترل کردن وضعیت: از SpatialGltfModelState.status برای پرسمان وضعیت بار کردن یا کنترل کردن پویانمایی‌ها استفاده کنید.
  • اندازه و مقیاس: به‌طور پیش‌فرض، اندازه چیدمان با کادر محدودکننده دارایی مطابقت دارد. می‌توانید این را با SubspaceModifier.size لغو کنید تا مدل به‌طور یکنواخت مقیاس‌بندی شود و در محدوده‌های مشخص‌شده قرار گیرد.

قرار دادن مدل سه‌بعدی بااستفاده از Compose SceneCoreEntity

برای قرار دادن مدل سه‌بعدی بااستفاده از SceneCoreEntity، ابتدا باید glTF را بااستفاده از GltfModel.create() در حافظه بار کنید. سپس می‌توانید مدل سه‌بعدی را در SceneCoreEntity قرار دهید تا مؤلفه‌های SceneCore را با Compose برای چیدمان‌های واقعیت گسترده مرتبط کنید. به استفاده از SceneCoreEntity برای قرار دادن شیء سه‌بعدی در چیدمان مراجعه کنید.

قرار دادن مدل سه‌بعدی بااستفاده از Jetpack Scenecore

برای بار کردن مدل glTF، با GltfModel.create() تماس بگیرید.

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

در این مرحله، مدل در حافظه بار می‌شود، اما هنوز رندر نشده است. اگر مدل‌های سه‌بعدی زیادی برای بار کردن دارید یا مدل شما بزرگ است، ایده خوبی است که آن‌ها را به‌صورت ناهمگام ازقبل بار کنید. به‌این‌ترتیب، کاربران مجبور نیستند منتظر بمانند تا مدل‌های شما در حافظه بار شود.

glTF را به ActivitySpace اضافه کنید. GltfModelEntity.create را فراخوانی کنید تا موجودیتی ایجاد کند و آن را در ActivitySpace قرار دهد. به‌عنوان روال مطلوب، باید بررسی کنید که برنامه در وضعیتی باشد که قابلیت‌های فضایی را امکان‌پذیر کند.

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

اکنون باید مدل سه‌بعدی بارشده را هنگام اجرای برنامه‌تان ببینید.

نمونه‌ای از مدل سه‌بعدی بارشده

بار کردن مدل سه‌بعدی بااستفاده از Scene Viewer

اگر به‌دنبال ساده‌ترین راه برای بار کردن مدل سه‌بعدی با قابلیت‌های تعامل پایه هستید، می‌توانید از Scene Viewer همان‌طور که در تلفن همراه استفاده می‌کنید، استفاده کنید. تفاوت کلیدی بین Scene Viewer در Android XR و در تلفن همراه این است که Scene Viewer فقط از پارامتر URI فایل که به فایل glTF اشاره می‌کند پشتیبانی می‌کند و همه پارامترهای دیگر نادیده گرفته می‌شوند.

Scene Viewer برنامه جداگانه‌ای است که بااستفاده از هدف فراخوانی می‌شود و در «حالت فضای کامل» اجرا می‌شود. درنتیجه، وقتی آن را فراخوانی می‌کنید، برنامه‌تان دیگر قابل‌مشاهده نخواهد بود و Scene Viewer تمرکز خواهد داشت. هر محیطی که ممکن است تغییر داده باشید به اولویت‌های سیستم کاربر بازنشانی خواهد شد.

در اینجا مثالی از استفاده از Intent برای مشاهده فایل glTF در Scene Viewer در Android XR آورده شده است:

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.
}

برای اطلاعات بیشتر درباره گزینه‌های تعاملی برای «نمای صحنه»، به اسناد طراحی مدل سه‌بعدی ما مراجعه کنید.

افزونه‌های glTF

Jetpack XR SDK از چندین افزونه glTF پشتیبانی می‌کند که قابلیت‌های مدل‌های سه‌بعدی را گسترش می‌دهند. این قابلیت‌ها هم ازطریق GltfModelEntity و هم Scene Viewer دردسترس است.