Videocamera e vista

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 abbia senso per loro. A qualsiasi livello di zoom, puoi spostare la mappa o modificarne la prospettiva con una latenza molto bassa grazie all'ingombro ridotto delle tile della mappa basate su vettori.

Esempi di codice

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

• 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 man mano che il mondo si avvolge su se stesso senza interruzioni. In direzione nord e sud, la mappa è limitata a circa 85 gradi a nord e 85 gradi a sud.

Nota: una proiezione di Mercatore ha una larghezza finita in senso longitudinale, ma un'altezza infinita in senso latitudinale. 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 delle tile.

Maps SDK for Android ti consente di modificare il punto di vista dell'utente sulla mappa modificando la videocamera 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 ascoltare i gesti dell'utente sulla mappa, puoi modificarla in risposta alle richieste dell'utente. 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 spostando o ingrandendo il punto. Sono disponibili metodi simili per rispondere ai tocchi sul fumetto di un indicatore o 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, è in movimento o smette di muoversi. Per maggiori dettagli, consulta la guida agli eventi di modifica della videocamera.

Posizione della videocamera

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

Target (posizione)

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

Orientamento

L'orientamento della videocamera specifica la direzione della bussola, misurata in gradi dal nord geografico, corrispondente al bordo superiore della mappa. Se tracci una linea verticale dal centro della mappa al bordo superiore della mappa, l'orientamento corrisponde alla direzione della videocamera (misurata in gradi) rispetto al nord geografico.

Un orientamento di 0 significa che la parte superiore della mappa punta verso il nord geografico. Un valore di orientamento pari a 90 significa che la parte superiore della mappa punta verso est (90 gradi su una bussola). Un valore pari a 180 significa che la parte superiore della mappa punta 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 videocamera su un arco direttamente sopra la posizione centrale della mappa, misurata in gradi dal nadir (la direzione che punta direttamente sotto la videocamera). Un valore pari a 0 corrisponde a una videocamera puntata verso il basso. I valori maggiori di 0 corrispondono a una videocamera inclinata verso l'orizzonte del numero di gradi specificato. Quando modifichi l'angolo di visione, la mappa viene visualizzata in prospettiva, con le funzionalità lontane che appaiono più piccole e quelle vicine più grandi. Le seguenti illustrazioni lo dimostrano.

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

Nelle immagini seguenti, l'angolo di visione è di 45 gradi. Tieni presente che la videocamera si sposta a metà di un arco tra la posizione verticale (0 gradi) e il terreno (90 gradi), fino alla posizione 3. La videocamera punta ancora al punto centrale della mappa, ma l'area rappresentata dalla linea in posizione 4 è ora visibile.

La mappa in questo screenshot è ancora centrata sullo stesso punto della mappa originale, ma nella parte superiore della mappa sono apparse altre funzionalità. Man mano che aumenti l'angolo oltre i 45 gradi, le funzionalità tra la videocamera e la posizione della mappa appaiono proporzionalmente più grandi, mentre le funzionalità oltre la posizione della mappa appaiono proporzionalmente più piccole, creando un effetto tridimensionale.

Zoom

Il livello di zoom della videocamera determina la scala della mappa. A livelli di zoom più elevati è possibile vedere più dettagli sullo schermo, mentre a livelli di zoom più bassi è possibile vedere più mondo sullo schermo. 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à).

L'aumento del livello di zoom di 1 raddoppia la larghezza del mondo sullo schermo. Pertanto, al livello di zoom N, la larghezza del mondo è di circa 256 * 2^N dp. Ad esempio, al livello di zoom 2, l'intero mondo ha una larghezza di circa 1024 dp.

Il livello di zoom non deve essere un numero intero. L'intervallo 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 valido più vicino, che può essere il livello di zoom minimo o il livello di zoom massimo. L'elenco seguente mostra il livello approssimativo di dettaglio previsto per ogni livello di zoom:

• 1: mondo
• 5: massa continentale/continente
• 10: città
• 15: strade
• 20: edifici

Spostamento della videocamera

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

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

Per modificare la posizione della videocamera, devi specificare dove vuoi spostarla utilizzando un oggetto 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() forniscono un oggetto CameraUpdate che modifica il livello di zoom di 1.0, mantenendo invariate tutte le altre proprietà.

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

