Videocamera e vista

Seleziona la piattaforma: Android iOS JavaScript

Le mappe nell'SDK di Maps per Android possono essere inclinate e ruotate con gesti semplici, offrendo agli utenti la possibilità di regolare la mappa con un orientamento adeguato. A qualsiasi livello di zoom, puoi eseguire la panoramica della mappa o cambiarne la prospettiva con una latenza molto ridotta grazie al minore ingombro dei riquadri della mappa basati su vettori.

Esempi di codice

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

Introduzione

Come Google Maps sul Web, l'SDK Maps per Android rappresenta la superficie del mondo (una sfera) sullo schermo del tuo dispositivo (un piano) con la proiezione del reindirizzamento. Nella direzione est e ovest, la mappa si ripete all'infinito mentre il mondo si avvolge senza soluzione di continuità. 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, in senso longitudinale, ma un'altezza latitudinalica, Abbiamo "tagliato" le immagini di base della mappa utilizzando la proiezione di Mercator a circa +/- 85 gradi per ottenere la forma della mappa quadrata risultante, il che consente una logica più semplice per la selezione delle schede.

L'SDK Maps per Android consente di modificare il punto di vista dell'utente della mappa modificando la fotocamera della mappa.

Le modifiche apportate alla fotocamera non apporteranno modifiche a indicatori, overlay o altri elementi grafici che hai aggiunto, anche se ti consigliamo di modificare gli elementi aggiunti in modo che si adattino 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 la latitudine e la longitudine della località tocco, puoi rispondere eseguendo una panoramica o lo zoom in quel punto. Sono disponibili metodi simili per rispondere ai tocchi con il fumetto di un indicatore o per rispondere a un gesto di trascinamento su un indicatore.

Puoi anche ascoltare i movimenti della videocamera, così la tua app riceverà una notifica quando la videocamera inizia a muoversi, è attualmente in movimento o smette di muoversi. Per informazioni dettagliate, consulta la guida agli eventi di cambio 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) è specificata dalle seguenti proprietà: target (posizione di latitudine/longitudine), cuscinetto, inclinazione e zoom.

Diagramma delle proprietà della fotocamera

Target (località)

La località target della fotocamera corrisponde alla posizione del centro della mappa, specificata come longitudine e longitudine.

La latitudine può essere compresa tra -85 e 85 gradi, inclusi. I valori superiori o inferiori a questo intervallo verranno limitati al valore più vicino. 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 superiori o inferiori a questo intervallo verranno aggregati, in modo che rientrino nell'intervallo (-180, 180). Ad esempio, i valori 480, 840 e 1200 vengono aggregati a 120 gradi.

Rilevamento (orientamento)

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

Il valore 0 indica che la parte superiore della mappa punta a nord. Un valore di rilevamento di 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 dovuti a sud.

L'API di Google Maps ti consente di modificare il rilevamento di una mappa. Ad esempio, un utente che guida un'auto spesso gira una mappa stradale per allinearla alla sua 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.

Inclinazione (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 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 cambi l'angolo di visione, la mappa appare in prospettiva, con gli elementi lontani che appaiono più piccoli e le funzionalità vicine 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 ciò; la posizione 1 è la posizione della fotocamera e la posizione 2 è la posizione corrente sulla mappa. La mappa risultante viene mostrata sotto di esso.

Screenshot di una mappa con fotocamera posizionata a un angolo di visione di 0°, con livello di zoom 18.
La mappa è visualizzata con l'angolo di visualizzazione predefinito della videocamera.
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. Tieni presente che la videocamera si sposta a metà dell'arco tra onda dritta (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°, con un livello di zoom di 18.
La mappa è stata visualizzata con un angolo di visione di 45 gradi.
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 di questo screenshot è ancora centrata sullo stesso punto della mappa originale, ma nella parte superiore della mappa sono state visualizzate altre funzionalità. Se aumenti l'angolo di oltre 45 gradi, gli elementi tra la fotocamera e la posizione sulla mappa appaiono proporzionalmente più grandi, mentre gli elementi oltre la posizione della mappa appaiono proporzionalmente più piccoli, con un effetto tridimensionale.

Assumi una prospettiva

Il livello di zoom della fotocamera determina la portata della mappa. A livelli di zoom più elevati, si possono vedere più dettagli sullo schermo, mentre a livelli di zoom più piccoli si può vedere più parte del mondo sullo schermo. 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à).

Aumentando di 1 il livello di zoom, aumenti la larghezza del mondo sullo schermo. Di conseguenza, a livello di zoom N, la larghezza del mondo è di circa 256 * 2N dp. Ad esempio, al livello di zoom 2, il mondo intero ha una larghezza di circa 1024 dp.

Il livello di zoom non deve essere un numero intero. La portata dei 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 successivo più vicino, che può essere il livello di zoom minimo o il livello di zoom massimo. Il seguente elenco mostra il livello approssimativo di dettaglio previsto da ciascun livello di zoom:

  • 1: mondo
  • 5: Terra di massa/continente
  • 10: città
  • 15: Strade
  • 20: Edifici
Le seguenti immagini mostrano l'aspetto visivo di diversi livelli di zoom:
Screenshot di una mappa a un livello di zoom 5
Una mappa al livello di zoom 5.
Screenshot di una mappa con un livello di zoom pari a 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 la parte del mondo visibile sulla mappa. Ciò si ottiene modificando la posizione della fotocamera (anziché sullo spostamento della mappa).

