Videocamera e vista

Seleziona la piattaforma: Android iOS JavaScript

Le mappe in Maps SDK for Android possono essere inclinate e ruotate con semplici gesti, consentendo agli utenti di regolare la mappa con un orientamento che ritengono più adatto. A qualsiasi livello di zoom, puoi spostarti sulla mappa o modificarne la prospettiva con una latenza minima grazie alle dimensioni ridotte dei riquadri della mappa basati su vettori.

Esempi di codice

Il repository ApiDemos su GitHub include un esempio che mostra le funzionalità della fotocamera:

• CameraDemoActivity - Kotlin: modifica della posizione della videocamera
• CameraDemoActivity - Java: modifica della posizione della videocamera

Introduzione

Come Google Maps sul web, Maps SDK for Android rappresenta la superficie del mondo (una sfera) sullo schermo del dispositivo (un piano piatto) utilizzando la proiezione di Mercatore. In direzione est e ovest, la mappa viene ripetuta all'infinito, poiché il mondo si avvolge su se stesso senza interruzioni. In direzione nord e sud, la mappa è limitata a circa 85 gradi nord e 85 gradi sud.

Nota: una proiezione di Mercatore ha una larghezza finita longitudinalmente, ma un'altezza infinita latitudinalmente. "Tagliamo" le immagini della mappa base utilizzando la proiezione di Mercatore a circa +/- 85 gradi per rendere quadrata la forma della mappa risultante, il che semplifica la logica per la selezione dei riquadri.

Maps SDK for Android ti consente di cambiare il punto di vista dell'utente sulla mappa modificando la fotocamera della mappa.

Le modifiche alla videocamera non influiranno su indicatori, overlay o altri elementi grafici che hai aggiunto, anche se potresti voler modificare le tue aggiunte per adattarle meglio alla nuova visualizzazione.

Poiché puoi rimanere in ascolto delle attivazioni dall'utente sulla mappa, puoi modificarla in risposta alle sue richieste. Ad esempio, il metodo di callback OnMapClickListener.onMapClick() risponde a un singolo tocco sulla mappa. Poiché il metodo riceve la latitudine e la longitudine della posizione del tocco, puoi rispondere eseguendo la panoramica o lo zoom su quel punto. Sono disponibili metodi simili per rispondere ai tocchi sul fumetto di un indicatore o per rispondere a un gesto di trascinamento su un indicatore.

Puoi anche rilevare i movimenti della fotocamera, in modo che la tua app riceva una notifica quando la fotocamera inizia a muoversi, è in movimento o si ferma. Per maggiori dettagli, consulta la guida agli eventi di modifica della videocamera.

La posizione della videocamera

La visualizzazione mappa è modellata come una fotocamera che guarda verso il basso su un piano piatto. La posizione della fotocamera (e quindi il rendering della mappa) è specificata dalle seguenti proprietà: target (posizione di latitudine/longitudine), bearing, tilt e zoom.

Target (località)

Il target della fotocamera è la posizione del centro della mappa, specificata come coordinate di latitudine e longitudine.

La latitudine può essere compresa tra -85 e 85 gradi inclusi. I valori superiori o inferiori a questo intervallo verranno bloccati al valore più vicino all'interno dell'intervallo. Ad esempio, se specifichi una latitudine di 100, il valore verrà impostato su 85. La longitudine è compresa tra -180 e 180 gradi inclusi. I valori al di sopra o al di sotto di questo intervallo verranno adattati in modo da rientrare nell'intervallo (-180, 180). Ad esempio, 480, 840 e 1200 verranno tutti convertiti in 120 gradi.

Orientamento

La direzione della fotocamera specifica la direzione della bussola, misurata in gradi rispetto al nord geografico, corrispondente al bordo superiore della mappa. Se tracci una linea verticale dal centro della mappa al bordo superiore della mappa, il rilevamento corrisponde alla direzione della fotocamera (misurata in gradi) rispetto al nord geografico.

Un orientamento pari a 0 indica che la parte superiore della mappa punta verso il nord geografico. Un valore di orientamento pari a 90 indica che la parte superiore della mappa punta verso est (90 gradi su una bussola). Un valore pari a 180 indica che la parte superiore della mappa è rivolta verso sud.

L'API di Google Maps ti consente di modificare l'orientamento di una mappa. Ad esempio, chi guida un'auto spesso ruota una mappa stradale per allinearla alla direzione di marcia, mentre gli escursionisti che utilizzano una mappa e una bussola di solito orientano la mappa in modo che una linea verticale punti verso nord.

Inclinazione (angolo di visione)

