docs: add documentation on new aruco_pose

docs/ru/aruco_map.md

@@ -0,0 +1,120 @@
+# Навигация по картам ArUco-маркеров
+
+> **Info** Для распознавания маркеров модуль камеры должен быть корректно подключен и [сконфигурирован](camera.md).
+
+Модуль `aruco_map` распознает карты ArUco-маркеров, как единое целое. Также возможна навигация по картам ArUco-маркеров с использованием механизма Vision Position Estimate (VPE).
+
+## Конфигурирование
+
+Для включения распознавания карт маркеров аргумент `aruco_map` в файле `~/catkin_ws/src/clever/clever/launch/aruco.launch` должен быть в значении `true`:
+
+```xml
+<arg name="aruco_map" default="true"/>
+```
+
+Для включения передачи координат в полетный контроллер по механизму VPE, аргумента `aruco_vpe` должен быть в значении `true`:
+
+```xml
+<arg name="aruco_vpe" default="true"/>
+```
+
+## Настройка карты маркеров
+
+Карта загружается из текстового файла, каждая строка которого имеет следующий формат:
+
+```
+id_маркера размер_маркера x y z угол_z угол_y угол_x
+```
+
+Где `угол_N` – это угол поворота маркера вокруг оси N в радианах.
+
+Путь к файлу с картой задается в параметре `map`:
+
+```xml
+<param name="map" value="$(find aruco_pose)/map/map.txt"/>
+```
+
+Смотрите примеры карт маркеров в каталоге [`~/catkin_ws/src/clever/aruco_pose/map`](https://github.com/CopterExpress/clever/tree/master/aruco_pose/map).
+
+### Проверка
+
+Для контроля карты, по которой в данный момент коптер осуществляет навигацию, можно просмотреть содержимое топика `/aruco_map/image`. Через браузер его можно просмотреть при помощи [web_video_server](web_video_server.md) по ссылке http://192.168.11.1:8080/snapshot?topic=/aruco_map/image:
+
+<img src="../assets/aruco_map.png" width=600>
+
+Клевер публикует текущую позицию распознанной карты в топик `aruco_map/pose`. Также публикуется [TF-фрейм](frames.md) `aruco_map` (VPE выключен) или `aruco_map_detected` (VPE включен). Используя топик `aruco_map/visualization` можно визуализировать текущую карту маркеров в [rviz](rviz.md).
+
+Наглядно позиция распознанной карты отображается в топике `aruco_map/debug` (просмотр доступен по ссылке http://192.168.11.1:8080/stream_viewer?topic=/aruco_map/debug):
+
+<img src="../assets/aruco_map_debug.png" width=600>
+
+## Система координат
+
+По [соглашению](http://www.ros.org/reps/rep-0103.html) в маркерном поле используется стандартная система координат <abbr title="East-North-Up">ENU</abbr>:
+
+* ось **<font color=red>x</font>** указывает кверху карты маркеров;
+* ось **<font color=green>y</font>** указывает на правую сторону карты маркеров;
+* ось **<font color=blue>z</font>** указывает от плоскости карты маркеров.
+
+<img src="../assets/aruco-map-axis.png" width="600">
+
+## Настройка VPE
+
+Для работы механизма Vision Position Estimation необходимы следующие [настройки PX4](px4_parameters.md).
+
+При использовании **EKF2** (параметр `SYS_MC_EST_GROUP` = `ekf2`):
+
+* В параметре `EKF2_AID_MASK` включены флажки `vision position fusion`, `vision yaw fusion`.
+* Шум угла по зрению: `EKF2_EVA_NOISE` = 0.1 rad
+* Шум позиции по зрению: `EKF2_EVP_NOISE` = 0.05 m
+* `EKF2_EV_DELAY` = 0
+
+При использовании **LPE** (параметр `SYS_MC_EST_GROUP` = `local_position_estimator, attitude_estimator_q`):
+
+* В параметре `LPE_FUSION` включены флажки `vision position`, `land detector`.
+* Вес угла по рысканью по зрению: `ATT_W_EXT_HDG` = 0.5
+* Включена ориентация по Yaw по зрению: `ATT_EXT_HDG_M` = 1 `Vision`.
+* Шумы позиции по зрению: `LPE_VIS_XY` = 0.05 m, `LPE_VIS_Z` = 0.05 m.
+* `LPE_VIS_DELAY` = 0 sec
+
+<!-- * Выключен компас: `ATT_W_MAG` = 0 -->
+
+> **Info** Для использования LPE в Pixhawk необходимо [скачать прошивку с названием `px4fmu-v2_lpe.px4`](https://github.com/PX4/Firmware/releases).
+
+## Полет
+
+При правильной настройке коптер начнет удерживать позицию в [режимах](modes.md) `POSCTL` и `OFFBOARD` автоматически.
+
+Для [автономных полетов](simple_offboard.md) можно будет использовать функции `navigate`, `set_position`, `set_velocity`. Для полета в определенные координаты маркерного поля необходимо использовать фрейм `aruco_map`:
+
+```python
+# Вначале необходимо взлететь, чтобы коптер увидел карту меток и появился фрейм aruco_map:
+navigate(0, 0, 2, frame_id='body', speed=0.5, auto_arm=True)  # взлет на 2 метра
+
+time.sleep(5)
+
+# Полет в координату 2:2 маркерного поля, высота 2 метра
+navigate(2, 2, 2, speed=1, frame_id='aruco_map')  # полет в координату 2:2, высота 3 метра
+```
+
+## Дополнительные настройки
+
+Если коптер нестабильно удерживает позицию по VPE, попробуйте увеличить коэффициенты *P* PID-регулятора по скорости – параметры `MPC_XY_VEL_P` и `MPC_Z_VEL_P`.
+
+## Расположение маркеров на потолке
+
+![Маркеры на потолке](../assets/IMG_4175.JPG)
+
+Для навигации по маркерам, расположенным на потолке, необходимо поставить основную камеру так, чтобы она смотрела вверх и [установить соответствующий фрейм камеры](camera_frame.md).
+
+Также в файле `~/catkin_ws/src/clever/clever/launch/aruco.launch` необходимо установить параметр `known_tilt` в секции `aruco_map` в значение `map_flipped`:
+
+```xml
+<param name="known_tilt" value="map_flipped"/>
+```
+
+При такой конфигурации фрейм `aruco_map` также окажется перевернутым. Таким образом, для полета на высоту 2 метра ниже потолка, аргумент `z` нужно устанавливать в 2:
+
+```python
+navigate(x=1, y=2, z=1.1, speed=0.5, frame_id='aruco_map')
+```

docs/ru/aruco_marker.md

@@ -0,0 +1,123 @@
+# Распознавание ArUco-маркеров
+
+> **Info** Для распознавания маркеров модуль камеры должен быть корректно подключен и [сконфигурирован](camera.md).
+
+Модуль `aruco_detect` распознает ArUco-маркеры и публикует их позиции в ROS-топики и в [TF](frames.md).
+
+Эта функция полезна для применения совместно с какой-либо системой позиционирования для дрона, такой как [GPS](gps.md), [Optical Flow](optical_flow.md), PX4Flow, визуальная одометрия, ультразвуковое ([Marvelmind](https://marvelmind.com)) или UWB-позиционирование ([Pozyx](https://www.pozyx.io)).
+
+Также возможно применение совместно с [навигацией по карте маркеров](aruco_map.md).
+
+## Настройка
+
+Для включения модуля аргумент `aruco_detect` в файле `~/catkin_ws/src/clever/clever/launch/aruco.launch` должен быть в значении `true`:
+
+```xml
+<arg name="aruco_detect" default="true"/>
+```
+
+Для правильной работы в этом же файле в секции `aruco_detect` должны быть выставлены параметры:
+
+```xml
+<param name="length" value="0.32"/>          <!-- размер маркеров в метрах (не включая белую рамку) -->
+<param name="estimate_poses" value="true"/>  <!-- включение вычисления позиций маркеров -->
+<param name="send_tf" value="true"/>         <!-- отправлять позиции маркеров в виде TF-фреймов -->
+<param name="known_tilt" value="map"/>       <!-- наклон маркеров, см. далее -->
+```
+
+Значение параметра `known_tilt` следует выставлять следующим образом:
+
+* если *все* маркеры наклеены на полу (земле), выставить значение `map`;
+* если *все* маркеры наклеены на потолке, выставить значение `map_flipped`;
+* противном случае удалить строку с параметром.
+
+Если некоторые маркеры имеют размер, отличный значения `length`, их размер может быть переопределен с помощью параметра `length_override`:
+
+```xml
+<param name="length_override/3" value="0.1"/>    <!-- маркер c id 3 имеет размер 10 см -->
+<param name="length_override/17" value="0.25"/>  <!-- маркер c id 17 имеет размер 25 см -->
+```
+
+## Система координат
+
+С маркером связана следующая система координат:
+
+* ось **<font color=red>x</font>** указывает кверху маркера;
+* ось **<font color=green>y</font>** указывает на правую сторону маркера;
+* ось **<font color=blue>z</font>** указывает от плоскости маркера.
+
+<img src="../assets/marker-axis.png" width="300">
+
+## Работа с распознанными маркерами
+
+Наглядно распознанные маркеры можно видеть в топике `aruco_detect/debug`. Просмотреть его можно с помощью [`rqt_image_view`](rviz.md) или через [web_video_server](web_video_server.md) по ссылке http://192.168.11.1:8080/snapshot?topic=/aruco_pose/debug:
+
+<img src="../assets/aruco-detect-debug.png" width=600>
+
+Распознанные маркеры и их позиции публикуются в топик `aruco_detect/markers`. Чтение топика из Bash:
+
+```bash
+rostopic echo /aruco_detect/markers
+```
+
+## Навигация по маркерам
+
+С использованием модуля [`simple_offboard`](simple_offboard.md) можно осуществлять навигацию по маркерам используя соответствующие TF-фреймы.
+
+Полет в точку над маркером 5 на высоту 1 метр:
+
+```python
+navigate(frame_id='aruco_5', x=0, y=0, z=1)
+```
+
+Полет в точку на метр левее маркера 7 на высоте 2 метра:
+
+```python
+navigate(frame_id='aruco_7', x=-1, y=0, z=2)
+```
+
+Вращаться против часовой стрелки на высоте 1.5 метра над маркером 10:
+
+```python
+navigate(frame_id='aruco_10', x=0, y=0, z=1.5, yaw_rate=0.5)
+```
+
+Если необходимый маркер не появится в поле зрения в течение полусекунды, дрон продолжит выполнять предыдущую команду.
+
+Подобные значения `frame_id` можно использовать и в других сервисах, например `get_telemetry`. Получение расположения дрона относительно маркера 3:
+
+```python
+telem = get_telemetry(frame_id='aruco_3')
+```
+
+Если необходимый маркер не появится в поле зрения в течение полусекунды, в полях `telem.x`, `telem.y`, `telem.z`, `telem.yaw` будет значение `NaN`.
+
+## Работа с результатом распознавания из Python
+
+Чтение топика `aruco_detect/markers` из Python:
+
+```python
+import rospy
+from aruco_pose.msg import MarkerArray
+rospy.init_node('my_node')
+
+# ...
+
+def markers_callback(msg):
+    print 'Detected markers:':
+    for marker in msg.markers:
+        print 'Marker: %s' % marker
+
+# Подписываемся. При получении сообщения в топик /foo будет вызвана функция foo_callback.
+rospy.Subscriber('aruco_detect/markers', MarkerArray, markers_callback)
+
+# ...
+
+rospy.spin()
+```
+
+Сообщения будут содержать ID маркера, его угловые точки на изображении и его позицию (относительно камеры).
+
+---
+
+См. далее: [навигация по картам маркеров](aruco_map.md).

docs/ru/aruco_new.md

@@ -0,0 +1,21 @@
+# ArUco-маркеры
+
+> **Note** Документация для версий [образа](microsd_images.md), начиная с версии **0.16**. Для более ранних версий см. [документацию для версии **0.15.1**](https://github.com/CopterExpress/clever/blob/v0.15.1/docs/ru/aruco.md).
+
+[ArUco-маркеры](https://docs.opencv.org/3.2.0/d5/dae/tutorial_aruco_detection.html) — это популярная технология для позиционирования
+робототехнических систем с использованием компьютерного зрения.
+
+![ArUco-маркеры](../assets/markers.jpg)
+
+> **Hint** При печати визуальных маркеров необходимо использовать максимально матовую бумагу. Глянцевая бумага будет бликовать на свету, сильно ухудшая качество распознавания.
+
+Для быстрого генерирования маркеров для печати можно использовать онлайн-инструмент: http://chev.me/arucogen/.
+
+На [образе Клевера для RPi](microsd_images.md) предустановлен пакет `aruco_pose`, предназначенный для работы с ArUco-маркерами.
+
+## Режимы работы
+
+Клевер имеет несколько преднастроенных режимов работы с ArUco-маркерами:
+
+* [распознавание и навигация по отдельным маркерам](aruco_marker.md);
+* [распознавание и навигация по картам маркеров](aruco_map.md).