דף זה תורגם על ידי Cloud Translation API.

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

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

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

מה תפַתחו

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

מה תלמדו

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

למה תזדקק?

מכשיר ARCore Android נתמך, שמחובר באמצעות כבל USB למכונת הפיתוח שלכם, מוגדר באמצעות ניפוי באגים ב-USB.
אפליקציית Android Studio מותקנת ומוגדרת ליצירת אפליקציות ל-Android.
Google Play Services ל-AR מגרסה 1.31 ואילך, מותקנת במכשיר הפיתוח של Android.

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

הגדרת Android Studio

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

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

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

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

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

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

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

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

פתיחת אפליקציה > מקור > AndroidManifest.xml.

חיפוש 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" />

מחליפים את PLACEHOLDER_API_KEY במפתח ה-API שיצרתם בפרויקט שלכם ב-Google Cloud.

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

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

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

פרויקט Boilerplate

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, האפליקציה יכולה לקבל מידע גיאו-מרחבי.

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

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

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

רוצה לנסות?

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

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

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

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

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

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

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

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

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

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

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

5. סיכום

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

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

הנושאים שטיפלנו בהם

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

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

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