Videocamera e vista

Seleziona piattaforma: Android iOS JavaScript

Le mappe nell'SDK Maps per Android possono essere inclinate e ruotate con semplici gesti, consentendo agli utenti di regolare la mappa con un orientamento adatto a loro. A qualsiasi livello di zoom, puoi eseguire una panoramica della mappa o cambiarne la prospettiva con una latenza molto bassa grazie all'impatto ridotto dei riquadri della mappa basati su vettori.

Esempi di codice

Il repository APIApis su GitHub include un esempio che illustra le funzionalità della videocamera:

Introduzione

Analogamente a Google Maps sul Web, l'SDK di Maps per Android rappresenta la superficie mondiale (una sfera) sullo schermo del dispositivo (un piano). In direzione est e ovest, la mappa viene ripetuta all'infinito man mano che il mondo avvolge se stessa. A nord e a sud la mappa è limitata a circa 85 gradi nord e 85 gradi sud.

Nota: una proiezione di Mercatore ha una larghezza limitata ma longitudinalmente, ma un'altezza infinita latitudinalmente. "Tagliamo" le immagini delle mappe di base utilizzando la proiezione di Mercator a circa +/- 85 gradi per rendere la forma della mappa quadrata risultante, il che consente una logica più semplice per la selezione di riquadri.

L'SDK Maps per Android consente di cambiare il punto di vista della mappa utilizzando la fotocamera.

Le modifiche apportate alla fotocamera non apportano modifiche agli indicatori, agli overlay o ad altre immagini aggiunte, anche se potresti modificare le aggiunte per adattarle meglio alla nuova visualizzazione.

Poiché puoi ascoltare i gesti degli utenti sulla mappa, puoi modificarla 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 i valori di latitudine e longitudine della posizione del tocco, puoi rispondere eseguendo una panoramica o un'operazione di zoom fino a 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 ascoltare i movimenti della videocamera, in modo che la tua app riceva una notifica quando la videocamera inizia a muoversi, attualmente è in movimento o smette di muoversi. Per i dettagli, 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. La posizione della fotocamera (e quindi il rendering della mappa) viene specificata dalle seguenti proprietà: target (posizione latitudine/longitudine), cuscinetto, inclinazione e zoom.

Diagramma proprietà proprietà videocamera

Target (località)

La fotocamera target è 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 fissati al valore più vicino all'interno di questo intervallo. Ad esempio, specificando una latitudine di 100 il valore verrà impostato su 85. La longitudine è compresa tra -180 e 180 gradi, inclusi. I valori superiori o inferiori a questo intervallo verranno inseriti in modo che rientrino nell'intervallo (-180, 180). Ad esempio, 480, 840 e 1200 vengono aggregati a 120 gradi.

Rilevamento (orientamento)

Il rilevamento della fotocamera specifica la direzione della bussola, misurata in gradi da nord, corrispondente al bordo superiore della mappa. Se tracci una linea verticale dal centro della mappa al bordo superiore della mappa, il rilevamento corrisponde all'intestazione della fotocamera (misurata in gradi) rispetto al nord effettivo.

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

L'API di Google Maps ti consente di modificare il rilevamento di una mappa. Ad esempio, un utente che guida spesso un'auto ruota una mappa per allinearla alla direzione di viaggio, mentre gli escursionisti che utilizzano una mappa e una bussola di solito orientano la mappa in modo che una linea verticale sia rivolta verso nord.

Inclina (angolo di visualizzazione)

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 fotocamera puntata verso il basso. I valori maggiori di 0 corrispondono a una videocamera inclinata verso l'orizzonte del numero di gradi specificato. Quando cambi l'angolo di visione, la mappa appare in prospettiva, con le funzionalità lontane che appaiono più piccole e le funzionalità vicine 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 aspetto; la posizione 1 è la posizione della fotocamera e la posizione 2 è la posizione corrente sulla mappa. La mappa risultante viene mostrata sotto di essa.

Screenshot di una mappa con una fotocamera posizionata a un angolo di visione di 0 gradi a un livello di zoom di 18.
La mappa viene mostrata con l'angolo di visualizzazione predefinito della fotocamera.
Diagramma che mostra la posizione predefinita della fotocamera, direttamente sopra la posizione della mappa, con un angolo di 0 gradi.
L'angolo di visione predefinito della videocamera.

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

Screenshot di una mappa con una fotocamera posizionata a un angolo di visione di 45° a un livello di zoom di 18.
La mappa è visualizzata con un angolo di visione di 45°.
Diagramma che mostra l'angolo di visione della videocamera impostato su 45°, con il livello di zoom ancora impostato su 18.
Un angolo di visione di 45 gradi.

