איך מתחילים לעבוד עם ממשקי ה-API של Streetscape Geometry ו-Rooftop anchors ב-ARCore

1. לפני שמתחילים

‫ARCore הוא מסגרת העבודה של Google ליצירת חוויות במציאות רבודה (AR) בסמארטפונים. ממשקי ה-API של גיאומטריית נוף רחוב ושל עוגן על גג עוזרים לחוויות המציאות הרבודה להבין את הבניינים שסביב המשתמשים.

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

הדגמה מלאה של אפליקציית ה-Codelab

דרישות מוקדמות

מה תלמדו

  • איך מגדירים פרויקט ב-Google Cloud שאפשר להשתמש בו ב-ARCore Geospatial APIs.
  • איך מקבלים גיאומטריה של תצלומי רחוב מ-Geospatial API.
  • איך מדמיינים בניינים ושטחים שמתקבלים מגיאומטריה של נוף רחוב.
  • איך מבצעים חישובים בסיסיים על המצולעים שהתקבלו.
  • איך מבצעים בדיקת פגיעה בגאומטריה.
  • איך משתמשים בנקודות עיגון על גגות כדי לצרף תוכן לחלק העליון של מבנים.

מה נדרש

2. הגדרת הסביבה

כדי להשתמש בממשקי ה-API למידע גיאוגרפי עם Kotlin ו-Android Studio, צריך פרויקט ב-Google Cloud ופרויקט התחלתי.

הגדרת פרויקט ב-Google Cloud

‫ARCore Geospatial API מתחבר ל-Google Cloud כדי לספק מידע על לוקליזציה ממערכת מיקום חזותי (VPS) של Google באזורים שמכוסים על ידי Google Street View.

כדי להשתמש בשרת הזה בפרויקט, פועלים לפי השלבים הבאים:

  1. יוצרים פרויקט ב-Google Cloud.יצירת פרויקט של Google Cloud
  2. בשדה Project name (שם הפרויקט), מזינים שם מתאים, כמו ARCore Geospatial API project, ובוחרים מיקום כלשהו.
  3. לוחצים על יצירה.
  4. במסוף Google Cloud, בדף לבחירת הפרויקט, לוחצים על Create Project.
  5. לוחצים על הקישור הבא כדי להציג את ARCore API עבור הפרויקט הזה ואז לוחצים על הפעלה:
  6. יוצרים מפתח API לפרויקט:
    1. בקטע APIs & services, בוחרים באפשרות Credentials.
    2. לוחצים על Create credentials ובוחרים באפשרות API key.
    3. חשוב לרשום את המפתח כי תצטרכו אותו בהמשך.

יצרתם פרויקט ב-Google Cloud עם הרשאה של מפתח API, ואתם מוכנים להשתמש ב-Geospatial API בפרויקט לדוגמה.

הגדרה של Android Studio

כדי להתחיל לעבוד עם Geospatial API, סיפקנו פרויקט התחלתי שכולל את היסודות של פרויקט ARCore שמשולב עם Geospatial API.

כדי להגדיר את Android Studio, צריך לבצע את השלבים הבאים:

  1. פותחים את Android Studio ומבצעים אחת מהפעולות הבאות:
    • אם כבר פתוח פרויקט, לוחצים על קובץ > חדש > פרויקט מניהול גרסאות.
    • אם מופיע החלון Welcome to Android Studio (ברוכים הבאים ל-Android Studio), לוחצים על Get from VCS (קבלת נתונים ממערכת בקרת גרסאות). אחזור ממיקום VCS
  2. בוחרים באפשרות Git ומזינים https://github.com/google-ar/codelab-streetscape-geometry-rooftop-anchors.git כדי לייבא את הפרויקט.

הטמעה של מפתח ה-API בפרויקט Android Studio

כדי לשייך את מפתח ה-API מ-Google Cloud לפרויקט שלכם, פועלים לפי השלבים הבאים:

  1. ב-Android Studio, לוחצים על app > src ולוחצים לחיצה כפולה על AndroidManifest.xml.
  2. מחפשים את הרשומות הבאות meta-data:
    <meta-data
    android:name="com.google.android.ar.API_KEY"
    android:value="API_KEY" />
  3. מחליפים את ה-placeholder‏ API_KEY במפתח ה-API שיצרתם בפרויקט ב-Google Cloud. הערך שמאוחסן ב-com.google.android.ar.API_KEY מאשר לאפליקציה הזו להשתמש ב-Geospatial API.

אימות הפרויקט

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

מידע גיאו-מרחבי מוצג באפליקציה

3. המחשה של נתוני גיאומטריה של נוף רחוב

אחרי שמוודאים ש-Geospatial API פועל במכשיר, מקבלים את הגיאומטריה של תצלומי הרחוב מ-Geospatial API.

