Bir videodaki kişinin hareketini — ya da bir fotoğraftaki pozu — Adobe Mixamo ile rig'lenmiş bir 3D karaktere aktarın.
Oyun geliştiricileri için: **tek kişilik** bir aksiyon videosu (ya da bir fotoğraf) ve bir Mixamo karakteri verin; araç önizleme videoları ile Blender veya Unity'ye doğrudan aktarabileceğiniz skin'lenmiş bir karakter dosyası (`.glb`) üretir.
> Motion2MixamoRig şu anda deneysel aşamadadır. 0.1.0 sürümü komut satırı pipeline'ıdır. Bu depo ayrıca aynı pipeline'ı harici bir Python ortamında çalıştıran bir Blender 4.2+ Extension da içerir. Eklentinin kurulumu ve kullanımı: [`blender_extension/README.md`](../../blender_extension/README.md).
Agent'lar işe [`AGENTS.md`](../../AGENTS.md) ile başlamalıdır.
https://github.com/user-attachments/assets/37c67642-f36c-4815-bcf3-028ed9546a2f
Başka bir demo:
https://github.com/user-attachments/assets/073f20c8-7283-4209-98e8-f247228bfd56
## Gereksinimler
Python 3.10+. Klonladıktan sonra bir virtualenv oluşturun ve bağımlılıkları kurun; ardından `m2mr` komutu kullanılabilir olur:
```bash
git clone https://github.com/MaxLiu22/Motion2MixamoRig.git
cd Motion2MixamoRig
python -m venv .venv && source .venv/bin/activate
# Bağımlılıkları ve bu projeyi kurun. chumpy (bağımlılık zincirindeki eski bir
# paket) setup betiğinde pip'i import ettiği için pip'in varsayılan izole
# build ortamında "No module named 'pip'" hatası verir. Önce izolasyon
# kapalıyken onu kurun, ardından bu projeyi kurun.
pip install --upgrade pip setuptools wheel \
&& pip install "numpy>=1.26" \
&& pip install --no-build-isolation "chumpy==0.70" \
&& pip install -e .
```
Çıkarım ağırlıkları (GVHMR vb.) bu adımda indirilmez. İlk `m2mr run` bunları `weights/` klasörüne indirir (~5 GB, yalnızca bir kez).
ffmpeg kurmanız önerilir (macOS: `brew install ffmpeg`, Ubuntu: `apt install ffmpeg`).
Pipeline onsuz da çalışır, ancak çıktı videoları **sessiz** olur ve tarayıcıda oynatılamaz.
## Çalıştırmadan önce: bunları `assets/` içine koyun
Bu depo bu dosyaları içermez; kendiniz edinmeniz gerekir. SMPL-X dosya adı tabloyla birebir aynı olmalıdır; FBX, video ve görsel adları serbesttir. Her çalıştırma için SMPL-X, bir Mixamo karakteri ve **ya** bir video **ya da** bir fotoğraf gerekir.
| Ne | Nereye | Nereden |
|---|---|---|
| SMPL-X vücut modeli | `assets/body_models/smplx/SMPLX_NEUTRAL.npz` | [SMPL-X](https://smpl-x.is.tue.mpg.de/) sitesine kaydolup indirin |
| Mixamo karakter FBX'i | `assets/mixamo/Y_Bot.fbx` | Bir Adobe hesabıyla [Mixamo](https://www.mixamo.com)'dan Y Bot'u (ya da Mixamo ile rig'lenmiş başka bir karakteri) indirin |
| Aksiyon videosu | `assets/video/.mp4` | **Tam olarak bir** kişinin net göründüğü ve **baştan ayağa sürekli kadrajda** olduğu bir klip (birden fazla dosya tutabilirsiniz; her çalıştırma en son ekleneni kullanır) |
| Poz fotoğrafı (isteğe bağlı) | `assets/image/.jpg` | **Tam olarak bir** kişinin net göründüğü ve **baştan ayağa kadrajda** olduğu bir fotoğraf. `--image` ile kullanın |
Not: Mixamo'dan inen dosyanın adı `Y Bot.fbx`'tir (**boşluklu**); tablodaki `Y_Bot.fbx`'ten (**alt çizgili**) tek bir karakter farklıdır.
Adını alt çizgili biçime çevirirseniz varsayılan rig olur (`--rig` olmadan `m2mr run`). Boşluğu bırakmak da sorun değildir — `Y_Bot.fbx` yoksa `assets/mixamo/` içindeki ilk `.fbx` kullanılır.
`assets/video/` birden fazla video içerebilir. `--video` ya da `--image` verilmezse çalıştırma `assets/video/` içine **en son eklenen** dosyayı kullanır; bu klasör boşsa `assets/image/` içindeki en yeni fotoğrafa geçer.
Her klip ya da fotoğrafta yalnızca bir kişi olmalı ve **baştan ayağa kadrajda** görünmelidir — kenarlarda kesik olmamalıdır. Kadrajda iki kişi varsa `m2mr doctor` / `m2mr run` çıkarım adımından önce durur.
## Hızlı Başlangıç
Sonuçlar `outputs/_/` altına yazılır. Video çalıştırmaları `videos/`, fotoğraf çalıştırmaları `images/` klasörüne yazar.
### 1. Varlıkları ve ortamı kontrol edin
Eksik olan her şey, nereden indirileceği ve nereye konacağıyla birlikte yazdırılır.
```bash
m2mr doctor
```
### 2. İlk çalıştırma: ekranda bir sonuç görün
Hiçbir parametre verilmezse **`assets/video/` içindeki en yeni dosya** ve `assets/mixamo/Y_Bot.fbx` kullanılır.
```bash
m2mr run
```
Yavaş adım budur. İlk çalıştırma ~5 GB çıkarım ağırlığını indirir (yalnızca bir kez), ardından videodan insan hareketini çıkarır.
CPU'da ~30 saniyelik bir klibin çıkarımı yaklaşık 8–15 dakika sürer; ağırlıklar hazırken benzer uzunluktaki sonraki çalıştırmalar yaklaşık 3–5 dakika sürer.
Retargeting ve render genellikle bir iki dakika sürer. Sonraki bölümdeki `--skeleton` ile bir iskeleti yeniden kullanmak çıkarımı tamamen atlar ve birkaç on saniyede biter.
### 3. Aynı hareket, farklı karakter
Mixamo'dan başka bir karakteri `assets/mixamo/` içine indirin. **Yalnızca `--rig` ile yeniden çalıştırmayın** — bu, yavaş çıkarımı tekrarlar.
Önceki bir çalıştırmanın iskeletini yeniden kullanmak için `--skeleton` verin; dakikalar birkaç on saniyeye iner:
```bash
m2mr run --skeleton outputs//skeleton_motion.npz --rig assets/mixamo/Vampire.fbx
```
### 4. Farklı bir video
`--video` klibi seçer. `--rig` ile serbestçe birleştirilebilir.
```bash
m2mr run --video assets/video/dance.mp4 --rig assets/mixamo/Vampire.fbx
```
### 5. Bir fotoğraf (sabit poz)
`--image`, tek bir kişinin fotoğrafından **sabit bir 3D poz** çıkarır ve onu bir video çalıştırmasıyla aynı şekilde Mixamo karakterine retarget eder. Önizlemeler `images/` içindeki dört görseldir (video çalıştırmasıyla aynı görünümler), ayrıca sola/sağa dönen bir yörünge klibi `before_after_360_compare.mp4` vardır. Aynı anda `--video` vermeyin.
```bash
m2mr run --image assets/image/pose.jpg
m2mr run --image assets/image/pose.jpg --rig assets/mixamo/Vampire.fbx
```
Yol verilmeden kullanılan `--image`, `assets/image/` içine en son eklenen dosyayı kullanır.
## Çıktılar
Her `m2mr run`, **komutun başladığı zamana** göre adlandırılmış bir dizin oluşturur. Kök dizindeki dört dosya video ve fotoğraf için aynıdır; yalnızca önizleme klasörü değişir.
```
outputs/20260829_193205_dance/ # fotoğraf için …_pose/
├── run.json # başlangıç zamanı, girdiler, tam komut
├── skeleton_motion.npz # 3D insan iskeleti (--skeleton ile yeniden kullanın)
├── mixamo_rotations.npz # kemik başına Mixamo rotasyonları
├── mixamo_character.glb # skin'lenmiş karakter, Blender / Unity'ye aktarın
└── videos/ veya images/ # önizlemeler — girdiye göre
```
**Video girdisi** `videos/` klasörüne yazar (klibin en-boy oranıyla aynı):
```
videos/
├── human_skeleton.mp4 # yeniden oluşturulan 3D insan iskeleti
├── mixamo_skeleton.mp4 # Mixamo rig iskeleti
├── mixamo_character.mp4 # skin'lenmiş Mixamo karakteri
└── compare.mp4 # 2×2: orijinal (sol üst) / Mixamo iskeleti (sağ üst)
# insan iskeleti (sol alt) / karakter (sağ alt)
```
**Fotoğraf girdisi** bunun yerine `images/` klasörüne yazar (aynı dört görünüm ve bir tam tur dönüş):
```
images/
├── human_skeleton.png # yeniden oluşturulan 3D insan iskeleti
├── mixamo_skeleton.png # Mixamo rig iskeleti
├── mixamo_character.png # skin'lenmiş Mixamo karakteri
├── compare.png # 2×2: orijinal (sol üst) / Mixamo iskeleti (sağ üst)
│ # insan iskeleti (sol alt) / karakter (sağ alt)
└── before_after_360_compare.mp4 # sol: orijinal fotoğraf
# sağ: rig etrafında 10°'lik adımlarla yörünge (tam bir tur)
```
`mixamo_character.glb` dosyasını Blender'da açın: File → Import → glTF 2.0 (.glb/.gltf). Kamera boş bir alana bakıyorsa karakter mesh'ini seçip View → Frame Selected kullanın. Baş ve ellerdeki küre kümesi kemik gösterimidir, mesh değildir: Outliner'da **Icosphere** ve **armature**'ü gizleyin; skin'lenmiş mesh'i görünür bırakın. Oynatmanın kaynakla eşleşmesi için sahnenin FPS'ini ve timeline'ın son karesini `run.json` (`fps`, `n_frames`) değerlerine göre ayarlayın. Bir video çalıştırmasını `videos/mixamo_character.mp4` ile, bir fotoğraf çalıştırmasını `images/mixamo_character.png` ya da yörünge klibiyle karşılaştırın.
## Lisans
Bu deponun kodu Apache-2.0 lisanslıdır. Kendi indirdiğiniz varlıkların kendi koşulları vardır ve bu depoyla birlikte yeniden dağıtılmamalıdır:
- **SMPL-X**: MPI erişim kontrollü; varsayılan olarak ticari olmayan araştırma / eğitim / sanat; ticari kullanım için ayrı bir anlaşma gerekir
- **Mixamo FBX**: yayınlanan bir üründe kullanılabilir; ham FBX'i bir varlık paketi olarak yeniden dağıtmayın
- **GVHMR ve diğer çıkarım ağırlıkları**: ilk `m2mr run` sırasında `weights/` içine otomatik indirilir, her birinin kaynak projesinin lisansı altındadır
## İletişim
Bir sorunla karşılaşırsanız, yerel kurulumu tamamlamak için yardıma ihtiyacınız olursa ya da iş birliği hakkında konuşmak isterseniz şu adrese e-posta gönderin:
[maxliu2022sz@gmail.com](mailto:maxliu2022sz@gmail.com)