La mappa in questo screenshot è ancora centrata rispetto allo stesso punto della mappa originale, ma nella parte superiore della mappa sono apparse altre funzionalità. Con l'aumentare dell'angolazione oltre i 45°, gli elementi tra la fotocamera e la posizione sulla mappa sembrano proporzionalmente più grandi, mentre gli elementi al di fuori della posizione della mappa appaiono proporzionalmente più piccoli, con un effetto tridimensionale.

Assumi una prospettiva

Il livello di zoom della fotocamera determina la scala della mappa. A livelli di zoom maggiori possono essere visualizzati più dettagli sullo schermo, mentre a livelli di zoom più piccoli possono essere visualizzati sullo schermo più persone di tutto il mondo. Al livello di zoom 0, la scala della mappa è tale che l'intero mondo abbia una larghezza di circa 256 dp (pixel indipendenti dalla densità).

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

  • 1: mondo
  • 5: massa terrestre/continente
  • 10: Città
  • 15: Strade
  • 20: edifici
Le seguenti immagini mostrano l'aspetto visivo di diversi livelli di zoom:
Screenshot di una mappa a livello di zoom 5
Una mappa al livello di zoom 5.
Screenshot di una mappa a livello di zoom 15
Una mappa al livello di zoom 15
.
Screenshot di una mappa al livello di zoom 20
Una mappa al livello di zoom 20
.

Spostamento della videocamera in corso...

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

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

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

Modificare il livello di zoom e impostare lo zoom minimo/massimo

CameraUpdateFactory.zoomIn() e CameraUpdateFactory.zoomOut() ti forniscono un CameraUpdate che modifica il livello di zoom di 1,0, mantenendo le stesse proprietà.

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

CameraUpdateFactory.zoomBy(float) e CameraUpdateFactory.zoomBy(float, Point) forniscono un CameraUpdate che aumenta (o diminuisce, se il valore è negativo) del livello di zoom in base al valore specificato. Quest'ultimo fissa il punto specificato sullo schermo in modo che resti nella stessa posizione (longitudine/longitudine) e può cambiare la posizione della videocamera per raggiungere questo obiettivo.

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

Java


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

      

Kotlin


private lateinit var map: GoogleMap

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

      

Tieni presente che alcune considerazioni tecniche potrebbero impedire all'API di consentire agli utenti di aumentare o diminuire lo zoom troppo in basso. Ad esempio, il satellite o il rilievo potrebbe avere uno zoom massimo inferiore rispetto ai riquadri della mappa base.

Modificare la posizione della fotocamera

Esistono due metodi per semplificare le modifiche comuni alla posizione. CameraUpdateFactory.newLatLng(LatLng) fornisce un CameraUpdate che modifica la latitudine e la longitudine della fotocamera, mantenendo tutte le altre proprietà. CameraUpdateFactory.newLatLngZoom(LatLng, float) ti offre una CameraUpdate che modifica la latitudine, la longitudine e lo zoom della fotocamera, mantenendo tutte le altre proprietà.

Per una maggiore flessibilità nel modificare la posizione della fotocamera, utilizza CameraUpdateFactory.newCameraPosition(CameraPosition) che ti offre una CameraUpdate che sposta la fotocamera nella posizione specificata. È possibile ottenere CameraPosition direttamente, utilizzando new CameraPosition() o con 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 tale che la mappa si muova in base al numero di pixel specificato. Un valore x positivo fa sì che la fotocamera si muova a destra, in modo che la mappa sembri essere spostata a sinistra. Un valore y positivo fa sì che la videocamera si sposti verso il basso, in modo che la mappa sembri avanzare verso l'alto. Al contrario, i valori x negativi indicano che la fotocamera si sposta verso sinistra, pertanto la mappa sembra avere spostato la direzione verso destra. Lo scorrimento è relativo all'orientamento attuale della videocamera. Ad esempio, se la fotocamera ha un orientamento di 90 gradi, est è "salita".

Impostare i limiti

Impostare i 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 stai visualizzando tutte le stazioni di servizio entro cinque chilometri dalla posizione attuale dell'utente, potresti provare a spostare la videocamera in modo che siano tutte visibili sullo schermo. Per farlo, innanzitutto calcola la LatLngBounds che vuoi rendere visibile sullo schermo. Puoi quindi utilizzare CameraUpdateFactory.newLatLngBounds(LatLngBounds bounds, int padding) per ottenere una CameraUpdate che cambi la posizione della fotocamera in modo che l'elemento LatLngBounds specificato si adatti interamente alla mappa, tenendo conto della spaziatura interna (in pixel) specificata. Il valore restituito da CameraUpdate garantisce che lo spazio (in pixel) tra i limiti e il bordo della mappa specificati sarà almeno pari alla spaziatura interna specificata. Tieni presente che l'inclinazione e il supporto della mappa saranno entrambi pari a 0.

