WebAR FácilAbrir ejemploEnglish

Integración con Three.js

Guía avanzada para una aplicación que ya necesita código Three.js o un renderer propio. Para imagen/GLB y SLAM básicos utiliza HTML declarativo, que ya configura estas clases. No crees otro renderer sobre una escena declarativa.

Escena gestionada

const app=new ThreeARScene({
  container:document.querySelector('#view'),
  maxPixelRatio:2,
  lighting:true,
  engineOptions:{opencvURL:new URL('./vision/opencv.js',document.baseURI)},
});
const model=new ThreeARModel();
app.addContent('poster',model);
await model.load('./modelo.glb');
await app.engine.startCamera();
await app.engine.addImageTarget('poster','./poster.png');

En TypeScript valida que querySelector devuelve un HTMLElement antes de pasarlo al constructor. El ejemplo es un fragmento para insertar después de importar las clases. El HTML completo está en integración programática.

app.engine, app.scene, app.camera y app.renderer son públicos. getAnchor(id) devuelve un ThreeARGroup enlazado a ese ID. addContent(id,object) añade contenido y registra modelos/vídeos para su gestión; removeContent(object) lo separa sin destruirlo. onRender(callback) ejecuta lógica independiente del tracker y devuelve una función de retirada.

const {THREE}=WebARFacil; // Con standalone; en ESM: import * as THREE from 'three'.
const box=new THREE.Mesh(new THREE.BoxGeometry(.05,.05,.05),new THREE.MeshNormalMaterial());
box.position.y=.025;
app.addContent('poster',box);
const off=app.onRender(dt=>{box.rotation.y+=dt;});
// Al retirar contenido de creación propia:
off();app.removeContent(box);box.geometry.dispose();box.material.dispose();

ThreeARScene.dispose() libera sus modelos y vídeos registrados, pero los recursos de mallas propias pertenecen a la aplicación. No instales un segundo setAnimationLoop en su renderer: usa onRender.

Renderer existente

Ejemplo 29 · Three.js con renderer propio muestra un GLB animado sobre un marcador con la cámara, la proyección y el bucle de render controlados desde JavaScript.

Usa WebAREngine, ThreeARGroup y ThreeCameraBackground. custom-app.html es una aplicación completa con control manual del viewport, fondo, matrices, animación y limpieza.

const tracked=new ThreeARGroup().bind(engine,'poster');
scene.add(tracked);
camera.matrixAutoUpdate=false;
const offPose=engine.onPose((_matrix,pose)=>{
  if(pose.backend==='webxr') return; // En XR el renderer XR controla las cámaras.
  camera.matrix.fromArray(pose.viewMatrix).invert();
  camera.updateMatrixWorld(true);
  if(pose.projectionMatrix){
    camera.projectionMatrix.fromArray(pose.projectionMatrix);
    camera.projectionMatrixInverse.copy(camera.projectionMatrix).invert();
  }
});

bind sincroniza worldMatrix, visibilidad, tolerancia y estado del motor. unbind() retira los listeners. dispose() desuscribe el grupo, pero no destruye sus hijos. update(matrix,pose?) permite integración manual: con metadata usa la matriz de mundo; sin metadata solo dispones de ModelView y debes mantener la cámara identidad.

El fondo y la proyección deben representar el mismo recorte/aspecto del vídeo. No estires el feed con CSS mientras mantienes otra proyección. ThreeARScene hace letterbox con la proporción de la cámara. ThreeCameraBackground permite rectificación cuando se proporciona calibración con distorsión; no exige un proceso manual para tracking normal.

XR y fallos de contexto

El wrapper gestionado configura el renderer XR. Un renderer propio debe suministrar attachXRSession, getXRContext y su bucle XR antes de usar el backend nativo. No dibujes el vídeo getUserMedia como fondo durante una sesión inmersiva: el compositor XR aporta la cámara real.

Al perderse el contexto WebGL, ThreeARScene detiene el motor. Tras restaurarlo vuelve el render, pero tu aplicación debe permitir reiniciar cámara y cargar targets otra vez. No se oculta este fallo con una pose artificial.

Apoya WebAR Fácil