Web SDK

Добавьте AR Clip VPS на свою веб-страницу. Web SDK прямо в браузере определяет, где посетитель стоит на ваших VPS-картах, и ставить приложение не нужно.

Что нужно

API-ключ. Чтобы его получить, напишите нам через Поддержку.
ID локаций ваших карт. Он есть у каждой карты, подробнее — во Введении.
Страница на HTTPS. Браузеры дают доступ к камере и датчикам движения только защищённым страницам. localhost тоже считается защищённым.

Установка

npm install @web-ar-studio/webar-engine-sdk

Пакет опубликован в npm, типы для TypeScript в нём уже есть.

Запуск VPS

VPS работает внутри сессии отслеживания мира. Добавьте в init() поле vps и перечислите ID локаций. Сам SDK ничего не рисует, поэтому сцену выводите любым движком: three.js, Babylon.js, PlayCanvas или на чистом WebGL.

import * as THREE from "three";
import WAS, {
  PROJECT_MODE_SLAM,
  TRIGGER_MODE_SLAM,
  CAMERA_MODE_ENVIRONMENT,
  PROVIDER_8THWALL,
  EVENT_FRAME,
  EVENT_VPS_READY,
  EVENT_VPS_LOCALIZED,
  EVENT_VPS_NOT_LOCALIZED,
  EVENT_VPS_ERROR,
} from "@web-ar-studio/webar-engine-sdk";

const was = new WAS();

const { canvas, context } = await was.init({
  apiKey: "your-api-key",
  mode: PROJECT_MODE_SLAM,
  cameraMode: CAMERA_MODE_ENVIRONMENT,
  container: document.querySelector("#ar"),
  triggers: [{ id: 1, mode: TRIGGER_MODE_SLAM, source: null }],
  vps: { locationIds: ["your-location-id"] },
});

const renderer = new THREE.WebGLRenderer({ canvas, context });

was.on(EVENT_VPS_READY, () => console.log("VPS started"));
was.on(EVENT_VPS_LOCALIZED, ({ locationId, offset }) => {
  console.log("Found the place on map", locationId, offset);
});
was.on(EVENT_VPS_NOT_LOCALIZED, ({ status, statusDescription }) => {
  console.log("Not found yet:", status, statusDescription);
});
was.on(EVENT_VPS_ERROR, (message) => console.warn("VPS error:", message));

// Отслеживание и VPS запускаются вместе с колбэком кадра. Регистрируйте его по нажатию:
// WebXR и датчики движения на iPhone требуют действия пользователя.
startButton.onclick = () =>
  was.on(EVENT_FRAME, () => renderer.render(scene, camera));

Если не указать locationIds, VPS ищет место глобально, без привязки к конкретной карте. Это дольше, поэтому увеличьте requestTimeoutMs.

Передавайте vps в init()

В Chrome на Android доступ к камере для VPS выдаётся только при старте сессии. Если начать сессию без vps, включить VPS в ней позже не получится: setupVPS() выбросит VpsError.

Где работает

SDK сам выбирает на устройстве движок отслеживания (provider). По умолчанию, с "auto", он пробует сначала webxr, потом 8thwall.

Движок	Где	VPS
`webxr`	Chrome на Android	Да. SDK сам ставит сцену на карту.
`8thwall`	Браузеры без WebXR, например Safari на iPhone	Да. `offset` вы применяете сами.
`arclip-webar`	Только если выбрать его явно	Нет

Контент на карте

Расставляйте контент в координатах вашей VPS-карты. Когда VPS находит место, событие EVENT_VPS_LOCALIZED передаёт offset — сдвиг, который переносит мир отслеживания на карту.

На webxr SDK уже применил offset и плавно подвёл к нему сцену, поэтому контент карты оказывается на своём месте.
На 8thwall SDK только сообщает offset. Сложите контент карты в одну группу и при каждой локализации задавайте группе преобразование, обратное offset:

const mapRoot = new THREE.Group(); // всё, что расставлено в координатах карты
scene.add(mapRoot);

