Videocamera e vista

Seleziona la piattaforma: Android iOS JavaScript

Le mappe nell'SDK di Maps per Android possono essere inclinate e ruotate con semplici gesti, offrendo agli utenti la possibilità di regolarla con l'orientamento più appropriato. A qualsiasi livello di zoom, puoi fare 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:

Introduzione

Come per Google Maps sul web, l'SDK Maps per Android rappresenta la superficie del mondo (una sfera) sullo schermo del dispositivo (un piano piatto) utilizzando la proiezione di merchandising. In direzione est e ovest, la mappa si ripete all'infinito mentre il mondo si avvolge su se stesso. 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 e un'altezza infinita latitudinalmente. 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 semplifica 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 videocamera non apporteranno alcuna modifica agli indicatori, agli overlay o alle altre immagini che hai aggiunto, anche se potresti voler apportare delle modifiche per adattarle meglio alla nuova visualizzazione.

Poiché puoi rimanere in ascolto dei 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 eseguendo una panoramica o aumentando lo zoom fino a quel punto. Sono disponibili metodi simili per rispondere ai tocchi sulla bolla di un indicatore o al gesto di trascinamento su un indicatore.

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

Posizione della fotocamera

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

Diagramma delle proprietà della videocamera

Target (località)

L'obiettivo 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 fissati al valore più vicino all'interno di questo intervallo. Ad esempio, se specifichi una latitudine pari a 100, il valore verrà impostato su 85. La longitudine va da -180 a 180 gradi inclusi. I valori al di sopra o al di sotto di questo intervallo verranno aggregati in modo che rientrino nell'intervallo (-180, 180). Ad esempio, 480, 840 e 1200 verranno tutti aggregati a 120 gradi.

