Конфигурация¶

SmartCamera хранит настройки камер в YAML, настройки веб-приложения — в отдельном JSON, а записи, калибровочные сессии и данные моделей — в каталоге материалов. Эти файлы решают разные задачи: изменение списка камер не переносит архив, а смена папки материалов не меняет ROS-топики.

Где находится рабочий файл¶

При запуске через smartcamera пути задаёт CLI. По умолчанию:

Что хранится	Путь
Настройки запуска CLI	`~/.config/smartcamera/settings.json`
Камеры	`~/.local/share/smartcamera/data/config/cameras.yaml`
Настройки веб-интерфейса	`~/.local/share/smartcamera/data/config/web.json`
Записи и данные моделей	`~/.local/share/smartcamera/data/recordings/`

Выбранные пути и режим запуска можно посмотреть командой:

smartcamera configure --show

Если при настройке задан другой каталог данных, YAML камер и настройки веб-интерфейса находятся в его подкаталоге config/. CLI передаёт эти пути приложению и создаёт пустую конфигурацию при первой настройке. В Docker используется тот же каталог данных на хосте.

При самостоятельном запуске через ros2 launch передавайте свой YAML через аргумент config_file. Без него launch использует файл из пакета smart_camera_config, который может содержать конфигурацию разработчика. Не запускайте второй экземпляр через ros2 launch одновременно с CLI.

Фактический путь доступен в настройках веб-панели и поле camera_config_path ответа GET /api/v1/settings. Для сохранения нужен доступ к файлу и его родительскому каталогу: запись выполняется через временный файл и атомарную замену. Скопированный путь к чужой калибровке или серийный номер из примера не становится действительным на другом компьютере.

Минимальный YAML¶

schema_version: 1
cameras: []

Пропущенные manager и web получают значения по умолчанию. Модели строгие: неизвестные поля отклоняются, поэтому опечатка не превращается в незаметно проигнорированную настройку.

Раздел и поле	По умолчанию	Допустимое значение / смысл
`schema_version`	`1`	Только версия 1
`manager.open_timeout_ms`	`5000`	100–60000 мс; ожидание открытия камеры
`manager.reconnect_delay_ms`	`2000`	100–60000 мс; задержка переподключения
`manager.failure_threshold`	`5`	1–1000; порог последовательных ошибок
`web.grid_preview_fps`	`12`	1–30; частота предпросмотра сетки
`web.raw_preview_jpeg_quality`	`80`	1–100; JPEG для просмотра raw-потока

Частота браузерного предпросмотра отличается от частоты захвата камеры и частоты обработки нейросетью. Уменьшение grid_preview_fps не меняет аппаратный профиль камеры.

Пример USB-камеры¶

Замените device реальным путём из /dev/v4l/by-id/, а разрешение, FPS и pixel_format — режимом, который показывает v4l2-ctl для этой камеры:

schema_version: 1
manager:
  open_timeout_ms: 5000
  reconnect_delay_ms: 2000
  failure_threshold: 5
web:
  grid_preview_fps: 12
  raw_preview_jpeg_quality: 80
cameras:
  - id: front
    display_name: Передняя камера
    enabled: true
    interface: v4l2
    device: /dev/v4l/by-id/usb-YOUR_CAMERA-video-index0
    topic: /smart_camera/front/image_raw
    frame_id: front_camera_optical_frame
    resolution: {width: 640, height: 480}
    fps: 30
    pixel_format: MJPG
    transport: compressed
    jpeg_quality: 85
    output_encoding: bgr8
    controls:
      auto_exposure: null
      exposure: null
      gain: null
      brightness: null
    calibration_file: null

null в controls означает «не менять значение драйвера». Это отличается от выключения автоматической экспозиции: для него задаётся auto_exposure: false. Набор доступных controls зависит от устройства. Значения экспозиции и усиления выбирайте по его диапазонам, а не переносите с другой модели камеры.

Общие поля камеры¶

Поле	Назначение
`id`	Уникальный идентификатор длиной 1–64; начинается с маленькой латинской буквы, далее буквы, цифры, `_` и `-`
`display_name`	Название в интерфейсе, 1–128 символов
`enabled`	Включена ли камера; по умолчанию `true`
`interface`	`v4l2`, `realsense` или `ros`; по умолчанию `v4l2`
`device`	Обязательная непустая строка устройства или обозначения источника
`topic`	Абсолютное ROS-имя без завершающего `/` и `//`
`frame_id`	Непустое имя системы координат изображения
`resolution`	`width` и `height`, каждое от 1 до 16384
`fps`	Частота больше 0 и не выше 240; оборудование должно поддерживать выбранное значение
`pixel_format`	`auto`, `MJPG` или `YUYV`; по умолчанию `auto`
`transport`	`raw` или `compressed`; по умолчанию `raw`
`jpeg_quality`	1–100, по умолчанию 85
`output_encoding`	`bgr8`, `rgb8` или `mono8`; по умолчанию `bgr8`
`calibration_file`	Путь к ROS calibration YAML либо `null`

