🇷🇺 | ᴇɴ

Semantic Motion Generation (SMoG): A PyTorch Implementation

🚶

Semantic Motion Generation (SMoG) — это модель для синтеза движений по тексту, использующая семантику CLIP и архитектуру Transformers с улучшением на основе сетей Колмогорова-Арнольда (KAN) для генерации реалистичных и разнообразных 3D-движений человека. В отличие от иных подходов, SMoG заменяет линейные слои в трансформерах на KANLayer, обеспечивая адаптивное нелинейное обучение и превосходное соответствие между текстом и движением. Она генерирует последовательность движений 3D модели SMPL на каждом кадре.

Особенности реализации:

• синтез движений на базе CLIP для семантической согласованности текста и анимации;
• архитектура KAN-Transformer с обучаемыми сплайновыми функциями активации (B-сплайны) вместо линейных слоев MLP;
• поддержка генерации движений для различных сценариев (танцы, спорт, повседневная активность) по свободным текстовым описаниям;
• совместимость с CPU и GPU (на GPU значительно быстрее).

Результат

💡 Плановые улучшения

[x] Релиз чекпоинтов

[ ] Добавить поддержку конфигураций .yaml с помощью Hydra (необходимо исключить argparse)

📁 Структура проекта

smog/
├── assets/                      # Вспомогательные файлы для тестирования и демонстрации
├── data/                        # Предобработанные данные (AMASS датасет в .pt и .npy формате)
├── exps/                        # 🔥 Чекпоинты и логгирование экспериментов
├── models/                      # Файлы моделей SMPL и SMPL+H
├── prepare/                     # Скрипт для загрузки SMPL и SMPL+H
├── src/                         # Исходный код проекта
    ├── datasets/                # Скрипты для обработки и загрузки данных (парсинг файлов .npz)
    ├── models/                  # Архитектуры моделей
        ├── architectures/       # Transformers + KAN
        ├── modeltype/           # CLIP
        ├── tools/               # Вспомогательные функции
    ├── parser/                  # Обработка аргументов командной строки
    ├── train/                   # Основной цикл обучения (с возможностью дообучения)
    ├── utils/                   # Вспомогательные функции (например, классификация действий, создание gif-анимации)
    ├── visualize/               # Скрипты для визуализации работы модели (рендер)
    ├── __init__.py              
    ├── config.py                # Фиксация направления суставов и их групп
├── visuals/                     # Изображения для проекта
├── evaluate_model.py            # 🐍 Метрики оценки модели и их логгирование в wandb
├── download_smpl_files.sh       # Скрипт для загрузка файлов модели SMPL (дубль prepare/)
├── environment.yml              # ♻️ Описание зависимостей для создания окружения Conda
├── README.md                    # Описание проекта и инструкции по использованию на русском языке
├── README_EN.md                 # Описание проекта и инструкции по использованию на английском языке

🛢️ Данные

---

Набор данных AMASS (Archive of Motion Capture as Surface Shapes) представляет собой важнейший ресурс для исследователей и разработчиков в области анимации, биомеханики и машинного обучения, объединяющий данные захвата движений из различных академических источников для обеспечения широкого спектра записанных действий - от ходьбы до сложных жестов.

Датасет фиксирует 3D-координаты суставов с помощью передовых технологий отслеживания движений, сохраняя временные последовательности, где каждая строка представляет собой временную метку, а столбцы - подробные координаты x, y, z для суставов тела, отформатированные в npz (стандартный формат для сохранения на диск нескольких массивов NumPy. Файл в этом формате — это zip-файл, содержащий несколько файлов .npy, по одному для каждого массива) для эффективной работы с большими объемами данных.

Примечательно, что в AMASS интегрированы метки действий, антропометрические параметры и синхронизированные данные датчиков, что позволяет проводить детальные биомеханические исследования и обучать модели глубокого обучения, такие как LSTM или Transformers, для предсказания позиционирования трехмерного меша. Еще одной критической особенностью данных является то, что они крайне масштабируемы,так как он охватывает десятки тысяч движений. Лицензия AMASS определена для академических исследований, допуская некоммерческое использование с указанием авторства, в то время как для коммерческих приложений требуется явное разрешение.

🚶 SMoG Model

В основе SMoG лежит MotionCLIP – 3D-автоэнкодер движений, обученный воссоздавать образы с помощью естественного языка. Задействуется скрытое пространство (latent space), относящееся к абстрактному, но сжатому представлению особенностей (признаков) данных, нетривиально присутствующих во входном пространстве. Если попытаться визуализировать latent space, то оно будет представлять собой набор точек, расположенных ближе друг к другу. Важно обратить внимание на то, что это позволяет в некоторой степени отказаться от классической разметки данных, так как в данном методе используется подход контрастивного обучения, направленный на подготовку к способности различать приближение, тождественность или различие между определенными текстами и движениями. В процессе обучения, пары действия и текста сопоставляются на наличие сходства (положительные), либо несходные (негативные). Основополагающим стремлением является максимизация сходства между векторами позитивных пар и минимизация между негативными.