Orientamento (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 al bordo superiore della mappa, l'orientamento corrisponde all'orientamento della fotocamera (misurato in gradi) rispetto al nord vero.

0 indica che la parte superiore della mappa indica il nord vero. Un valore di rilevamento 90 indica la parte superiore dei punti sulla mappa rivolti verso est (90 gradi su una bussola). Il valore 180 indica la parte superiore dei punti sulla mappa orientati verso sud.

L'API di Google Maps ti consente di cambiare l'orientamento di una mappa. Ad esempio, una persona alla guida di un'auto spesso ruota una mappa stradale per allinearla alla direzione di viaggio, mentre gli escursionisti che utilizzano una mappa e una bussola di solito la orientano 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). Il valore 0 corrisponde a una videocamera puntata verso il basso. I valori maggiori di 0 corrispondono a una telecamera con un'inclinazione verso l'orizzonte del numero di gradi specificato. Se cambi l'angolo di visualizzazione, la mappa viene visualizzata in prospettiva, con gli elementi distanti che appaiono più piccoli e quelli vicini più grandi. Le illustrazioni seguenti lo dimostrano.

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

Screenshot di una mappa con una fotocamera posizionata a 0 gradi di angolo di visualizzazione, con un livello di zoom di 18.
La mappa visualizzata con l'angolo di visualizzazione predefinito della fotocamera.
Diagramma che mostra la posizione predefinita della fotocamera, direttamente sopra la posizione sulla mappa, con un angolo di 0 gradi.
L'angolo di visualizzazione 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 la linea diritta dall'alto (0 gradi) e il suolo (90 gradi) per raggiungere la 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 gradi, con un livello di zoom di 18.
La mappa viene visualizzata con un angolo di visualizzazione di 45 gradi.
Diagramma che mostra l'angolo di visione della videocamera impostato su 45 gradi, con il livello di zoom ancora impostato su 18.
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 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 appaiono proporzionalmente più piccoli, generando un effetto tridimensionale.

Zoom

Il livello di zoom della fotocamera determina la scala della mappa. A livelli di zoom più grandi si possono vedere più dettagli sullo schermo, mentre a livelli di zoom più piccoli si possono vedere più parti del mondo sullo schermo. A livello di zoom 0, la scala della mappa è tale che l'intero mondo ha una larghezza di circa 256 dp (pixel indipendenti dalla densità).

Aumentando il livello di zoom di 1, si raddoppia la larghezza del globo sullo schermo. Quindi, a livello di zoom N, la larghezza della Terra è di circa 256 * 2N dp. Ad esempio, a livello di zoom 2, il mondo intero ha un'ampiezza 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 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 che puoi aspettarti di vedere a ogni livello di zoom:

  • 1: Mondo
  • 5: massa continentale/continente
  • 10: Città
  • 15: strade
  • 20: edifici
Le seguenti immagini mostrano l'aspetto di diversi livelli di zoom:
Screenshot di una mappa con livello di zoom 5
Una mappa con livello di zoom 5.
Screenshot di una mappa con livello di zoom 15
Una mappa con livello di zoom 15.
Screenshot di una mappa a livello di zoom 20
Una mappa con livello di zoom 20.

Spostamento della fotocamera

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

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

Per modificare la posizione della videocamera, devi specificare dove vuoi spostarla, utilizzando un pulsante 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 impostandolo sul 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 per il valore specificato. Quest'ultimo fissa il punto specifico sullo schermo in modo che rimanga nella stessa posizione (latitudine/longitudine) e, di conseguenza, potrebbe cambiare la posizione della fotocamera.

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 riquadri personalizzati con un insieme limitato di livelli di zoom.

Kotlin



private lateinit var map: GoogleMap

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

      

Java


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 lo zoom troppo basso o troppo alto. Ad esempio, il satellite o il terreno potrebbe avere uno zoom massimo inferiore rispetto ai riquadri della mappa base.

Modifica della posizione della fotocamera

Esistono due metodi di convenienza per le modifiche di posizione comuni. CameraUpdateFactory.newLatLng(LatLng) offre un CameraUpdate che modifica la latitudine e la longitudine della fotocamera, mantenendo invariate tutte le altre proprietà. CameraUpdateFactory.newLatLngZoom(LatLng, float) offre un elemento 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 videocamera 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 fa sì che la fotocamera si sposti verso destra, per far sembrare che la mappa sia stata spostata a sinistra. Un valore y positivo fa spostare la videocamera verso il basso, mostrando così la mappa che sembri spostata in alto. Viceversa, un valore x negativo fa sì che la fotocamera si sposti verso sinistra, per cui la mappa sembri spostata a destra, mentre valori y negativi fanno spostare la fotocamera verso l'alto. Lo scorrimento è relativo all'orientamento attuale della fotocamera. Ad esempio, se la fotocamera ha un rilevamento di 90 gradi, l'est è "in alto".

Stabilire dei limiti

Impostazione dei limiti 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 mostri 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, devi prima calcolare 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 il valore LatLngBounds specificato si adatti completamente alla mappa, tenendo conto della spaziatura interna (in pixel) specificata. L'oggetto 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 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));

      

Centra la mappa all'interno di un'area

In alcuni casi è consigliabile centrare la videocamera entro un margine anziché includere i confini estremi. Ad esempio, centrarla su un paese mantenendo costante lo zoom. In questo caso, puoi utilizzare un metodo simile, creando una 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 sovraccarico del metodo, newLatLngBounds(boundary, width, height, padding), ti consente di specificare la larghezza e l'altezza in pixel di un rettangolo, in modo che 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, allora il rettangolo coincide con la visualizzazione della mappa). L'elemento CameraUpdate restituito sposterà la fotocamera in modo che gli elementi LatLngBounds specificati siano centrati 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 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 l'elemento CameraUpdate restituito dal metodo più complesso newLatLngBounds(boundary, width, height, padding) in qualsiasi momento, anche prima che il layout della mappa sia stato modificato, perché l'API calcola i limiti di visualizzazione in base agli argomenti trasmessi.

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 limiti del centro di latitudine e longitudine del punto focale della mappa (l'obiettivo della fotocamera) 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 di un centro commerciale o di un aeroporto può limitare la mappa a un limite specifico, in modo che gli utenti possano scorrere ed effettuare la panoramica all'interno di questi limiti.

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 l'obiettivo della videocamera è vincolato 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 limitata. La croce rappresenta l'obiettivo della fotocamera:

Diagramma che mostra i LatLngBounds di una fotocamera più grande dell'area visibile.

La mappa riempie sempre l'area visibile, anche se quest'ultima mostra aree che non rientrano nei limiti 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:

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

Nel seguente diagramma, l'obiettivo della fotocamera presenta limiti molto ristretti, da cui l'utente ha pochissima opportunità di scorrere o fare una panoramica della mappa. La croce rappresenta l'obiettivo della videocamera:

Diagramma che mostra i LatLngBounds di una fotocamera di dimensioni inferiori all'area visibile.

Aggiornamento della visualizzazione della videocamera

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

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

cameraUpdate
L'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 viene completata senza interruzioni.
onCancel()

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

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

duration
Durata desiderata dell'animazione, in millisecondi, sotto forma di int.

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

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