CameraUpdateFactory.zoomBy(float) e CameraUpdateFactory.zoomBy(float, Point) forniscono un oggetto 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 quindi potrebbe modificare la posizione della videocamera per raggiungere questo obiettivo.

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

private lateinit var map: GoogleMap

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

      

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

      

Tieni presente che esistono considerazioni tecniche che potrebbero impedire all'API di consentire agli utenti di eseguire uno zoom troppo basso o troppo alto. Ad esempio, le tile satellitari o del rilievo potrebbero avere uno zoom massimo inferiore rispetto alle tile della mappa base.

Modifica della posizione della videocamera

Esistono due metodi pratici per le modifiche comuni della posizione. CameraUpdateFactory.newLatLng(LatLng) fornisce un oggetto CameraUpdate che modifica la latitudine e la longitudine della videocamera, mantenendo invariate tutte le altre proprietà. CameraUpdateFactory.newLatLngZoom(LatLng, float) fornisce un oggetto CameraUpdate che modifica la latitudine, la longitudine e lo zoom della videocamera, mantenendo invariate tutte le altre proprietà.

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

Panoramica (scorrimento)

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

Impostazione dei limiti

Impostazione dei limiti della mappa

A volte è utile spostare la videocamera in modo che un'intera area di interesse sia visibile al livello di zoom più elevato possibile. Ad esempio, se stai mostrando tutti i distributori di benzina entro otto chilometri dalla posizione attuale dell'utente, potresti voler spostare la videocamera in modo che siano tutti visibili sullo schermo. Per farlo, calcola prima il LatLngBounds che vuoi rendere visibile sullo schermo. Puoi quindi utilizzare CameraUpdateFactory.newLatLngBounds(LatLngBounds bounds, int padding) per ottenere un CameraUpdate che modifichi la posizione della videocamera in modo che l'oggetto LatLngBounds specificato si adatti completamente alla 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.

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

      

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

      

Centramento della mappa all'interno di un'area

In alcuni casi, potresti voler centrare la videocamera all'interno di un limite 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 l' LatLngBounds.Metodo getCenter(). Il metodo getCenter() restituirà il centro geografico dell'oggetto LatLngBounds.

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

      

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) ti 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 sia lo stesso 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ù elevato possibile, tenendo conto della spaziatura interna richiesta.

Nota: utilizza il metodo più semplice newLatLngBounds(boundary, padding) per generare un oggetto CameraUpdate solo se verrà utilizzato per spostare la videocamera dopo che la mappa ha subito il layout. Durante il layout, l'API calcola i limiti di visualizzazione della mappa necessari per proiettare correttamente il riquadro di delimitazione. Al contrario, puoi utilizzare l' CameraUpdate restituito dal metodo più complesso newLatLngBounds(boundary, width, height, padding) in qualsiasi momento, anche prima che la mappa abbia subito il layout, perché l'API calcola i limiti di visualizzazione dagli argomenti che passi.

Limitazione della panoramica dell'utente a un'area specifica

Negli scenari precedenti, hai impostato i limiti della mappa, ma l'utente può scorrere o spostarsi al di fuori di questi limiti. In alternativa, potresti voler limitare i limiti del centro di latitudine/longitudine del punto focale della mappa (il target della videocamera) 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 limite specifico, consentendo agli utenti di scorrere e spostarsi all'interno di questi limiti.

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

      

// 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 della finestra. L'utente può scorrere e spostarsi, a condizione che il target della videocamera rimanga all'interno dell'area delimitata. La croce rappresenta il target della videocamera:

La mappa riempie sempre la finestra, anche se ciò comporta la visualizzazione di aree al di fuori dei limiti definiti. Ad esempio, se posizioni il target della videocamera in un angolo dell'area delimitata, l'area oltre l'angolo è visibile nella finestra, 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 videocamera ha limiti molto ristretti, offrendo all'utente pochissime opportunità di scorrere o spostare la mappa. La croce rappresenta il target della videocamera:

Aggiornamento dell'inquadratura

Per applicare un CameraUpdate alla mappa, puoi spostare la videocamera immediatamente o animarla senza problemi. Per spostare immediatamente la videocamera con l'oggetto 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à senza problemi ai 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 videocamera.

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

      

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