Именно скрытое пространство призвано осуществить семантическое выравнивание между вводимым текстом и генерируемым движением, что приводит к более осмысленному процессу интерпретации. Например, введя произвольное описание, допустим, "крылья" или отметив культурную ссылку, возможно получить несущее смысл движение, осознанное, в рамках контекста: взмах руками, имитирующий взмахи крыльев, без явного представления примеров в тренировочных данных.

MotionCLIP — это инновационная нейросетевая модель, предназначенная для генерации реалистичных 3D-человеческих движений на основе семантических текстовых описаний. Её работа основывается на комбинации автоэнкодера движения и пространства CLIP (Contrastive Language-Image Pretraining), что позволяет связывать текстовые метки с визуальными паттернами движений. Рассмотрим ключевые аспекты её функционирования подробнее.

SMoG состоит из:

1. Автоэнкодер на базе Transformers (с добавлением KANLayer вместо линейных слоев):

   • энкодера, преобразующего входные данные о движении (например, позы скелета в 3D-пространстве) в латентное (скрытое) простанство;
   • декодера, восстанавливающего исходное движение из латентного вектора.
   • интеграция KANLayer в автоэнкодер, взамен стандартным линейным слоям.

Трансформеры эффективны для захвата долгосрочных зависимостей в данных, что критично для моделирования динамики человеческих движений, где временная согласованность - базис.

2. Выравнивание с CLIP-пространством:

   • модель обучается не только на реконструкцию движений, но и на выравнивание их латентных представлений с текстовыми метками в CLIP-пространстве

3. KAN-слой:

KANLayer, являющийся ключевым элементом архитектуры Kolmogorov–Arnold Networks (KAN), реализует гибридный подход к аппроксимации функций, основанный на теореме Колмогорова-Арнольда, утверждающей, что любую многомерную непрерывную функцию можно представить как суперпозицию одномерных функций, что в KANLayer достигается через комбинацию линейных преобразований и нелинейных B-сплайновых компонентов. Структурно слой состоит из двух параллельных ветвей: базовой , выполняющей линейное преобразование с активацией (по умолчанию — SiLU), и сплайновой , добавляющей нелинейность через адаптивные B-сплайны.

Сплайновая ветвь оперирует коэффициентами spline_weight, которые вычисляются путем интерполяции B-сплайнов на фиксированной сетке grid, разбивающей входной диапазон (например, [-1, 1]) на grid_size интервалов. Порядок сплайна (spline_order) определяет их гладкость и сложность, а метод b_splines реализует рекурсивную формулу Кокса-де Бора для построения базисных функций.

Инициализация сплайновых весов включает добавление шума (scale_noise) и решение задачи наименьших квадратов в методе curve2coeff, что позволяет приблизить начальные значения к заданным точкам функции. Для повышения устойчивости обучения параметр enable_standalone_scale_spline позволяет независимо масштабировать сплайновые коэффициенты через spline_scaler. Во время прямого прохода входные данные обрабатываются обеими ветвями: базовая генерирует линейный выход через активацию и матричное умножение, а сплайновая вычисляет нелинейное смещение, сворачивая B-сплайны с обучаемыми весами. Таким образом, результаты суммируются, формируя выходной тензор.

🗃️ Примеры анимаций

Wings	Swan Lake	Running	Opened the door and walked in	Lift the weights

Запуск проекта

🐍 Создание Conda-среды

Код был протестирован на Ubuntu 24.04 CUDA 12.8 + Python 3.8.11 + PyTorch 2.4.1+cu118

Настоятельно рекомендуется использовать данную conda-среду, чтобы избежать потенциальных проблем, в особенности на Windows, где могут возникать конфликты между библиотеками одних и тех же версий из-за различий в системных зависимостях и двоичной совместимости.

# Клонируйте репозиторий
git clone https://github.com/vonexel/smog.git

# Перейдите в корневую директорию проекта
cd ./smog

# Создайте и активируйте Conda-среду
conda env create -f environment.yml
conda activate smog

🚀 Начало работы

1. Загрузите предобработанный датасет

Предобработанный датасет AMASS -> ./data/amass_db

Если Вы предпочтете обработать данные самостоятельно, то следуйте следующей инструкции:

Загрузите и разархивируйте вышеуказанные наборы данных и разместите их соответствующим образом:

• AMASS -> ./data/amass (Загрузите версию SMPL+H для каждого набора данных отдельно, обратите внимание, что весь набор данных следует загружать с официального сайта AMASS)

• BABEL -> ./data/babel_v1.0_release

• Rendered AMASS images -> ./data/render

  Затем обработайте эти три набора данных в единый 3D-датасет вида (text, image, motion):

Для разбиения датасета AMASS, запустите:

python -m src.datasets.amass_parser --dataset_name amass

2. Загрузите модель тела SMPL

bash prepare/download_smpl_files.sh

Данный скрипт позволит загрузить SMPL нейтральную модель из данного github репозитория, а также прочие дополнительные файлы.

