מצלמה ותצוגה

בחירת פלטפורמה: Android iOS JavaScript

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

דוגמאות קוד

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

• CameraDemoActivity – Kotlin: שינוי של מיקום המצלמה
• CameraDemoActivity – Java: שינוי מיקום המצלמה

מבוא

כמו במפות Google באינטרנט, ה-SDK של מפות Google ל-Android מייצג את פני השטח של העולם (כדור) על מסך המכשיר (מישור שטוח) באמצעות הקרנת Mercator. בכיוון מזרח ומערב, המפה חוזרת על עצמה אינסופית כשהעולם עוטף את עצמו בצורה חלקה. בכיוון צפון ודרום המפה מוגבלת ל-85 מעלות צפונה ול-85 מעלות דרום.

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

SDK של מפות ל-Android מאפשר לשנות את נקודת המבט של המשתמש במפה על ידי שינוי המצלמה של המפה.

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

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

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

מיקום המצלמה

תצוגת המפה מעוצבת כמצלמה שמביטה למטה על מישור שטוח. מיקום המצלמה (ומכאן גם הצגת המפה) נקבע באמצעות המאפיינים הבאים: target (קו רוחב/קו אורך), נושא, הטיה ומרחק התצוגה.

טירגוט (מיקום)

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

קו הרוחב יכול להיות בין 85- ל-85 מעלות, כולל. ערכים מעל או מתחת לטווח הזה יוצמדו לערך הקרוב ביותר בטווח הזה. לדוגמה, ציון קו רוחב 100 יגרום להגדרת הערך ל-85. קו האורך נע בין 180- ל-180 מעלות, כולל. הערכים שמעל או מתחת לטווח הזה ייכתבו כך שהם ימוקמו בטווח (-180, 180). לדוגמה, 480, 840 ו-1200 יכסו את כולן ל-120 מעלות.

כיוון (כיוון)

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

המשמעות של סיבוב 0 היא שהחלק העליון של המפה מצביע על הצפון האמיתי. ערך כיוון 90 משמעו החלק העליון של המפה מצביע לכיוון מזרח (90 מעלות במצפן). ערך 180 פירושו החלק העליון של הנקודות במפה שהיעד מדרום.

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

הטיה (זווית תצוגה)

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

בתמונות שלמטה, זווית הצפייה היא 0 מעלות. בתמונה הראשונה אפשר לראות סכימה של זה. מיקום 1 הוא מיקום המצלמה, ומיקום 2 הוא המיקום הנוכחי במפה. המפה שתתקבל מוצגת מתחתיה.

המפה שמוצגת עם זווית הצפייה שמוגדרת כברירת מחדל במצלמה.

זווית הצפייה המוגדרת כברירת מחדל במצלמה

בתמונות שלמטה, זווית הצפייה היא 45 מעלות. שימו לב שהמצלמה נעה בחצי לאורך קשת בין התקורה ישרה (0 מעלות) לקרקע (90 מעלות), למיקום 3. המצלמה עדיין מצביעה על נקודת המרכז של המפה, אבל עכשיו אפשר לראות את האזור שמיוצג על ידי הקו במיקום 4.

המפה מוצגת בזווית של 45 מעלות.

זווית צפייה במצלמה של 45 מעלות.

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

זום

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

הגדלת מרחק התצוגה ב-1 מכפילה את רוחב העולם במסך. במקרה כזה, ברמת הזום N, רוחב העולם הוא בערך 256 * 2^N dp. לדוגמה, ברמת זום 2, העולם כולו ברוחב של בערך 1024dp.

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

• 1: עולם
• 5: קרקע/יבשת
• 10: עיר
• 15: רחובות
• 20: בניינים

הערה: בגלל גודל המסך והצפיפות, יכול להיות שחלק מהמכשירים לא יתמכו ברמות הזום הנמוכות ביותר. משתמשים ב-GoogleMap.getMinimumZoomLevel() על מנת להגדיל את הזום המינימלי האפשרי של המפה. אם אתם צריכים להציג את כל העולם באזור התצוגה, יכול להיות שעדיף להשתמש במצב בסיסי.

בתמונות הבאות אפשר לראות את המראה החזותי של רמות זום שונות:

מפה ברמת זום 5.

מפה ברמת זום 15.

מפה ברמת זום 20.

הזזת המצלמה

