פיתוח באמצעות Geospatial Creator ו-Places API מהפלטפורמה של מפות Google

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

הכלי Geospatial Creator ב-Unity, שמבוסס על ARCore ועל משבצות תלת-ממד פוטו-ריאליסטיות מ-Google Maps Platform, מאפשר לכם ליצור במהירות חוויות מציאות רבודה (AR) ולראות אותן בתצוגה מקדימה עבור קו רוחב וקו אורך ספציפיים, והכול בתוך Unity Editor. השימוש ב-Geospatial יכול לקצר משמעותית את הזמן שנדרש ליצירת סצנת AR אחת עם מיקום גיאוגרפי לאפליקציה, אבל מה קורה אם רוצים ליצור כמה חוויות דומות במיקומים שונים? אפשר לעשות את זה גם באמצעות C# API ב-Geospatial Creator.

ב-codelab הזה תכתבו קוד C# ‎ שמשתמש ב-Geospatial Creator וב-Places API מתוך הפלטפורמה של מפות Google כדי ליצור כמה חוויות גיאוספציאליות באמצעות תבנית ראשונית. אפשר לבדוק את התוצאות ולשפר אותן ב-Unity Editor לפני שיוצרים מהן אפליקציה.

הספר בגובה הנכון

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

מה תלמדו

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

מה נדרש

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

כדי להשתמש ב-Geospatial Creator, צריך להגדיר הרשאה לגישה ל-Photorealistic 3D Tiles, לשירותי ARCore ב-Google Cloud ול-Places API מהפלטפורמה של מפות Google.

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

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

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

  1. יוצרים פרויקט במסוף Google Cloud.יצירת פרויקט של Google Cloud
  2. בתיבת הטקסט Project name, מזינים שם מתאים, כמו ARCore Geospatial Project, ואז בוחרים מיקום כלשהו.
  3. לוחצים על יצירה.
  4. במסוף Google Cloud, בדף לבחירת הפרויקט, לוחצים על Create Project.
  5. אפשר לעיין במאמר בנושא הפעלת חיוב ובמאמרים בנושא תמחור של Photorealistic 3D Tiles ותמחור של Places API (חדש).

הפעלת Map Tiles API

‫Map Tiles API מספק קטעי מפה ריאליסטיים בתלת-ממד, שמוצגים ב-Unity Editor.

  • כדי להפעיל את Map Tiles API, לוחצים על הלחצן הבא ואז על הפעלה:

הפעלת ARCore API

‫ARCore API ב-Google Cloud מאפשר לכם לגשת אל ARCore Geospatial API במכשיר היעד.

  • כדי להפעיל את ARCore API, לוחצים על הלחצן הבא ואז בוחרים באפשרות הפעלה:

הפעלת Places API

ממשק ה-API של Places מהפלטפורמה של מפות Google מאפשר לכם לקבל נתוני מיקום של יותר מ-200 מיליון מקומות, ותשתמשו בו בסדנת הקוד כדי למצוא מקומות קשורים. ‫API שמספק תוצאות חיפוש וקואורדינטות גיאוגרפיות של מקומות.

  • כדי להפעיל את Places API, לוחצים על הלחצן הבא ואז בוחרים באפשרות הפעלה:

יצירת מפתח API לפרויקט

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

  1. במסוף Google Cloud, בקטע APIs & services, בוחרים באפשרות Credentials.
  2. בחלק העליון של הדף, לוחצים על Create Credentials ואז על API Key.
  3. חשוב לשים לב למפתח כי תצטרכו אותו בשלבים הבאים.

הגדרת התוכנה

כדי להתחיל להשתמש בתוכנת Geospatial Creator, פועלים לפי השלבים הבאים:

  1. משכפלים את המאגר הזה.
  2. מורידים את Unity Hub ומשתמשים בו כדי להתקין את Unity גרסה 2022.3. חשוב לוודא שאתם מתקינים את כלי הבנייה האופציונליים ל-Android או ל-iOS.
  3. ב-Unity Hub, לוחצים על Add > Add project from disk (הוספה > הוספת פרויקט מהדיסק).
  4. בחלונית Hierarchy, בוחרים באפשרות AR Geospatial Creator Origin.
  5. בתיבת הטקסט Google Maps Tile API Key (מפתח API של משבצות במפות Google), מזינים את מפתח ה-API ואז לוחצים על Enter (או על return ב-macOS).הוספת מפתח ה-API ל-Origin ב-Geospatial Creator
  6. בקטע עריכה > הגדרות הפרויקט > ניהול תוספים של XR > תוספים של ARCore, משתמשים באימות של מפתח API ל-Android או ל-iOS ומזינים את מפתח ה-API.
  7. בקטע File > Build Settings (קובץ > הגדרות Build), מעבירים את פלטפורמת היעד ל-Android או ל-iOS.

