Best practice per 3D Maps

Questa guida fornisce una panoramica dettagliata dei componenti web di 3D Maps e delle considerazioni da fare durante l'integrazione con la tua applicazione.

Esempio di ricerca di luoghi e di calcolo del percorso.

Considerazioni sulle prestazioni

Per garantire un'esperienza fluida e reattiva per l'interattività e gli elementi visivi, valuta i seguenti approcci.

Caricare la mappa

La configurazione iniziale del caricamento e del rendering di Maps 3D combina tecniche di configurazione del browser e best practice dell'interfaccia utente per un'esperienza utente ottimale.

• Caricamento dell'API: utilizza il caricamento dinamico asincrono di Maps 3D per caricare l'API Maps JavaScript al caricamento iniziale della pagina.
• Librerie: carica le librerie in modo programmatico dove necessario, ad esempio google.maps.importLibrary("maps3d"). In alternativa, se utilizzi componenti web come <gmp-map-3d> direttamente nella tua pagina HTML con caricamento diretto dello script, le librerie verranno caricate automaticamente al momento opportuno.
• Gestisci le funzionalità della mappa di base:utilizza un mapId personalizzato per filtrare i PDI della mappa di base (modalità IBRIDA) e controllarne la densità, soprattutto se l'applicazione ha un proprio insieme di elementi personalizzati come indicatori o polilinee. In questo modo si evita il disordine visivo e la potenziale sovrapposizione. In alternativa, puoi disattivare le funzionalità dei vector tile della basemap, come i PDI, le polilinee delle strade, i nomi delle strade e i nomi delle vie (modalità SATELLITE).
• Eventi: ascolta gli eventi gmp-steadystate o gmp-error per creare la logica successiva, ad esempio caricare i marker e animare la fotocamera.

Canvas di sfondo > Riquadri ridotti > Mesh del terreno > Mesh della superficie (ad es. edifici) > Punti di interesse ed etichette stradali, elementi personalizzati caricati in parallelo (indicatori, modelli 3D e così via)

• Interazione utente:attendi l'evento gmp-steadystate prima di apportare modifiche ai contenuti della mappa. Se un utente inizia a interagire (panoramica, zoom) con la mappa prima dell'evento gmp-steadystate iniziale, l'evento verrà attivato solo dopo che l'utente smette di interagire. Evita di mostrare o aggiornare i contenuti di overlay (come indicatori o poligoni) mentre l'utente esegue la panoramica o lo zoom della mappa. Evita di mostrare o aggiornare i contenuti di overlay (come indicatori o poligoni) ascoltando gmp-centerchange, gmp-headingchange gmp-rangechange gmp-rollchange gmp-tiltchange.

• Utilizza requestAnimationFrame() (rAF) per aggiornamenti continui e separa rigorosamente i calcoli intensivi dalle chiamate di disegno.

  • Utilizza rAF: sincronizza gli aggiornamenti con la frequenza di visualizzazione del browser per un'animazione fluida a 60 FPS e un consumo energetico ridotto.
  • Evita operazioni di disegno intensive: non eseguire attività pesanti e non di disegno durante l'aggiornamento finale.
  • Logica separata: esegui tutta la logica intensiva prima delle chiamate di aggiornamento dei componenti web minimi all'interno del ciclo rAF.

• Impostazioni iniziali della scena: <gmp-map-3d> le impostazioni della videocamera come l'inclinazione influiranno sulla velocità di caricamento. Più la scena viene ingrandita o inclinata, più poligoni dettagliati verranno visualizzati e richiedono il caricamento. Il livello di dettaglio dipenderà anche dalla posizione (ad es. città con molti edifici rispetto alla campagna con sole caratteristiche naturali).

  • Preferisci visualizzazioni meno ingrandite (ad alta quota), basse o non inclinate.
  • Aggiungi confini (esempio) alla mappa in modo che gli utenti rimangano concentrati su un'area specifica e i riquadri possano essere caricati completamente.

