Descrizione del progetto di esempio del plugin Mega per mini program WeChat

Questo articolo descrive in dettaglio come usare le funzioni mostrate nel progetto di esempio, le modalità di implementazione e le note da considerare.

Prima di iniziare

• È possibile creare e caricare annotation con l'editor Unity, quindi registrare il nome dell'annotation e il relativo ID.
• È possibile creare contenuti 3D allineati al mondo reale con l'editor Unity.
• È possibile eseguire completamente il progetto di esempio.

Come visualizzare un modello nella posizione di un'annotation

1. Posizionare e caricare annotazioni con precisione nell'editor Unity e registrare il nome dell'annotazione e il relativo ID

   

2. Aggiungere risorse modello GLTF

   Aggiungere la risorsa modello a sampleAssets in miniprogram/components/sample-easyar-mega/index.ts.

   const sampleAssets = {
       your_model_name: {
           assetId: "your_model_asset_id",
           type: "gltf",
           src: "url/model.glb",
           options: {}
       }
   }
   

3. Caricare la risorsa modello aggiunta

   Caricare il modello nella funzione loadAsset() in miniprogram/components/sample-easyar-mega/index.ts.

   async loadAsset() {
       try {
           await scene.assets.loadAsset(sampleAssets.your_model_name);
       } catch (err) {
           console.error(`Failed to load assets: ${err.message}`);
       }
   }
   

4. Configurare le annotazioni da sostituire

   Configurare le annotazioni da sostituire in miniprogram/components/sample-data/annotation-metadata.ts. Se ne vanno sostituite più di una, separarle con virgole.

   export const AnnotationMetaData: Record<string, any> = {
       "aaaaaaaa-bbbb-cccc-dddd-123456789012": {
           assetId: "panda",
           scale: "0.5 0.5 0.5"
       },
       "aaaaaaaa-bbbb-cccc-dddd-123456789013": {
           assetId: "your_model_asset_id",
           scale: "1 1 1"
       }
   };
   

5. Sostituire annotazioni e caricare modelli

   Nel callback dopo il caricamento di EMA, usare il "metodo factory" di xr-frame scene.createElement(xrFrameSystem.XRGLTF, options) per creare il nodo modello.

   • Parametri:

     • xrFrameSystem.XRGLTF: specifica che il tipo di elemento da creare è un modello GLTF.
     • options: elementi di configurazione di inizializzazione corrispondenti alle proprietà del componente.

   • Proprietà chiave nel codice:

     • "model": obbligatorio. Punta all'ID della risorsa caricata (asset-id).
     • "anim-autoplay": facoltativo. Specifica il nome dell'animazione da riprodurre automaticamente dopo il caricamento.
     • "scale": facoltativo. assetInfo.scale o "1 1 1".
     • name: obbligatorio. Nome dell'annotazione.

   Attenzione

   Prestare attenzione a distinguere le chiavi proprietà stringa e non stringa, e compilarle esattamente come nell'esempio.

   Montare il modello sotto il nodo annotazione con xrNode.addChild(child).

   Per garantire che il modello GLTF appaia uguale con loader su piattaforme diverse, ruotare il modello caricato di 180 gradi attorno all'asse Y sul posto.

   if (assetInfo && assetInfo.assetId && assetInfo.assetId.trim().length > 0) {
       model = scene.createElement(
           xrFrameSystem.XRGLTF,
           {
               /** assetId del passaggio precedente */
               "model": assetInfo.assetId,
               /** Qui è possibile specificare l’animazione del modello da riprodurre */
               "anim-autoplay": assetInfo.animation ? assetInfo.animation : "",
               "scale": assetInfo.scale ? assetInfo.scale : "1 1 1",
               name: emaName
           }
       );
       xrNode.addChild(model);
       /**
        * Poiché i loader GLTF si comportano in modo diverso, per mantenere l’orientamento del modello in xr-frame esattamente coerente con il risultato renderizzato in Unity
        * Il modello caricato deve essere ruotato sul posto di 180 gradi attorno all’asse Y
        */
       let modelTransform = model.getComponent(xrFrameSystem.Transform);
       let currentRotation = modelTransform.quaternion.clone();
       let targetRotation = currentRotation.multiply(new xrFrameSystem.Quaternion().setValue(0, 1, 0, 0));
       modelTransform.quaternion.set(targetRotation);
   }
   

