הכלי ARCore Geospatial Creator for Unity מאפשר לכם לראות תצוגה מקדימה של תוכן גיאו-מרחבי ב-Unity Editor, על ידי הצגת נתונים של מפות Google בפורמט חדש של משבצות תלת-ממדיות. כך תוכלו לראות איפה התוכן יוצג בעולם האמיתי בזמן שאתם מפתחים את האפליקציה.
הכלי ליצירת נתונים גיאו-מרחביים זמין כחלק מהתוספים של ARCore ל-AR Foundation. במדריך המקוצר הזה נסביר איך להשתמש ב-Geospatial Creator ב-Unity כדי להוסיף תוכן AR גיאו-מרחבי לאפליקציית הדוגמה הגיאו-מרחבית של ARCore.
אם יש לכם אפליקציה קיימת שבה אתם רוצים להשתמש במקום בדוגמה ל-Geospatial, תצטרכו קודם לפעול לפי המדריך למפתחים בנושא Geospatial ל-Unity. אחרי שמגדירים את האפליקציה לשימוש ב-Geospatial API, מדלגים לשלב הוספת יחסי תלות נדרשים שבהמשך ופועלים לפי ההוראות.
דרישות מוקדמות
כדי להגדיר את סביבת Unity ליצירת חוויות AR, פועלים לפי ההוראות במאמר תחילת העבודה עם ARCore Extensions for AR Foundation.
התוסף ARCore Extensions תומך בגרסאות קודמות של Unity, אבל כדי להשתמש ב-Geospatial Creator צריך Unity 2021.3 או גרסה חדשה יותר.
הרשאה ל-API
כדי להשתמש ב-ARCore Geospatial API וב-Google Map Tiles API, צריך להגדיר גישה ל-API.
Google Map Tiles API
Map Tiles API מספק ייצוג תלת-ממדי ופוטו-ריאליסטי של מיקומים נתמכים. נשתמש במשבצות האלה ב-Unity Editor כדי להציג תצוגה מקדימה של האזור שמסביב לסצנת ה-AR.
בדף Map Tiles API אפשר להפעיל את ה-API ולקרוא מידע נוסף על Map Tiles.
ARCore Geospatial API
האפליקציה משתמשת ב-ARCore Geospatial API בזמן הריצה כדי ליצור עוגנים גאוגרפיים ולקיים איתם אינטראקציה.
כדי להפעיל את ממשקי ה-API של Geospatial, צריך להגדיר את ARCore API באפליקציה. אפשר להשתמש בשיטות ההרשאה Keyless (מומלץ) או API Key.
הרחבת אפליקציית הדוגמה הגיאו-מרחבית
במדריך הזה נסביר איך להשתמש ב-Geospatial Creator כדי להוסיף תוכן גיאו-מרחבי לאפליקציית הדוגמה הגיאו-מרחבית של ARCore.
הגדרת הדוגמה הגיאו-מרחבית
קודם כל, כדאי להכיר את אפליקציית הדוגמה הגיאו-מרחבית של ARCore. בפרויקט חדש של Unity, פותחים את Unity Package Manager ובוחרים את חבילת ARCore Extensions. בחלונית הפרטים של Package Manager, מרחיבים את Samples ומייבאים את Geospatial Sample לפרויקט Unity.
לפני שמריצים את האפליקציה, צריך להפעיל את ARCore ואת הפונקציונליות הגיאו-מרחבית בפרויקט. משתמשים באפשרות עריכה > הגדרות הפרויקט... > XR Plug-in Management (ניהול פלאגינים של XR). מסמנים את התיבות המתאימות כדי להפעיל את ספק הפלאגין ARCore ל-Android או את ספק הפלאגין ARKit ל-iOS.
לאחר מכן, בתפריט עריכה > הגדרות הפרויקט... > XR Plug-in Management (ניהול פלאגינים של XR), פותחים את החלונית ARCore Extensions (תוספים של ARCore). מוודאים שהתיבה 'גיאו-מרחבי' מסומנת (עדיין לא צריך להפעיל את הכלי ליצירת נתונים גיאו-מרחביים), ומזינים את פרטי הכניסה ל-API. פרטים נוספים מופיעים במאמר בנושא הפעלת Geospatial Unity API ל-Android ול-iOS.
יש עוד כמה הגדרות של Player שספציפיות לפלטפורמה ונדרשות לכל אפליקציית Unity שמשתמשת ב-ARCore. בקטע Configure Player Settings (הגדרת הגדרות של נגן) במסמכים שלנו מפורטים השינויים הנדרשים.
בשלב הזה, אין אובייקטים של משחקים בסצנה שלכם, מלבד מה שנדרש להרצת הדוגמה הגיאוספציאלית. זה הזמן המתאים ליצור ולהריץ את האפליקציה. אם היא הוגדרה בצורה נכונה, בזמן הריצה יוצג באפליקציה תצוגת המצלמה של המכשיר. כשזזים, הדיוק הגיאוגרפי שמוצג בחלק העליון של המסך מתחיל להשתפר. כשמקישים על המסך, נוצרים עוגנים גיאו-מרחביים שיישארו במיקום המקורי שלהם בזמן שמסתובבים.
בהמשך נראה איך להשתמש ב-Geospatial Creator כדי ליצור תוכן AR מתוחכם ולראות אותו בתצוגה מקדימה מתוך Unity Editor. התוכן הזה יופיע באפליקציה במיקומים ספציפיים בעולם לפי קווי רוחב ואורך.
הוספת יחסי תלות נדרשים
הכלי Geospatial Creator משתמש בחבילת Unity של צד שלישי שנקראת Cesium כדי לעבד את משבצות המפה של Google בחלון Scene ב-Unity Editor. לפני שמפעילים את התכונות של Geospatial Creator, צריך להוסיף את חבילת Cesium לפרויקט.
מומלץ להתקין את הגרסה האחרונה של חבילת Cesium for Unity מדף GitHub של Cesium:
- מורידים את הגרסה העדכנית ביותר של
.tgzשל Cesium for Unity מהדף GitHub Releases. הגרסה המומלצת הנוכחית של חבילת Cesium for Unity היא 1.1.0. - פותחים את Unity Package Manager (מנהל חבילות Unity) על ידי לחיצה על התפריט 'Window' (חלון) ב-Unity ואז על 'Package Manager' (מנהל חבילות).
- לוחצים על סמל הפלוס (+) ובוחרים באפשרות 'הוספת חבילה מקובץ tarball'.
- בוחרים את קובץ ה- .tgz של Cesium for Unity שהורד בשלב 1.
- יכול להיות שתתבקשו להתקין יחסי תלות נוספים, כמו Text Mesh Pro.
הפעלת Geospatial Creator
עכשיו אפשר להפעיל את הכלי ליצירת נתונים גיאו-מרחביים:
- בתיבת הדו-שיח Build Settings (הגדרות build), מוודאים שהפלטפורמה שנבחרה היא Android או iOS. בשלב הזה, התכונות של Geospatial Creator לא זמינות בפלטפורמות אחרות.
- עוברים אל Project Settings > XR Plug-in Management > ARCore Extensions.
- אם לא הגדרתם את מפתחות ה-API של ARCore ל-Android או ל-iOS בשלב קודם, עכשיו זה הזמן לעשות זאת.
- מפעילים את המתגים 'גיאו-מרחבי' ו'Geospatial Creator'. אחרי שתלחצו על המתג להפעלת הכלי ליצירת נתונים גיאו-מרחביים, יוצג אשף לא מודאלי כדי לאשר שהפרויקט שלכם תואם לכלי ליצירת נתונים גיאו-מרחביים.
- לוחצים על 'סיום' באשף.
אחרי שמסיימים את האשף, Unity מפעיל קומפילציה של הסקריפטים. צריך להמתין עד שהקומפילציה מחדש תסתיים לפני שממשיכים. (אם הפלטפורמה שבחרתם היא לא Android או iOS, עברו לאחת מהן עכשיו).
הוספת מקור של Geospatial Creator באמצעות כרטיסי מידע של מפות
הסצנה צריכה לכלול אובייקט אחד בלבד מסוג Geospatial Creator Origin. האובייקט הזה משמש כנקודת ההתייחסות להמרה של ערכי קו רוחב, קו אורך וגובה בעולם האמיתי לקואורדינטות של משחק Unity.
כדי להוסיף רכיב Origin של Geospatial Creator לסצנה, בוחרים באפשרות Game Object > XR > Geospatial Creator Origin. האובייקט החדש שנוצר דורש הפניה גיאוגרפית, שמקשרת בין קו רוחב, קו אורך וגובה ספציפיים לבין מיקום המקור בקואורדינטות של המשחק. בחלונית Inspector של Geospatial Creator Origin, מוסיפים הפניה גיאוגרפית בלחיצה על הלחצן Add Cesium Georeference Component.
בנוסף להיותו נקודת הייחוס לאובייקטים של מציאות רבודה, האובייקט Cesium Georeference מוסיף לסצנה אובייקט Cesium 3D Tileset. האובייקט הזה יעבד את משבצות המפה של Google בתצוגת הסצנה של העורך, ויאפשר לכם לראות בדיוק איפה בעולם יופיע תוכן ה-AR שלכם. יש שדה בכלי לבדיקת מקורות של Geospatial Creator שבו אפשר להוסיף את מפתח ה-API של Map Tiles שהגדרתם קודם. אחרי שמגדירים את המפתח הזה, אמורים לראות את טעינת משבצות המפה בתצוגת הסצנה.
עכשיו משנים את השדות של קו הרוחב, קו האורך והגובה כך שיהיו קרובים למיקום שבו רוצים שהתוכן של ה-AR יופיע באפליקציה.
בתצוגת הסצנה בעורך אמורים להופיע עכשיו משבצות המפה בקו הרוחב ובקו האורך שצוינו במיקום המוצא. בזמן הריצה, אנחנו מניחים שהאפליקציה תשתמש במצלמת ה-AR, ולכן כלי היצירה הגיאו-מרחבית כבר הגדיר את אובייקט ה-Tileset של מפת Cesium 3D עם התג EditorOnly. לכן, המשבצות לא יורדו ולא יוצגו בזמן הריצה במשחק. אפשר לשנות את זה בכלי לבדיקת אובייקטים של Cesium3DTileset. מידע נוסף על Georeference ועל 3D Tileset GameObjects של Cesium זמין במאמרי העזרה של Cesium for Unity.
הוספה ומיקום של עוגן בכלי ליצירת נתונים גיאו-מרחביים
עכשיו אפשר להוסיף תוכן AR לסצנה. לוחצים על GameObject > XR > Geospatial Creator Anchor כדי להוסיף עוגן להיררכיית הסצנה. בכלי לבדיקת נקודות עוגן, אפשר לציין קו רוחב, קו אורך וגובה מדויקים. הטרנספורמציה של האובייקט תתעדכן באופן מיידי למיקום הנכון בסצנה, ותוכלו לראות בדיוק איפה בעולם האובייקט יופיע.
כשמכווננים את קו הרוחב וקו האורך של העוגן, כדאי לבחור מקום קרוב כדי שתוכלו לוודא שהוא נמצא במקום הנכון בזמן הריצה. כשמגדירים את הגובה של עוגן ב-Geospatial Creator, יש שלוש אפשרויות:
- שטח ממקם את העוגן ברמת הקרקע בקו הרוחב ובקו האורך שצוינו. רמת הקרקע נקבעת בזמן הריצה על ידי מערכת מיקום חזותי. אם אתם חדשים בשימוש בממשקי ה-API הגיאו-מרחביים של ARCore, כדאי לבחור באפשרות Terrain (שטח), כי העוגן יזוהה ישירות על הקרקע ברמת דיוק אנכית גבוהה. בשדה 'היסט גובה' אפשר להזין ערך במטרים כדי למקם את העוגן מעל או מתחת לפני הקרקע. לדוגמה, אם מציינים היסט של '1.0', העוגן 'צף' מטר אחד מעל פני השטח.
- גג: העוגן ממוקם ביחס לחלק העליון של מבנה כלשהו בקווי האורך והרוחב שצוינו. בדומה לעוגן של פני השטח, השדה 'הזחת גובה' מאפשר להזיז את העוגן למעלה או למטה ביחס למיקום הגג, במטרים.
- WGS84 ממקם את העוגן בגובה מוחלט ספציפי, במטרים, על סמך מערכת הקואורדינטות WGS84. יכול להיות שתצטרכו לנסות כמה פעמים עד שתצליחו למקם את האובייקט בצורה הזו, כי גובה של '0' ב-WSG84 לא בהכרח מציין את גובה פני הים, ויכול להיות שהוא לא יתאים לגובה שמוצג ב-GPS. בנוסף, למרות שקווי הרוחב והאורך של משבצות התלת-ממד שעברו רינדור מדויקים מאוד, ניסיון להציב את האובייקט בגובה פני הקרקע באמצעות משבצות התלת-ממד כהפניה עלול לגרום לשגיאת גובה של עד כמה מטרים.
מידע נוסף על הסוגים השונים של עוגנים גיאו-מרחביים של ARCore זמין במדריך למפתחים בנושא גיאו-מרחביות.
גם לעוגנים של פני השטח וגם לעוגנים של גגות יש שדה WGS84 Altitude (גובה לפי תקן WGS84). הערך הזה משמש רק במצב עריכה, כדי להגדיר את הגובה של האובייקט בתצוגת הסצנה. הגובה של השטח והגג נקבע רק בזמן הריצה, ולכן השדה WGS84 Altitude מאפשר לכם לראות את העוגן בגובה מסוים בזמן פיתוח האפליקציה. השדה WGS84 Altitude מתעלם בזמן הריצה מעוגנים של השטח והגג.
הוספת גיאומטריה לעוגן
אם תיצרו את האפליקציה ותפעילו אותה עכשיו, לא תראו את העוגן באפליקציה עם תמיכה ב-AR, כי לא מצורפת אליו גיאומטריה. מוסיפים צורה תלת-ממדית פשוטה לנקודת העיגון: בהיררכיית הסצנה, לוחצים לחיצה ימנית על אובייקט נקודת העיגון של AR Geospatial Creator. בתפריט ההקשר, בוחרים באפשרות אובייקט תלת-ממדי > קוביה. אמור להופיע קובייה אפורה בתצוגת הסצנה כצאצא של העוגן. אם מחליטים לשנות את המיקום או הסיבוב של האובייקט בכלי העריכה, מומלץ לשנות את המיקום של אובייקט העוגן הראשי ולא של הפרימיטיב המשני של הקובייה. כך אפשר לצמצם את השגיאות בתרגום מקווי רוחב ואורך לקואורדינטות במשחק.
כמובן שאפשר להוסיף לעוגן גם גיאומטריה מורכבת יותר ורכיבים שרירותיים ורכיבי צאצא.
איך יוצרים ומריצים את האפליקציה
הגיע הזמן לראות את העוגן בעולם האמיתי. מנסים ליצור ולהפעיל את האפליקציה, ואז עוברים למיקום שבו אמור להופיע הקובייה. האם הוא שם? מעולה, עכשיו אפשר ליצור חוויות מציאות רבודה מורכבות יותר באמצעות הכלי Geospatial Creator.
אם נתקלתם בבעיות, כדאי לעיין במדריך לפתרון בעיות.
זה הזמן להוסיף עוד עוגנים גיאוגרפיים של AR עם גיאומטריות שונות. כדאי להתנסות עם כמה עוגנים של גגות ושל פני השטח ועם ההיסטים שלהם. מוסיפים סקריפטים כדי להנפיש את האובייקטים או להפעיל אינטראקציות איתם.
הסבר על רכיבי העוגן ב-Geospatial Creator ועל המחלקה ARGeospatialAnchor
כשיוצרים חוויות מציאות רבודה מורכבות ואינטראקטיביות, כדאי להבין את הקשר בין עוגנים של Geospatial Creator לבין המחלקה ARGeospatialAnchor C# של ARCore:
אפשר ליצור ARGeospatialAnchor רק בזמן הריצה על ידי הפעלת אחת מהפונקציות ב-ARAnchorManager, ורק אחרי שהסשן של AR התייצב. אפשר לחשוב על עוגן של יוצר גיאוספציאלי כעל placeholder שקיים בסצנה, ומחכה שהסשן של ה-AR יהיה מוכן לפתור אובייקטים של ARGeospatialAnchor.
כשהסשן מוכן, ה-placeholder יתקשר אוטומטית אל ARAnchorManager כדי ליצור ולפתור את ARGeospatialAnchor.
מיד אחרי שהעוגן של זמן הריצה נפתר, העוגן של Geospatial Creator
בהיררכיית הסצנה יצורף כצאצא ל-GameObject החדש.
כלומר, כל הרכיבים או הצאצאים של רכיב העוגן של Geospatial Creator יהפכו לרכיבי משנה או לנכדים של אובייקט המשחק החדש ARGeospatialAnchor. לדוגמה, ה-transform של פרימיטיב גיאומטרי שמצורף ל-Geospatial Creator Anchor יירש את ה-transform של ARGeospatialAnchor, ולכן הוא יוצב במיקום הצפוי בסשן ה-AR בזמן הריצה.
אם אתם צריכים לזהות ARGeospatialAnchor GameObjects ספציפיים בזמן הריצה, אתם יכולים לחפש בסצנה אובייקטים שהמאפיין name שלהם תואם לעוגן שנוצר באמצעות Geospatial Creator. אם סשן ה-AR מאותחל, הערך של parent באובייקט הזה יהיה אובייקט ARGeospatialAnchor תואם.
פתרון בעיות
למה נקודת העיגון שלי זזה?
יכול להיות שתשימו לב, במיוחד כשהאפליקציה מופעלת בפעם הראשונה, שהעוגן כאילו "נסחף" לאט, או אפילו קופץ בפתאומיות כמה מטרים. זה קורה כשבמהלך הסשן של VPS עדיין מתבצעת קביעה של המיקום המדויק של המצלמה ושיפור שלו. ככל שהדיוק האופקי והאנכי משתפר על פני כמה פריימים, נקודת העיגון מצוירת מחדש במיקום מדויק יותר, ונוצרת אשליה של תנועה. יכול להיות שתרצו להציג את האובייקט בצורה שונה (או לא להציג אותו בכלל) עד שרמת הדיוק של המיקום תגיע לסף מסוים. כדי לעשות זאת, אפשר לשלוח שאילתה למאפיין ARCoreEarthManager.CameraGeospatialPose כדי לקבוע את רמת הדיוק של עדכון המסגרת הנוכחי.
למה העוגן שלי מופיע בגובה הלא נכון?
כשמשתמשים בסוג הגובה 'ידני' עבור עוגנים ב-Geospatial Creator, הגובה של העוגן מוגדר (במטרים) לפי WGS84. במיקום מסוים, יכול להיות פער של כמה מטרים בין מפלס הקרקע שמוצג במשבצות המפה לבין מפלס הקרקע בפועל, כפי שמדווח על ידי מערכת מיקום חזותי (VPS) של Google. אם נראה שמיקום של עוגן גיאו-מרחבי שגוי בזמן הריצה, מומלץ לאמת את הגובה של VPS באופן אישי באמצעות שכבת העל לניפוי באגים באפליקציה לדוגמה. לאחר מכן אפשר לשנות את הגובה בעורך Unity כך שיתאים לגובה הידוע של VPS במיקום הזה.
משבצות של מפות לא עוברות רינדור כמו שצריך בתצוגת הסצנה של העורך
אם נראה שמשבצות נטענות ב-Cesium3DTileset, אבל הן מוצגות במג'נטה מלא בתצוגת הסצנה, צריך להוסיף את חבילת Shader Graph של Unity לפרויקט. החבילה הזו נדרשת על ידי Cesium, אבל פרויקטים שמשתמשים במעבד התצוגה המובנה של Unity לא כוללים אותה כברירת מחדל.
כדי להוסיף את Shader Graph, פותחים את Unity Package Manager (מנהל החבילות של Unity) (Window > Package Manager (חלון > מנהל החבילות)). מוודאים שאתם מעיינים בחבילות שזמינות במאגר החבילות של Unity. לשם כך, בוחרים באפשרות Packages: Unity Registry (חבילות: מאגר Unity) מהתפריט הנפתח שבראש חלון מנהל החבילות. מחפשים את com.unity.shadergraph
החבילה ומתקינים את הגרסה האחרונה. אחרי שהחבילה תיטען, המשבצות התלת-ממדיות אמורות להיטען מחדש ולהופיע בצורה תקינה בתצוגת הסצנה.
בזמן הריצה, האפליקציה מציגה מסך שחור במקום תצוגת המצלמה
צינור הרינדור האוניברסלי (URP) של Unity לא מוגדר כברירת מחדל למצלמת AR. אם מוצג מסך שחור בזמן הריצה במקום הפלט של המצלמה, צריך להוסיף את AR Background Renderer Feature לכל רכיב URP Renderer בסצנה.
כדי להוסיף את התכונה, מחפשים את renderer בפרויקט. לכל אובייקט URP Renderer, לוחצים על הלחצן Add Renderer Feature (הוספת תכונת Renderer) בחלונית Inspector ומוסיפים את AR Background Renderer.
למה נראה שהעוגנים שממוקמים רחוק מהמקור ממוקמים בצורה שגויה?
ההמרה מקואורדינטות WGS84 לקואורדינטות של משחק Unity כפופה לשגיאה בגלל דיוק אריתמטי של נקודה צפה, שאפשר לצמצם אותה על ידי הקפדה על כך שהמקור יהיה קרוב לעוגני ה-AR. יכול להיות שיהיו אי דיוקים במרחקים של יותר מ-20 ק"מ. אם חוויית ה-AR שלכם מתפרסת על פני מרחקים גדולים, מומלץ להשתמש בכמה סצנות, עם עוגן ייחודי בכל סצנה.