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