התאמה אישית של מודלים תלת-ממדיים באפליקציה

מכשירי XR שמתאימים לשימוש
ההנחיות האלה יעזרו לכם ליצור חוויות למכשירי XR מהסוגים הבאים.
מידע על סוגי מכשירי XR →
משקפי XR
משקפי XR חוטיים
מידע על סוגי מכשירי XR →

לפני שמתאימים אישית מודל תלת-ממדי, צריך קודם להוסיף אותו לאפליקציה. אחרי שמוסיפים מודל תלת-ממדי לאפליקציה, אפשר לשפר את החוויה החזותית והאינטראקטיבית על ידי התאמה אישית של המראה והתנועה של המודל התלת-ממדי.

לדוגמה, אתם יכולים להפעיל ולשלוט באנימציות מוטמעות של glTF, לגשת לצמתים שמרכיבים את המודל ולהזיז אותם, או אפילו לטעון טקסטורות בהתאמה אישית ולהגדיר מאפייני חומר כדי לבטל רשתות פנימיות. היכולות האלה מאפשרות לכם לשנות באופן דינמי את המראה וההתנהגות של אובייקט בזמן הריצה.

אובייקטים בתלת ממד ב-Android XR

‫Jetpack XR SDK תומך בתקן הפתוח glTF 2.0 של Khronos Group למודלים תלת-ממדיים, ומבצע עיבוד של האובייקטים האלה באמצעות טכניקות של עיבוד פיזיקלי (PBR) שמוגדרות בתקן glTF 2.0 (יחד עם תוספים נתמכים). ‫glTF (פורמט העברה של ספריית גרפיקה) הוא פורמט קובץ סטנדרטי להעברה ולטעינה של סצנות ומודלים תלת-ממדיים. מודל glTF מורכב ממבנה היררכי של רכיבים פנימיים.

אלה הרכיבים העיקריים שחשוב להכיר:

  • צמתים: הצמתים מגדירים את המבנה וההיררכיה של המודל. לכל צומת יכולים להיות מיקום, סיבוב וקנה מידה משלו.
  • רשתות: הגיאומטריה התלת-ממדית והמבנית שיוצרת את הצורה של אובייקט תלת-ממדי.
  • חומרים: החומרים מגדירים את המראה החזותי של הרשתות, כמו הצבע, החספוס או האופן שבו הן מגיבות לתאורה.
  • טקסטורות: נכס תמונה, כמו קובץ PNG, שאפשר להחיל על פני השטח של מודל תלת-ממדי כדי ליצור דוגמאות, צבעים, פרטים או אפקטים חזותיים אחרים בהתאמה אישית.
  • אנימציות: אלה רצפים מוגדרים מראש או טראקים של אנימציה שמכילים שינויים בצמתים ובמִשטחים בודדים כדי ליצור מראה של תנועה לאורך זמן.

ב-Jetpack Compose for XR, מעבדים את הקבצים האלה באמצעות SpatialGltfModel ועוקבים אחרי סטטוס הטעינה והאנימציה באמצעות SpatialGltfModelState. מידע נוסף זמין במאמר הוספת מודלים תלת-ממדיים לאפליקציה.

הנפשת מודלים תלת-ממדיים

יכול להיות שיוטמעו אנימציות במודלים תלת-ממדיים. באופן פנימי, אנימציות משתמשות בדגימות כדי להגדיר את התזמון והערכים של תנועה, ובערוצים כדי לקשר את התנועות האלה לצמתים ולרשתות בודדים. אנימציות של שלד ואנימציות של חומרים שנוצרו באמצעות KHR_animation_pointer התוסף glTF נתמכות ב-Jetpack XR SDK.

כדי להפעיל אנימציה באמצעות Compose for XR, מציינים את השם של הטראק הספציפי מתוך רשימת animations. משתמשים ב-animation.start() כדי להתחיל בהפעלה. אופציונלי: אפשר לציין את המהירות, את זמן ההמתנה ואם האנימציה תפעל בלולאה באמצעות 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()
    }
}

שינוי צמתים: תנוחות וסיבוב

כדי לשנות חלקים ספציפיים במודל ולשנות את המאפיינים שלו, כמו סיבוב או תנוחה, צריך לשלוח שאילתה ל-nodes הפנימי של מודל ה-glTF באמצעות 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" }

