פיתוח אפליקציה של מציאות רבודה (AR) באמצעות ARCore Geospatial API

1. סקירה כללית

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

מה תפַתחו

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

מה תלמדו

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

הדרישות

2. הגדרת סביבת הפיתוח

הגדרה של Android Studio

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

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

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

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

  1. יוצרים פרויקט במסוף Google Cloud:
    • אפשר לעיין במאמר בנושא יצירת פרויקט ב-Google Cloud Platform.
      יצירת פרויקט של Google Cloud
    • מזינים שם פרויקט מתאים (לדוגמה, ARCore Geospatial API project) ובוחרים מיקום כלשהו.
    • לוחצים על יצירה.
  2. מפעילים את ממשקי ה-API הנדרשים:
    • בסרגל הצד, בוחרים באפשרות APIs & Services (ממשקי API ושירותים) ואז באפשרות Library (ספרייה).
    • מחפשים את ARCore API.
    • לוחצים על הפעלה.
    • חוזרים לספרייה.
    • מחפשים את SDK של מפות ל-Android.
    • לוחצים על הפעלה.
  3. יצירת פרטי כניסה של מפתח API:
    • בקטע APIs & Services, בוחרים באפשרות Credentials.
    • בסרגל העליון, לוחצים על Create Credentials (יצירת אמצעי אימות) ואז על API Key (מפתח API).
    • חשוב לשים לב למפתח שנוצר כי תצטרכו להזין אותו בשלב הבא. חוזרים לדף Credentials אם צריך לאחזר אותו.

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

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

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

  1. פותחים את app > src > AndroidManifest.xml.
  2. מחפשים את הרשומות הבאות של meta-data:
    <meta-data
    android:name="com.google.android.ar.API_KEY"
    android:value="PLACEHOLDER_API_KEY" />

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="PLACEHOLDER_API_KEY" />
  3. מחליפים את PLACEHOLDER_API_KEY במפתח ה-API שיצרתם בפרויקט בענן ב-Google Cloud.

הערך שמאוחסן ב-com.google.android.ar.API_KEY מאשר לאפליקציה הזו להשתמש ב-Geospatial API, והערך שמאוחסן ב-com.google.android.geo.API_KEY מאשר לאפליקציה הזו להשתמש ב-SDK של מפות Google.

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

מוודאים שהפרויקט מוכן להפעלה. ב-Android Studio, מריצים את האפליקציה. אמורה להופיע שידור מהמצלמה, יחד עם מפה פעילה בחלק התחתון של המסך.

פרויקט שבלוני

3. קביעת המיקום של המשתמש

בשלב הזה מוסיפים קוד לפרויקט לדוגמה כדי להתחיל להשתמש ב-Geospatial API.

הגדרת סשן ARCore לשימוש ב-Geospatial API

כדי לקבל נתונים גיאו-מרחביים, צריך להפעיל את Geospatial API. משנים את GeospatialMode בהגדרות הסשן ל-ENABLED על ידי שינוי הפונקציה configureSession ב-HelloGeoActivity.kt:

fun configureSession(session: Session) {
  session.configure(
    session.config.apply {
      // Enable Geospatial Mode.
      geospatialMode = Config.GeospatialMode.ENABLED
    }
  )
}

בזמן שמצב הגיאו-מרחבי הוא ENABLED, האפליקציה יכולה לקבל מידע גיאו-מרחבי.

בקשת נתונים מ-Geospatial API

בשורה HelloGeoRenderer.kt, מחפשים את השורה הבאה:

// TODO: Obtain Geospatial information and display it on the map.

מתחת לזה, בודקים שאובייקט Earth זמין לשימוש. זה קורה כשיש trackingState TrackingState.ENABLED.

val earth = session.earth
if (earth?.trackingState == TrackingState.TRACKING) {
  // TODO: the Earth object may be used here.
}

מתחת ל-TODO, מבקשים מידע גיאו-מרחבי מ-ARCore. מוסיפים את השורה הבאה:

val cameraGeospatialPose = earth.cameraGeospatialPose

