Table of Contents

Cómo cargar contenido 3D en una scene AR en runtime con xr-frame

Este artículo explica en detalle el mecanismo de separación entre resource loading y node mounting en xr-frame. Mediante scripts dinámicos, el contenido 3D puede montarse de forma flexible bajo nodos Block para realizar AR.

Recursos oficiales

Los recursos oficiales ya contienen suficiente explicación sobre cómo cargar contenido 3D en runtime. Este artículo solo describe brevemente algunos contenidos y métodos de carga comunes en scenes AR.

Resource loading vs node mounting

En xr-frame, mostrar un modelo 3D se divide en dos etapas:

  1. Resource loading: descargar un archivo de modelo (por ejemplo .glb) desde la red o localmente, y analizarlo en memoria. En este momento el modelo está listo, pero no es visible en la scene.

  2. Node mounting: crear un node en el scene tree y asociar el resource cargado a ese node. Solo entonces el modelo aparece oficialmente en el rendering canvas.

Cómo cargar dinámicamente contenido 3D con código

  1. Resource loading

    Cargue manualmente resources llamando a loadAsset mediante el sistema de gestión de resources de la scene xr-frame.

    El parámetro type indica el tipo de resource, assetId indica el id del resource después de la carga, y src indica la url del resource, normalmente la dirección del servidor de hosting de resources.

    Debe registrar assetId para el mounting posterior y la liberación de resources.

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

  2. Node mounting

    Use element.addChild() para colocar el modelo cargado bajo ShadowRoot.

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

    El elemento ShadowRoot es el root node que xr-frame usa especialmente para evitar la creación y eliminación dinámicas de nodes. Consulte Shadow node para más detalles.

    El método createXRNodeFromNodeAnnotation proporcionado por el plugin object permite crear child nodes de Block según datos EMA, garantizando que el contenido 3D se muestre en la posición espacial correcta.

    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);

Cómo montar contenido directamente bajo Block sin usar annotation

Advertencia

El requisito previo para usar este método es que haya verificado que el valor LocalTransform puede lograr el efecto de rendering esperado en el sistema de coordenadas de xr-frame.

Para otros casos, use la función annotation del Unity Editor.

Obtenga el object node block del scene tree mediante getBlockById(id). Si no existe el block node correspondiente, significa que la localization de este Block aún no ha tenido éxito (el node se creará automáticamente la primera vez que se localice este Block). Puede usar holdBlock(blockInfo, blockTransformInput) para crear un node de este Block, o determinar en el localization callback que la localization de este Block tuvo éxito antes de montar contenido.

Consejo

Seleccione node Block en el scene tree del Unity Editor y registre el ID mostrado en el panel Inspector

BlockID en Unity Editor

También puede encontrar Block ID en la página de cloud localization library

BlockID en localization library

const blockID = "aaaa1234-bbbb-cccc-dddd-eeeeee123456"
if (!blockHolder.getBlockById(blockParent.id)) {
    // no existe ningun nodo Block; crea uno
    blockHolder.holdBlock({
        id: blockID
    })
}
let blockElement = blockHolder.getBlockById(blockParent.id).el;

Monte el model node bajo el Block especificado, y use position.setArray(), quaternion.set() y scale.setArray() para modificar el LocalTransform del model node.

export interface LocalTransform {
    /** @description posicion */
    position: xrfs.Vector3;
    /** @description rotacion */
    rotation: xrfs.Quaternion;
    /** @description Scale */
    scale: xrfs.Vector3;
}

// supone que hay un LocalTransform conocido bajo 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
    ]);

Tipos de resources soportados por xr-frame

  • Texture, texturas e imágenes
  • CubeTexture, texturas cúbicas
  • VideoTexture, texturas de video
  • EnvData, environment
  • GLTF models
  • Keyframe, frame animation
  • Atlas

Los métodos detallados de carga de cada resource se encuentran en la documentación oficial de WeChat y los ejemplos oficiales de xr-frame

Nota

Para formatos GLTF soportados y extensions, consulte las instrucciones oficiales de uso de GLTF de xr-frame