# Motion2MixamoRig

![Motion2MixamoRig](../assets/repo_poster.png)

<p align="center">
  <a href="README.zh-CN.md">中文</a> · <a href="../../README.md">English</a> · <a href="README.ko.md">한국어</a> · <a href="README.ja.md">日本語</a> · <a href="README.de.md">Deutsch</a> · <a href="README.ru.md">Русский</a> · العربية · <a href="README.vi.md">Tiếng Việt</a> · <a href="README.fil.md">Filipino</a> · <a href="README.th.md">ไทย</a> · <a href="README.fr.md">Français</a> · <a href="README.es-MX.md">Español</a> · <a href="README.tr.md">Türkçe</a> · <a href="README.ne.md">नेपाली</a>
</p>

ينقل حركة شخص في مقطع فيديو — أو الوضعية في صورة ثابتة — إلى شخصية ثلاثية الأبعاد بهيكل تحريك Adobe Mixamo.

للمطوّرين في مجال الألعاب: قدّم فيديو حركة لـ**شخص واحد** (أو صورة) وشخصية Mixamo؛ يكتب معاينات وملف شخصية مكسوّة (`.glb`) يمكن وضعه في Blender أو Unity.

> Motion2MixamoRig لا يزال تجريبيًا. الإصدار 0.1.0 هو مسار سطر الأوامر. يضم هذا المستودع أيضًا امتداد Blender 4.2+ يشغّل المسار نفسه في Python خارجي. تثبيت الإضافة واستخدامها: [`blender_extension/README.md`](../../blender_extension/README.md).

ينبغي للوكلاء البرمجيين (Agents) البدء من [`AGENTS.md`](../../AGENTS.md).

https://github.com/user-attachments/assets/37c67642-f36c-4815-bcf3-028ed9546a2f

<p align="center">
  <sub>افتح <a href="../assets/demo.mp4">demo.mp4</a> في هذا المستودع.</sub>
</p>

عرض توضيحي آخر:

https://github.com/user-attachments/assets/073f20c8-7283-4209-98e8-f247228bfd56

## المتطلبات

يلزم توفر Python 3.10+. بعد الاستنساخ، أنشئ بيئة افتراضية وثبّت الاعتماديات؛ يصبح أمر `m2mr` متاحًا بعد ذلك:

```bash
git clone https://github.com/MaxLiu22/Motion2MixamoRig.git
cd Motion2MixamoRig
python -m venv .venv && source .venv/bin/activate

# ثبّت الاعتماديات وهذا المشروع. حزمة chumpy (قديمة في سلسلة الاعتماديات)
# تستورد pip في سكربت الإعداد، فيفشل البناء المعزول الافتراضي لـ pip
# برسالة "No module named 'pip'". ثبّتها أولًا مع إيقاف العزل
# (--no-build-isolation)، ثم ثبّت هذا المشروع.
pip install --upgrade pip setuptools wheel \
  && pip install "numpy>=1.26" \
  && pip install --no-build-isolation "chumpy==0.70" \
  && pip install -e .
```

أوزان الاستدلال (GVHMR وغيرها) لا تُنزَّل في هذه الخطوة. أول `m2mr run` يسحبها إلى `weights/` (حوالي 5 غيغابايت، مرة واحدة فقط).

يُفضَّل تثبيت ffmpeg (macOS: `brew install ffmpeg`، Ubuntu: `apt install ffmpeg`).
يعمل مسار المعالجة بدونه، لكن مقاطع الإخراج ستكون **صامتة** ولن تُشغَّل في المتصفح.

## قبل التشغيل: ضع هذه في `assets/`

هذا المستودع لا يتضمّن هذه الملفات؛ ينبغي جلبها بنفسك. يجب أن يطابق اسم ملف SMPL-X الجدول حرفيًا؛ أما أسماء FBX والفيديو والصورة فحرة. يحتاج التشغيل إلى SMPL-X وشخصية Mixamo و**إما** فيديو **أو** صورة.

