kimodo.cpp README

The project's README from github.com/localai-org/kimodo.cpp. As one markdown file: README.md.

kimodo.cpp

GGML/C++ implementation of NVIDIA's Kimodo text-to-motion model.

Status

The five released Kimodo motion checkpoints accept either a UTF-8 prompt or a precomputed LLM2Vec embedding and generate local rotations plus root translations on CPU or Vulkan:

NVIDIA's Python API expands SOMA's predicted 30 joints to a relaxed-hand 77-joint presentation skeleton. The native API currently returns the 30 joints the model actually predicts. The text encoder uses eight-layer Vulkan chunks by default; set KIMODO_TEXT_LAYER_CHUNK=1..32 to tune VRAM use.

Included: checked GGUF loading, safetensors conversion, DDIM sampling, C/C++ APIs, conditioned multi-prompt transitions, CPU/Vulkan parity tests, skeleton-only GLB export, and a local text-to-motion demo. General constraint input, 77-joint SOMA expansion, skinned-mesh GLB export, and quantised models are not implemented yet.

Build and test on Linux

Install a C++23 compiler, CMake 3.25+, Ninja, Python 3 with the Hugging Face CLI (pip install huggingface_hub), and the Vulkan loader/headers for Vulkan support. GGML is a pinned Git submodule:

git submodule update --init --recursive
scripts/download_gguf_weights.sh --output "$PWD" --model soma-rp-v1.1
cmake --preset debug
cmake --build --preset debug
ctest --preset debug

The standard test suite requires the local motion GGUF, text bundle, and fixtures. It never downloads weights by itself. release, asan-ubsan, and fuzz presets are also available.

Nix is optional and provides these dependencies reproducibly:

nix develop path:. --command cmake --preset debug
nix develop path:. --command cmake --build --preset debug

For sanitizer work:

nix develop path:. --command cmake --preset asan-ubsan
nix develop path:. --command cmake --build --preset asan-ubsan
nix develop path:. --command env \
  LD_LIBRARY_PATH="$PWD/build/asan-ubsan/ggml/src:$PWD/build/asan-ubsan/ggml/src/ggml-vulkan:$LD_LIBRARY_PATH" \
  ASAN_OPTIONS=detect_leaks=0:abort_on_error=1 UBSAN_OPTIONS=print_stacktrace=1 \
  ctest --preset asan-ubsan --output-on-failure

Leak detection is disabled because Vulkan loader/driver allocations are global to the process. The GGUF parser fuzzer requires Clang.

API

include/kimodo/kimodo_capi.h is the C API. Model loading checks the motion GGUF and text bundle before inference. Use kimodo_generate_embedding for 4096 F32 values or kimodo_generate for text. Both return the selected model's root translations and local XYZW rotations; query the joint count from the result rather than assuming a fixed skeleton.

Demo

After building the debug preset and downloading the native GGUF bundle:

go run ./demo -addr 0.0.0.0:8094

Open http://localhost:8094. The left sidebar contains the prompt and a persistent history; choosing a previous animation restores its prompt for a new generation. Every successful animation also writes a standalone animation.glb beside its raw streams, for example demo-output/<animation-id>/animation.glb. It contains the selected animated node hierarchy (no mesh), ready to copy into a Three.js project. It is also available from /api/animations/<animation-id>/animation.glb while the demo is running.

Weights

