Videocamera e vista

Le mappe in Maps SDK for Android possono essere inclinate e ruotate con semplici gesti, offrendo agli utenti la possibilità di regolarla con l'orientamento più adatto alle loro esigenze. A qualsiasi livello di zoom, puoi eseguire una panoramica della mappa o cambiarne la prospettiva con una latenza minima grazie all'ingombro ridotto dei riquadri della mappa basati su vettori.

Esempi di codice

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

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

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 Mercator. In direzione est e ovest, la mappa si ripete all'infinito mentre il mondo si avvolge continuamente su se stesso. In direzione nord e sud, la mappa si limita a circa 85 gradi a nord e 85 a sud.

Nota: una proiezione di Mercatore ha una larghezza finita longitudinalmente e un'altezza infinita dalla latitudine. Abbiamo "tagliato" le immagini della mappa base utilizzando la proiezione di Mercatore a circa +/- 85 gradi per rendere quadrata la forma della mappa risultante, il che consente una logica più semplice per la selezione dei riquadri.

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

Le modifiche alla fotocamera non apporteranno modifiche agli indicatori, agli overlay o ad altri elementi grafici che hai aggiunto, ma ti consigliamo di modificarli per adattarli meglio alla nuova visualizzazione.

Poiché puoi ascoltare i gesti degli utenti sulla mappa, puoi modificare la mappa in risposta alle richieste degli utenti. 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 usando la panoramica o lo zoom fino a quel punto. Sono disponibili metodi simili per rispondere ai tocchi sulla bolla di un indicatore o a un gesto di trascinamento su un indicatore.

Puoi anche ascoltare i movimenti della videocamera in modo che l'app riceva una notifica quando la videocamera inizia a muoversi, è in movimento o smette di muoversi. Per informazioni dettagliate, consulta la guida agli eventi di modifica della videocamera.

La posizione della fotocamera

La visualizzazione mappa è modellata come una fotocamera rivolta 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), cuscinetto, inclinazione e zoom.

Target (località)

L'obiettivo della fotocamera è la posizione del centro della mappa, specificata come coordinate di latitudine e longitudine.

Direzione (orientamento)

L'orientamento della fotocamera specifica la direzione della bussola, misurata in gradi dal nord vero, corrispondente al bordo superiore della mappa. Se tracci una linea verticale dal centro della mappa fino al bordo superiore della mappa, l'orientamento corrisponde all'orientamento della fotocamera (misurato in gradi) rispetto al nord vero.

Un rilevamento pari a 0 indica che la parte superiore della mappa punta al nord. Un valore di rilevamento pari a 90 indica la parte superiore dei punti della mappa orientati verso est (90 gradi su una bussola). Il valore 180 indica la parte superiore dei punti sulla mappa orientata verso sud.

L'API di Google Maps ti consente di modificare l'orientamento di una mappa. Ad esempio, chi guida un'auto spesso piega una mappa stradale per allinearla al senso di marcia, mentre gli escursionisti che utilizzano una mappa e una bussola di solito la orientano in modo che una linea verticale sia rivolta a 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 rivolta direttamente sotto la fotocamera). Il valore 0 corrisponde a una fotocamera puntata verso il basso. I valori superiori a 0 corrispondono a una fotocamera con un'inclinazione verso l'orizzonte del numero di gradi specificato. Quando modifichi l'angolo di visualizzazione, la mappa viene mostrata in prospettiva, con gli elementi lontani che appaiono più piccoli e quelli vicini più grandi. Le seguenti illustrazioni lo dimostrano.

Nelle immagini seguenti, l'angolo di visione è di 0 gradi. La prima immagine mostra uno schema di questo concetto; la posizione 1 è la posizione della fotocamera e la posizione 2 è la posizione attuale sulla mappa. La mappa risultante è mostrata sotto.

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

La mappa in questo screenshot è ancora centrata sullo stesso punto della mappa originale, ma nella parte superiore sono stati visualizzati altri elementi. Aumentando l'angolo oltre i 45 gradi, gli elementi tra la fotocamera e la posizione sulla mappa appaiono proporzionalmente più grandi, mentre quelli oltre la posizione sulla mappa vengono proporzionalmente più piccoli, generando un effetto tridimensionale.

Assumi una prospettiva

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