אחרי שמאתרים את הצומת הנכון, אפשר להגדיר את localPose כדי לשנות את המיקום והסיבוב בתלת-ממד ביחס לצומת האב המיידי GltfModelNode, או להשתמש ב-modelPose כדי להגדיר את המיקום ביחס לצומת הבסיס GltfModelEntity. באופן דומה, אפשר להשתמש ב-localScale/modelScale כדי לשנות את קנה המידה של המודל ביחס לתבנית ההורה או לתבנית הבסיס שלו.

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

התאמה אישית של מאפייני החומר של המודל התלת-ממדי

אתם יכולים לשנות את המאפיינים של חומרים במהלך זמן הריצה כדי לשנות את המראה של אובייקט באופן דינמי על סמך קלט של משתמשים או המצב הנוכחי של האפליקציה.

ב-Jetpack XR, המחלקות KhronosPbrMaterial ו-KhronosUnlitMaterial משמשות ליצירה ולשינוי של החומרים האלה. כפי שהשם מרמז, KhronosUnlitMaterials לא מוארים ולא מושפעים מתאורה בסצנה. KhronosPbrMaterial מאפשרת לכם להתאים אישית מגוון רחב יותר של מאפיינים, כמו צבע הברק, מידת המתכתיות או החספוס של אובייקט והאם הוא פולט אור.

מידע נוסף על כל מאפיין נתמך ועל הפרמטרים הניתנים להתאמה אישית ב-Android XR זמין במסמכי העזר. כדי להבין טוב יותר את המאפיינים האלה, אפשר לעיין במילון המונחים של Khronos.

איור 1. דוגמה לשינוי הצבעים הבסיסיים במודל תלת-ממדי.

כדי להתאים אישית את מאפייני החומר של המודל התלת-ממדי, קודם צריך ליצור את החומר החדש באמצעות KhronosPbrMaterial. תצטרכו להגדיר את AlphaMode המתאים כדי להשיג את המראה הרצוי:

לאחר מכן, מגדירים את המאפיינים שרוצים לשנות. בדוגמה הזו נעשה שימוש ב-setBaseColorFactor כדי לשנות את צבע הבסיס של הרשת לסגול. בשיטה הזו נדרש Vector4, כאשר הרכיבים x, y, z, ו-w תואמים לערכי ה-RGBA (אדום, ירוק, כחול ואלפא) בהתאמה:

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

טעינת טקסטורות בהתאמה אישית למודל תלת-ממדי

Texture הוא נכס תמונה שאפשר להחיל על פני השטח של מודל תלת-ממדי כדי לספק צבע, פרטים או מידע אחר על פני השטח. ‫Jetpack XR Texture API מאפשר לטעון נתוני תמונה, כמו קובצי PNG, מהתיקייה /assets/ של האפליקציה באופן אסינכרוני.

כשמעלים טקסטורה, אפשר לציין TextureSampler, שקובע איך הטקסטורה תוצג. הסמפלר מגדיר מאפייני סינון (למקרים שבהם הטקסטורה מופיעה קטנה יותר או גדולה יותר מהגודל המקורי שלה) ומצבי גלישה (לטיפול בקואורדינטות מחוץ לטווח [0, 1] הרגיל). צריך להקצות Texture ל-KhronosPbrMaterial כדי ליצור אפקט חזותי במודל תלת-ממדי.

איור 2. דוגמה לשינוי הטקסטורה בדגם תלת-ממדי.

כדי לטעון טקסטורה בהתאמה אישית, קודם צריך לשמור את קובץ התמונה בתיקייה /assets/. מומלץ גם ליצור textures תיקיית משנה בתיקייה הזו.

אחרי ששומרים את הקובץ בספרייה המתאימה, יוצרים את הטקסטורה באמצעות API‏ Texture. כאן גם אפשר להחיל TextureSampler אופציונלי, אם צריך.

בדוגמה הזו מוחלת טקסטורת חסימה ומוגדרת עוצמת החסימה:

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

החלת חומרים וטקסטורות על אובייקטים בתלת-ממד

כדי להחיל את החומר או הטקסטורה החדשים, צריך לבטל את החומר הקיים בצומת ספציפי ב-node של קובץ ה-glTF. כדי לעשות זאת, קוראים ל-API‏ setMaterialOverride:

node?.setMaterialOverride(
    material = material
)

כדי להסיר את החומרים שנוצרו, מתקשרים אל clearMaterialOverride בצומת שהוחלף קודם. הפעולה הזו מחזירה את המודל התלת-ממדי למצב ברירת המחדל שלו:

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

‫glTF והלוגו של glTF הם סימנים מסחריים של Khronos Group Inc.