Как нанести надирную подпись на сферическую панораму

Русский · English · Español · Français · Deutsch

Сферические панорамы формата 360° обычно хранятся как обычные JPEG-файлы с эквиректангулярной проекцией и соотношением сторон 2:1. Верх изображения соответствует зениту, середина — горизонту, а нижняя граница — надиру, то есть точке строго под камерой.

После съёмки именно в надире часто остаётся штатив, тень фотографа или плохо сшитый участок. Его можно закрыть круглой плашкой с названием компании, адресом сайта или логотипом. Однако простое наложение круга внизу прямоугольного JPEG не подходит: при просмотре панорамы такое изображение сильно исказится. Нужна обратная проекция, учитывающая геометрию сферы.

В этой статье разберём веб-приложение «Надирная подпись для панорам». Оно загружает сферический JPG, показывает интерактивный просмотр 360°, корректно проецирует круглую подпись в нижнюю часть сферы и сохраняет новый JPEG. Вся обработка выполняется локально в браузере — исходная панорама не отправляется на сервер.

Возможности приложения

  • загрузка JPG или JPEG перетаскиванием либо через диалог выбора файла;
  • проверка максимального размера файла и пропорции панорамы 2:1;
  • текстовая подпись длиной до 60 символов;
  • настройка цвета, прозрачности и углового радиуса плашки;
  • интерактивный WebGL-просмотр панорамы;
  • вращение мышью или пальцем и изменение поля зрения колёсиком;
  • быстрый переход взглядом к надиру;
  • обработка изображения в исходном разрешении;
  • сохранение EXIF, GPS, XMP, IPTC и комментариев JPEG;
  • скачивание результата с суффиксом _nadir.jpg.

Почему надир выглядит необычно на исходном JPEG

В эквиректангулярной проекции горизонтальная координата задаёт долготу, а вертикальная — широту сферы. Полный оборот на 360° занимает всю ширину изображения, а диапазон от зенита до надира в 180° — всю высоту.

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

Для пикселя исходной панорамы используются сферические координаты:

longitude = x / width × 2π − π
latitude  = π/2 − y / height × π

В нижней части изображения вычисляется угловое расстояние до надира. Если оно меньше выбранного радиуса, пикселю сопоставляется точка круглой плашки.

Архитектура проекта

Приложение написано на React и TypeScript. Интерфейс находится в app/page.tsx, стили — в app/globals.css, а метаданные страницы — в app/layout.tsx.

Основная логика разделена на четыре части:

  1. загрузка и проверка JPEG;
  2. создание круглой плашки с текстом;
  3. интерактивный WebGL-предпросмотр;
  4. финальное наложение на полном разрешении через Canvas 2D.

Серверная база данных приложению не нужна. После загрузки страницы операции с фотографией выполняются API браузера.

Загрузка и проверка панорамы

Приложение принимает файлы с MIME-типом image/jpeg или расширением .jpg/.jpeg. Затем файл читается через arrayBuffer(), а его размеры определяются с помощью createImageBitmap().

Проверяется отношение ширины к высоте:

abs(width / height − 2) ≤ 0,035

Небольшой допуск позволяет принимать панорамы, которые отличаются от идеальных 2:1 на несколько пикселей. Ограничение интерфейса — 250 МБ на файл. Реальный предел также зависит от объёма памяти, реализации Canvas и максимального размера текстуры WebGL в конкретном браузере.

Формирование плашки

Функция makeBadge() создаёт квадратный Canvas размером 1800 × 1800 пикселей. В нём рисуются:

  • круг выбранного цвета и прозрачности;
  • белая обводка;
  • белый текст по центру.

Размер шрифта уменьшается от 280 до 60 пикселей, пока строка не поместится в 80% ширины круга. Благодаря этому короткий адрес отображается крупно, а длинная подпись автоматически масштабируется.

Интерактивный просмотр через WebGL

Предпросмотр не изменяет исходный JPEG. Он использует две текстуры:

  • панораму;
  • созданную плашку.

Вершинный шейдер выводит два треугольника на весь Canvas. Фрагментный шейдер для каждого пикселя экрана строит луч виртуальной камеры, применяет поворот по горизонтали и вертикали, а затем переводит направление луча в координаты эквиректангулярной текстуры.