| ماذا | أين | من أين |
|---|---|---|
| نموذج جسم SMPL-X | `assets/body_models/smplx/SMPLX_NEUTRAL.npz` | سجّل في [SMPL-X](https://smpl-x.is.tue.mpg.de/) ثم نزّله |
| ملف FBX لشخصية Mixamo | `assets/mixamo/Y_Bot.fbx` | بحساب Adobe نزّل Y Bot (أو أي شخصية بهيكل Mixamo) من [Mixamo](https://www.mixamo.com) |
| فيديو الحركة | `assets/video/<your_clip>.mp4` | مقطع فيه **شخص واحد بالضبط** ظاهر بوضوح، **من الرأس إلى القدمين داخل الإطار طوال المقطع** (يمكن وضع عدة ملفات؛ كل تشغيل يستخدم آخر ملف أُضيف) |
| صورة وضعية (اختياري) | `assets/image/<your_photo>.jpg` | صورة فيها **شخص واحد بالضبط** ظاهر بوضوح، **من الرأس إلى القدمين داخل الإطار**. مع `--image` |

ملاحظة: ملف التنزيل من Mixamo اسمه `Y Bot.fbx` (**مسافة**)، ويختلف بحرف واحد عن `Y_Bot.fbx` (**شرطة سفلية**) في الجدول.
أعد تسميته بالشرطة السفلية فيصبح الهيكل الافتراضي (`m2mr run` دون `--rig`). الإبقاء على المسافة جائز أيضًا — إن غاب `Y_Bot.fbx` يُستخدم أول `.fbx` في `assets/mixamo/`.

يمكن وضع عدة فيديوهات في `assets/video/`. دون `--video` أو `--image` يستخدم التشغيل **آخر ملف أُضيف إلى `assets/video/`**؛ إن كان المجلد فارغًا يعود إلى أحدث صورة في `assets/image/`.
يجب أن يظهر في كل مقطع أو صورة شخص واحد فقط، **من الرأس إلى القدمين داخل الإطار** — دون قص عند الحواف. يتوقف `m2mr doctor` / `m2mr run` قبل الاستخراج إن ظهر شخصان.

## البدء السريع

النتائج في `outputs/<وقت-التشغيل>_<المصدر>/`. تشغيل الفيديو يكتب `videos/`؛ تشغيل الصورة يكتب `images/`.

### 1. تحقق من الأصول والبيئة

يُطبع الناقص مع مصدر التنزيل ومكان الوضع.

```bash
m2mr doctor
```

### 2. أول تشغيل: إظهار نتيجة على الشاشة

دون خيارات، يُستخدم **أحدث ملف في `assets/video/`** و`assets/mixamo/Y_Bot.fbx`.

```bash
m2mr run
```

هذه الخطوة الأبطأ. أول تشغيل ينزّل حوالي 5 غيغابايت من أوزان الاستدلال (مرة واحدة)، ثم يستخرج حركة الإنسان من الفيديو.
على المعالج المركزي (CPU)، يستغرق استخراج مقطع مدته نحو 30 ثانية حوالي 8–15 دقيقة؛ التشغيلات اللاحقة بطول مشابه مع وجود الأوزان تستغرق حوالي 3–5 دقائق.
إعادة توجيه الحركة والتصيير عادة دقيقة أو دقيقتان. إعادة استخدام الهيكل بـ `--skeleton` في القسم التالي تتخطى الاستخراج بالكامل وتنتهي خلال عشرات الثواني.

### 3. الحركة نفسها، شخصية مختلفة

نزّل شخصية أخرى من Mixamo إلى `assets/mixamo/`. **لا تُعِد التشغيل باستخدام `--rig` فقط** — ذلك يكرر الاستخراج البطيء.
استخدم `--skeleton` لإعادة استخدام هيكل تشغيل سابق؛ الدقائق تصبح عشرات الثواني:

```bash
m2mr run --skeleton outputs/<previous-run-dir>/skeleton_motion.npz --rig assets/mixamo/Vampire.fbx
```

### 4. فيديو مختلف

`--video` يختار المقطع. ويمكن جمعه مع `--rig` بحرية.

```bash
m2mr run --video assets/video/dance.mp4 --rig assets/mixamo/Vampire.fbx
```

### 5. صورة ثابتة (وضعية ساكنة)

`--image` يستعيد **وضعية ثلاثية الأبعاد ساكنة** من صورة لشخص واحد، ثم ينقلها إلى شخصية Mixamo كما يفعل تشغيل الفيديو. المعاينات أربع صور في `images/` (نفس المناظر كتشغيل الفيديو) إضافة إلى مقطع المدار يمين/يسار `before_after_360_compare.mp4`. لا تُجمع مع `--video`.

```bash
m2mr run --image assets/image/pose.jpg
m2mr run --image assets/image/pose.jpg --rig assets/mixamo/Vampire.fbx
```

`--image` دون مسار يستخدم آخر ملف أُضيف إلى `assets/image/`.

## المخرجات

كل `m2mr run` ينشئ مجلدًا باسم **وقت بدء الأمر**. الملفات الأربعة في الجذر واحدة للفيديو والصورة؛ يتغيّر مجلد المعاينة فقط.

```
outputs/20260829_193205_dance/          # تشغيل الصورة: …_pose/
├── run.json                            # وقت البدء، المدخلات، الأمر الكامل
├── skeleton_motion.npz                 # هيكل إنسان ثلاثي الأبعاد (إعادة استخدام بـ --skeleton)
├── mixamo_rotations.npz                # دورانات عظام Mixamo لكل عظم
├── mixamo_character.glb                # شخصية مكسوّة، استيراد إلى Blender / Unity
└── videos/   أو   images/              # المعاينات — حسب المدخل
```

**إدخال الفيديو** يكتب `videos/` (نسبة العرض إلى الارتفاع نفسها كالمقطع):

```
videos/
├── human_skeleton.mp4                  # هيكل الإنسان الثلاثي المستعاد
├── mixamo_skeleton.mp4                 # هيكل Mixamo
├── mixamo_character.mp4                # شخصية Mixamo المكسوّة
└── compare.mp4                         # 2×2: الأصل (أعلى اليسار) / هيكل Mixamo (أعلى اليمين)
                                        #      هيكل الإنسان (أسفل اليسار) / الشخصية (أسفل اليمين)
```

**إدخال الصورة** يكتب `images/` بدلًا من ذلك (نفس المناظر الأربعة مع مدار):

```
images/
├── human_skeleton.png                  # هيكل الإنسان الثلاثي المستعاد
├── mixamo_skeleton.png                 # هيكل Mixamo
├── mixamo_character.png                # شخصية Mixamo المكسوّة
├── compare.png                         # 2×2: الأصل (أعلى اليسار) / هيكل Mixamo (أعلى اليمين)
│                                       #      هيكل الإنسان (أسفل اليسار) / الشخصية (أسفل اليمين)
└── before_after_360_compare.mp4        # اليسار: الصورة الأصلية
                                        # اليمين: مدار 10° حول الهيكل (دورة كاملة)
```

افتح `mixamo_character.glb` في Blender: File → Import → glTF 2.0 (.glb/.gltf). إن وُجّهت الكاميرا إلى فراغ، حدّد شبكة الشخصية ثم View → Frame Selected. مجموعة الكرات على الرأس واليدين هي عرض للعظام وليست الشبكة: في Outliner أخفِ **Icosphere** و**armature** واترك الشبكة المكسوّة ظاهرة. اضبط FPS المشهد وإطار نهاية الخط الزمني من `run.json` (`fps` و`n_frames`) حتى تطابق مدة المصدر. في تشغيل الفيديو قارن مع `videos/mixamo_character.mp4`، وفي تشغيل الصورة مع `images/mixamo_character.png` أو مقطع المدار.

## الرخصة

شيفرة هذا المستودع Apache-2.0. للأصول التي تنزّلها شروطها الخاصة، ويجب ألا تُعاد توزيعها مع هذا المستودع:

- **SMPL-X**: يخضع لقيود MPI؛ الاستخدام الافتراضي بحث / تعليم / فن غير تجاري؛ الاستخدام التجاري يحتاج اتفاقًا منفصلًا
- **Mixamo FBX**: جائز في منتج نهائي؛ يُحظر إعادة توزيع ملف FBX الخام كحزمة أصول
- **GVHMR وأوزان الاستدلال الأخرى**: تُنزَّل تلقائيًا إلى `weights/` عند أول `m2mr run`، وفق رخصة كل مصدر

## التواصل

إن واجهت مشكلة، أو احتجت إلى مساعدة لإكمال الإعداد المحلي، أو رغبت في الحديث عن التعاون، يُرجى المراسلة على:
[maxliu2022sz@gmail.com](mailto:maxliu2022sz@gmail.com)