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

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

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

מה תפַתחו

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

מה תלמדו

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

מה הדרישות כדי להצטרף לתוכנית?

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

הגדרת Android Studio

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

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

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

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

  1. יוצרים פרויקט במסוף Google Cloud:
  2. הפעל את ממשקי ה-API הנחוצים:
    • בסרגל הצד, בוחרים באפשרות APIs & Services (ממשקי API ושירותים) ואז בוחרים באפשרות Library (ספרייה).
    • מחפשים את ARCore API.
    • לוחצים על Enable.
    • חוזרים לספרייה.
    • מחפשים את מפות ה-SDK ל-Android.
    • לוחצים על Enable.
  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

כדי לקבל נתונים גיאו-מרחביים, צריך להפעיל את ממשק ה-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, לוחצים על הפעלה. מחזיקים את המכשיר ומזיזים אותו כדי לעזור ל-ARCore ליצור מעקב. לאחר זמן מה, אמור להופיע סמן ירוק במפה. הסמן הזה מסתובב כשמביטים על הסביבה. כמו כן, עליך לכוון את המצלמה לכיוון הנכון: כאשר אתה פונה פיזית לצפון, החץ יצביע גם על צפון.

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

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

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

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

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

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

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

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

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

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

אחרי שמוודאים שאובייקט Earth עוקב, מנתקים את 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, לוחצים על הפעלה. מחזיקים את המכשיר ומזיזים אותו כדי לעזור ל-ARCore ליצור מעקב. לאחר זמן מה, אמור להופיע סמן ירוק במפה שמציין את המיקום הנוכחי שלכם.

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

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

5. סיכום

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

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

מה נכלל

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

משאבים נוספים

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