• Elemento visivo precaricamento: anche se <gmp-map-3d> viene caricato molto rapidamente, potrebbe volerci un po' di tempo per visualizzarlo alla massima risoluzione per gli utenti con dispositivi di fascia bassa (GPU bassa) o larghezza di banda (4G lento). In questo caso, puoi creare un precaricamento con immagine, animazione o testo con il caricamento della scena 3D in background. Di seguito è riportato l'evento chiave da utilizzare:

Esempio di preloader

// create the map in the background and wait for gmp-steadystate event
async function initMap() {
    await google.maps.importLibrary("maps3d");
    const map = document.querySelector('gmp-map-3d');
    const div = document.querySelector('div'); // preloader "
    map.addEventListener('gmp-steadystate', ({isSteady}) => {
        if (isSteady) {
            div.style.display = 'none';
        }
    });
}
initMap();

• Mappa 2D:
  • A questi utenti può essere fornita una mappa 2D alternativa (SATELLITE) che include comunque i tuoi dati geografici, ad esempio i segnaposto.

• In alternativa, durante il caricamento può essere visualizzata una mappa statica 2D complementare in modalità SATELLITE per consentire agli utenti di visualizzare un determinato luogo.

Nota: per il momento ogni caricamento di mappe 2D e 3D viene fatturato separatamente, quindi esegui il rendering della seconda mappa solo quando gli utenti intendono interagire con essa.

Rendimento e gestione degli elementi visivi

Le mappe 3D offrono diversi modi per visualizzare elementi visivi come indicatori, polilinee, polilinee e modelli 3D con prestazioni ottimali e tempi di rendering minimi, anche per immagini con volumi più elevati.

Indicatori

Scenario di esempio: 150-300 ms per caricare 300 indicatori con 41 glifi di indicatori SVG diversi (laptop moderno: macOS M3 Pro, Chrome)

• Scelta di personalizzazione ottimale:
  • PinElement:per modifiche di base ai marcatori (colore, scala, bordo, glifo di testo), utilizza l'elemento <gmp-pin> o la classe PinElement. Questo è il metodo di personalizzazione più efficiente.
  • Utilizza con parsimonia i marcatori HTMLImageElement o SVGElement:utilizzali per una maggiore personalizzazione, ad esempio per aggiungere trasparenza o inserire un'immagine come un'icona in un SVGElement (richiede la codifica base64). Verranno rasterizzati al caricamento e comportano un sovraccarico delle prestazioni. HTMLImageElement e SVGElement devono essere racchiusi nell'elemento <template> prima di essere assegnati allo slot predefinito di Marker3DElement.
  • Al momento non è possibile aggiungere HTML o CSS semplici.