Aumentando il livello di zoom di 1, si raddoppia la larghezza del mondo sullo schermo. Quindi, a livello di zoom N, la larghezza della Terra è di circa 256 * 2^N dp. Ad esempio, con il 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 il target, il tipo di mappa e le dimensioni dello schermo. Qualsiasi numero al di fuori dell'intervallo verrà convertito nel successivo valore valido più vicino, che può essere il livello di zoom minimo o massimo. Il seguente elenco mostra il livello approssimativo di dettaglio previsto per ogni livello di zoom:

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

Spostare la videocamera

L'API di Google Maps ti consente di modificare la parte del mondo visibile sulla mappa. A tal fine, devi cambiare la posizione della fotocamera (anziché spostare la mappa).

Quando cambi la videocamera, hai la possibilità di animare il movimento della videocamera risultante. L'animazione si interpola tra gli attributi correnti della fotocamera e i nuovi attributi della fotocamera. Puoi anche controllare la durata dell'animazione.

Per cambiare la posizione della fotocamera, devi specificare dove vuoi spostarla utilizzando un CameraUpdate. L'API di Google Maps 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() offrono un CameraUpdate che modifica il livello di zoom di 1,0, mantenendo invariate tutte le altre proprietà.

CameraUpdateFactory.zoomTo(float) offre un CameraUpdate che modifica il livello di zoom in base al valore specificato, mantenendo invariate tutte le altre proprietà.

CameraUpdateFactory.zoomBy(float) e CameraUpdateFactory.zoomBy(float, Point) ti dà un CameraUpdate che aumenta (o diminuisce, se il valore è negativo) il livello di zoom del valore specificato. Quest'ultimo consente di correggere il punto specificato sullo schermo in modo che rimanga nella stessa posizione (latitudine/longitudine) e di conseguenza potrebbe cambiare la posizione della videocamera per ottenere questo risultato.

Potrebbe essere 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 riquadro personalizzato con un insieme limitato di livelli di zoom.

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

      

private lateinit var map: GoogleMap

    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 ridurre lo zoom. Ad esempio, il satellite o il rilievo potrebbero avere uno zoom massimo inferiore rispetto ai riquadri della mappa base.

Modifica della posizione della fotocamera

Esistono due metodi di convenienza per i cambiamenti di posizione comuni. CameraUpdateFactory.newLatLng(LatLng) offre un CameraUpdate che modifica la latitudine e la longitudine della videocamera, mantenendo invariate tutte le altre proprietà. CameraUpdateFactory.newLatLngZoom(LatLng, float) offre un CameraUpdate che modifica la latitudine, la longitudine e lo zoom della videocamera, mantenendo tutte le altre proprietà.

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

Panoramica (scorrimento)

CameraUpdateFactory.scrollBy(float, float) fornisce un valore CameraUpdate che modifica la latitudine e la longitudine della fotocamera in modo che la mappa si sposti del numero specificato di pixel. Un valore x positivo comporta lo spostamento della fotocamera verso destra, in modo che la mappa sembri spostata a sinistra. Un valore y positivo comporta lo spostamento della fotocamera verso il basso, in modo che la mappa sembri spostata in alto. Al contrario, valori x negativi fanno sì che la fotocamera si sposti a sinistra, in modo che la mappa sembri spostata a destra, mentre valori negativi y fanno sì che la fotocamera si sposti verso l'alto. Lo scorrimento è relativo all'orientamento corrente della fotocamera. Ad esempio, se la fotocamera ha una inclinazione di 90 gradi, l'est è "verso l'alto".

Stabilire dei confini

Impostazione dei limiti della mappa

A volte è utile spostare la videocamera in modo che un'intera area di interesse sia visibile al massimo livello di zoom possibile. Ad esempio, se vuoi mostrare tutte le stazioni di servizio entro cinque miglia dalla posizione corrente dell'utente, puoi spostare la videocamera in modo che siano tutte visibili sullo schermo. Per farlo, calcola innanzitutto il valore LatLngBounds che vuoi che sia visibile sullo schermo. Puoi quindi utilizzare CameraUpdateFactory.newLatLngBounds(LatLngBounds bounds, int padding) per ottenere un CameraUpdate che cambi la posizione della fotocamera in modo che la LatLngBounds specificata si adatti completamente alla mappa, tenendo conto della spaziatura interna (in pixel) specificata. CameraUpdate restituito assicura che lo spazio (in pixel) tra i limiti specificati e il bordo della mappa sia almeno pari alla spaziatura interna specificata. Tieni presente che l'inclinazione e l'orientamento della mappa sono entrambi pari a 0.

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

      

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

      