ה-API של מפות Google מאפשר לשנות את החלק של העולם שמוצג במפה. כדי לעשות את זה צריך לשנות את המיקום של המצלמה (בניגוד להזיז את המפה).

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

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

כדי לשנות את מיקום המצלמה, יש לציין לאן רוצים להעביר את המצלמה באמצעות CameraUpdate. ה-API של מפות Google מאפשר ליצור סוגים רבים ושונים של CameraUpdate באמצעות CameraUpdateFactory. אלו האפשרויות הזמינות:

שינוי רמת הזום והגדרת זום מינימלי/מקסימלי

CameraUpdateFactory.zoomIn() ו-CameraUpdateFactory.zoomOut() ייתנו לכם CameraUpdate שמשנה את מרחק התצוגה ב-1.0, בלי לשנות את כל שאר המאפיינים.

CameraUpdateFactory.zoomTo(float) נותן לכם CameraUpdate שמשנה את מרחק התצוגה לערך הנתון, בלי לשנות את כל שאר המאפיינים.

CameraUpdateFactory.zoomBy(float) ו-CameraUpdateFactory.zoomBy(float, Point) בוחרים ב-CameraUpdate שמגדיל (או מקטין, אם הערך שלילי) את רמת הזום בערך הנתון. האפשרות השנייה מתקנת את הנקודה המסוימת על המסך כך שתישאר באותו מיקום (קו רוחב/אורך), וכך היא עשויה לשנות את מיקום המצלמה כדי להשיג זאת.

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

Kotlin

private lateinit var map: GoogleMap

    map.setMinZoomPreference(6.0f)
    map.setMaxZoomPreference(14.0f)

      

Java

private GoogleMap map;
    map.setMinZoomPreference(6.0f);
    map.setMaxZoomPreference(14.0f);

      

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

משנה את מיקום המצלמה

יש שתי שיטות נוחות לביצוע שינויי מיקום נפוצים. CameraUpdateFactory.newLatLng(LatLng) נותן לך CameraUpdate שמשנה את קווי האורך והרוחב של המצלמה, תוך שמירה על כל שאר המאפיינים. CameraUpdateFactory.newLatLngZoom(LatLng, float) מספק CameraUpdate שמשנה את קו הרוחב, קו האורך והזום של המצלמה תוך שמירה על כל שאר המאפיינים.

כדי ליהנות מגמישות מלאה בשינוי מיקום המצלמה, מומלץ להשתמש ב-CameraUpdateFactory.newCameraPosition(CameraPosition), שמספק CameraUpdate שמעביר את המצלמה למיקום הנתון. אפשר לקבל CameraPosition באופן ישיר, באמצעות new CameraPosition() או באמצעות CameraPosition.Builder באמצעות new CameraPosition.Builder().

הזזה (גלילה)

CameraUpdateFactory.scrollBy(float, float) מספק CameraUpdate שמשנה את קווי האורך והרוחב של המצלמה, כך שהמפה זזה לפי מספר הפיקסלים שצוין. ערך x חיובי גורם למצלמה לעבור ימינה, כך שנראה שהמפה זזה שמאלה. ערך y חיובי גורם למצלמה לנוע למטה, כך שנראה שהמפה זזה למעלה. לעומת זאת, ערכי x שליליים גורמים למצלמה לזוז שמאלה, כך שנראה שהמפה זזה ימינה וערכי y שליליים גורמים למצלמה לעלות למעלה. הגלילה מתבצעת ביחס לכיוון הנוכחי של המצלמה. לדוגמה, אם המצלמה בכיוון של 90 מעלות, אז מזרח הוא "למעלה".

הגדרת גבולות

הגדרת גבולות המפה

לפעמים כדאי להזיז את המצלמה כך שאזור העניין כולו גלוי ברמת המרחק מהתצוגה. לדוגמה, אם כל תחנות הדלק מוצגות במרחק של עד חמישה קילומטרים ממיקומו הנוכחי של המשתמש, כדאי להזיז את המצלמה כך שכולן יוצגו במסך. כדי לעשות זאת, קודם צריך לחשב את הערך של LatLngBounds שרוצים שיוצג במסך. לאחר מכן תוכלו להשתמש ב-CameraUpdateFactory.newLatLngBounds(LatLngBounds bounds, int padding) כדי לקבל CameraUpdate שמשנה את מיקום המצלמה כך שה-LatLngBounds הנתון יהיה בתוך המפה, תוך התחשבות במרווח הפנימי (בפיקסלים) שצוין. בעזרת הערך CameraUpdate שמוחזר אפשר להבטיח שהפער (בפיקסלים) בין הגבולות הנתונים לקצה המפה יהיה לפחות כמו המרווח שצוין. שימו לב שההטיה והנושא של המפה יהיו 0.