3. יצירת העוגן הראשון

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

מידע על הרכיב Origin ב-Geospatial Creator

כל סצנת Unity שנבנית באמצעות Geospatial Creator מחייבת בדיוק Geospatial Creator Origin אחד. אובייקט המשחק הזה הוא נקודת ההתייחסות להמרה של ערכי קו רוחב, קו אורך וגובה בעולם האמיתי לקואורדינטות של משחק Unity.

פרויקט הדוגמה מכיל Geospatial Creator Origin, שמשתמש ב-Cesium כדי לעבד Photorealistic 3D Tiles בתצוגה Scene של Editor, ומאפשר לכם לראות בדיוק איפה בעולם יופיע תוכן ה-AR שלכם.

העברת המקור

מעבירים את המקור של Geospatial Creator לקווי הרוחב והאורך של הסניף הראשי של ספריית סן פרנסיסקו.

כדי להשתמש בשילוב המובנה של Geospatial Creator עם Places API כדי להעביר אוטומטית את המקור למיקום הנכון, פועלים לפי השלבים הבאים:

  1. בחלונית Hierarchy, בוחרים באובייקט המשחק Geospatial Creator Origin.
  2. בחלונית Inspector, לוחצים על Search for Location (חיפוש מיקום).
  3. בתיבת הדו-שיח של החיפוש, מקלידים San Francisco Public Library. התוצאה הראשונה צריכה להיות בכתובת 100 Larkin Street.
  4. לוחצים על החלה על אובייקטים כדי להחיל את תוצאת החיפוש על המקור. אפשר לראות שקווי האורך והרוחב של המקור מתעדכנים לקואורדינטות החדשות.

המבנה נראה בתמונה

הוספת עוגן של Geospatial Creator לסצנה

אחרי שיוצרים Origin, מוסיפים עוגן של Geospatial Creator באמצעות GameObject > XR > AR Geospatial Creator Anchor. כברירת מחדל, נקודת העיגון תמוקם יחד עם המקור.

העוגן הזה משמש למיקום של תוכן תלת-ממדי ב-AR. מודל תלת-ממדי של ספר כלול בפרויקט לדוגמה.

כדי למקם את הספר בסצנה:

  1. בחלונית Project, גוררים את המודל Book לחלונית התצוגה Editor.
  2. בחלונית היררכיה, מוודאים שהפריט Book הוא צאצא של העוגן שיצרתם קודם. כל אובייקט משחק צאצא של העוגן ב-Geospatial Creator ימוקם ביחס לעוגן.
  3. בחלונית היררכיה, בוחרים באפשרות ספר. מגדירים את ערכי המיקום שלו כ-0, 0, 0.

הספר נוסף לסצנה

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

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

  • כדי לעשות זאת, פותחים את חלונית הבדיקה של העוגן ומגדירים את המאפיין Altitude Type לערך Rooftop.

חלונית הבדיקה

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

  • כדי שהמודל ירחף מעל גג הספרייה במקום להיות מונח עליו, משנים את הפרמטר Altitude relative to rooftop ל-15 מטרים מעל הגג.

המודל מרחף עכשיו מעל הספרייה.

הספר בגובה הנכון

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

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

4. חיפוש מיקומי עוגן חדשים באמצעות Places API

‫Places API מתוך Google Maps Platform מאפשר לכם לקבל נתוני מיקום עבור יותר מ-200 מיליון מקומות. ב-codelab הזה, משתמשים ב-API הזה כדי למצוא סניפים אחרים של ספריות ציבוריות בסן פרנסיסקו, ומשתמשים בתוצאות האלה כדי ליצור עוגן ב-Geospatial Creator עבור עשר תוצאות החיפוש הבאות.

  • כדי להתחיל, לוחצים על נכסים > סקריפטים > עורך ופותחים את הקובץ AnchorDuplicator.cs. בקובץ הזה יש קוד boilerplate שיעזור לכם להתחיל להשתמש ב-Places API ולנתח את התוצאות שלו.

אימות באמצעות Places API

  1. מחפשים את השורה הבאה בכיתה AnchorDuplicator:
    private const string API_KEY = "<YOUR_API_KEY_HERE>";
  2. מחליפים את הערך <YOUR_API_KEY_HERE> במפתח שהתקבל בשלבי ההגדרה.

ביצוע שאילתה ב-Places API לחיפוש מונח