Если направление попадает внутрь заданного углового радиуса от надира, шейдер вычисляет координаты соответствующего пикселя плашки и смешивает его с панорамой с учётом альфа-канала.

Такой подход удобен для просмотра: GPU быстро пересчитывает картинку при вращении и масштабировании. Если панорама превышает MAX_TEXTURE_SIZE видеоустройства, для предпросмотра создаётся уменьшенная копия. Это не уменьшает итоговый файл — финальная обработка отдельно выполняется в исходном разрешении.

Финальная обработка через Canvas 2D

После нажатия «Нанести и скачать JPG» приложение создаёт Canvas размером с исходную панораму и копирует в него фотографию. Обрабатывается не весь кадр, а только нижняя полоса, в которой физически может находиться надирная плашка:

stripHeight ≈ imageHeight × radius / 180

Для каждой горизонтальной координаты заранее вычисляются синус и косинус долготы. Это устраняет повторные тригонометрические вычисления внутри основного цикла.

Для каждого пикселя нижней полосы алгоритм:

  1. находит угловое расстояние до надира;
  2. пропускает пиксели за пределами выбранного радиуса;
  3. переводит сферическое расстояние в радиальную координату плашки через отношение тангенсов;
  4. находит пиксель плашки;
  5. смешивает RGB-каналы изображения и плашки по альфа-каналу.

Периодический setTimeout(..., 0) возвращает управление циклу событий браузера. Благодаря этому интерфейс может обновлять индикатор прогресса и не выглядит полностью зависшим во время обработки большого изображения.

Сохранение метаданных JPEG

Обычный вызов canvas.toBlob("image/jpeg") перекодирует изображение, но теряет исходные метаданные. Поэтому перед обработкой приложение читает структуру JPEG и сохраняет сегменты:

  • APP1 — обычно EXIF и XMP;
  • APP2 — расширенные профили и служебные данные;
  • APP13 — IPTC/Photoshop metadata;
  • COM — комментарии JPEG.

После кодирования результата сохранённые сегменты вставляются сразу после маркера SOI FF D8. В результате EXIF, GPS и XMP переносятся в готовый файл.

Нужно учитывать, что это аккуратный перенос исходных блоков, а не полноценный редактор метаданных. Размеры изображения внутри некоторых редких нестандартных полей могут остаться прежними, хотя в данном приложении ширина и высота результата обычно совпадают с оригиналом.

Конфиденциальность

Фотография обрабатывается локально. File, ImageBitmap, Canvas, WebGL и объектный URL существуют только в браузере пользователя. В коде нет отправки изображения через fetch, формы или серверный API.

Это особенно важно для панорам с GPS-координатами: метаданные не передаются приложению на сервер, но сохраняются в скачанном результате. Если готовый файл планируется публиковать, GPS при необходимости следует удалить отдельным инструментом.

Запуск проекта локально

Потребуется Node.js версии 22.13 или новее.

npm ci
npm run dev

После запуска нужно открыть адрес, указанный Vite в терминале. Для проверки production-сборки:

npm run build
npm run start

Дополнительные команды:

npm test
npm run lint

Подробности находятся в файле INSTALL.md, приложенном к архиву.

Практические ограничения

  • Поддерживается только JPEG, PNG и TIFF не принимаются.
  • Требуется полноценная сферическая панорама приблизительно 2:1.
  • Итоговый JPEG перекодируется с качеством 0,95, поэтому побитовой идентичности с оригиналом не будет.
  • Очень крупные изображения требуют много оперативной памяти: Canvas хранит несжатые пиксели, а 20 000 × 10 000 RGBA занимает около 800 МБ только для одного буфера.
  • Во время обработки мобильный браузер может закрыть вкладку из-за нехватки памяти.
  • Текст рисуется системным шрифтом Arial/Helvetica; отдельная загрузка фирменных шрифтов не реализована.

Возможные улучшения

Проект можно расширить загрузкой прозрачного логотипа, выбором шрифта, обработкой в Web Worker, плиточной обработкой больших файлов и экспортом без повторного JPEG-сжатия. Для профессионального применения полезны настройка толщины обводки, предварительные шаблоны и удаление GPS по отдельному переключателю.

Уже в текущем виде приложение решает основную задачу: позволяет без установки настольного редактора добавить корректную подпись в надир сферической панорамы, проверить результат в интерактивном просмотрщике и скачать готовый JPG, не передавая фотографию стороннему серверу.