כך מקבלים GeospatialPose שמכיל את הפרטים הבאים:

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

הצגת מידע על המיקום במפה

אפשר להשתמש בGeospatialPose שמאוחסן ב-cameraGeospatialPose כדי להזיז סמן במפה שמראה איפה המשתמש נמצא. ממשיכים מהמקום שבו הפסקתם ומוסיפים את הקוד הבא:

activity.view.mapView?.updateMapPosition(
  latitude = cameraGeospatialPose.latitude,
  longitude = cameraGeospatialPose.longitude,
  heading = cameraGeospatialPose.heading
)

המיקום של המפה מתעדכן כל הזמן באמצעות הערכים שמתקבלים מ-Geospatial API.

רוצה לנסות?

ב-Android Studio, לוחצים על Play (הפעלה). מחזיקים את המכשיר ומזיזים אותו כדי לעזור ל-ARCore לבצע מעקב. אחרי זמן קצר, סמן ירוק אמור להופיע במפה. הסמן הזה מסתובב כשמסתכלים על הסביבה. הוא גם צריך להצביע לכיוון הנכון: כשאתם פונים פיזית לכיוון צפון, החץ גם מצביע לכיוון צפון.

החץ הירוק עוקב אחרי המיקום והכיוון שלכם.

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

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

בשלב הזה, מוסיפים דרך להצבת עוגן על ידי הקשה על המפה.

הגדרת פעולה כשמקישים על המפה

הפרויקט כולל פונקציה בשם onMapClick, שמופעלת עם קו רוחב וקו אורך כשלוחצים על קטע המפה. מאתרים את הפונקציה onMapClick ב-HelloGeoRenderer.kt.

מוודאים שאפשר להשתמש באובייקט Earth

לפני שיוצרים עוגנים ב-Earth, מוודאים שהערך של TrackingState באובייקט Earth הוא TRACKING, כלומר שהמיקום של כדור הארץ ידוע. כדאי גם לוודא שEarthState הוא ENABLED, כלומר לא נתקלתם בבעיות ב-Geospatial API. מוסיפים את השורות האלה בתוך onMapClick:

val earth = session?.earth ?: return
if (earth.trackingState != TrackingState.TRACKING) {
  return
}

קביעת המיקום של העוגן החדש

אחרי שמוודאים שאובייקט כדור הארץ מתעדכן, מנתקים את האובייקט הקודם earthAnchor, אם קיים. בשלבים הבאים מחליפים את earthAnchor בעוגן חדש:

earthAnchor?.detach()

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

// Place the earth anchor at the same altitude as that of the camera to make it easier to view.
val altitude = earth.cameraGeospatialPose.altitude - 1
// The rotation quaternion of the anchor in the East-Up-South (EUS) coordinate system.
val qx = 0f
val qy = 0f
val qz = 0f
val qw = 1f
earthAnchor =
  earth.createAnchor(latLng.latitude, latLng.longitude, altitude, qx, qy, qz, qw)

‫createAnchor יוצרת Anchor שקבוע לקואורדינטות גאודטיות עם סיבוב נתון. העוגן הזה מנסה להישאר יציב וקבוע בקואורדינטות ובגובה שצוינו.

הצגת הסמן שהוצב במפה

לבסוף, מעבירים סמן חדש שמציין איפה הסמן הוצב:

activity.view.mapView?.earthMarker?.apply {
  position = latLng
  isVisible = true
}

רוצה לנסות?

ב-Android Studio, לוחצים על Play (הפעלה). מחזיקים את המכשיר ומזיזים אותו כדי לעזור ל-ARCore לבצע מעקב. אחרי זמן קצר, במפה אמור להופיע סמן ירוק שמציין את המיקום הנוכחי שלכם.

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

מקישים על המפה כדי למקם סמן.

5. סיכום

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

מקישים על המפה כדי למקם סמן.

מה נכלל

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

מקורות מידע נוספים

לפרטים נוספים על המושגים הגיאוגרפיים ועל ערכות ה-SDK שבהן נעשה שימוש ב-codelab הזה, אפשר לעיין במקורות המידע הנוספים הבאים: