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

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

דוגמאות קוד

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

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

מבוא

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

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

כדי להוסיף GroundOverlay, צריך ליצור GroundOverlayOptions שמגדיר גם תמונה ומיקום. אפשר גם לציין ה��דרות נוספות ישפיעו על מיקום התמונה במפה. אחרי שמגדירים את האפשרויות הנדרשות, מעבירים את האובייקט אל GoogleMap.addGroundOverlay() כדי להוסיף את התמונה למפה. ה-method 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

// 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 עבור בשכבת-על.

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

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

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