WebAREngine

Referencia práctica. Las firmas completas y tipos de opciones están en API generada.

Esta es la API programática avanzada. Para aplicaciones básicas empieza con HTML declarativo. Una escena HTML expone su motor como scene.engine tras ar-ready, sin que debas construirlo. Recuerda que el motor se reemplaza al parar/reiniciar la escena declarativa.

const engine=new WebAREngine({
  opencvURL:new URL('./vision/opencv.js',document.baseURI),
  imageLossGraceMs:500,
  keepContentOnLost:false,
  imageSmoothingMs:65,
  camera:{width:1280,height:720,fps:60,maxFrameWidth:640},
});

Opciones principales

Opción	Valor inicial / contrato
`opencvURL`	`./vision/opencv.js`, relativo a `document.baseURI`; configurar si el HTML está en subcarpeta
`camera`	Opciones de `CameraManager` salvo callbacks `onFrame` y `onError`
`tracker`	Opciones de `Tracker`
`imageLossGraceMs`	500 ms; entre 0 y 10000; 0 confirma pérdida inmediatamente
`keepContentOnLost`	`false`; permite conservar visualmente la última transformación
`imageSmoothingMs`	65 ms; entre 0 y 500; 0 desactiva filtrado temporal
`calibration`	Intrínsecos opcionales; no se exigen para uso normal
`fallback`	Opciones de odometría o `false`; por defecto se usa el backend incluido
`keyframeCorrection`	false; corrección local experimental, no cierre de bucle global
`attachXRSession`, `getXRContext`, `overlayRoot`	Hooks para integrar XR con un renderer propio

ThreeARScene conecta los hooks XR automáticamente. El núcleo sin renderer requiere que la aplicación los suministre para WebXR. Si proporcionas opciones explícitas de fallback respeta el contrato OpticalFlowOptions, incluidos intrinsics y floorROI; no son simples flags de calidad.

Ciclo de vida y targets

Método	Resultado y comportamiento
`startCamera()`	`Promise<void>`; abre la cámara
`loadImageTarget(source, options?)`	Compila JPG/PNG y reemplaza todos los targets por `default`
`addImageTarget(id, source, options?)`	Compila y añade/reemplaza solo ese ID
`loadTarget(url)`	Carga `.dat` y reemplaza todos por `default`
`addTarget(id, url)`	Añade/reemplaza un `.dat` por ID
`removeTarget(id)`	Elimina tracking y visibilidad de ese target
`setKeepContentOnLost(enabled, targetId?)`	Cambia política global o de un target existente
`setFocus(mode, distance?)`	`Promise<boolean>`; `false` si no existe soporte
`stop()`	`Promise<void>`; cierra sesión y elimina targets; instancia reutilizable
`dispose()`	`void`; liberación definitiva

source acepta Blob/File, string URL o URL. ImageTargetOptions tiene physicalWidthMeters (por defecto 0.2) y maxDimension (por defecto 1024). Los métodos de imagen devuelven {buffer, metadata}. El JSON no es un argumento requerido del tracker.

Los IDs deben cumplir ^[a-zA-Z0-9_-]{1,64}$. Se admiten hasta 8. Espera las operaciones de configuración en orden; si ejecutas startCamera(), carga, retirada o transición simultáneamente, el motor puede rechazar la operación concurrente.

await engine.startCamera();
const result=await engine.addImageTarget('producto','./producto.jpg',{
  physicalWidthMeters:0.15,
});
console.log(result.metadata.quality);
// No usar Promise.all para estas operaciones de configuración del motor.

Propiedades de consulta

state, videoElement, cameraSettings, calibration y targetIds son de lectura. targetIds permite comprobar qué IDs están registrados; no es una lista de marcadores visibles. cameraSettings puede ser null sin captura activa.

Observación y eventos

const unsubscribe=engine.onPose((matrix,pose)=>{
  // matrix === pose.matrix; usar el contrato completo si la cámara se mueve.
  console.log(pose.targetId,pose.backend,pose.scale);
});
const unsubscribeError=engine.onError(error=>console.error(error));
// Al abandonar esta pantalla:
unsubscribe();unsubscribeError();

onStatus(listener), onSurface(listener) y onMetrics(listener) también devuelven una función de retirada. onSurface recibe una matriz de la superficie propuesta; no implica que un objeto ya esté colocado.

on(name,listener) acepta únicamente targetFound, targetLost, trackingQuality y targetVisibility; existen los atajos onTargetFound, onTargetLost, onTrackingQuality y onTargetVisibility. No existe un evento genérico pose en on: usa onPose. Las cadenas de onStatus son diagnósticos abiertos; no sustituyen los eventos tipados de detección.

Seguimiento espacial

enableSLAM(options?) devuelve Promise<SurfaceTransitionResult>. Opciones: targetId, backend: 'auto' | 'webxr' | 'optical-flow', placement: 'auto' | 'preserve' | 'hit-test', initializationTimeoutMs (12000 por defecto, >0 y <=120000).

Resultados backend: 'webxr' | 'optical-flow' y placement: 'preserved' | 'scan-marker' | 'select-surface' | 'scan-floor'. Solo preserved confirma continuidad ya conseguida. Lee transiciones y límites antes de conectar el botón.

exportSLAMMap() e importSLAMMap(snapshot) operan sobre la odometría activa; consulta persistencia. No existe un método público del motor llamado switchToSLAM: esa función pertenece a la clase avanzada SLAMManager, con otro contrato.