Aggiungere modelli 3D al web con <model-viewer>

Oggi è comune che le persone portino in tasca dispositivi in grado di supportare la realtà aumentata (AR) e la realtà virtuale (VR). Sempre più spesso, i contenuti che condividiamo tra noi su questi dispositivi sono in 3D. In questo lab di programmazione imparerai a utilizzare un componente web chiamato <model-viewer> per aggiungere contenuti 3D al tuo sito web o alla tua app web progressiva (PWA) con la stessa facilità con cui aggiungeresti un'immagine con HTML.

Cosa creerai

Un sito web contenente un modello 3D interattivo con la possibilità di visualizzare ologrammi AR

Cosa imparerai a fare

  • Come installare il componente web <model-viewer> sul tuo sito web
  • Come utilizzare <model-viewer> per presentare un modello 3D in un layout web standard
  • Come personalizzare <model-viewer> per aggiungere un tocco in più alla presentazione

Che cosa ti serve

  • Un browser web. Ti consigliamo Chrome, ma qualsiasi browser moderno (Firefox, Safari, Edge) funzionerà.
  • Node.js e un editor di testo oppure l'accesso a Glitch.
  • Conoscenza di base di HTML, CSS, JavaScript e Chrome DevTools.

Questo codelab è incentrato su <model-viewer> e sui modelli 3D. Concetti e blocchi di codice non pertinenti sono trattati solo superficialmente e sono forniti solo per operazioni di copia e incolla.

Opzione 1: Glitch

Puoi utilizzare uno strumento di modifica del codice online come Glitch per ospitare il tuo progetto e visualizzare le modifiche.

Per iniziare a utilizzare Glitch, fai clic sul pulsante seguente:

Apri l'ambiente Glitch precaricato

Da questo momento in poi, puoi utilizzare l'editor di codice su Glitch per modificare i file e, quando è tutto pronto, iniziare a pubblicare l'applicazione utilizzando il pulsante "Mostra live". Prova ora e dovresti visualizzare la pagina seguente:

Opzione 2: server locale

Un server locale ti consente di utilizzare l'editor di codice che preferisci.

Installa il server

Avremo bisogno di un modo per pubblicare pagine web locali. Un modo semplice è tramite Node.js e serve, un semplice server di contenuti statici.

Consulta il sito web di Node.js per istruzioni su come installarlo sul tuo sistema operativo. Una volta installato Node.js, esegui questo comando per installare serve:

npm install -g serve

Scarica il codice

Un modello iniziale, insieme a tutti gli asset di esempio, è disponibile per il download. Fai clic sul seguente link e decomprimi i contenuti nella directory in cui vuoi inserire il progetto:

Scarica il codice sorgente

In alternativa, utilizza git per clonare il repository:

git clone https://github.com/googlecodelabs/model-viewer-codelab.git

Esecuzione del server