Дополнительно, загрузите расширенную SMPL+H модель (используется в проекте AMASS) из MANO, и поместите ее в ./models/smplh.

3. Обучение модели

python -m src.train.train --clip_text_losses cosine --clip_image_losses cosine --pose_rep rot6d \
--lambda_vel 100 --lambda_rc 100 --lambda_rcxyz 100 \
--jointstype vertices --batch_size 20 --num_frames 60 --num_layers 8 \
--lr 0.0001 --glob --translation --no-vertstrans --latent_dim 512 --num_epochs 100 --snapshot 10 \
--device <GPU DEVICE ID> \
--dataset amass \
--datapath ./data/amass_db/amass_30fps_db.pt \
--folder ./exps/smog

📌 Обученные модели будут сохранены в exp/smog/checkpoint_0000.pth.tar, а лог тренировок в exps/smog/training.txt

4. Генерация 3D-анимации

python -m src.visualize.text2motion ./exps/smog/checkpoint_0100.pth.tar --input_file assets/paper_texts.txt

📌 Для того, чтобы провести эксперимент на собственных текстах, создайте .txt файл, в котором каждая строка отражает желаемое движение и / или последовательность действий (используйте assets/paper_texts.txt в качестве примера) и укажите на него с помощью --input_file.

5. Оценка модели

python evaluate_model.py ./exps/smogx/checkpoint_0100.pth.tar --sample_size -1 --batch_size 32  --device cuda --project smog --run_name smog-metrics --n_runs 100

📦 Model Checkpoints

🏷️ Модель	🔗 Ссылка
exps/smog/checkpoint_0100.pth.tar	Лучшая модель (минимальные потери)

🔑 Ключевая особенность

KAN-слой с B-сплайнами

class KANLayer(nn.Module):
    def init(self, in_features, out_features, grid_size=5, spline_order=3, ...):
        ...
        self.spline_weight = nn.Parameter(torch.Tensor(out_features, in_features, grid_size + spline_order))
        ...
    def forward(self, x):
        ...
        bspline = self.b_splines(x_flat)
        spline_output = F.linear(bspline, self.scaled_spline_weight)
        output = base_output + spline_output
        ...

• Адаптивная нелинейность через B-сплайны:

В отличие от стандартных линейных слоев или активаций (ReLu, GELU), KANLayer использует B-сплайны для создания гладких, параметризуемых нелинейных преобразований. Это позволяет модели адаптироваться к сложным паттернам движения, улучшая аппроксимацию функций.

• Комбинация линейных и сплайновых весов:

Слой объединяет базовую линейную трансформацию (base_weight) и сплайновое смещение (spline_weight), что повышает выразительность модели без значительного увеличения числа параметров.

• Инициализация через задачу наименьших квадратов:

Метод curve2coeff инициализирует сплайн-веса, минимизируя ошибку интерполяции, что стабилизирует обучение на ранних этапах.

По итогу, KAN-слои улучшают способность модели к захвату динамики движений (например, плавных переходов между позами), что критично для задач анимации. Это особенно заметно в skelEmbedding энкодера, где входные данные сжимаются в латентное пространство с учётом скелетной структуры.

📊 Результаты по метрикам

Лучшая модель выделена подчеркиванием.

Метод	R@1	R@5	MMD	FCD
MotionCLIP	0.0004158	0.002079	0.57388	0.58497
SMoG (ours)	0.0004158	0.006237	0.020108	0.50885

Потери:

Метод	Vel-Loss	Text Cosine	rcxyz	rc	Mixed without CLIP	Mixed with CLIP	Mixed CLIP only	Image Cosine
MotionCLIP	0.00039165	0.2778	0.0065555	0.0070464	1.39936	1.89313	0.49378	0.21598
SMoG (ours)	0.00029719	0.27195	0.00066315	0.0014857	0.24461	0.73316	0.48855	0.2166

📚 Источники

1. Learning Transferable Visual Models From Natural Language Supervision
2. OpenAI CLIP simple implementation
3. MotionCLIP
4. AMASS: Archive of Motion Capture As Surface Shapes
5. KAN: Kolmogorov-Arnold Networks
6. KAN or MLP: A Fairer Comparison
7. An Efficient Implementation of Kolmogorov-Arnold Network

🤝 Благодарность

Код модели трансформатора и загрузчика данных основан на репозиториях ACTOR и MotionCLIP.

📄 Лицензия

Код распространяется под лицензией MIT LICENSE.

Обратите внимание, что используемые библиотеки CLIP, SMPL, SMPL-X, PyTorch3D, MotionCLIP и датасет имеют собственные лицензии, которые необходимо соблюдать.

✏️ Цитирование

Если вы считаете этот проект полезным, пожалуйста, оставьте звезду ⭐️ и процитируйте его, используя следующую запись BibTeX:

@Misc{smog,
  title =        {SMoG: Semantic Motion Generation - motion synthesis from text},
  author =       {Nikolai Mozgovoi},
  howpublished = {\url{https://github.com/vonexel/smog}},
  year =         {2025}
}