Instalación y distribución

HTML directo: opción recomendada

Sigue inicio con HTML. Copia solo webar-facil.min.js y úsalo con webar-scene, webar-target y webar-model. El archivo compilado incluye OpenCV/WASM, Workers, Draco, Meshopt y Three.js.

El paquete npm se llama webar-facil. En código nuevo, usa WebARFacil al cargar el script clásico. Los scripts clásicos también conservan el alias anterior MiLibreriaAR para integraciones existentes que ya lo usan.

Si alojas el SDK en otro dominio HTTPS, apunta el script a ese servidor. En la capa declarativa OpenCV/Draco se localizan junto al script, mientras las URLs de imagen/modelo se interpretan respecto al HTML. El servidor de recursos debe permitir CORS; referencia declarativa y despliegue detallan rutas y actualización de caché. La biblioteca no publica por sí sola una URL CDN.

Formatos disponibles

Para HTML directo se recomienda standalone. No mezcles accidentalmente dos copias de Three.js: si usas ese archivo, crea tus objetos con WebARFacil.THREE. El IIFE sin Three se reserva a aplicaciones que ya suministran un global compatible.

El standalone registra automáticamente las etiquetas de HTML declarativo y usa sus recursos integrados. Las opciones explícitas de URL y directorio siguen disponibles para proyectos que quieran servir sus propios recursos.

Consumir con NPM y Vite

Esta alternativa es para aplicaciones con bundler. Si quieres mantener las etiquetas, importa registerARComponents y regístralas una vez con assetBase apuntando a una copia estática de la distribución. Los imports de ThreeARScene de abajo se reservan para control programático.

import {registerARComponents} from 'webar-facil';
registerARComponents({assetBase:new URL('/vendor/webar/',location.href)});

La existencia del paquete local no significa que esté publicado en el registro NPM. Para instalar tu propia distribución:

# En este repositorio, después de npm ci:
npm run build
npm pack

# En la aplicación consumidora; ajusta la ruta real del tarball:
npm install /ruta/webar-facil-0.1.0.tgz three
npm install --save-dev @types/three

import {ThreeARScene, ThreeARModel} from 'webar-facil';
import {WebAREngine} from 'webar-facil/core';

Son ejemplos de importaciones alternativas; no necesitas crear dos motores. La distribución validada utiliza Three.js 0.180. La declaración de peers admite >=0.170.0 <1, sin afirmar que cada versión intermedia esté certificada.

Para el ejemplo declarativo con assetBase: '/vendor/webar/', copia el contenido completo de node_modules/webar-facil/dist/ a public/vendor/webar/ de tu app. No basta con escribir el import: Vite no copia automáticamente esos recursos auxiliares.

En una integración programática con los defaults relativos al documento, puedes copiar dist/vision/ y dist/decoders/ a public/vision/ y public/decoders/, o configurar sus URLs explícitamente. Los Workers se resuelven respecto al bundle de la biblioteca; conserva dist/workers/ al distribuir los bundles sin transformación. Si tu bundler reubica el JS y no copia sus referencias de Worker, sirve la distribución completa como recursos estáticos e impórtala desde allí, o configura explícitamente el copiado.

ESM sin empaquetador

Integración avanzada. Para una app HTML básica usa el standalone, que evita este importmap y la construcción manual de escena.

En un sitio cuya carpeta raíz contiene el contenido de dist/:

<script type="importmap">
{"imports":{"three":"./vendor/three.module.js"}}
</script>
<script type="module">
  import {ThreeARScene} from './webar-facil.js';
  const app=new ThreeARScene({container:document.querySelector('#view')});
</script>

El contenedor #view debe existir y tener altura. Los ejemplos ESM del repositorio usan las rutas adecuadas a su subcarpeta. No uses require() para estos exports ESM.

Recursos y licencias

vision/opencv.js contiene el runtime OpenCV/WASM de esta distribución; conserva su archivo de licencias. Draco necesita draco_wasm_wrapper.js y draco_decoder.wasm en la ruta configurada; se distribuye también el decoder JS. Meshopt está integrado en el cargador. No hace falta un servicio remoto de compilación ni de tracking.

Al redistribuir conserva LICENSE, THIRD_PARTY_NOTICES.md y los avisos de vision/, decoders/ y vendor/. Los modelos y marcadores del ejemplo pueden sustituirse sin cambiar la API.