Dalla directory dei modelli estratta sopra (o all'interno della directory clonata, se hai utilizzato git), esegui il comando serve per avviare un server web:

Visita questo indirizzo (nello screenshot sopra, è http://localhost:5000, ma potrebbe essere diverso sul tuo computer) per visualizzare un punto di partenza molto semplice:

Inizieremo modificando il file index.html tramite l'editor web Glitch o, se utilizzi il server locale, il tuo editor di codice preferito.

Aggiungere la libreria <model-viewer>

Per utilizzare <model-viewer>, dobbiamo includere un insieme di file JavaScript.

La sezione seguente aggiunge la libreria <model-viewer> alla tua pagina. Incolla il seguente codice alla fine di <body>.

<!-- 💁 Include both scripts below to support all browsers! -->

<!-- Loads <model-viewer> for modern browsers: -->
<script type="module"
    src="https://unpkg.com/@google/model-viewer/dist/model-viewer.js">
</script>

<!-- Loads <model-viewer> for old browsers like IE11: -->
<script nomodule
    src="https://unpkg.com/@google/model-viewer/dist/model-viewer-legacy.js">
</script>

Abbiamo appena aggiunto le librerie, senza modificare i contenuti. Se aggiorni la pagina, vedrai gli stessi contenuti. Se apri la console DevTools, potresti visualizzare alcuni avvisi relativi alle API WebXR mancanti, ma questi sono previsti fino al rilascio completo dell'API.

Massimizzare la compatibilità

<model-viewer> supporta molti browser moderni. Tuttavia, se vuoi estendere il numero di browser supportati dalla tua pagina, puoi includere ulteriori polyfill.

Di seguito è riportato l'elenco completo dei consigli. Questi ti aiuteranno a supportare un'esperienza ottimale su tutti i browser moderni. Per ulteriori informazioni, consulta la documentazione sui polyfill di<model-viewer>.

Incolla il seguente codice in <head>.

<!-- The following libraries and polyfills are recommended to maximize browser support -->
<!-- NOTE: you must adjust the paths as appropriate for your project -->
    
<!-- 🚨 REQUIRED: Web Components polyfill to support Edge and Firefox < 63 -->
<script src="https://unpkg.com/@webcomponents/webcomponentsjs@2.1.3/webcomponents-loader.js"></script>

<!-- 💁 OPTIONAL: Intersection Observer polyfill for better performance in Safari and IE11 -->
<script src="https://unpkg.com/intersection-observer@0.5.1/intersection-observer.js"></script>

<!-- 💁 OPTIONAL: Resize Observer polyfill improves resize behavior in non-Chrome browsers -->
<script src="https://unpkg.com/resize-observer-polyfill@1.5.1/dist/ResizeObserver.js"></script>

<!-- 💁 OPTIONAL: Fullscreen polyfill is required for experimental AR features in Canary -->
<!--<script src="https://unpkg.com/fullscreen-polyfill@1.0.2/dist/fullscreen.polyfill.js"></script>-->

<!-- 💁 OPTIONAL: Include prismatic.js for Magic Leap support -->
<!--<script src="https://unpkg.com/@magicleap/prismatic@0.18.2/prismatic.min.js"></script>-->

Aggiungere <model-viewer>

Ora aggiungiamo il tag <model-viewer > alla pagina per visualizzare un po' di 3D. Sostituisci l'elemento <p> esistente con il seguente codice:

<model-viewer src="third_party/Astronaut/Astronaut.glb"
              alt="A 3D model of an astronaut">
</model-viewer>

Qui sono da menzionare solo due attributi:

  • L'attributo src specifica da dove caricare il modello 3D. In questo esempio è stato utilizzato un modello Astronauta di Poly, reso disponibile con licenza CC-BY.
  • L'attributo alt contiene una descrizione di testo alternativa del modello per l'accessibilità.

Potresti notare che entrambi questi attributi hanno forti parallelismi con gli attributi del tag img.

Un ricaricamento mostrerà l'astronauta:

Bene! Hai un modello 3D sul web.


Nei passaggi successivi, sperimenteremo maggiore interattività e movimento, modificheremo l'aspetto dell'elemento e faremo un primo passo nell'AR.

Aggiungiamo un po' di interattività al modello. Per impostazione predefinita, il modello ruoterà per dare agli utenti un suggerimento che il modello è interattivo (e anche per mostrarlo) e poi attiveremo i controlli in modo che gli utenti possano spostare il modello da soli con il mouse o tramite tocco.

Per farlo, aggiungi gli attributi auto-rotate e camera-controls all'elemento <model-viewer>. 

<model-viewer src="third_party/Astronaut/Astronaut.glb"
              auto-rotate camera-controls
              alt="A 3D model of an astronaut">
</model-viewer>

Quando aggiorni la pagina, l'astronauta ruota lentamente. Se provi a trascinare il modello (facendo clic e spostando il mouse o trascinando il dito se usi un dispositivo touch), il modello ruoterà.

Queste funzionalità combinate danno all'utente un indizio che si tratta di qualcosa di più di una semplice immagine statica e un senso di interattività che lo coinvolge (e gli consente di vedere il retro del modello).

Ora che abbiamo un po' di movimento, vediamo come modificare l'aspetto per rendere il modello davvero accattivante.

Aggiornare il modello

Alcune di queste modifiche (in particolare quelle all'illuminazione) saranno più evidenti con determinati modelli. Innanzitutto, aggiorniamo l'attributo src in modo che rimandi a un nuovo modello: third_party/DamagedHelmet/DamagedHelmet.gltf (rilasciato con licenza Creative Commons Attribution-NonCommercial su Sketchfab). L'origine dell'intero elemento ora dovrebbe essere:

<model-viewer src="third_party/DamagedHelmet/DamagedHelmet.gltf"
              auto-rotate camera-controls
              alt="A 3D model of a damaged sci-fi helmet">
</model-viewer>

Questo modello mostrerà alcune delle modifiche che stiamo per apportare.

Modifica il colore dello sfondo

Innanzitutto, cambiamo il colore dello sfondo per far risaltare il modello sulla pagina. Aggiungi il seguente attributo al tag <model-viewer>:

background-color="#70BCD1"

Impostare la mappa dell'ambiente

Le mappe dell'ambiente vengono utilizzate per fornire una scena circostante che si riflette sul modello e per specificare la configurazione dell'illuminazione. L'illuminazione predefinita è eccellente (e compatibile con l'illuminazione di Scene Viewer di ARCore), ma a volte potresti avere un ambiente personalizzato o potresti aver bisogno di un'illuminazione specifica per i risultati che stai cercando di ottenere. Specifichiamo l'attributo immagine dell'ambiente (studio_small_07_1k.hdr proviene da hdrihaven.com).

environment-image="third_party/hdrihaven/studio_small_07_1k.hdr"

Aggiungere un'ombra

Se l'oggetto proietta un'ombra, la scena acquisisce maggiore profondità. Il seguente attributo, se aggiunto all'elemento <model-viewer>, proietterà un'ombra:

shadow-intensity="1"

Modificare l'intensità dell'illuminazione

Il modello è un po' scuro, quindi alziamo un po' le luci per vedere meglio i dettagli. Sia l'illuminazione predefinita del palco sia l'illuminazione della mappa dell'ambiente che abbiamo aggiunto possono essere regolate in modo indipendente. Aggiungi questo:

stage-light-intensity="3" environment-intensity="2"

Ognuna di queste modifiche era piuttosto piccola, ma ora il modello è molto migliore.

Successivamente, esamineremo alcune modalità di visualizzazione alternative.

Sempre più dispositivi sono dotati di una qualche forma di realtà aumentata (AR). Alcune di queste modalità sono difficili da attivare o richiedono un codice speciale, ma <model-viewer> può gestire tutta questa complessità per te.

Scene Viewer di ARCore

Sui dispositivi supportati, <model-viewer> può attivare Scene Viewer di ARCore. Aggiungi l'attributo ar all'elemento <model-viewer>. Sì, è tutto ciò che devi fare.

<model-viewer src="third_party/DamagedHelmet/DamagedHelmet.gltf"
              ar
              auto-rotate camera-controls
              background-color="#70BCD1"
              shadow-intensity="1"
              alt="A 3D model of a damaged sci-fi helmet">
</model-viewer>

Ora, se lo visualizzi su un dispositivo supportato con una versione recente di ARCore, vedrai un'icona aggiuntiva (come nell'immagine di seguito). Se fai clic, il modello si aprirà in Esplora scene.

Altri dispositivi: iOS Quick Look, Magic Leap, WebXR

Molti altri dispositivi richiedono un po' più di lavoro.

Su iOS, l'attributo ios-src consente di specificare una versione USDZ aggiuntiva del modello 3D (obbligatoria su iOS). Quando viene fornito questo attributo, l'icona standard di AR Quick Look viene visualizzata sul modello per i dispositivi iOS supportati. Per saperne di più sul formato USDZ, consulta la documentazione per gli sviluppatori di Apple.

Sui dispositivi Magic Leap, l'attributo magic-leap attiverà il supporto AR. Tieni presente che devi includere anche la libreria prismatic.js (inclusa, ma commentata, nei polyfill facoltativi) e il modello 3D deve essere un file .glb (non .gltf).

<script src="https://unpkg.com/@magicleap/prismatic@0.18.2/prismatic.min.js"></script>

L'angolazione e la posizione iniziali della videocamera possono essere controllate. Questo controllo ci consente di mostrare agli utenti una visualizzazione predefinita migliore del casco. Aggiungi il seguente snippet al tag <model-viewer>:

camera-orbit="-20deg 75deg 2m"

Naturalmente, questi modelli possono essere utilizzati con altri contenuti, anche su pagine adattabili. La creazione di una pagina web adattabile non rientra nell'ambito di questo codelab, ma consulta la pagina Nozioni di base sul responsive web design per ulteriori informazioni.

Abbiamo incluso una pagina di esempio nel nostro repository. Dai un'occhiata a responsive.html in formato widescreen (come su un computer):

La stessa pagina, in un'area visibile stretta (ad esempio un dispositivo mobile):

Hai incorporato un elemento di contenuti 3D sul web. Ottimo!

Passaggi successivi

Esistono molte altre opzioni di configurazione. Per saperne di più, consulta la nostra documentazione online o il codice.

Una volta identificati i modelli, ecco alcuni passaggi successivi che potresti prendere in considerazione:

  • Alcuni modelli possono essere piuttosto grandi. In questi casi, <model-viewer> fornisce diversi metodi per offrire comunque esperienze eccellenti. Per ulteriori informazioni, consulta la pagina della documentazione relativa al caricamento lento.
  • I modelli animati possono essere davvero divertenti. Per saperne di più sull'attivazione (e sul passaggio da un'animazione all'altra) delle animazioni definite nei modelli, consulta la nostra pagina Animazioni.
  • E questo è ancora il web: i modelli possono essere incorporati nelle tue pagine web per integrare i tuoi contenuti.

Il nostro processo di sviluppo è aperto su GitHub. Vorremmo conoscere la tua opinione.