L'inclinazione definisce la posizione della fotocamera su un arco direttamente sopra la posizione centrale della mappa, misurata in gradi dal nadir (la direzione che punta direttamente sotto la fotocamera). Un valore pari a 0 corrisponde a una videocamera puntata verso il basso. I valori maggiori di 0 corrispondono a una fotocamera inclinata verso l'orizzonte del numero di gradi specificato. Quando modifichi l'angolo di visualizzazione, la mappa viene visualizzata in prospettiva, con gli elementi lontani che appaiono più piccoli e quelli vicini che appaiono più grandi. Le seguenti illustrazioni lo dimostrano.

Nelle immagini di seguito, l'angolo di visione è di 0 gradi. La prima immagine mostra uno schema di questo: la posizione 1 è la posizione della videocamera e la posizione 2 è la posizione attuale sulla mappa. La mappa risultante viene visualizzata sotto.

La mappa visualizzata con l'angolo di visione predefinito della videocamera.

L'angolo di visione predefinito della videocamera.

Nelle immagini di seguito, l'angolo di visione è di 45 gradi. Nota che la videocamera si sposta a metà di un arco tra la posizione perpendicolare (0 gradi) e il suolo (90 gradi), fino alla posizione 3. La fotocamera è ancora puntata sul punto centrale della mappa, ma l'area rappresentata dalla linea nella posizione 4 è ora visibile.

La mappa visualizzata con un angolo di visualizzazione di 45 gradi.

Un angolo di visione della videocamera di 45 gradi.

La mappa in questo screenshot è ancora centrata sullo stesso punto della mappa originale, ma nella parte superiore sono apparse altre caratteristiche. Se aumenti l'angolo oltre i 45 gradi, gli elementi tra la videocamera e la posizione della mappa appaiono proporzionalmente più grandi, mentre gli elementi oltre la posizione della mappa appaiono proporzionalmente più piccoli, creando un effetto tridimensionale.

Zoom

Il livello di zoom della fotocamera determina la scala della mappa. A livelli di zoom più elevati, sullo schermo è possibile visualizzare maggiori dettagli, mentre a livelli di zoom più bassi è possibile visualizzare una parte maggiore del mondo. Al livello di zoom 0, la scala della mappa è tale che l'intero mondo ha una larghezza di circa 256 dp (pixel indipendenti dalla densità).

Se aumenti il livello di zoom di 1, la larghezza del mondo sullo schermo raddoppia. Pertanto, al livello di zoom N, la larghezza del mondo è di circa 256 * 2^N dp. Ad esempio, al livello di zoom 2, il mondo intero è largo circa 1024 dp.

Il livello di zoom non deve essere un numero intero. La gamma di livelli di zoom consentiti dalla mappa dipende da una serie di fattori, tra cui la destinazione, il tipo di mappa e le dimensioni dello schermo. Qualsiasi numero al di fuori dell'intervallo verrà convertito nel valore valido più vicino, che può essere il livello di zoom minimo o massimo. Il seguente elenco mostra il livello di dettaglio approssimativo che puoi aspettarti di vedere a ogni livello di zoom:

• 1: Mondo
• 5: massa continentale/continente
• 10: Città
• 15: Strade
• 20: Edifici

Nota: a causa delle dimensioni e della densità dello schermo, alcuni dispositivi potrebbero non supportare i livelli di zoom più bassi. Utilizza GoogleMap.getMinimumZoomLevel() per ottenere il livello di zoom minimo possibile per la mappa. Se devi mostrare il mondo intero nell'area visibile, potrebbe essere meglio utilizzare la modalità Lite.

Le seguenti immagini mostrano l'aspetto visivo dei diversi livelli di zoom:

Una mappa con livello di zoom 5.

Una mappa con livello di zoom 15.

Una mappa con livello di zoom 20.

Spostamento della videocamera

L'API di Google Maps ti consente di modificare la parte del mondo visibile sulla mappa. Per farlo, si modifica la posizione della videocamera (anziché spostare la mappa).

Quando cambi la videocamera, hai la possibilità di animare il movimento della videocamera risultante. L'animazione esegue l'interpolazione tra gli attributi della fotocamera corrente e quelli della nuova fotocamera. Puoi anche controllare la durata dell'animazione.

Nota: tutti i movimenti programmatici della fotocamera vengono calcolati in base alle dimensioni dell'oggetto GoogleMap dopo aver preso in considerazione l'eventuale spaziatura interna aggiunta alla mappa. Ad esempio, l'aggiunta di 100 pixel di spaziatura interna al bordo sinistro della mappa sposterà il centro della mappa verso destra di 50 pixel. Per saperne di più, consulta la documentazione sulla spaziatura interna della mappa.

Per modificare la posizione della videocamera, devi specificare dove vuoi spostarla utilizzando un CameraUpdate. L'API di Google Maps ti consente di creare molti tipi diversi di CameraUpdate utilizzando CameraUpdateFactory. Sono disponibili le seguenti opzioni:

Modifica del livello di zoom e impostazione dello zoom minimo/massimo