הפעלת גיאומטריית נוף רחוב

  1. בקובץ StreetscapeGeometryActivity.kt, מחפשים את השורה הבאה:
    // TODO: Enable Streetscape Geometry.
  2. אחרי השורה הזו, מפעילים את מצב streetscape-geometry:
    streetscapeGeometryMode = Config.StreetscapeGeometryMode.ENABLED
    כשמפעילים את Geospatial API ואת מצב streetscape-geometry, האפליקציה יכולה לקבל מידע על גיאומטריית נוף רחוב בסביבת המשתמש.

קבלת גיאומטריה של תצוגת רחוב

  1. בקובץ StreetscapeGeometryActivity.kt, מחפשים את השורה הבאה:
    // TODO: Obtain Streetscape Geometry.
  2. אחרי השורה הזו, מקבלים את הגיאומטריה של תצוגת הרחוב על ידי קבלת כל האובייקטים מסוג Trackable וסינון לפי StreetscapeGeometry:
    val streetscapeGeometry = session.getAllTrackables(StreetscapeGeometry::class.java)
    השתמשו בגיאומטריות האלה בהדמיה פשוטה שמופיעה בפרויקט לדוגמה. בתצוגה החזותית הזו, כל פוליגון של בניין או שטח מוצג בצבע שונה.
  3. בשורה הבאה, מוסיפים את הקוד הבא:
    streetscapeGeometryRenderer.render(render, streetscapeGeometry)
  4. מפעילים את האפליקציה ומבקרים בבניין באזור שלכם.
  5. אחרי שמסיימים את הלוקליזציה הגיאוגרפית, מקישים על סמל ההגדרות הגדרות ומפעילים את ההדמיה של גיאומטריית נוף הרחוב.
  6. מסתכלים על בניין ב-AR. לכל בניין מפולח יש צבע משלו, ומוצגים ערכי ה-Enum של הגיאומטריה המרכזית ביותר Quality ו-Type.

גיאומטריית נוף הרחוב מוצגת באפליקציה

4. ביצוע בדיקת פגיעה באמצעות נתוני גיאומטריה של תצוגת רחוב

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

ביצוע בדיקת כניסות

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

  1. בקובץ StreetscapeCodelabRenderer.kt, מחפשים את השורה הבאה:
    // TODO: determine the Streetscape Geometry at the center of the viewport
  2. אחרי השורה הזו, מוסיפים את הקוד הבא:
    ‫
    val centerHits = frame.hitTest(centerCoords[0], centerCoords[1])
val hit = centerHits.firstOrNull {
  val trackable = it.trackable
  trackable is StreetscapeGeometry && trackable.type == StreetscapeGeometry.Type.BUILDING
} ?: return
    הקוד הזה משתמש בקואורדינטות של המרכז כדי למצוא גיאומטריה של נוף רחוב שהיא בניין. משתמשים בתוצאה הזו כדי להוסיף קישוטים.

הוספת קישוט של כוכב בלחיצה

  1. בקובץ StreetscapeCodelabRenderer.kt, מחפשים את השורה הבאה:
    // TODO: Create an anchor for a star, and add it to the starAnchors object.
  2. אחרי השורה הזו, מוסיפים את הקוד הבא:
    ‫
    val transformedPose = ObjectPlacementHelper.createStarPose(hit.hitPose)
val anchor = hit.trackable.createAnchor(transformedPose)
starAnchors.add(anchor)
    המחלקות ObjectPlacementHelper קובעות מיקום מתאים להצבת הכוכב על ידי בחינת תנוחת הפגיעה. האובייקט starAnchors משמש לעיבוד הכוכבים בתצוגת ה-AR.

רוצה לנסות?

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

הכוכבים מוצבים באפליקציה

5. שימוש בנתונים של נקודות עיגון על גגות

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

הוספת התנהגויות למצב הבלון

לפרויקט יש שני מצבי מיקום נכסים: מצב החמנייה שבו כבר השתמשתם ומצב הבלון.

כדי לתכנת את ההתנהגות של מצב הבלון:

  1. בקובץ StreetscapeCodelabRenderer.kt, מחפשים את השורה הבאה:
    // TODO: Create an anchor for a balloon and add it to the balloonAnchors object.
  2. כדאי להשתמש בתנוחת הפגיעה כדי ליצור נקודה טובה למיקום הבלון:
    val transformedPose = ObjectPlacementHelper.createBalloonPose(frame.camera.pose, hit.hitPose)
  3. המרת המשתנה transformedPose לתנוחה גיאו-מרחבית:
    val earth = session?.earth ?: return
val geospatialPose = earth.getGeospatialPose(transformedPose)
  4. יוצרים עוגן על הגג עם קו הרוחב וקו האורך שעברו טרנספורמציה:
    earth.resolveAnchorOnRooftopAsync(
  geospatialPose.latitude, geospatialPose.longitude,
  0.0,
  transformedPose.qx(), transformedPose.qy(), transformedPose.qz(), transformedPose.qw()
) { anchor, state ->
  if (!state.isError) {
    balloonAnchors.add(anchor)
  }
}

רוצה לנסות?

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

מניחים בלונים על גגות

6. סיכום

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

הדגמה מלאה של אפליקציית ה-Codelab

מידע נוסף