was.on(EVENT_VPS_LOCALIZED, ({ offset }) => {
  if (was.getActiveProviderId() !== PROVIDER_8THWALL) return; // webxr применяет сам
  const { position: p, orientation: q } = offset;
  new THREE.Matrix4()
    .compose(
      new THREE.Vector3(p.x, p.y, p.z),
      new THREE.Quaternion(q.x, q.y, q.z, q.w),
      new THREE.Vector3(1, 1, 1),
    )
    .invert()
    .decompose(mapRoot.position, mapRoot.quaternion, mapRoot.scale);
});

SDK принимает результат, только если совпадение достаточно надёжное, а скачок от прошлого результата человек мог бы пройти пешком. Всё остальное приходит как EVENT_VPS_NOT_LOCALIZED. Так контент не прыгает в похожих друг на друга местах, например в длинных коридорах.

События

Событие	Что приходит
`EVENT_VPS_READY`	Ничего. VPS запущен.
`EVENT_VPS_LOCALIZED`	`locationId`, `offset` (`position`, `orientation`), `trackingPosition`, `trackingRotation`, `vpsPosition`, `vpsRotation`, `timestamp`
`EVENT_VPS_NOT_LOCALIZED`	`status`, `statusDescription`, `failCount`
`EVENT_VPS_ERROR`	Текст ошибки строкой

Управление VPS

Метод	Что делает
`startVPS()`, `stopVPS()`	Возобновляет или приостанавливает локализацию
`isVPSActive()`	Сообщает, работает ли VPS
`setVPSLocationIds(ids)`	Переключает на другие карты; с пустым списком VPS ищет глобально
`setupVPS(config)`	Меняет настройки VPS во время сессии
`updateVPSSession()`	Начинает новую сессию VPS, чтобы прежние результаты больше не влияли на новые
`resetTracking()`	Сбрасывает поправку VPS и начинает заново, например после ошибочной локализации

Настройки

Все поля vps необязательные. apiKey SDK берёт из init(), повторять его не нужно.

Поле	По умолчанию	Что делает
`locationIds`	нет	Карты, с которыми сравнивается изображение с камеры. Без него VPS ищет глобально.
`captureInterval`	`2500`	Пауза между запросами локализации, мс
`requestTimeoutMs`	`20000`	Сколько ждать ответа, мс
`maxFailsCount`	`5`	Сколько промахов подряд нужно, чтобы SDK начал новую сессию VPS
`imageFormat`	`"jpeg"`	`"jpeg"` или `"webp"`. WebP выбирайте, только если ваш сервер его читает. Если браузер не умеет кодировать WebP, SDK отправит JPEG.
`jpegQuality`	`1`	Качество изображения, от 0 до 1
`targetWidth`, `targetHeight`	`540`, `960`	Размер кадра, который уходит на сервер
`minInlierRatio`, `minNumInliers`	`0.6`, `600`	Насколько надёжным должно быть совпадение, чтобы его принять
`maxJumpBaseMeters`, `maxJumpSpeedMps`	`3`, `2`	Насколько далеко новый результат может уйти от прошлого: `maxJumpBaseMeters` плюс `maxJumpSpeedMps` за каждую секунду с прошлого результата
`serverUrl`	AR Clip VPS	Другой VPS-сервер
`sendApiKeyHeader`	`true`	Отправляет ключ в заголовке `x-vps-apikey`. Отключайте, только если ваш собственный сервер не принимает этот заголовок.

Ошибки

Если VPS не может работать в этой сессии, init() или метод VPS завершится ошибкой с именем VpsError (константа VPS_ERROR). Ошибки после запуска, например неудачный запрос, приходят в EVENT_VPS_ERROR.

Ещё

В README пакета описаны остальные режимы отслеживания, якоря и полная настройка three.js.
Чтобы настроить VPS без кода, используйте VPS-сцены в AR Clip Studio.

Дальше: Поддерживаемые устройства — телефоны, браузеры и шлемы.

Что нужно​

Установка​

Запуск VPS​

Где работает​

Контент на карте​

События​

Управление VPS​

Настройки​

Ошибки​

Ещё​