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