6. Esecuzione su dispositivo

   • Il risultato dell'esecuzione su dispositivo è mostrato sotto e può essere confrontato con la posizione nell'editor Unity nel Passaggio 1:

   • Attivare il pulsante video trasparente a sinistra. All'origine del sistema di coordinate mondo, posizione (0, 0, 0), appare un cubo con materiale video trasparente.

     Nota

     La posizione dell'origine può essere casuale nello spazio. È possibile usare annotazioni per posizionare il modello di occlusione nella posizione desiderata. Per dettagli, vedere creare e caricare annotazioni con l'editor Unity.

   • Attivare il pulsante occlusione a sinistra. All'origine del sistema di coordinate mondo, posizione (0, 0, 0), compaiono un modello panda e cubi sovrapposti verticalmente. Il cubo centrale ha materiale di occlusione e dall'altra parte c'è un modello panda statico con materiale di occlusione.

     Nota

     La posizione dell'origine può essere casuale nello spazio. È possibile usare annotazioni per posizionare il modello di occlusione nella posizione desiderata. Per dettagli, vedere creare e caricare annotazioni con l'editor Unity.

     

Come riprodurre un video trasparente nella posizione di un'annotation

1. Caricare una risorsa video di tipo video-texture.

   async loadAsset() {
       const videoTexture = {
           assetId: "fireball",
           type: "video-texture",
           // 视频资源 URL
           src: "url/video-resource.mp4",
           options: {
               autoPlay: true,
               loop: true,
           }
       };
       try {
           // 加载 video-texture 类型资源
           await scene.assets.loadAsset(videoTexture);
       } catch (err) {
           console.error(`Failed to load video texture: ${err.message}`);
       }
   }
   

2. Modificare il callback di caricamento EMA

   Nel callback di caricamento EMA, usare scene.createElement(xrFrameSystem.XRMesh,options) per creare una geometria semplice, assegnarle il materiale easyar-video-tsbs e modificare uniform in u_baseColorMap:video-{$assetId}.

   • Parametri:

     • xrFrameSystem.XRMesh: specifica che il tipo di elemento creato è una geometria di base.
     • options: elementi di configurazione di inizializzazione, corrispondenti alle proprietà del componente.

   • Proprietà chiave nel codice:

     • "geometry": "cube": usa i dati geometrici del cubo integrati in xr-frame.
     • "material": "easyar-video-tsbs": specifica un materiale predefinito. Dal nome si presume sia un materiale speciale che supporta texture video.
     • "uniforms": "u_baseColorMap:video-{$assetId}":

     Attenzione

     Fare attenzione a distinguere le property Key stringa e non stringa, e compilarle esattamente come mostrato nell'esempio.

     Questa è un'associazione dinamica di un parametro del materiale.

     Mappa la risorsa video (texture) denominata video-{$assetId} sulla base color map del materiale.

     Effetto: genera un cubo sulla cui superficie viene riprodotto il video.

   model = scene.createElement(xrFrameSystem.XRMesh, {
       geometry: "cube",
       material: "easyar-video-tsbs",
       uniforms: "u_baseColorMap:video-fireball",
   });
   xrNode.addChild(model);
   

   Nota

   Quando si usa video-texture, se nella console compare l'avviso wx.createVideoDecoder with type: 'wemedia' is deprecated, ignorarlo.

   Abbiamo confermato con il team ufficiale WeChat che questo avviso non influisce sull'uso.

3. Eseguire su dispositivo reale

