append spawn objects

2026-09-18 12:37:28 +10:00
parent 9dc1073f42
commit b1b8cedef1
26 changed files with 124049 additions and 77 deletions
@@ -39,3 +39,101 @@
 - Действуют настроенные ограничения суставов и TCP; симуляция не воспроизводит все защиты физического робота
 - Физика не идеальна — инерция, трение и упругость приближённые
 - FRI-протокол не задействован — связь идёт через Webots-драйвер ROS 2
+
+## Спавн объектов с текстурами
+
+В `cobot-setting.yaml` (секция `digital_twin.webots`) задайте:
+
+```yaml
+objects:
+  enabled: true
+  count: 5
+  models:
+    - path: pkg://iiwa_description/objects/hammer/hammer1.obj
+      rotation_deg: [0, 0, 0]
+    - path: pkg://iiwa_description/objects/hammer/hammer2.obj
+      rotation_deg: [0, 0, 0]
+  area:
+    x: [0.3, 0.7]
+    y: [-0.3, 0.3]
+    z: [0.1, 0.1]
+```
+
+При запуске Webots создаётся ровно `count` объектов: каждая модель независимо
+выбирается из `models`, повторения разрешены. `enabled: false`, `count: 0` или
+отсутствие секции отключает спавн. Список — разрешённые модели, а не количество
+экземпляров каждой модели. Пути могут быть `pkg://`, абсолютными или относительно
+файла настроек. Пока поддерживается Wavefront OBJ.
+
+Область задаётся в метрах в системе основания робота: применяется та же пара
+`webots.transform` / `webots.rotation` (ось и угол в радианах), что и при спавне
+робота. Формула: `p_world = t_robot + R_robot * p_local`. Это начальная область,
+а не ограничитель движения: физика затем может перемещать объекты. Перемещение
+робота мышью после запуска не переносит уже созданные предметы.
+
+Точка спавна — центр габаритов по X/Y и нижняя точка по Z. Смещение вершин
+в экспортированном OBJ компенсируется автоматически; исходные файлы, UV,
+масштаб (1 единица = 1 метр) сохраняется; ориентация задаётся отдельно для каждой модели. Диапазон ограничивает
+эту точку, а не весь габарит. Пересечения объектов при случайном размещении
+не исключаются: выбирайте достаточно просторную область.
+
+`CadShape` загружает материалы из `mtllib` и текстуры из MTL. Сохраняйте OBJ,
+MTL и PNG в исходной структуре каталогов: например, `hammer1.mtl` ссылается на
+`hammer1_basecolor.png`. Весь каталог `objects` устанавливается вместе с
+`iiwa_description`. Отсутствующие модели, MTL и текстуры вызывают ошибку до
+первого запроса спавна. Для физики используется упрощённый габаритный Box и
+масса 0.5 кг; это не точная модель инерции или захвата молотка. В MoveIt Planning
+Scene эти объекты автоматически не добавляются.
+
+Нода `object_spawner` вызывает
+`/Ros2Supervisor/spawn_node_from_string` (`webots_ros2_msgs/srv/SpawnNodeFromString`)
+однократно для каждого предмета. Отказ сервиса прерывает оставшийся спавн;
+тайм-аут не повторяется, чтобы не создавать дубликаты. Нода завершается после
+успеха. На физическом роботе она не запускается.
+
+### Проверка в симуляции
+
+1. Пересоберите пакеты:
+   `colcon build --base-paths src --packages-select iiwa_description iiwa_utils iiwa_bringup iiwa_config --symlink-install`.
+2. Выполните `source install/setup.bash`, затем `cobot run local` и выберите Webots.
+3. Проверьте пять узлов `spawned_object_0000` … `spawned_object_0004` в дереве сцены,
+   текстуры молотков и сообщение `All 5 objects spawned`.
+4. Измените `transform` и `rotation`, перезапустите: область должна переместиться
+   и повернуться вместе с основанием робота. Для проверки начальных координат
+   используйте паузу симулятора до падения объектов.
+5. Проверьте `count: 0`, запуск без камер и ошибку при несуществующей модели.
+
+Справочник: [Webots CadShape](https://cyberbotics.com/doc/reference/cadshape).
+
+### Индивидуальный поворот модели
+
+Каждая запись `models` может содержать `path` и `rotation_deg: [X, Y, Z]`.
+Углы фиксированные, в градусах; сначала применяется поворот вокруг X, затем Y,
+затем Z в системе основания робота: `R_model = Rz * Ry * Rx`,
+`R_world = R_robot * R_model`. Например:
+
+```yaml
+models:
+  - path: pkg://iiwa_description/objects/hammer/hammer1.obj
+    rotation_deg: [0, 0, 0]
+  - path: pkg://iiwa_description/objects/hammer/hammer2.obj
+    rotation_deg: [90, 0, 0]
+  - path: pkg://iiwa_description/objects/hammer/hammer3.obj
+    rotation_deg: [0, 0, 45]
+```
+
+В предоставленных OBJ длинная ось молотка направлена по Z: `[0, 0, 0]`
+задаёт вертикальную начальную ориентацию, `[90, 0, 0]` кладёт молоток набок,
+а `[0, 0, 45]` поворачивает его вокруг вертикальной оси. В обоих конфигурационных
+файлах для всех моделей явно указано `[0, 0, 0]`; изменяйте каждую независимо.
+Записи только с путём остаются совместимыми и означают нулевой поворот.
+
+Поворачиваются и видимая модель, и её коллизионный Box. После поворота
+пересчитывается высота: `area.z` задаёт нижнюю точку повёрнутого коллизионного
+габарита в системе робота, а X/Y — его центр. Поворот модели не поворачивает
+саму область спавна. Изменения применяются при следующем запуске.
+
+Это начальная ориентация, а не фиксация: после появления гравитация и контакты
+могут опрокинуть молоток. Для проверки поставьте симуляцию на паузу при спавне.
+Проверьте разные углы у двух моделей, отсутствие погружения Box ниже `area.z`
+и сохранение локальных углов при изменении `webots.rotation`.