Для аппаратной камеры с compressed фактический топик изображения — <topic>/compressed. Для внешнего источника interface: ros поле topic всегда содержит точное имя уже существующего топика, включая суффикс, если он есть. SmartCamera подписывается на него и не управляет внешним издателем. Пример такого источника:

schema_version: 1
cameras:
  - id: external
    display_name: Внешний ROS-поток
    interface: ros
    device: ros
    topic: /external/image/compressed
    frame_id: external_optical_frame
    resolution: {width: 640, height: 480}
    fps: 30
    transport: compressed

Конфигурация проверяет уникальность ID, топиков, V4L2-устройств и серийных номеров RealSense. Проверяются и эффективные топики: например, изображение одной камеры не должно пересекаться с camera_info другой. Отключённая запись остаётся частью конфигурации и тоже участвует в проверке уникальности.

RealSense и калибровка¶

Для interface: realsense обязателен serial. Поля color и depth описывают ширину, высоту и FPS потоков; у depth также есть topic и frame_id. Если color не задан, он получается из resolution и fps; пропущенный depth создаётся с тем же профилем. Реальную поддержку сочетания потоков проверяйте через discovery, особенно для L515.

pointcloud.enabled по умолчанию false. Для облака можно задать topic, frame_id и max_points (по умолчанию 150000, диапазон 1–2000000). depth_visualization задаёт только отображение: min_m по умолчанию 0.2, max_m 4.0, colormap — turbo, viridis, magma или gray. Максимальная дистанция должна быть больше минимальной. Цветной поток RealSense допускает bgr8 и rgb8.

calibration_file принимает абсолютный путь или адрес вида package://smart_camera_config/config/calibration/front.yaml. Для обычной камеры без калибровки фиктивный CameraInfo не создаётся; RealSense предоставляет заводские параметры. При применении результата монокалибровки приложение сохраняет первоначальную настройку в calibration_baseline. Не удаляйте исходный calibration YAML, если планируете вернуться к нему. Работа с профилями описана в руководстве по камерам.

Применение и конфликты изменений¶

Веб-панель сохраняет конфигурацию с текущей ревизией и применяет изменения через менеджеры. При неудачном открытии выполняется откат. HTTP-клиент передаёт If-Match, ROS-клиент — expected_revision; устаревшая ревизия требует повторного чтения. Это защищает от перезаписи изменений другого клиента.

Если YAML редактировался вручную, используйте действие перечитывания конфигурации в настройках приложения. Само сохранение файла редактором не равнозначно применению через API. Для интеграции см. HTTP API и ROS 2 управление.

Launch, настройки веб-сервера и материалы¶

Аргумент launch	По умолчанию
`config_file`	`config/cameras.yaml` установленного пакета
`web_host`	`127.0.0.1`
`web_port`	`8000`
`recordings_dir`	`~/smart_camera_recordings`
`photo_sync_tolerance_ms`	`30` (веб-сервер принимает 0–30)
`realsense_sdk_prefix`	`~/.local/librealsense-l515-2.50.0`

JSON настроек находится в ~/.config/smart_camera_web/settings.json; путь можно изменить переменной SMART_CAMERA_WEB_SETTINGS_FILE. Он содержит recordings_directory и dashboard_refresh_seconds (1–300, по умолчанию 5). При наличии сохранённого JSON его каталог материалов используется вместо стартового значения recordings_dir в обычном запуске сервера.

В каталоге материалов находятся записи и подкаталоги calibrations, handeye, inference. Смена папки в настройках не переносит существующие файлы; службы калибровки и inference выбирают свои корни при старте. После изменения папки перезапустите приложение, чтобы все службы использовали новое расположение. Для резервной копии сохраняйте YAML камер, связанные calibration-файлы, JSON настроек и весь каталог материалов.

CLI автоматически задаёт SMART_CAMERA_INFERENCE_PYTHON: .venv-inference/bin/python внутри исходников для локального режима и /opt/inference/bin/python для Docker. При самостоятельном запуске порядок выбора: SMART_CAMERA_INFERENCE_PYTHON, затем существующий ~/.venvs/smart-camera-inference/bin/python, затем Python веб-сервера. Его окружение не заменяет YAML камер; подробности — в разделе моделей.