CameraUpdateFactory.zoomIn() e CameraUpdateFactory.zoomOut() restituiscono un CameraUpdate che modifica il livello di zoom di 1,0, mantenendo invariate tutte le altre proprietà.

CameraUpdateFactory.zoomTo(float) restituisce un CameraUpdate che modifica il livello di zoom impostandolo sul valore specificato, mantenendo invariate tutte le altre proprietà.

CameraUpdateFactory.zoomBy(float) e CameraUpdateFactory.zoomBy(float, Point) restituiscono un CameraUpdate che aumenta (o diminuisce, se il valore è negativo) il livello di zoom del valore specificato. Quest'ultimo fissa il punto specificato sullo schermo in modo che rimanga nella stessa posizione (latitudine/longitudine) e, per farlo, potrebbe modificare la posizione della videocamera.

Potresti trovare utile impostare un livello di zoom minimo e/o massimo preferito. Ad esempio, questo è utile per controllare l'esperienza dell'utente se la tua app mostra un'area definita intorno a un punto d'interesse o se utilizzi un overlay di riquadri personalizzato con un insieme limitato di livelli di zoom.

Kotlin

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

      

Java

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

      

Tieni presente che esistono considerazioni tecniche che potrebbero impedire all'API di consentire agli utenti di aumentare o diminuire troppo lo zoom. Ad esempio, le immagini satellitari o del terreno potrebbero avere uno zoom massimo inferiore rispetto ai riquadri della mappa base.

Modifica della posizione della videocamera

Esistono due metodi pratici per le modifiche di posizione comuni. CameraUpdateFactory.newLatLng(LatLng) restituisce un CameraUpdate che modifica la latitudine e la longitudine della fotocamera, preservando tutte le altre proprietà. CameraUpdateFactory.newLatLngZoom(LatLng, float) restituisce un CameraUpdate che modifica la latitudine, la longitudine e lo zoom della fotocamera, preservando tutte le altre proprietà.

Per la massima flessibilità nella modifica della posizione della videocamera, utilizza CameraUpdateFactory.newCameraPosition(CameraPosition) che ti fornisce un CameraUpdate che sposta la videocamera nella posizione specificata. Un CameraPosition può essere ottenuto direttamente, utilizzando new CameraPosition() o con un CameraPosition.Builder utilizzando new CameraPosition.Builder().

Panning (scorrimento)

CameraUpdateFactory.scrollBy(float, float) fornisce un CameraUpdate che modifica la latitudine e la longitudine della fotocamera in modo che la mappa si sposti del numero di pixel specificato. Un valore x positivo fa sì che la fotocamera si sposti verso destra, in modo che la mappa sembri essersi spostata verso sinistra. Un valore y positivo fa spostare la fotocamera verso il basso, in modo che la mappa sembri essersi spostata verso l'alto. Al contrario, i valori X negativi fanno sì che la fotocamera si sposti verso sinistra, in modo che la mappa sembri essersi spostata verso destra, mentre i valori Y negativi fanno sì che la fotocamera si sposti verso l'alto. Lo scorrimento è relativo all'orientamento attuale della videocamera. Ad esempio, se la videocamera ha un rilevamento di 90 gradi, l'est è "su".

Definizione dei limiti

Impostazione dei limiti della mappa

A volte è utile spostare la fotocamera in modo che un'intera area di interesse sia visibile al livello di zoom più alto possibile. Ad esempio, se mostri tutte le stazioni di servizio entro cinque miglia dalla posizione attuale dell'utente, potresti voler spostare la fotocamera in modo che siano tutte visibili sullo schermo. Per farlo, calcola innanzitutto la LatLngBounds che vuoi che sia visibile sullo schermo. Puoi quindi utilizzare CameraUpdateFactory.newLatLngBounds(LatLngBounds bounds, int padding) per ottenere un CameraUpdate che modifica la posizione della fotocamera in modo che l'oggetto LatLngBounds specificato rientri interamente nella mappa, tenendo conto del padding (in pixel) specificato. L'oggetto CameraUpdate restituito garantisce che lo spazio (in pixel) tra i limiti specificati e il bordo della mappa sia almeno pari al padding specificato. Tieni presente che l'inclinazione e l'orientamento della mappa saranno entrambi pari a 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));

      

Nota: puoi richiamare newLatLngBounds(boundary, padding) per cambiare la videocamera solo dopo aver completato il layout della mappa. Questo perché l'API calcola i confini di visualizzazione della mappa durante il layout. Se vuoi chiamare newLatLngBounds() prima che il layout sia stato eseguito, puoi utilizzare newLatLngBounds(boundary, width, height, padding) descritto di seguito.

Centrare la mappa all'interno di un'area