Kotlin

val australiaBounds = LatLngBounds(
    LatLng((-44.0), 113.0),  // SW bounds
    LatLng((-10.0), 154.0) // NE bounds
)
map.moveCamera(CameraUpdateFactory.newLatLngBounds(australiaBounds, 0))

      

Java

LatLngBounds australiaBounds = new LatLngBounds(
    new LatLng(-44, 113), // SW bounds
    new LatLng(-10, 154)  // NE bounds
);
map.moveCamera(CameraUpdateFactory.newLatLngBounds(australiaBounds, 0));

      

הערה: אפשר להפעיל את newLatLngBounds(boundary, padding) רק כדי לשנות את המצלמה אחרי שפריסת המפה תושלם. הסיבה לכך היא שה-API מחשב את גבולות התצוגה של המפה במהלך הפריסה. אם רוצים להפעיל את newLatLngBounds() לפני שנוצרה הפריסה, אפשר להשתמש ב-newLatLngBounds(boundary, width, height, padding) שמתואר למטה.

מרכוז המפה בתוך אזור מסוים

במקרים מסוימים, כדאי למרכז את המצלמה בגבולות מסוימים במקום לכלול את הגבולות הקיצוניים. לדוגמה, כדי למרכז את המצלמה על מדינה מסוימת תוך שמירה על זום קבוע. במקרה כזה, אפשר להשתמש בשיטה דומה על ידי יצירת LatLngBounds ושימוש ב-CameraUpdateFactory.newLatLngZoom(LatLng latLng, float zoom) עם LatLngBounds.getCenter(). השיטה getCenter() תחזיר את המרכז הגיאוגרפי של LatLngBounds.

Kotlin

val australiaBounds = LatLngBounds(
    LatLng((-44.0), 113.0),  // SW bounds
    LatLng((-10.0), 154.0) // NE bounds
)
map.moveCamera(CameraUpdateFactory.newLatLngZoom(australiaBounds.center, 10f))

      

Java

LatLngBounds australiaBounds = new LatLngBounds(
    new LatLng(-44, 113), // SW bounds
    new LatLng(-10, 154)  // NE bounds
);
map.moveCamera(CameraUpdateFactory.newLatLngZoom(australiaBounds.getCenter(), 10));

      

עומס יתר של השיטה, newLatLngBounds(boundary, width, height, padding), מאפשר לציין רוחב וגובה בפיקסלים עבור מלבן, מתוך כוונה להתאים אותם למידות המפה. המלבן ממוקם כך שהמרכז שלו זהה לזה של תצוגת המפה (כך שאם המידות שצוינו זהות לאלו של תצוגת המפה, המלבן חופף לתצוגת המפה). השדה המוחזר CameraUpdate יזיז את המצלמה כך שה-LatLngBounds שצוין יהיה במרכז המסך בתוך המלבן הנתון ברמת הזום הגדולה ביותר, תוך התחשבות במרווח הפנימי הנדרש.

הערה: יש להשתמש בשיטה הפשוטה יותר newLatLngBounds(boundary, padding) כדי ליצור CameraUpdate אם מתכוונים להשתמש בו כדי להזיז את המצלמה אחרי פריסת המפה. במהלך הפריסה, ה-API מחשב את גבולות התצוגה של המפה שנדרשים כדי להקרין בצורה נכונה את התיבה התוחמת. לשם השוואה, אפשר להשתמש ב-CameraUpdate שהוחזר על ידי השיטה המורכבת יותר newLatLngBounds(boundary, width, height, padding) בכל שלב, עוד לפני שהמפה עברה פריסה, מפני שה-API מחשב את גבולות התצוגה מהארגומנטים שמעבירים.

הגבלת ההזזה של המשתמש לאזור נתון

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

Kotlin

// Create a LatLngBounds that includes the city of Adelaide in Australia.
val adelaideBounds = LatLngBounds(
    LatLng(-35.0, 138.58),  // SW bounds
    LatLng(-34.9, 138.61) // NE bounds
)

// Constrain the camera target to the Adelaide bounds.
map.setLatLngBoundsForCameraTarget(adelaideBounds)

      

