Table of Contents

Come utilizzare xr-frame per caricare contenuti 3D in runtime in uno scenario AR

Questo articolo spiega in dettaglio il meccanismo di separazione tra caricamento delle risorse e montaggio dei nodi in xr-frame, consentendo il montaggio flessibile di contenuti 3D sotto nodi Block tramite script dinamici per implementare la realtà aumentata.

Documentazione ufficiale

La documentazione ufficiale contiene già spiegazioni sufficienti su come caricare contenuti 3D in runtime. Questo articolo illustrerà brevemente alcuni contenuti e metodi di caricamento comuni negli scenari AR.

Caricamento delle risorse vs montaggio dei nodi

In xr-frame, la visualizzazione di un modello 3D avviene in due fasi:

  1. Caricamento delle risorse: scaricamento e analisi del file del modello (es. .glb) dalla rete o localmente nella memoria. Il modello è pronto ma non visibile nella scena.

  2. Montaggio dei nodi: creazione di un nodo nell'albero della scena e associazione della risorsa caricata a tale nodo. Solo allora il modello apparirà nel canvas di rendering.

Come caricare dinamicamente contenuti 3D con codice

  1. Caricamento delle risorse

    Utilizzare il sistema di gestione delle risorse della scena xr-frame per chiamare loadAsset e caricare manualmente le risorse.

    Il parametro type indica il tipo di risorsa, assetId è l'id della risorsa dopo il caricamento, src è l'url della risorsa, solitamente l'indirizzo del server di hosting.

    Registrare assetId per il successivo montaggio e rilascio delle risorse.

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

  2. Montaggio dei nodi

    Utilizzare element.addChild() per posizionare il modello caricato sotto ShadowRoot.

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

    L'elemento ShadowRoot è un nodo radice specifico di xr-frame per prevenire la creazione e rimozione dinamica di nodi. Vedi Nodo Shadow.

    Il metodo createXRNodeFromNodeAnnotation fornito dall'oggetto plugin consente di creare nodi figli di Block in base ai dati EMA, garantendo la corretta posizione spaziale dei contenuti 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);

Come montare contenuti sotto Block senza utilizzare annotazioni

Avvertenza

Prerequisito per questo metodo è aver verificato che i valori di LocalTransform producano l'effetto di rendering desiderato nel sistema di coordinate di xr-frame.

In altri casi, utilizzare la funzionalità di annotazione dell'editor Unity.

Ottenere l'oggetto nodo block nell'albero della scena tramite getBlockById(id). Se non esiste, significa che il Block non è mai stato localizzato con successo (il nodo viene creato automaticamente alla prima localizzazione). È possibile creare un nodo per quel Block con holdBlock(blockInfo, blockTransformInput) o attendere la conferma di localizzazione nella callback prima di montare i contenuti.

Consiglio

Nell'albero della scena dell'editor Unity, selezionare il nodo Block e annotare l'ID mostrato nel pannello Inspector.

BlockID nell'editor Unity

L'ID Block è consultabile anche nella pagina della libredia di localizzazione cloud.

BlockID nella libreria di localizzazione

const blockID = "aaaa1234-bbbb-cccc-dddd-eeeeee123456"
if (!blockHolder.getBlockById(blockParent.id)) {
    // Nessun nodo Block esistente, crearne uno
    blockHolder.holdBlock({
        id: blockID
    })
}
let blockElement = blockHolder.getBlockById(blockParent.id).el;

Montare il nodo del modello sotto il Block specificato, utilizzando position.setArray(), quaternion.set() e scale.setArray() per modificare il LocalTransform del nodo modello.

export interface LocalTransform {
    /** @description Posizione */
    position: xrfs.Vector3;
    /** @description Rotazione */
    rotation: xrfs.Quaternion;
    /** @description Scala */
    scale: xrfs.Vector3;
}

// Supponendo un LocalTransform noto sotto il 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
    ]);

Tipi di risorse supportati da xr-frame

  • Texture: texture e immagini
  • CubeTexture: texture cubiche
  • VideoTexture: texture video
  • EnvData: ambiente
  • GLTF: modelli
  • Keyframe: animazione keyframe
  • Atlas: atlanti

I dettagli per ogni tipo di risorsa sono disponibili nella documentazione ufficiale WeChat e nelle demo ufficiali xr-frame

Nota

Per i formati GLTF supportati e le estensioni, consultare la specifica GLTF di xr-frame