Открытие подготовленной AR-сессии by_scan

Результат

Результат: интеграционная система создаёт ограниченную по времени AR-сессию с моделью, параметрами выравнивания и настройками интерфейса. Пользователь открывает её в GIP VISION на iOS по PIN или глубокой ссылке.

Кому и платформа

  • Разработчику интеграции и BIM-инженеру, который готовит модель и данные выравнивания.

  • Пользовательская часть выполняется только в приложении GIP VISION на iOS.

  • Это технический API-сценарий, а не отдельная кнопка Разместить по скану в обычном меню приложения.

Перед началом

  • Получите X-API-Key или Bearer-токен с доступом к публичному API GIP VISION.

  • Подготовьте один файл GLB, IFC или USDZ либо набор файлов GLB/IFC в пределах ограничений API.

  • Подготовьте ровно один вариант выравнивания:

    • две точки point_1 и point_2; или

    • четыре угла проёма corners и нормаль стены wall_normal.

  • Для точек и углов используйте три координаты [x, y, z] в метрах. Если исходные данные имеют ось Z вверх, явно передайте coordinate_system: z-up; по умолчанию используется y-up.

  • На iPhone или iPad должно быть установлено актуальное приложение GIP VISION, разрешён доступ к камере и доступен интернет.

Быстрый маршрут

POST /api/gip-vision/v1/session/by_scan/ → получить PIN, глубокую ссылку и expires_at → дождаться готовности → открыть на iOS → выполнить выравнивание по подсказкам

Пошагово

  1. Отправьте авторизованный POST на /api/gip-vision/v1/session/by_scan/.

  2. Передайте model_file либо model_files, но не оба поля одновременно.

  3. Передайте объект alignment только в одном из поддерживаемых вариантов: пара точек либо проём с нормалью стены.

  4. При необходимости добавьте параметры конвертации, AR и ui.presentation. Не привязывайте пользовательскую инструкцию к необязательным кнопкам: интеграция может скрывать и показывать элементы интерфейса.

  5. Сохраните PIN, глубокую ссылку и expires_at из ответа. Сессия действует до 24 часов.

  6. Дождитесь готовности серверных материалов. Не отправляйте PIN пользователю, пока подготовка не завершена.

  7. На iOS откройте сессию по глубокой ссылке либо через PIN → PIN-код → Открыть модель.

  8. Приложение загрузит модель, выравнивание и настройки интерфейса сессии. Выполните предлагаемый приложением захват помещения или привязку к проёму.

  9. Завершите выравнивание и проверьте модель минимум по двум независимым ориентирам.

by_scan не распознаёт произвольное помещение без исходных данных. Сервер требует заранее подготовленное выравнивание, а фактический экран зависит от переданных параметров сессии. Для обычного пользователя, который размещает модель по сохранённому дверному проёму, используйте отдельный сценарий По двери.

Контроль результата

  • API принял модель и только один полный набор параметров выравнивания.

  • Сессия перешла в состояние готовности до передачи ссылки или PIN пользователю.

  • Глубокая ссылка либо шестизначный PIN открывает нужную сессию на iOS.

  • В приложении применились ожидаемые параметры модели и интерфейса.

  • После выравнивания модель совпадает с выбранным проёмом или контрольными точками.

Если не получается

  • Ответ 400 по выравниванию — передайте либо обе точки, либо одновременно четыре угла и нормаль стены. Не смешивайте два способа.

  • Файл отклонён — проверьте поддерживаемый формат, размер и ограничения модели.

  • Ответ 401 или 403 — проверьте X-API-Key, Bearer-токен и выданные интеграции права.

  • PIN не открывается — убедитесь, что это шесть цифр, сессия готова и не истекли 24 часа.

  • Ссылка не открывает приложение — проверьте установку актуальной iOS-версии и полный формат глубокой ссылки.

  • Набор кнопок отличается от тестового — сравните переданный ui.presentation; интерфейс сессии может быть переопределён интеграцией.

  • Модель смещена — перепроверьте единицы, порядок точек, направление wall_normal и выбранную систему координат.

Связанные материалы