Что такое SpatialClaw
SpatialClaw – это «обёртка‑агент» вокруг постоянного Python‑ядра, в которое загружены входные кадры и набор базовых примитивов. Инструменты восприятия (перцепции) представлены обычными Python‑функциями, а их результаты – маски, карты глубины, параметры камер и плотные облака точек – обычные переменные.
Ядро предоставляет шесть публичных точек входа:
- InputImages – массив изображений.
- Metadata – частота кадров, длительность и индексы.
- tools – набор примитивов восприятия и геометрии.
- show() – визуализирует изображение в следующем контексте агента.
- vlm – отправка запросов в отдельный сеанс VLM.
- ReturnAnswer() – отправка окончательного ответа.
Ключевые инструменты:
tools.Reconstruct– обёртка над Depth Anything 3, выводит глубину, внутренние и внешние параметры камер, плотные облака точек.tools.SAM3– обёртка над SAM 3, генерирует маски из текста, точек или прямоугольников.- Дополнительные лёгкие утилиты:
tools.Geometry,tools.Mask,tools.Time,tools.Graph,tools.Draw.
Фреймворк работает без дообучения: один системный промпт, один набор инструментов и одинаковые гиперпараметры используют для всех бенчмарков и моделей.
Почему важен «action interface»
Исследователи сравнили три способа взаимодействия агента с инструментами на задаче «измерить расстояние между нагревателем и дверью»:
- Однопроходный код – пишет полностью программу и сразу её исполняет. Ошибочное предположение сразу же влияет на результат.
- Структурированный вызов инструментов – использует фиксированную JSON‑схему, не позволяя свободно комбинировать результаты с NumPy или SciPy. Операция «ближайшая точка» отсутствует, поэтому ответ неверен.
- SpatialClaw – комбинирует инструменты в Python‑коде, последовательно проверяет промежуточные результаты и при необходимости исправляет стратегию. В примере агент сначала вычислил расстояние между центрами масс, затем заметил, что нужен минимум между точками, переключился на
scipy.spatial.KDTreeи получил 0.9439 м против истинных 0.9 м.
Результаты на бенчмарках
Тестирование проводилось на 20 бенчмарках из пяти категорий (одиночное изображение, мультивид, общее, видео/4D, общее видео‑понимание). Во всех шести проверенных базовых моделях (от 26 B до 397 B параметров) SpatialClaw улучшил показатели.
| Интерфейс | Средняя точность (20 бенч) | Δ vs без‑инструментов |
|---|---|---|
| No‑tool baseline | 53.4 | – |
| Однопроходный код | 55.2 | +1.8 |
| Структурированный вызов | 56.7 | +3.3 |
| SpatialClaw (код как действие) | 59.9 | +6.5 |
Сравнение с другими пространственными агентами (Gemma4‑31B): VADAR – 40.5, pySpatial – 47.8, SpaceTools – 48.7, SpatialClaw – 59.9. На динамических задачах (DSI‑Bench, MindCube) прирост превысил 15 пунктов.
Пятиэтапный цикл работы
Каждый пример проходит через пять шагов:
- Планирование – агент формирует стратегию без доступа к изображениям.
- Генерация кода – пишет один Python‑ячейку на каждый шаг.
- Выполнение кода – статический проверщик AST отклоняет опасные конструкции.
- Сбор обратной связи – агент получает результаты инструментов и может их визуализировать.
- Отправка ответа – вызывается
ReturnAnswer()либо цикл завершается после 30 шагов.
Официальный репозиторий использует LangGraph, постоянный Jupyter‑ядро, модели через vLLM и перцептивные сервисы FastAPI. Запуск одного бенчмарка на одной машине выглядит так:
git clone --recursive https://github.com/NVlabs/SpatialClaw.git
cd SpatialClaw
bash spatial_agent/scripts/setup.sh
cp .env.example .env # добавить ключи API или задать свой vLLM
python -m spatial_agent.entrypoints.run \
--dataset spatial_agent/config/dataset/erqa.json \
--model spatial_agent/config/model/gemini-3-pro.json \
--concurrency 4
Пример кода агента
# Восстановление сцены и сегментация объектов recon = tools.Reconstruct.Reconstruct(InputImages) seg = tools.SAM3.segment_video_by_text(["radiator heater", "door"]) show(seg.visualize(1)) # визуальная проверка масок # Поиск ближайших точек через KD‑tree pts_h = seg.get_masked_points(recon, frame=1, object=0) # нагреватель pts_d = seg.get_masked_points(recon, frame=2, object=1) # дверь dists, _ = scipy.spatial.KDTree(pts_d).query(pts_h, k=1) ReturnAnswer(float(dists.min()))
Практические сценарии применения
- Робототехника и эмбедд‑агенты – измерение метрических расстояний между объектами перед действием.
- Мультивидовая инспекция – восстановление направления объекта из нескольких камер.
- Анализ видео и 4D‑данных – отслеживание движения объектов и камеры.
- Вопрос‑ответ по внутренним сценам – «Где находится дверь относительно раковины?»
Поскольку система не требует дообучения, её можно подключить к уже развернутому VLM без новых данных и без дополнительного fine‑tuning.
Ссылки
- Оригинальная статья и PDF – https://spatialclaw.github.io/static/pdfs/spatialclaw.pdf
- GitHub‑репозиторий – https://github.com/NVlabs/SpatialClaw
- Depth Anything 3 – https://github.com/isl-org/Depth-Anything
- Segment Anything Model 3 – https://github.com/facebookresearch/segment-anything-3