Centra la mappa all'interno di un'area

In alcuni casi potresti voler centrare la videocamera all'interno dei confini invece di includere i bordi estremi. ad esempio per centrare la fotocamera su un paese mantenendo lo zoom costante. In questo caso, puoi utilizzare un metodo simile, creando un elemento LatLngBounds e utilizzando CameraUpdateFactory.newLatLngZoom(LatLng latLng, float zoom) con LatLngBounds.getCenter(). Il metodo getCenter() restituirà il centro geografico di LatLngBounds.

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

      

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

      

Un sovraccarico del metodo, newLatLngBounds(boundary, width, height, padding), consente di specificare la larghezza e l'altezza in pixel di un rettangolo, affinché corrispondano alle dimensioni della mappa. Il rettangolo è posizionato in modo che il suo centro sia identico a quello della visualizzazione della mappa (in modo che, se le dimensioni specificate sono uguali a quelle della visualizzazione della mappa, il rettangolo coincide con la visualizzazione della mappa). L'elemento CameraUpdate restituito sposterà la videocamera in modo che le LatLngBounds specificate siano centrate sullo schermo all'interno del rettangolo specificato al livello di zoom più alto possibile, tenendo conto della spaziatura interna richiesta.

Nota: utilizza il metodo più semplice newLatLngBounds(boundary, padding) per generare un CameraUpdate solo se hai intenzione di spostare la fotocamera dopo il layout della mappa. Durante il layout, l'API calcola i confini di visualizzazione della mappa necessari per proiettare correttamente il riquadro di delimitazione. In confronto, puoi utilizzare CameraUpdate restituito dal metodo più complesso newLatLngBounds(boundary, width, height, padding) in qualsiasi momento, anche prima che la mappa sia stata sottoposta a layout, perché l'API calcola i limiti di visualizzazione dagli argomenti passati.

Limitare la panoramica dell'utente a una determinata area

Negli scenari precedenti, imposti i limiti della mappa, ma l'utente può poi scorrere o eseguire la panoramica al di fuori di questi limiti. Puoi invece limitare i confini centrali latitudine/longitudine del punto focale della mappa (l'obiettivo della videocamera) in modo che gli utenti possano scorrere ed eseguire la panoramica solo all'interno di questi limiti. Ad esempio, un'app di vendita al dettaglio per un centro commerciale o un aeroporto può voler limitare la mappa a un determinato limite, consentendo agli utenti di scorrere ed eseguire la panoramica all'interno di questi confini.

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

      

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

      

Il seguente diagramma illustra uno scenario in cui l'obiettivo della videocamera è limitato a un'area leggermente più grande dell'area visibile. L'utente può scorrere ed eseguire la panoramica, a condizione che l'obiettivo della videocamera rimanga all'interno dell'area delimitata. La croce rappresenta l'obiettivo della videocamera:

La mappa riempie sempre l'area visibile, anche se l'area visibile mostra aree al di fuori dei confini definiti. Ad esempio, se posizioni il target della videocamera in un angolo dell'area delimitata, l'area oltre l'angolo sarà visibile nell'area visibile, ma gli utenti non potranno scorrere ulteriormente in quell'area. Il seguente diagramma illustra questo scenario. La croce rappresenta il target della fotocamera:

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

Aggiornamento della visualizzazione della videocamera in corso...

Per applicare una CameraUpdate alla mappa, puoi spostare all'istante la fotocamera o animarla in modo uniforme. Per spostare istantaneamente la videocamera 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à gradualmente sui nuovi attributi. La forma più dettagliata di questo metodo, GoogleMap.animateCamera(cameraUpdate, duration, callback), offre tre argomenti:

cameraUpdate

La 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()

Richiamato se l'animazione si completa senza interruzioni.

onCancel()

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

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

duration

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

I seguenti snippet di codice illustrano alcuni dei metodi più comuni per spostare la videocamera.

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

      

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