Quando cambi la videocamera, hai la possibilità di animare il movimento della videocamera risultante. L'animazione interpola tra gli attributi della videocamera corrente 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 vari tipi 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 cambia il livello di zoom di 1,0, mantenendo le stesse proprietà.

CameraUpdateFactory.zoomTo(float) ti fornisce un CameraUpdate che modifica il livello di zoom sul valore specificato, mantenendo invariate 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 corregge il punto specifico sullo schermo in modo che rimanga nella stessa posizione (longitudine/longitudine) e potrebbe cambiare la posizione della videocamera per raggiungere questo obiettivo.

Potresti trovare utile impostare un livello minimo e/o massimo di zoom. Ad esempio, questa impostazione è 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.

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 ci sono considerazioni tecniche che potrebbero impedire all'API di consentire agli utenti di eseguire lo zoom troppo in basso o troppo in alto. Ad esempio, il satellite o il rilievo potrebbero avere uno zoom massimo inferiore rispetto ai riquadri della mappa di base.

Modifica della posizione della fotocamera

Esistono due metodi pratici per i cambi di posizione più comuni. CameraUpdateFactory.newLatLng(LatLng) offre un CameraUpdate che cambia la latitudine e la longitudine della fotocamera, mantenendo le altre proprietà. CameraUpdateFactory.newLatLngZoom(LatLng, float) ti offre un CameraUpdate che modifica la latitudine, la longitudine e lo zoom della fotocamera, mantenendo inalterate tutte le altre proprietà.

Per una maggiore flessibilità nel cambiare la posizione della fotocamera, utilizza CameraUpdateFactory.newCameraPosition(CameraPosition) che ti offre una CameraUpdate che sposta la fotocamera nella posizione specificata. È possibile ottenere un CameraPosition direttamente, utilizzando new CameraPosition() o con un CameraPosition.Builder utilizzando new CameraPosition.Builder().

Panoramica (scorrimento)

CameraUpdateFactory.scrollBy(float, float) fornisce un CameraUpdate che modifica la latitudine e la longitudine della fotocamera in modo che la mappa si sposti 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 appaia come spostata a sinistra. Un valore y positivo fa sì che la videocamera si sposti verso il basso, in modo che la mappa sembri spostata in alto. Al contrario, valori x negativi fanno sì che la fotocamera si muova a sinistra, in modo che la mappa sembri avere spostato a destra e 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 fotocamera ha un cuscinetto di 90 gradi, allora est è "su".

Definizione dei confini

Impostazione dei confini della mappa

A volte è utile spostare la fotocamera 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 voler spostare la videocamera in modo che sia tutte visibili sullo schermo. Per farlo, devi prima calcolare il LatLngBounds che vuoi rendere visibile sullo schermo. Puoi quindi utilizzare CameraUpdateFactory.newLatLngBounds(LatLngBounds bounds, int padding) per ottenere un CameraUpdate che cambia 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 CameraUpdate restituito garantisce che il divario (in pixel) tra i limiti specificati e il bordo della mappa sia almeno pari alla spaziatura interna specificata. Tieni presente che l'inclinazione e il cuscinetto 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, centrando la fotocamera in un paese mantenendo uno zoom costante. In questo caso, puoi utilizzare un metodo simile creando un elemento LatLngBounds e utilizzando CameraUpdateFactory.newLatLngZoom(LatLng latLng, float zoom) con LatLngBounds.Metodo getCenter(). Il metodo getCenter() restituirà il centro geografico del 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 che corrispondano alle dimensioni della mappa. Il rettangolo è posizionato in modo che il suo centro sia lo stesso della vista 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'oggetto CameraUpdaterestitato sposterà la fotocamera in modo cheLatLngBounds sia centrato sullo schermo all'interno del rettangolo specificato al livello di zoom più alto possibile, tenendo conto dell'imbottitura 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 ha subito un layout. 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'elemento CameraUpdate restituito dal metodo più complesso newLatLngBounds(boundary, width, height, padding) in qualsiasi momento, anche prima che la mappa abbia subito un layout, perché l'API calcola i limiti di visualizzazione dagli argomenti trasmessi.

Limitazione della panoramica dell'utente a una determinata area

Negli scenari sopra indicati, hai impostato i limiti della mappa, ma l'utente può quindi scorrere o scorrere al di fuori di questi limiti. Ti consigliamo invece di vincolare i limiti di latitudine/longitudine 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 voler limitare la mappa a particolari confini, consentendo agli utenti di scorrere e spostarsi all'interno di quei 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 e eseguire la panoramica, a condizione che il target della videocamera rimanga all'interno dell'area delimitata. La croce rappresenta il target della fotocamera:

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

La mappa riempie sempre l'area visibile, anche se in questo modo l'area visibile mostra aree esterne ai confini definiti. Ad esempio, se posizioni il target della fotocamera 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:

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

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

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

Aggiornamento dell'inquadratura della fotocamera

Per applicare una CameraUpdate alla mappa, puoi spostare la fotocamera all'istante o animarla senza problemi. Per spostare la fotocamera all'istante con il dispositivo CameraUpdate specificato, puoi chiamare GoogleMap.moveCamera(CameraUpdate).

Puoi rendere l'esperienza utente più piacevole, soprattutto per gli spostamenti 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
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 le animazioni, i metodi sono chiamati nelle seguenti circostanze:
onFinish()
Richiamato se l'animazione va a buon fine senza interruzioni.
onCancel()

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

In alternativa, questo problema 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 modi 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))