• Gestisci il comportamento di collisione: sfrutta la proprietà collisionBehavior del marcatore. Per i marcatori critici che devono essere sempre visibili, imposta il comportamento di conseguenza. Per i segnaposto meno importanti, consentine la visualizzazione per mantenere un'esperienza più pulita e meno disordinata sulla mappa, soprattutto a livelli di zoom elevati.
• Solo PDI critici: utilizza drawsWhenOccluded (o imposta la proprietà in modo programmatico) solo per i marcatori che devono assolutamente essere visti attraverso edifici o terreni (ad es. un obiettivo di salvataggio, una linea di utilità interrata o l'avatar di un utente).
• Test Occlusion:poiché la mappa è in 3D, i marcatori possono essere oscurati visivamente (occlusi) da edifici o terreno. Prova diverse angolazioni della videocamera e altitudini dei marcatori per garantire che i PDI cruciali rimangano visibili o implementa una logica per regolare la visibilità e l'altitudine quando sono occlusi.
• Sfrutta l'altitudine:nelle mappe 3D, i segnaposto devono utilizzare la posizione con un valore di altitudine. Per i marcatori associati al terreno o agli edifici, utilizza altitudeMode: 'RELATIVE_TO_GROUND', 'RELATIVE_TO_MESH' o impostazioni simili per assicurarti che il marcatore sia ancorato correttamente quando la mappa è inclinata o ruotata.

Poligoni e polilinee

Scenario di esempio: 100-150 ms per caricare 1000 poligoni (laptop moderno: macOS M3 Pro, Chrome)

• Semplifica geometria: prima del rendering, applica un algoritmo di semplificazione ai dati del percorso. In questo modo si riduce il numero di vertici mantenendo la forma generale, migliorando drasticamente la velocità di rendering, soprattutto per i confini o i percorsi complessi.
• Riduzione in base al livello di zoom: per set di dati molto grandi, valuta la possibilità di caricare una geometria più dettagliata solo quando l'utente esegue lo zoom in un'area. A un livello di zoom basso, è necessaria solo una versione molto semplificata della polilinea o del poligono.
• Precalcola per i poligoni estrusi: se i tuoi poligoni sono estrusi (extruded: true), i dati del percorso definiscono un volume 3D (una mesh). L'elaborazione di poligoni complessi con un numero elevato di vertici è costosa dal punto di vista computazionale. Assicurati che i dati di origine per i poligoni siano il più semplici possibile.
• Testa le prestazioni di polilinee e poligoni:quando aggiungi polilinee/poligoni numerosi o complessi, soprattutto se estrusi per il 3D, assicurati che non causino cali del frame rate. Limita il numero di vertici o utilizza algoritmi di semplificazione se necessario.
• Quando aggiorni una forma, modifica l'intero array di percorsi in una singola operazione anziché eseguire un ciclo e modificare i singoli elementi. Una singola operazione di assegnazione (ad es. polyline.path = newPathArray;) è molto più efficiente di più aggiornamenti iterativi.
• Evita le polilinee estruse (se possibile): mentre le polilinee possono utilizzare un valore di altitudine per essere posizionate nello spazio 3D, l'estrusione di una polilinea (ad es. assegnandole una larghezza del tratto e un ampio intervallo di altitudine) può essere graficamente intensa. Quando possibile, utilizza polilinee 2D a terra (RELATIVE_TO_GROUND) o una larghezza tratto minima per prestazioni migliori.
• Utilizza drawsOccludedSegments solo per gli elementi di routing critici. Per le forme di sfondo o contestuali, consenti che vengano occluse naturalmente dalla geometria 3D della mappa. La visualizzazione della geometria nascosta non critica aggiunge una complessità di rendering non necessaria.

Modelli 3D

Il rendering e l'interattività dei modelli 3D .glb, come l'evento gmp-click, sono molto veloci in <gmp-map-3d>.

Scenario di esempio: occorrono circa 2 secondi per visualizzare 1000 occorrenze di un modello 3D (200 KB) di una luce che si muove lungo un percorso. (laptop moderno: macOS M3 Pro, Chrome)

• Ridurre al minimo le dimensioni dei file con la compressione: per garantire un caricamento rapido, soprattutto sulle reti mobile, mantieni i file di modelli .glb complessi sotto i 5 MB (idealmente meno). Il metodo principale per raggiungere questo obiettivo è applicare la compressione Draco ai dati della mesh all'interno dei file .glb, che può ridurre significativamente le dimensioni del file (spesso di oltre il 50%) con una perdita minima di qualità visiva.
• Centra l'origine del modello:assicurati che il software di modellazione 3D esporti il modello con l'origine (punto 0, 0, 0) centrata alla base del modello. In questo modo si semplificano il posizionamento e la rotazione sulla mappa, garantendo che il modello sia ancorato correttamente alle coordinate di latitudine e longitudine.
• Gestisci CORS: se i file del modello sono ospitati su un dominio o una CDN diversi dalla tua applicazione web, devi configurare il server di hosting in modo che includa le intestazioni CORS (Cross-Origin Resource Sharing) necessarie (ad es. Access-Control-Allow-Origin: *). In caso contrario, la mappa non può caricare il modello.