🛣️ Landing board heatmap generation

🛣️ Генерация тепловых карт летка

🎯 Назначение

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

🎭 Пользовательская история

Как пчеловод, заинтересованный в оптимизации входа улья,
я хочу открыть раздел Entrance Observer в деталях улья и переключиться с live view или записей на тепловые карты,
чтобы по умолчанию сравнивать последний день и переходить к предыдущим дням при расследовании узких мест в трафике.

🚀 Ключевые преимущества

Оптимизация трафика: выявление перегруженных зон и потенциальных улучшений
Инсайты по конструкции входа: подход к модификации летка на основе данных
Долгосрочный анализ поведения: понимание сезонных и суточных паттернов
Ценность для исследований: визуальные данные для изучения поведения пчёл у входа

🔧 Технический обзор

Вычисление тепловых карт выполняется в gate-video-stream, а не на edge-устройстве entrance-observer.

entrance-observer по-прежнему детектирует пчёл и ведёт локальную суточную JSONL-историю треков для отладки. После каждого анализа он также отправляет отслеживаемые координаты в gate-video-stream с ID корпуса, временной меткой, размерами кадра и trackHistory. gate-video-stream агрегирует эти траектории в высокоразрешающую разреженную пиксельную сетку на пользователя, корпус и день, рендерит суточную PNG тепловую карту в исходном разрешении кадра, сохраняет её в том же паттерне object-storage, что и видеозаписи, и отдаёт в веб-приложение через GraphQL.

📋 Критерии приёмки

entrance-observer загружает payload траекторий в video stream service после анализа трекинга
gate-video-stream вычисляет и сохраняет одну накопительную тепловую карту на вход и день
Сохранённые тепловые карты адресуются по URL аналогично видео-активам
В веб-приложении Hive details > Entrance Observer три вкладки: live view, записи и тепловые карты
Вкладка тепловых карт по умолчанию показывает последний доступный день
Элементы управления «предыдущий день», «следующий день» и «последний» позволяют навигировать по историческим картам
Отсутствующие дни показывают пустое состояние вместо ошибки

🚫 Вне области

3D-визуализация или анализ глубины
Корреляция с погодой и паттернами трафика
Автоматические рекомендации по конструкции летка
Замена сырых видеозаписей тепловыми картами

🏗️ Подход к реализации

Входные данные: массивы координат track history, сгенерированные на edge, по ID трека
Транспорт: аутентифицированная REST-загрузка из entrance-observer в gate-video-stream
Обработка: серверное суточное накопление по пикселям с логарифмическим визуальным масштабированием, сохраняющее детали вроде задержки в углах и трафика у краёв
Визуализация: высокоразрешающая PNG тепловая карта, генерируемая gate-video-stream
Хранение: object storage в пространстве имён пользователя и камеры входа, плюс строка индекса MySQL для навигации по дням
Веб-приложение: GraphQL-запрос entranceHeatmaps питает вкладку тепловых карт в деталях улья

📊 Метрики успеха

Корректная обработка координат в границах кадра (0 <= x < width, 0 <= y < height)
Суточная тепловая карта генерируется из загруженных пакетов траекторий
Правильная нормализация и цветовое отображение для визуальной интерпретации
Веб-приложение может открыть последнюю доступную тепловую карту без знания даты заранее
Историческая навигация работает по дням с картами и без них

💳 Доступность

Тепловые карты летка включены в Professional plan как часть аналитики Entrance Observer.

🔗 Связанные функции

📚 Ресурсы и ссылки

💬 Заметки

Старый локальный скрипт heatmap_generator.py остаётся полезным для офлайн-отладки и backfill. Продакшен-тепловые карты генерируются централизованно как высокоразрешающие PNG, чтобы веб-приложение могло показывать их рядом с live-стримами и сохранёнными видеозаписями без потери деталей летка.