Ready-to-run native GGML weights are published under the Hugging Face LocalAI-io organisation (not GitHub's localai-org). The reusable Llama-3-Kimodo-GGML text encoder is separate from the four redistributable motion repositories, each of which preserves a one-to-one relationship to its NVIDIA upstream:

Download one or repeat --model to install several:

scripts/download_gguf_weights.sh --output "$PWD" \
  --model soma-rp-v1.1 --model g1-rp-v1

The installer verifies each published manifest and SHA-256 hashes. Use --motion-only when supplying a precomputed 4096-float LLM2Vec embedding. SMPL-X RP is deliberately absent from the published-weight installer: its internal-R&D licence prohibits distributing derivative models, so it must be converted locally after the user obtains the upstream checkpoint under its gated terms.

The text bundle includes converted Meta Llama 3 material and retains its separate terms. Review every selected model card before downloading or redistributing.

License

The C++ port and its original tooling are licensed under Apache-2.0; see LICENSE. GGML and the model weights retain their respective licences.

Motion checkpoint Upstream terms Commercial use
Kimodo-SMPLX-RP-v1 NVIDIA Internal Scientific Research and Development Model License No; internal, non-production R&D only; derivative model redistribution is prohibited
SOMA RP/SEED v1.1 NVIDIA Open Model License Permitted by the model licence
G1 RP/SEED v1 NVIDIA Open Model License Permitted by the model licence

The SMPL-X warning is about NVIDIA's trained Kimodo checkpoint, not the mere fact that its output uses an SMPL-X-shaped 22-joint hierarchy. Converting that checkpoint to GGUF is a new runtime representation of the same weights and does not replace its licence. Skeleton names, parent links, and the Apache-2.0 port source do not by themselves make the SOMA or G1 checkpoints non-commercial. The SMPL-X Hugging Face metadata, model card, and access terms identify the internal-R&D licence; treat those restrictive terms as controlling even though an apparently inconsistent LICENSE file has also appeared in that upstream repository.

Regenerating the bundle

This is only needed to reproduce a conversion. The SMPL-X checkpoint and Llama base model are gated. After accepting their Hugging Face licences and authenticating, download the exact revisions and hash manifests with:

nix develop path:. --command hf auth login
scripts/download_weights.sh --output "$PWD/models" --with-text \
  --model smplx-rp-v1 --model soma-rp-v1.1 --model soma-seed-v1.1 \
  --model g1-rp-v1 --model g1-seed-v1

Convert the local LLM2Vec model to the native component bundle with:

nix develop path:. --command scripts/convert_llm2vec_bundle.sh \
  "$PWD/models/llama3-8b-instruct-base" "$PWD/generated/llm2vec-text-bundle"

Validate a prospective release without network access, then explicitly upload it from an account allowed to publish to LocalAI-io:

nix develop path:. --command python scripts/publish_gguf.py --component motion \
  --motion-model soma-rp-v1.1
nix develop path:. --command python scripts/publish_gguf.py --component motion \
  --motion-model soma-rp-v1.1 --upload --confirm-upstream-licences
nix develop path:. --command python scripts/publish_gguf.py --component text \
  --upload --confirm-upstream-licences

kimodo.cpp (localai-org/kimodo.cpp)

Searching Database…

913 ·GitHub
Kimodo.cpp
Что это?Это C++/GGML-порт модели NVIDIA Kimodo text-to-motion: вы даёте ей промпт на естественном языке, а она генерирует скелетную анимацию (вращения суставов и перемещения корня).
Это библиотека или готовое к запуску приложение?Это нативная библиотека на C/C++ с C API, плюс CLI установщика моделей и локальное веб-демо, экспортирующее анимации в файлы GLB.
Как его запустить?Заберите зафиксированный сабмодуль GGML, соберите с CMake/Ninja, затем скачайте один из опубликованных GGML-чекпоинтов с помощью установщика моделей (повторяйте --model, чтобы взять несколько), прежде чем запускать демо или API.
Что нужно установить перед сборкой?Компилятор C++23, CMake 3.25+, Ninja, Python 3 с Hugging Face CLI и загрузчик/заголовки Vulkan, если хотите ускорение через Vulkan; Nix может воспроизводимо предоставить всё это.
Есть ли подвох перед использованием модели SMPL-X?SMPL-X RP намеренно исключён из автоматического установщика, поскольку внутренняя лицензия NVIDIA на R&D запрещает распространение производных моделей, так что вам придётся конвертировать его самостоятельно после принятия закрытых (gated) условий оригинала. Универсальный ввод ограничений (constraint input), полное 77-суставное расширение SOMA, экспорт GLB со скиннинговым мешем и квантованные модели тоже пока не реализованы.
Он работает и на Windows и на macOS?Инструкции по сборке и тестированию в README рассчитаны только на Linux.
Какие скелеты он умеет анимировать?Пять чекпоинтов покрывают три семейства скелетов: SMPL-X RP (22 сустава), SOMA RP/SEED (компактный управляющий скелет из 30 суставов, расширяемый до 77 суставов в Python API NVIDIA) и G1 RP/SEED (34 сустава робота Unitree G1).
Что выдаёт демо?Каждая успешная генерация записывает автономный animation.glb с анимированной иерархией узлов (без меша) рядом со своими сырыми выходными потоками, готовый к вставке в сцену Three.js, а файл также раздаётся через HTTP API демо.
Можно ли пропустить текст и скормить заранее вычисленный эмбеддинг?Да — передайте заранее вычисленный LLM2Vec-эмбеддинг из 4096 float через C-функцию kimodo_generate_embedding или флаг --motion-only установщика вместо сырого текстового промпта.
Откуда берутся веса моделей?Готовые к запуску GGML-веса четырёх распространяемых чекпоинтов размещены на Hugging Face в организации LocalAI-io, отдельно от переиспользуемого текстового энкодера Llama-3-Kimodo-GGML.
What are similar projects?skin-tokens.cpp, UniMate, image-to-3dlab, TRELLIS, NoGraphicsAPI, llama.cpp, motion-bricks.cpp, stable-diffusion.cpp
Which topics is it in?text-to-3d, character-animation, motion, computer-graphics, cmake, vulkan, 3d, animation, nvidia, huggingface, cpp, c++
Creator
localai-org
Size
0.4 MB
Stars
913
Updated
CommitSep 17
Age
1mo
Commits · 90 Days