In alcuni casi, potresti voler centrare la videocamera all'interno di un confine anziché includere i bordi estremi. Ad esempio, per centrare la videocamera su un paese mantenendo uno zoom costante. In questo caso, puoi utilizzare un metodo simile creando un LatLngBounds e utilizzando CameraUpdateFactory.newLatLngZoom(LatLng latLng, float zoom) con LatLngBounds.getCenter(). Il metodo getCenter() restituirà il centro geografico di 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));

      

Un overload del metodo, newLatLngBounds(boundary, width, height, padding), consente di specificare una larghezza e un'altezza in pixel per un rettangolo, con l'intenzione che corrispondano alle dimensioni della mappa. Il rettangolo è posizionato in modo che il suo centro coincida con quello della visualizzazione della mappa (in modo che, se le dimensioni specificate sono le stesse della visualizzazione della mappa, il rettangolo coincida con la visualizzazione della mappa). L'oggetto CameraUpdate restituito sposterà la fotocamera in modo che l'oggetto LatLngBounds specificato sia centrato sullo schermo all'interno del rettangolo specificato al livello di zoom più alto possibile, tenendo conto del padding richiesto.

Nota: Utilizza solo il metodo più semplicenewLatLngBounds(boundary, padding) per generare unCameraUpdate se deve essere utilizzato per spostare la telecamera dopo che la mappa è stata impaginata. Durante il layout, l'API calcola i confini di visualizzazione della mappa necessari per proiettare correttamente il riquadro di delimitazione. In confronto, puoi utilizzare l'oggetto CameraUpdate restituito dal metodo più complesso newLatLngBounds(boundary, width, height, padding) in qualsiasi momento, anche prima che la mappa sia stata sottoposta al layout, perché l'API calcola i confini di visualizzazione dagli argomenti che passi.

Limitazione della panoramica dell'utente a un'area specifica

Negli scenari precedenti, imposti i limiti della mappa, ma l'utente può scorrere o spostarsi al di fuori di questi limiti. In alternativa, puoi limitare i limiti di latitudine/longitudine del centro del punto focale della mappa (il target della fotocamera) in modo che gli utenti possano scorrere e spostarsi solo all'interno di questi limiti. Ad esempio, un'app di vendita al dettaglio per un centro commerciale o un aeroporto potrebbe voler limitare la mappa a un confine specifico, consentendo agli utenti di scorrere e spostarsi all'interno di questi confini.

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);

      

Il seguente diagramma illustra uno scenario in cui il target della videocamera è limitato a un'area leggermente più grande dell'area visibile. L'utente può scorrere e spostarsi, a condizione che il target della fotocamera rimanga all'interno dell'area delimitata. La croce rappresenta il target della videocamera:

La mappa riempie sempre l'area visibile, anche se ciò comporta la visualizzazione di aree esterne ai limiti definiti. Ad esempio, se posizioni il target della videocamera in un angolo dell'area delimitata, l'area oltre l'angolo è visibile nell'area visibile, ma gli utenti non possono scorrere ulteriormente in quell'area. Il seguente diagramma illustra questo scenario. La croce rappresenta il target della videocamera:

Nel seguente diagramma, il target della fotocamera ha limiti molto ristretti, offrendo all'utente pochissime opportunità di scorrere o eseguire la panoramica della mappa. La croce rappresenta il target della videocamera:

Aggiornamento della visualizzazione della videocamera

Per applicare un CameraUpdate alla mappa, puoi spostare la fotocamera istantaneamente o animarla in modo fluido. Per spostare la videocamera istantaneamente con il CameraUpdate specificato, puoi chiamare GoogleMap.moveCamera(CameraUpdate).

Puoi rendere l'esperienza utente più piacevole, soprattutto per i movimenti brevi, animando la modifica. Per farlo, anziché chiamare GoogleMap.moveCamera chiama GoogleMap.animateCamera. La mappa si sposterà in modo fluido sui nuovi attributi. La forma più dettagliata di questo metodo, GoogleMap.animateCamera(cameraUpdate, duration, callback), offre tre argomenti:

cameraUpdate

L'oggetto CameraUpdate che descrive dove spostare la videocamera.

callback

Un oggetto che implementa GoogleMap.CancellableCallback. Questa interfaccia generalizzata per la gestione delle attività definisce due metodi "onCancel()" e "onFinished()". Per l'animazione, i metodi vengono chiamati nelle seguenti circostanze:

onFinish()

Viene richiamato se l'animazione viene completata senza interruzioni.

onCancel()

Viene richiamato se l'animazione viene interrotta chiamando stopAnimation() o avviando un nuovo movimento della videocamera.

In alternativa, questo può verificarsi anche se chiami GoogleMap.stopAnimation().

duration

Durata desiderata dell'animazione, in millisecondi, come int.

I seguenti snippet di codice illustrano alcuni dei modi più comuni per spostare la fotocamera.

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));