אחרי שתשלימו את הגדרת ההרשאה ל-Places API, תוכלו לכתוב קוד שיפעיל בקשת POST.

  • כדי לעשות זאת, מאתרים את CreatePlacesRequest ומשתמשים בהגדרת השיטה הבאה:
    ‫
    string postBody = "{ \"textQuery\": \"" + searchTerm + "\", " + 
                    "   \"locationBias\": { \"circle\": { " +
                    "      \"center\": { \"latitude\": " + lat + ", \"longitude\": " + lon + " }, " +
                    "      \"radius\": 10000 }" +
                    "   }" +
                    "}";

string url = "https://places.googleapis.com/v1/places:searchText";

UnityWebRequest request = UnityWebRequest.Post(url, postBody, "application/json");
request.SetRequestHeader("X-Goog-Api-Key", apiKey);
request.SetRequestHeader("X-Goog-FieldMask", "places.displayName,places.location");

return request;
    עכשיו, כשקוראים לשיטה CreatePlacesRequest, נשלחת בקשה לחיפוש searchTerm בעיגול שממורכז סביב lat ו-lon.

בדיקת העבודה

לפני שממשיכים, צריך לוודא שהקריאות ל-Places API בוצעו בהצלחה.

  1. מריצים את הפונקציות ב-Unity Editor:
    1. ב-Google AR Codelab, לוחצים על Run Places Request (הפעלת בקשה ל-Places).
    2. פותחים את מסוף Unity. התוצאות אמורות להופיע.מקומות מופיעים במסוף

5. הוספת עוגנים למקומות באופן פרוגרמטי

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

יצירת פריט בתפריט

  1. בקטע AnchorDuplicator class, מחפשים את השיטה CreateNewAnchorsFromPlaces ומשתמשים בהגדרה הבאה של השיטה:
    if (_places == null)
{
    Debug.LogError("Cannot create anchors: Places has not been initialized.");
    return;
}

// You start with only one anchor in the scene, which you want to copy:
var prototypeAnchorObject = GameObject
    .FindObjectOfType<ARGeospatialCreatorAnchor>()
    .gameObject;

foreach (var place in _places)
{
    var newAnchorObject = GameObject.Instantiate(prototypeAnchorObject);
    var anchor = newAnchorObject.GetComponent<ARGeospatialCreatorAnchor>();
    anchor.Latitude = place.location.latitude;
    anchor.Longitude = place.location.longitude;

    newAnchorObject.name = place.displayName.text;
}
    פריט התפריט הזה בודק בקשה שהופעלה קודם ומשתמש ב-ARGeospatialCreatorAnchor הראשון בסצנה כאב-טיפוס ליצירת עוגנים, אחד לכל מקום בתוצאה של Places API.
  2. כדי ליצור את העוגנים, משתמשים באפשרות החדשה בתפריט Create New Anchors from Places Response ב-Google AR Codelab.
  3. אמורים להופיע כמה עוגנים בחלונית Hierarchy.

אימות המיקומים של העוגנים

כדי לוודא שכל הנכסים מעוגנים במיקומים הנכונים לפני שמריצים את האפליקציה, פועלים לפי השלבים הבאים:

  1. לוחצים על עוגן שהוסף בחלונית היררכיה.
  2. מקישים על F.
  3. בודקים את העוגן בתצוגה Scene.
  4. אם נקודת העיגון לא נמצאת במיקום הנכון, לוחצים על הצמדה למשבצת או משנים ידנית את הערכים Latitude, Longitude או Editor Override Altitude.

6. צפייה בנכס ב-AR

כדי לראות את הנכס ב-AR במכשיר Android או iOS שתומך ב-ARCore, פועלים לפי השלבים הבאים:

  1. לוחצים על File (קובץ) > Build Settings (הגדרות בנייה), ואז בוחרים בפלטפורמות הבנייה Android או iOS.
  2. לוחצים על החלפת פלטפורמה.
  3. מוודאים שמכשיר הפיתוח מחובר ומוגדר לפיתוח.
  4. לוחצים על Build and run (בנייה והפעלה).
  5. מוודאים שהאפליקציה פועלת במכשיר.
  6. עוברים למיקומים שבהם הצמדתם את התוכן. אם לא שיניתם את הדוגמאות, המיקומים הם ספריות ציבוריות בסן פרנסיסקו.

צפייה בחוויית ה-AR

7. סיכום

מעולה! כתבתם אפליקציית Unity שמשתמשת ב-Geospatial Creator וב-Google Maps Platform Places API כדי ליצור כמה חוויות גיאו-מרחביות באמצעות תבנית ראשונית. אנחנו מקווים שתשתמשו בידע הזה כדי להרחיב את היקף החשיפה של התוכן שלכם ב-Geospatial Creator.

מידע נוסף