diff --git a/docs/assets/duocam/duocam.png b/docs/assets/duocam/duocam.png new file mode 100644 index 000000000..02d28d0ea Binary files /dev/null and b/docs/assets/duocam/duocam.png differ diff --git a/docs/assets/duocam/gitup_seek.jpg b/docs/assets/duocam/gitup_seek.jpg new file mode 100644 index 000000000..27a7c21a5 Binary files /dev/null and b/docs/assets/duocam/gitup_seek.jpg differ diff --git a/docs/assets/duocam/qgc_duocam_widget.png b/docs/assets/duocam/qgc_duocam_widget.png new file mode 100644 index 000000000..7f1e6324e Binary files /dev/null and b/docs/assets/duocam/qgc_duocam_widget.png differ diff --git a/docs/ru/SUMMARY.md b/docs/ru/SUMMARY.md index 10f3192d8..33a510596 100644 --- a/docs/ru/SUMMARY.md +++ b/docs/ru/SUMMARY.md @@ -91,6 +91,8 @@ * [Светодиодная лента (legacy)](leds_old.md) * [Вклад в Клевер](contributing.md) * [Переход на версию 0.20](migrate20.md) + * [COEX Duocam](duocam.md) + * [Виртуальная MAVLink-камера](duocam_mavlink.md) * [Мероприятия](events.md) * [CopterHack-2021](copterhack2021.md) * [CopterHack-2019](copterhack2019.md) diff --git a/docs/ru/duocam.md b/docs/ru/duocam.md new file mode 100644 index 000000000..d76699e23 --- /dev/null +++ b/docs/ru/duocam.md @@ -0,0 +1,197 @@ +# COEX DuoCam + +"COEX DuoCam" – это программно-аппаратный комплекс, позволяющий получать комбинированное визуально-тепловизионное изображение. + +duocam + +В качестве источника визуальной картинки теоретически можно использовать любую камеру, имеющую CSI или HDMI-выход. + +В качестве источника тепловизионной картинки можно использовать тепловизоры Seek Compact или Seek Compact Pro. + +В качестве платформы для запуска обрабатывающего софта рекомендуется использовать одноплатный компьютер Raspberry Pi 4B. + +## Подключение устройств + +Тепловизор подключается в один из портов USB 3.0 на RPi4. Во второй USB 3.0-порт подключается Wi-Fi адаптер для осуществления связи с наземной станцией. + +Визуальная камера подключается в CSI порт напрямую или через HDMI-CSI-конвертер. + +В порт USB 2.0 следует подключить USB-flash устройство, на которое будет производиться сохранение фото и видеофайлов. + +## Принцип работы + +Программная часть осуществляет наложение тепловизионной картинки на визуальную. С помощью конфигурационного файла или виджета управления свойствами камеры в QGroundControl можно изменять результирующее изображение. + +### Выбор модели тепловизора + +Первоначально надо определиться, какая у вас модель тепловизора (простая или Pro) и выставить соответствующую настройку в конфиг-файле (`enable: yes` у seek_thermal_pro или seek_thermal в разделе thermal_camera_models. Важно не забыть выставить `enable: no` у камеры, которую не предполагается использовать). + +### Управление наложением + +При включенном визуальном (`show_visual: yes`) и термическом (`show_thermal: yes`) изображениях, термическое будет налагаться на визуальное в регион, заданный в свойстве `overlay_thermal_on_visual` (начальная точка с координатами `(x_start, y_start)`, ширина региона - `thermal_region_width`, высота - `thermal_region_height`). + +Если отключить визуальное изображение (`show_visual: no`), то термическое развернется на весь экран. + +Если отключить термическое (`show_thermal: no`), то будет транслироваться только визуальное. + +Если отключить оба – изображение перестанет транслироваться. + +### Центровка + +Для центровки результирующего изображения (из-за физического сдвига объективов камер термическое будет сдвинутого относительно центра визуального) следует использовать свойства раздела `final_frame_cropping`. Принцип аналогичен предыдущему разделу. + +### Детекторы контуров (edge detectors) + +Для облегчения понимания термического изображения, есть возможность включения наложения на него соответствующих контуров визуального изображения. В программе реализована поддержка двух алгоритмов детектирования контуров: [Sobel](https://docs.opencv.org/3.4/d2/d2c/tutorial_sobel_derivatives.html) и [Canny](https://docs.opencv.org/3.4/da/d5c/tutorial_canny_detector.html). В соответствующих разделах конфига (`apply_sobel` и `apply_canny`) можно поэкспериментировать с некоторыми свойствами детекторов. + +### Колоризация + +Для большей наглядности, тепловизионное изображение можно колорифицировать. Для этого необходимо выставить свойство `apply_colormap: yes`. + +Конкретную схему колорификации можно выбрать из [списка](https://docs.opencv.org/2.4/modules/contrib/doc/facerec/colormaps.html), указав порядковый номер схемы в свойстве `colormap`. + +### Свойства транслируемого видео и сохраняемых файлов + +Свойства транслируемого видео можно изменять в разделе `output_video`. Делать это стоит с четким пониманием того, что делаешь - неправильные настройки могут сломать трансляцию. Например, разрешение видео должно совпадать с настройками gstreamer'а, который осуществляет последующее кодирование. + +Для настройки сохраняемого на флеш-накопитель видео следует пользоваться группой свойств `encode_video`. + +Каталоги для сохранения фото и видеофайлов можно указать в свойствах `path_to_save`. + +### Настройки дополнительной отображаемой информации + +Скрывать\показывать частоту кадров в секунду визуального и термического изображений можно при помощи свойства `show_fps`. + +Показывать\скрывать перекрестие с температурой центрального пикселя можно при помощи свойства `draw_temp`. + +### Подстройка температуры + +В зависимости от используемого тепловизора, может потребоваться корректировка температурного диапазона. В секции `temperature_calibration` Доступны две настройки: + +* Сдвиг (`offset`) - линейный сдвиг температурного диапазон на указанное число. +* Масштаб (`scale`) - пропорциональное изменение шкалы. + +### Выравнивание градиента температуры от центра к краям + +Если на тепловизионном изображении наблюдается "рамка", вызванная увеличением определяемой температуры к краям, то следует применить выравнивающий фильтр (виньетирование). Настройки располагаются в секции `vignette`: + +* `enable` - включить-выключить наложение фильтра. +* `show_center` - показать точку "центра" для отладки ее положения. +* `center_x` - X-координата "центра". +* `center_y` - Y-координата "центра". +* `max_decrement_relative` - максимальное уменьшение температуры к краям. + +## Виджет управления камерой для QGroundControl + +![QGC_widget](../assets/duocam/qgc_duocam_widget.png) + +### Где взять + +QGC c необходимый функционалом для управления "COEX DuoCam" можно скачать в нашем [репозитории](https://github.com/CopterExpress/qgroundcontrol/releases). Скачивать следует тот релиз, в названии которого присутствует слово `duocam` с максимальным порядковым номером. + +### Как использовать + +При открытии виджета QGC пошлет MAVLink-сообщения с запросом текущих значений свойств. Необходимо дождаться, пока они все до конца загрузятся. Если загрузка не завершается в течение минуты, необходимо нажать кнопку "Refresh values". + +При изменении значений свойств QGC осуществляет коммуникацию с DuoCam посредством протокола MAVLink, поэтому нет смысла очень часто нажимать контролы - наоборот, после нажатия следует дождаться изменения картинки и только потом переходить к следующему свойству. + +[Подробнее об архитектуре DuoCam и программе `duocam-mavlink`](duocam_mavlink.md). + +## Конфигурационный файл + +Для более глубокой настройки DuoCam можно использовать конфигурационный файл. + +### Как добраться + +Для редактирования конфигурационного файла необходимо извлечь microSD-карту из RPi4, вставить в кард-ридер своего компьютера (от операционной системы требуется возможность читать файловую систему ext4), открыть файл по адресу `/etc/duocam/camera.yaml`. + +Также можно зайти по SSH на работающую RPi4 и отредактировать конфигурационный файл внутри системы по тому же пути. + +### Образец конфигурационного файла + +```yaml +show_visual: yes +show_thermal: yes +flip_thermal: no +apply_sobel: + enable: yes + sobel_scale: 3 + sobel_delta: 0 +apply_canny: no +draw_temp: yes + +output_video: + device: /dev/video1 + width: 1280 + height: 720 + bytes_per_pixel: 3 + framerate: 20 + +path_to_save_photos: /media/usb0/ +path_to_save_videos: /media/usb0/ + +encode_video: + width: 720 + height: 480 + framerate: 10 + +thermal_camera_models: + seek_thermal_pro: + enable: no + sensor_resolution: + width: 320 + height: 240 + overlay_thermal_on_visual: + # These values are for GitUp3 + x_start: 282 + y_start: 102 + thermal_region_width: 600 + thermal_region_height: 400 + transparency: 0.3 + # These values are for Raspicam + # x_start: 425 + # y_start: 155 + # thermal_region_width: 900 + # thermal_region_height: 600 + final_frame_cropping: + enable: yes + x_start: 0 + y_start: 0 + width: 1160 + height: 610 + + seek_thermal: + enable: yes + sensor_resolution: + width: 206 + height: 156 + overlay_thermal_on_visual: + x_start: 282 + y_start: 102 + thermal_region_width: 600 + thermal_region_height: 400 + transparency: 0.3 + final_frame_cropping: + enable: yes + x_start: 0 + y_start: 0 + width: 1160 + height: 610 + +# Colormaps are taken from: https://docs.opencv.org/2.4/modules/contrib/doc/facerec/colormaps.html +# COLORMAP_AUTUMN = 0, +# COLORMAP_BONE = 1, +# COLORMAP_JET = 2, +# COLORMAP_WINTER = 3, +# COLORMAP_RAINBOW = 4, +# COLORMAP_OCEAN = 5, +# COLORMAP_SUMMER = 6, +# COLORMAP_SPRING = 7, +# COLORMAP_COOL = 8, +# COLORMAP_HSV = 9, +# COLORMAP_PINK = 10, +# COLORMAP_HOT = 11 +apply_colormap: + enable: yes + colormap: 4 +``` diff --git a/docs/ru/duocam_mavlink.md b/docs/ru/duocam_mavlink.md new file mode 100644 index 000000000..d6e65e041 --- /dev/null +++ b/docs/ru/duocam_mavlink.md @@ -0,0 +1,104 @@ +# Виртуальная MAVLink-камера COEX DuoCam + +Полётные контроллеры поддерживают разные способы взаимодействия с внешними камерами, включая протокол MAVLink. Обычно коммуникация с помощью данного протокола требует использования UART-порта на полётном контроллере, но есть возможность работать с камерой в основном потоке MAVLink-телеметрии с БПЛА. + +Утилита `duocam-mavlink` отвечает за работу виртуальной MAVLink-камеры и встраивается в общую телеметрию между полётным контроллером и QGroundControl. + +![Блок-схема COEX DuoCam](../assets/duocam/duocam.png) + +На блок-схеме прямыми линиями обозначены взаимодействия между блоками, пунктирными линиями уточняется характер взаимодействия. + +> **Warning** Протокол взаимодействия находится в процессе модификации. В новых версиях планируется избавиться от прямой отправки значений параметров и их количества от `duocam-mavlink` к QGroundControl. + +`duocam-camera` и `duocam-mavlink` обмениваются данными с помощью очередей POSIX. Имена очередей и формат сообщений доступен в репозитории [duocam-common](https://github.com/CopterExpress/duocam-common). + +Для объединения блоков, взаимодействующих через MAVLink, можно использовать любой MAVLink-коммутатор/маршрутизатор, который либо позволяет отключить таблицу коммутации, либо заполняет её по схеме *MAVLink ID:Component ID* (например, `cmavnode`, `mavlink-fast-switch`, `mavlink-switch`). + +> **Warning** При использовании `mavlink-fast-switch` требуется использовать `mavlink-serial-bridge`, либо любой другой мост для передачи MAVLink из последовательного порта в UDP, так как `mavlink-fast-switch` работает только с UDP. + +## Конфигурационный файл + +Для редактирования конфигурационного файла необходимо извлечь microSD-карту из RPi4, вставить в кард-ридер своего компьютера (от операционной системы требуется возможность читать файловую систему ext4), открыть файл по адресу `/etc/duocam/mavlink.yaml`. + +Также можно зайти по SSH на работающую RPi4 и отредактировать конфигурационный файл внутри системы по тому же пути. + +Для корректной работы `duocam-mavlink` требуется *MAVLink ID* полётного контроллера (параметр `vehicle_id`) и `MAVLink ID` QGroundControl (параметр `qgc_vehicle_id`). `duocam-mavlink` ожидает телеметрию на UDP (параметры `ip` и `port`) и отправляет сообщения HEARTBEAT с частотой, согласно параметру `heartbeat_frequency`, представляясь, как компонент полётного контроллера `MAV_COMP_ID_CAMERA`. + +Максимальная задержка от `duocam-camera` задаётся параметром `command_timeout`. + +Если система DuoCam используется для полётов внутри помещений, то должен быть включен параметр `no_gps`. + +## Пример конфигурационного файла + +```yaml +# MAVLink vehicle ID that owns the camera +vehicle_id: 1 +# Enable this flag for indoor use +no_gps: False +# QGC vehicle ID +qgc_vehicle_id: 255 +mavlink: + # IP address of the interface to listen port on (0.0.0.0 for all interfaces) + ip: 127.0.0.1 + # UDP port + port: 14540 + # Heartbeat frequency (Hz) + heartbeat_frequency: 1.0 +# Camera driver command timeout (s) +command_timeout: 3.0 +``` + +## Пример конфигурационного файла для `mavlink-fast-switch` + +```yaml +# MAVLink endpoints +endpoints: + # UAV endpoint + - name: "uav" + local: + port: 14588 + # DuoCam MAVLink endpoint + - name: "duocam-mavlink" + remote: + ip: "127.0.0.1" + port: 14540 + # GCS endpoint + - name: "gcs" + remote: + ip: "127.0.0.1" + port: 14550 +# Enable MAVLink ID table +# HINT: Can't use this feature with duocam +id-table: False +``` + +## Пример конфигурационного файла для `mavlink-serial-bridge` + +```yaml +# Serial device settings +serial: + # Device file + device: "/dev/ttyS0" + # Baudrate + baudrate: 57600 + # Flow control (hardware, none) + flow: none + # Software serial TX buffer (bytes) (2048 by default) + tx-buffer: 2048 +# UDP port settings +udp: + # Remote host settings (optional, listening mode if not presented) + remote: + ip: 127.0.0.1 + port: 14588 + # Lock remote host on the initial value (optional, False by default) + lock: True + # Broadcast mode (optional, False by default) + broadcast: False + # Local settings (optional, all interfaces and a random port by default) + local: + # Local IP address (0.0.0.0 to listen on all interfaces) (optional, all interfaces by default) + ip: 127.0.0.1 + # Local UDP port (0 to select a random free port) (optional, 0 by default) + port: 0 +```