Table of Contents

Comment charger des contenus 3D dans un scénario AR en temps réel avec xr-frame

Cet article détaille le mécanisme de séparation entre le chargement des ressources et l'attachement des nœuds dans xr-frame, permettant d'attacher dynamiquement des contenus 3D sous des nœuds Block via des scripts pour réaliser la RA.

Documentation officielle

La documentation officielle explique déjà amplement comment charger des contenus 3D en temps réel. Cet article se contente de présenter brièvement les méthodes de chargement couramment utilisées dans les scénarios AR.

Chargement des ressources vs attachement des nœuds

Dans xr-frame, l'affichage d'un modèle 3D se déroule en deux étapes :

  1. Chargement des ressources : Télécharge et analyse le fichier modèle (comme .glb) depuis le réseau ou localement en mémoire. Le modèle est prêt mais invisible dans la scène.

  2. Attachement des nœuds : Crée un nœud dans l'arbre de scène et associe la ressource chargée à ce nœud. Le modèle devient alors visible sur le canevas de rendu.

Comment charger dynamiquement des contenus 3D avec du code

  1. Chargement des ressources

    Utilisez le système de gestion des ressources de la scène xr-frame pour appeler manuellement loadAsset.

    Le paramètre type indique le type de ressource, assetId est l'identifiant de la ressource après chargement, et src est l'URL de la ressource, généralement l'adresse d'un serveur d'hébergement.

    Enregistrez assetId pour l'attachement ultérieur et la libération des ressources.

    try {
    await scene.assets.loadAsset({type: 'gltf', assetId: 'panda', src: 'url/EasyARPanda.glb'});
} catch (err) {
    console.error(`Failed to load assets: ${err.message}`);
}

  2. Attachement des nœuds

    Utilisez element.addChild() pour placer le modèle chargé sous le ShadowRoot.

    const root = scene.getElementById("shadow-root");
let panda = scene.createElement(xrFrameSystem.XRGLTF,
    {
        "model": "panda",
        "anim-autoplay": ""
    }
);
root.addChild(panda);

    L'élément ShadowRoot est un nœud racine spécialement conçu par xr-frame pour la création et suppression dynamique de nœuds. Voir Nœud Shadow.

    La méthode createXRNodeFromNodeAnnotation fournie par le plugin permet de créer des sous-nœuds Block basés sur les données EMA, garantissant l'affichage correct des contenus 3D.

    const nodeAnnotation = annotation as easyar.ema.v0_5.Node;
const xrNode: xrfs.XRNode = easyarPlugin.createXRNodeFromNodeAnnotation(nodeAnnotation, blockHolder);
let panda = scene.createElement(xrFrameSystem.XRGLTF,
    {
        "model": "panda",
        "anim-autoplay": ""
    }
);
xrNode.addChild(panda);

Comment attacher du contenu sous un Block sans utiliser d'annotations

Avertissement

Cette méthode n'est valable que si vous avez vérifié que les valeurs de LocalTransform produisent l'effet de rendu attendu dans le système de coordonnées xr-frame.

Dans les autres cas, utilisez la fonction d'annotation de l'éditeur Unity.

Obtenez l'objet nœud block via getBlockById(id). Si aucun nœud block correspondant n'existe, cela signifie que le Block n'a jamais été localisé (le nœud est automatiquement créé lors de la première localisation). Vous pouvez créer un nœud pour ce Block avec holdBlock(blockInfo, blockTransformInput), ou vérifier la réussite de la localisation dans le callback avant d'attacher le contenu.

Astuce

Dans l'arborescence de scène de l'éditeur Unity, sélectionnez le nœud Block et notez son ID affiché dans l'Inspector.

BlockID dans l'éditeur Unity

Vous pouvez aussi trouver le Block ID dans la page de la bibliothèque de localisation.

BlockID dans la bibliothèque de localisation

const blockID = "aaaa1234-bbbb-cccc-dddd-eeeeee123456"
if (!blockHolder.getBlockById(blockParent.id)) {
    // Crée un nœud Block s'il n'existe pas
    blockHolder.holdBlock({
        id: blockID
    })
}
let blockElement = blockHolder.getBlockById(blockParent.id).el;

Attachez le nœud modèle au Block spécifié. Utilisez position.setArray(), quaternion.set() et scale.setArray() pour modifier le LocalTransform du nœud modèle.

export interface LocalTransform {
    /** @description Position */
    position: xrfs.Vector3;
    /** @description Rotation */
    rotation: xrfs.Quaternion;
    /** @description Échelle */
    scale: xrfs.Vector3;
}

// Suppose un LocalTransform connu sous le Block
const targetTransform: LocalTransform;

blockElement.addChild(modelNode);
let modelTransform = modelNode.getComponent(xrFrameSystem.Transform);
    modelTransform.position.setArray([
        targetTransform.position.x,
        targetTransform.position.y,
        targetTransform.position.z
    ]);
    let annoRotation = new xrFrameSystem.Quaternion().setValue(
        targetTransform.rotation.x,
        targetTransform.rotation.y,
        targetTransform.rotation.z,
        targetTransform.rotation.w
    );
    modelTransform.quaternion.set(annoRotation);
    modelTransform.scale.setArray([
        targetTransform.scale.x,
        targetTransform.scale.y,
        targetTransform.scale.z
    ]);

Types de ressources pris en charge par xr-frame

  • Texture Textures et images
  • CubeTexture Textures cubiques
  • VideoTexture Textures vidéo
  • EnvData Environnement
  • GLTF Modèles
  • Keyframe Animation d'images clés
  • Atlas Atlas

Les méthodes de chargement détaillées pour chaque ressource sont disponibles dans la documentation officielle WeChat et les exemples officiels xr-frame

Note

Formats GLTF pris en charge et extensions : voir Spécifications GLTF xr-frame