Descrição do projeto de exemplo do plugin Mega para Mini Programs do WeChat

Este artigo descreve em detalhes como usar as funções mostradas no projeto de exemplo, os métodos de implementação e as observações.

Antes de começar

• Você consegue criar e carregar annotation usando o editor Unity, e registrar o nome da annotation e seu ID.
• Você consegue criar conteúdo 3D alinhado ao mundo real usando o editor Unity.
• Você consegue executar completamente o projeto de exemplo.

Como exibir um modelo na posição da annotation

1. Posicionar e enviar anotações com precisão no editor Unity e registrar o nome da anotação e seu ID

   

2. Adicionar recursos de modelo GLTF

   Adicione o recurso de modelo a sampleAssets em 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. Carregar o recurso de modelo adicionado

   Carregue o modelo na função loadAsset() em 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. Configurar as anotações a substituir

   Configure as anotações a substituir em miniprogram/components/sample-data/annotation-metadata.ts. Se várias forem substituídas, separe-as por vírgulas.

   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. Substituir anotações e carregar modelos

   No callback após o carregamento de EMA, use o "método factory" do xr-frame scene.createElement(xrFrameSystem.XRGLTF, options) para criar o nó de modelo.

   • Parâmetros:

     • xrFrameSystem.XRGLTF: especifica que o tipo de elemento a criar é um modelo GLTF.
     • options: itens de configuração de inicialização correspondentes às propriedades do componente.

   • Propriedades principais no código:

     • "model": obrigatório. Aponta para o ID do recurso carregado (asset-id).
     • "anim-autoplay": opcional. Especifica o nome da animação a reproduzir automaticamente após o carregamento.
     • "scale": opcional. assetInfo.scale ou "1 1 1".
     • name: obrigatório. Nome da anotação.

   Cuidado

   Preste atenção à distinção entre chaves de propriedade string e não string, e preencha exatamente como no exemplo.

   Monte o modelo sob o nó de anotação com xrNode.addChild(child).

   Para garantir que o modelo GLTF tenha o mesmo resultado em loaders de diferentes plataformas, gire o modelo carregado 180 graus em torno do eixo Y no próprio local.

   if (assetInfo && assetInfo.assetId && assetInfo.assetId.trim().length > 0) {
       model = scene.createElement(
           xrFrameSystem.XRGLTF,
           {
               /** assetId da etapa anterior */
               "model": assetInfo.assetId,
               /** A animação do modelo a ser reproduzida pode ser especificada aqui */
               "anim-autoplay": assetInfo.animation ? assetInfo.animation : "",
               "scale": assetInfo.scale ? assetInfo.scale : "1 1 1",
               name: emaName
           }
       );
       xrNode.addChild(model);
       /**
        * Como os loaders GLTF se comportam de formas diferentes, para manter a orientação do modelo no xr-frame exatamente igual ao resultado renderizado no Unity
        * O modelo carregado precisa ser girado 180 graus em torno do eixo Y no próprio local
        */
       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. Executar no dispositivo

   • O resultado da execução no dispositivo é mostrado abaixo e pode ser comparado com a posição no editor Unity na Etapa 1:

   • Ative o botão de vídeo transparente à esquerda. Um cubo com material de vídeo transparente aparece na origem do sistema de coordenadas do mundo, na posição (0, 0, 0).

     Nota

     A posição da origem pode ser uma posição aleatória no espaço. Você pode usar anotações para posicionar o modelo de oclusão no local desejado. Veja criar e enviar anotações com o editor Unity.

   • Ative o botão de oclusão à esquerda. Na origem do sistema de coordenadas do mundo, posição (0, 0, 0), aparecem um modelo de panda e cubos empilhados verticalmente. O cubo do meio tem material de oclusão, e do outro lado há um modelo de panda estático com material de oclusão.

     Nota

     A posição da origem pode ser uma posição aleatória no espaço. Você pode usar anotações para posicionar o modelo de oclusão no local desejado. Veja criar e enviar anotações com o editor Unity.

     

Como reproduzir vídeo transparente na posição da annotation

1. Carregar um recurso de vídeo do 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. Modificar o callback de carregamento EMA

   No callback de carregamento EMA, use scene.createElement(xrFrameSystem.XRMesh,options) para criar uma geometria simples, atribua o material easyar-video-tsbs e altere uniform para u_baseColorMap:video-{$assetId}.

   • Parâmetros:

     • xrFrameSystem.XRMesh: especifica que o tipo do elemento criado é uma geometria básica.
     • options: itens de configuração de inicialização, correspondentes às propriedades do componente.

   • Propriedades principais no código:

     • "geometry": "cube": usa os dados de geometria de cubo integrados ao xr-frame.
     • "material": "easyar-video-tsbs": especifica um material predefinido. Pelo nome, presume-se que seja um material especial compatível com texturas de vídeo.
     • "uniforms": "u_baseColorMap:video-{$assetId}":

     Cuidado

     Preste atenção para distinguir property Key em string e não string, e preencha exatamente como no exemplo.

     Esta é uma vinculação dinâmica de parâmetro de material.

     Ela mapeia o recurso de vídeo (textura) chamado video-{$assetId} para o mapa de cor base do material.

     Efeito: isso cria um cubo cuja superfície reproduz vídeo.

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

   Nota

   Ao usar video-texture, se a console exibir o aviso wx.createVideoDecoder with type: 'wemedia' is deprecated, ignore-o.

   Confirmamos com a equipe oficial do WeChat que esse aviso não afeta o uso.

3. Executar em um dispositivo real

Como posicionar um modelo de occlusion alinhado ao espaço

1. Posicione com precisão o modelo usado para occlusion e envie a anotação.

   

2. Carregue o GLTF usado como occlusion no xr-frame Mini Program.

   Carregue o recurso de modelo por scene.assets.loadAsset() (é necessário descarregar 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. Em runtime, carregue o modelo no callback de carregamento EMA e atribua o material de occlusion

   Use scene.createElement(xrFrameSystem.XRGLTF,options) no callback de carregamento EMA para criar o nó do modelo.

   • Parâmetros:

     • xrFrameSystem.XRGLTF: especifica que o tipo de elemento criado é um modelo GLTF.
     • options: itens de configuração de inicialização, correspondentes às propriedades do componente.

   • Propriedades-chave no código:

     • "model": obrigatório, aponta para o ID do recurso carregado (asset-id).
     • "scale": opcional, assetInfo.scale ou "1 1 1".
     • name: obrigatório, nome da anotação.

   Cuidado

   Preste atenção em distinguir property Keys string e não string, e preencha exatamente como no exemplo.

   Monte o modelo sob o nó de anotação com xrNode.addChild(child).

   Para garantir que o modelo GLTF tenha o mesmo resultado em loaders de diferentes plataformas, gire o modelo carregado 180 graus em torno do eixo Y no próprio local.

   Por fim, use model.getComponent(xrFrameSystem.GLTF).meshes.forEach((m: any) => {m.setData({ neverCull: true, material: occlusionMaterial });} para modificar o material do modelo GLTF.

   Nota

   O carregamento, registro, cancelamento de registro e unload do material easyar-occulusion são controlados por AR Session.

   Use o modelo na posição da anotação como occlusion:

   if (...) {
       model = scene.createElement(
           xrFrameSystem.XRGLTF,
           {
               "model": assetInfo.assetId,
               "scale": assetInfo.scale ? assetInfo.scale : "1 1 1",
               name: emaName
           }
       );
       /**
       * Como os loaders GLTF se comportam de formas diferentes, para manter a orientação do modelo no xr-frame exatamente igual ao resultado renderizado no Unity,
       * às vezes é preciso girar o modelo carregado 180 graus em torno do eixo Y no próprio local
       */
       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);
       // Observação: o material deve ser alterado depois de modificar Transform
       if (assetInfo.assetId == 'occlusion1') {
           // Obter o material de oclusão fornecido pelo plugin Mega
           let occlusionMaterial = scene.assets.getAsset("material", "easyar-occlusion");
           // Modificar o material de oclusão
           model.getComponent(xrFrameSystem.GLTF).meshes.forEach((m: any) => {
               m.setData({ neverCull: true, material: occlusionMaterial });
           });
       }
   }
   

4. Executar em um dispositivo real

   Compare com o resultado de execução simulada no Unity editor.

Tópicos relacionados

• Occlusion ambiental
• Vídeo transparente
• Execução simulada com o editor Unity
• Introdução ao formato EasyAR Mega Annotation (EMA)