Come posizionare un modello di occlusion allineato allo spazio

1. Posizionare con precisione il modello usato per occlusion e caricare l'annotazione.

   

2. Caricare il GLTF usato come occlusion nel xr-frame Mini Program.

   Caricare la risorsa modello tramite scene.assets.loadAsset() (è necessario scaricarla manualmente).

   const sampleAssets = {
       occlusion1: {
           assetId: "occlusion1",
           type: "gltf",
           src: "url/occlusion1.glb",
           options: {}
       }
   }
   async loadAsset() {
       if (!scene) {console.error("Empty scene"); return;}
       try {
           await scene.assets.loadAsset(sampleAssets.occlusion1);
       } catch (err) {
           console.error(`Failed to load assets: ${err.message}`);
       }
   }
   

3. A runtime, caricare il modello nel callback di caricamento EMA e assegnare il materiale occlusion

   Usare scene.createElement(xrFrameSystem.XRGLTF,options) nel callback di caricamento EMA per creare il nodo modello.

   • Parametri:

     • xrFrameSystem.XRGLTF: specifica che il tipo di elemento creato è un modello GLTF.
     • options: elementi di configurazione di inizializzazione, corrispondenti alle proprietà del componente.

   • Proprietà chiave nel codice:

     • "model": obbligatorio, punta all'ID della risorsa caricata (asset-id).
     • "scale": opzionale, assetInfo.scale o "1 1 1".
     • name: obbligatorio, nome annotazione.

   Attenzione

   Prestare attenzione a distinguere le property Key stringa e non stringa, e compilare esattamente come nell'esempio.

   Montare il modello sotto il nodo annotazione con xrNode.addChild(child).

   Per garantire che il modello GLTF appaia uguale con loader su piattaforme diverse, ruotare sul posto il modello caricato di 180 gradi attorno all'asse Y.

   Infine, usare model.getComponent(xrFrameSystem.GLTF).meshes.forEach((m: any) => {m.setData({ neverCull: true, material: occlusionMaterial });} per modificare il material del modello GLTF.

   Nota

   Caricamento, registrazione, deregistrazione e scaricamento del material easyar-occulusion sono controllati da AR Session.

   Usare il modello nella posizione annotazione come occlusion:

   if (...) {
       model = scene.createElement(
           xrFrameSystem.XRGLTF,
           {
               "model": assetInfo.assetId,
               "scale": assetInfo.scale ? assetInfo.scale : "1 1 1",
               name: emaName
           }
       );
       /**
       * Poiché i loader GLTF si comportano in modo diverso, per mantenere l’orientamento del modello in xr-frame esattamente coerente con il risultato renderizzato in Unity,
       * a volte il modello caricato deve essere ruotato sul posto di 180 gradi attorno all’asse Y
       */
       let modelTransform = model.getComponent(xrFrameSystem.Transform);
       let currentRotation = modelTransform.quaternion.clone();
       let targetRotation = currentRotation.multiply(new xrFrameSystem.Quaternion().setValue(0, 1, 0, 0));
       modelTransform.quaternion.set(targetRotation);
       // Nota: il materiale deve essere modificato dopo aver modificato Transform
       if (assetInfo.assetId == 'occlusion1') {
           // Ottiene il materiale di occlusione fornito dal plugin Mega
           let occlusionMaterial = scene.assets.getAsset("material", "easyar-occlusion");
           // Modifica il materiale di occlusione
           model.getComponent(xrFrameSystem.GLTF).meshes.forEach((m: any) => {
               m.setData({ neverCull: true, material: occlusionMaterial });
           });
       }
   }
   

4. Eseguire su un dispositivo reale

   Confrontare con il risultato di esecuzione simulata in Unity editor.

Argomenti correlati

• Occlusion ambientale
• Video trasparente
• Esecuzione simulata con l'editor Unity
• Introduzione al formato EasyAR Mega Annotation (EMA)