Java


LatLngBounds australiaBounds = new LatLngBounds(
    new LatLng(-44, 113), // SW bounds
    new LatLng(-10, 154)  // NE bounds
);
map.moveCamera(CameraUpdateFactory.newLatLngBounds(australiaBounds, 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))

      

Centrare la mappa all'interno di un'area

In alcuni casi, potresti voler centrare la fotocamera entro i confini anziché includere i bordi estremi. Ad esempio, per centrare la fotocamera in un paese e mantenere al contempo uno zoom costante. In questo caso, puoi utilizzare un metodo simile creando LatLngBounds e utilizzando CameraUpdateFactory.newLatLngZoom(LatLng latLng, float zoom) con LatLngBounds.getCenter(). Il metodo getCenter() restituirà il centro geografico della LatLngBounds.

Java


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

      

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

      

Un sovraccarico del metodo, newLatLngBounds(boundary, width, height, padding) ti consente di specificare una larghezza e un'altezza in pixel per un rettangolo, con l'intenzione di far corrispondere le dimensioni della mappa. Il rettangolo è posizionato in modo che il suo centro corrisponda a quello della visualizzazione della mappa (in modo che, se le dimensioni specificate sono uguali a quelle della vista della mappa, il rettangolo coincide con la vista della mappa). L'elemento CameraUpdate restituito sposterà la fotocamera in modo che l'elemento LatLngBounds specificato sia centrato sullo schermo all'interno del rettangolo specificato, al massimo livello di zoom possibile, tenendo conto della spaziatura interna richiesta.

Nota: utilizza il metodo più semplice newLatLngBounds(boundary, padding) per generare un CameraUpdate solo se verrà utilizzato per spostare la fotocamera dopo che la mappa è stata sottoposta a layout. Durante il layout, l'API calcola i limiti 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.

Limitazione della panoramica dell'utente a un'area specifica

Negli scenari precedenti, hai impostato i limiti della mappa, ma l'utente può quindi scorrere o panoramica all'esterno di questi limiti. Ti consigliamo di limitare i limiti del centro latitudine e latitudine del punto focale della mappa (il target della fotocamera) in modo che gli utenti possano scorrere e scorrere solo all'interno di questi limiti. Ad esempio, un'app di vendita al dettaglio per un centro commerciale o un aeroporto potrebbe decidere di associare la mappa a limiti specifici, consentendo agli utenti di scorrere ed eseguire la panoramica di tali confini.

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

      

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)

      

Il seguente diagramma illustra uno scenario in cui il target della fotocamera è limitato a un'area leggermente più grande dell'area visibile. L'utente può scorrere ed eseguire una panoramica, a condizione che il target della fotocamera rimanga nell'area delimitata. La croce rappresenta il target della fotocamera:

Diagramma che mostra un oggetto LatLngBounds della fotocamera più grande dell'area visibile.

La mappa riempie sempre l'area visibile, anche se questo fa sì che l'area visibile mostri aree che non rientrano nei limiti definiti. Ad esempio, se posizioni la fotocamera in un angolo dell'area delimitata, l'area oltre l'angolo è visibile nell'area visibile, ma gli utenti non possono scorrere ulteriormente nell'area. Lo scenario seguente illustra questo scenario. La croce rappresenta il target della fotocamera:

Diagramma che mostra il target della fotocamera posizionato nell'angolo in basso a destra della fotocamera LatLngBounds.

Nel diagramma seguente, la fotocamera target ha dei limiti molto limitati, offrendo all'utente pochissima possibilità di scorrere o esplorare la mappa. La croce rappresenta il target della videocamera:

Diagramma che mostra un oggetto LatLngBounds della fotocamera più piccolo dell'area visibile.

Aggiornamento della visualizzazione della videocamera in corso...

Per applicare una CameraUpdate alla mappa, puoi spostare la fotocamera all'istante o animarla senza problemi. Per spostare all'istante la videocamera con l'oggetto CameraUpdate specificato, puoi chiamare l'app 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à senza problemi con i nuovi attributi. La forma più dettagliata di questo metodo, GoogleMap.animateCamera(cameraUpdate, duration, callback), offre tre argomenti:

cameraUpdate
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 "`Finished()". Per l'animazione, i metodi vengono chiamati nelle seguenti circostanze:
onFinish()
Richiamato se l'animazione viene completata senza interruzioni.
onCancel()

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, espressa come int.

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

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

      

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