שכבות-על של קרקע

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

דוגמאות קוד

במאגר ApiDemos ב-GitHub יש דוגמה שממחישה שכבות-על של קרקע:

• ‫GroundOverlayDemoActivity – Java: תכונות של שכבת-על של קרקע ומאזינים ב-Java
• ‫GroundOverlayDemoActivity – Kotlin: תכונות של שכבת-על של קרקע ומאזינים ב-Kotlin

מבוא

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

הוספת שכבת-על

כדי להוסיף GroundOverlay, יוצרים אובייקט GroundOverlayOptions שמגדיר גם תמונה וגם מיקום. אפשר גם לציין הגדרות נוספות שישפיעו על המיקום של התמונה במפה. אחרי שמגדירים את האפשרויות הנדרשות, מעבירים את האובייקט לשיטה GoogleMap.addGroundOverlay() כדי להוסיף את התמונה למפה. השיטה addGroundOverlay() מחזירה אובייקט GroundOverlay. כדאי לשמור הפניה לאובייקט הזה אם רוצים לשנות אותו בהמשך.

הוראות מפורטות:

1. יצירת מופע של אובייקט GroundOverlayOptions חדש
2. מציינים את התמונה כ-BitmapDescriptor.
3. מגדירים את המיקום של התמונה באחת מהשיטות הזמינות:
   • position(LatLng location, float width, float height)
   • position(LatLng location, float width)
   • positionFromBounds(LatLngBounds bounds)
4. מגדירים מאפיינים אופציונליים, כמו transparency, לפי הצורך.
5. מתקשרים אל GoogleMap.addGroundOverlay() כדי להוסיף את התמונה למפה.

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

val newarkLatLng = LatLng(40.714086, -74.228697)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f)
map.addGroundOverlay(newarkMap)

      

LatLng newarkLatLng = new LatLng(40.714086, -74.228697);

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f);
map.addGroundOverlay(newarkMap);

      

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

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
val imageOverlay = map.addGroundOverlay(newarkMap)

      

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);

      

הסרת שכבת-על

אפשר להסיר שכבת-על של קרקע באמצעות השיטה GroundOverlay.remove().

imageOverlay?.remove()

      

imageOverlay.remove();

      

שינוי שכבת-על

אפשר לשנות את תמונת שכבת העל הקרקעית אחרי שמוסיפים אותה למפה באמצעות השיטה GroundOverlay.setImage(BitmapDescriptor).

// Update the GroundOverlay with a new image of the same dimension
imageOverlay?.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))

      

// Update the GroundOverlay with a new image of the same dimension
imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922));

      

השיטה setImage() תחליף את התמונה הקיימת בתמונה אחרת עם אותם ממדים.

מיקום של שכבת-על של קרקע

יש שתי דרכים לציין את המיקום של שכבת-העל הקרקעית:

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

צריך לציין את המיקום של שכבת העל של הקרקע לפני שמוסיפים אותה למפה.

שימוש במיקום כדי למקם תמונה

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

הקוד שבהמשך ממקם תמונה במיקום 40.714086, -74.228697 ברוחב של 8.6 ק"מ ובגובה של 6.5 ק"מ. התמונה מעוגנת בפינה הימנית התחתונה.

val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0f, 1f)
    .position(LatLng(40.714086, -74.228697), 8600f, 6500f)

      

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0, 1)
    .position(new LatLng(40.714086, -74.228697), 8600f, 6500f);

      

שימוש ב-LatLngBounds למיקום תמונה

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

הקוד שלמטה מציב תמונה במפה, כשהפינה הדרום-מערבית שלה קשורה ל-40.712216,-74.22655 והפינה הצפון-מזרחית שלה קשורה ל-40.773941, -74.12544.

val newarkBounds = LatLngBounds(
    LatLng(40.712216, -74.22655),  // South west corner
    LatLng(40.773941, -74.12544)   // North east corner
)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds)

      

LatLngBounds newarkBounds = new LatLngBounds(
    new LatLng(40.712216, -74.22655),       // South west corner
    new LatLng(40.773941, -74.12544));      // North east corner
GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds);

      

שיוך נתונים לשכבת-על של הקרקע

אפשר להתקשר אל GroundOverlay.setTag() כדי לאחסן אובייקט נתונים שרירותי עם שכבת-על של קרקע, ולאחזר את אובייקט הנתונים באמצעות GroundOverlay.getTag().

בדוגמת קוד הבאה, תיאור מחרוזת מאוחסן עם שכבת-על של קרקע:

val sydneyGroundOverlay = map.addGroundOverlay(
    GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
        .position(LatLng(-33.873, 151.206), 100f)
        .clickable(true)
)
sydneyGroundOverlay?.tag = "Sydney"

      

GroundOverlay sydneyGroundOverlay = map.addGroundOverlay(new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
    .position(new LatLng(-33.873, 151.206), 100)
    .clickable(true));

sydneyGroundOverlay.setTag("Sydney");

      

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

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

טיפול באירועים של שכבת-על קרקעית

כברירת מחדל, אי אפשר ללחוץ על שכבות-על של קרקע. אפשר להפעיל ולהשבית את האפשרות ללחוץ על הקישור באמצעות הקריאה ל-GroundOverlay.setClickable(boolean).

משתמשים ב-OnGroundOverlayClickListener כדי להאזין לאירועי קליקים בשכבת-על של קרקע שאפשר ללחוץ עליה. כדי להגדיר את מאזין המיקום במפה, צריך להתקשר אל GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener). כשמשתמש לוחץ על שכבת-על של הקרקע, מתקבל קריאה חוזרת (callback) של onGroundOverlayClick(GroundOverlay).