Java

// Create a LatLngBounds that includes the city of Adelaide in Australia.
LatLngBounds adelaideBounds = new LatLngBounds(
    new LatLng(-35.0, 138.58), // SW bounds
    new LatLng(-34.9, 138.61)  // NE bounds
);

// Constrain the camera target to the Adelaide bounds.
map.setLatLngBoundsForCameraTarget(adelaideBounds);

      

התרשים הבא ממחיש תרחיש שבו יעד המצלמה מוגבל לאזור קצת יותר גדול מאזור התצוגה. המשתמש יכול לגלול ולנוע, בתנאי שיעד המצלמה נשאר בתוך האזור המתוחם. הצלב מייצג את יעד המצלמה:

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

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

מתבצע עדכון של תצוגת המצלמה

כדי להחיל CameraUpdate על המפה, אפשר להזיז את המצלמה מיד או להוסיף אנימציה למצלמה. כדי להזיז את המצלמה מיד עם CameraUpdate הנתון, תוכלו להתקשר ל-GoogleMap.moveCamera(CameraUpdate).

אפשר ליצור אנימציה של השינוי כדי ליצור חוויית משתמש נעימה יותר, במיוחד בתנועות קצרות. כדי לעשות זאת, במקום להתקשר אל GoogleMap.moveCamera, צריך להתקשר אל GoogleMap.animateCamera. המפה תעבור בצורה חלקה למאפיינים החדשים. בשיטה המפורטת ביותר של השיטה הזו, GoogleMap.animateCamera(cameraUpdate, duration, callback), יש שלושה ארגומנטים:

cameraUpdate

הסמל CameraUpdate מתאר לאן להעביר את המצלמה.

callback

אובייקט שמטמיע את GoogleMap.CancellableCallback. בממשק הכללי הזה לטיפול במשימות מוגדרות שתי שיטות 'onCancel() ' ו-'onFinish() '. באנימציה, השיטות נקראות בשיטות הבאות:

onFinish()

מופעלת כאשר האנימציה מסתיימת ללא הפרעה.

onCancel()

מופעלת אם האנימציה נעצרת על ידי קריאה ל-stopAnimation() או הפעלה של תנועת מצלמה חדשה.

לחלופין, מצב כזה יכול לקרות גם כשמתקשרים אל GoogleMap.stopAnimation().

duration

משך הזמן הרצוי של האנימציה, באלפיות השנייה, כint.

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

Kotlin

val sydney = LatLng(-33.88, 151.21)
val mountainView = LatLng(37.4, -122.1)

// Move the camera instantly to Sydney with a zoom of 15.
map.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, 15f))

// Zoom in, animating the camera.
map.animateCamera(CameraUpdateFactory.zoomIn())

// Zoom out to zoom level 10, animating with a duration of 2 seconds.
map.animateCamera(CameraUpdateFactory.zoomTo(10f), 2000, null)

// Construct a CameraPosition focusing on Mountain View and animate the camera to that position.
val cameraPosition = CameraPosition.Builder()
    .target(mountainView) // Sets the center of the map to Mountain View
    .zoom(17f)            // Sets the zoom
    .bearing(90f)         // Sets the orientation of the camera to east
    .tilt(30f)            // Sets the tilt of the camera to 30 degrees
    .build()              // Creates a CameraPosition from the builder
map.animateCamera(CameraUpdateFactory.newCameraPosition(cameraPosition))

      

Java

LatLng sydney = new LatLng(-33.88,151.21);
LatLng mountainView = new LatLng(37.4, -122.1);

// Move the camera instantly to Sydney with a zoom of 15.
map.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, 15));

// Zoom in, animating the camera.
map.animateCamera(CameraUpdateFactory.zoomIn());

// Zoom out to zoom level 10, animating with a duration of 2 seconds.
map.animateCamera(CameraUpdateFactory.zoomTo(10), 2000, null);

// Construct a CameraPosition focusing on Mountain View and animate the camera to that position.
CameraPosition cameraPosition = new CameraPosition.Builder()
    .target(mountainView )      // Sets the center of the map to Mountain View
    .zoom(17)                   // Sets the zoom
    .bearing(90)                // Sets the orientation of the camera to east
    .tilt(30)                   // Sets the tilt of the camera to 30 degrees
    .build();                   // Creates a CameraPosition from the builder
map.animateCamera(CameraUpdateFactory.newCameraPosition(cameraPosition));