Retarget human motion from video to an Adobe Mixamo-rigged 3D character.
Python
Add Korean, Japanese, German, and Russian readme files
MaxLiu32af659ee2e4
diff --git a/README.de.md b/README.de.mdnew file mode 100644index 0000000..8678d74--- /dev/null+++ b/README.de.md@@ -0,0 +1,136 @@+# Motion2MixamoRig++++<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> · Deutsch · <a href="README.ru.md">Русский</a>+</p>++Überträgt die Bewegung einer Person aus einem Video auf einen Adobe-Mixamo-geriggten 3D-Charakter.++Für Spieleentwickler: ein Video mit **genau einer Person** und ein Mixamo-Charakter; Ausgabe sind Vorschauvideos plus eine Charakterdatei mit Skinning (`.glb`) für Blender oder Unity.++Agents beginnen mit [`AGENTS.md`](AGENTS.md).++https://github.com/user-attachments/assets/37c67642-f36c-4815-bcf3-028ed9546a2f++<p align="center">+ <sub><a href="demo.mp4">demo.mp4</a> in diesem Repository öffnen.</sub>+</p>++Weiteres Demo:++https://github.com/user-attachments/assets/073f20c8-7283-4209-98e8-f247228bfd56++## Voraussetzungen++Python 3.10+. Nach dem Klonen eine virtuelle Umgebung anlegen und Abhängigkeiten installieren; danach steht `m2mr` bereit:++```bash+git clone https://github.com/MaxLiu22/Motion2MixamoRig.git+cd Motion2MixamoRig+python -m venv .venv && source .venv/bin/activate++# Abhängigkeiten und dieses Projekt installieren. chumpy (ein altes Paket in der+# Abhängigkeitskette) importiert pip im Setup-Skript; das schlägt in pips+# isoliertem Build mit "No module named 'pip'" fehl. Zuerst ohne Isolation+# installieren (--no-build-isolation), dann dieses Projekt.+pip install --upgrade pip setuptools wheel \+ && pip install "numpy>=1.26" \+ && pip install --no-build-isolation "chumpy==0.70" \+ && pip install -e .+```++Inferenzgewichte (GVHMR usw.) werden hier nicht geladen. Der erste `m2mr run` zieht sie nach `weights/` (~5 GB, nur einmal).++ffmpeg wird empfohlen (macOS: `brew install ffmpeg`, Ubuntu: `apt install ffmpeg`).+Ohne ffmpeg läuft die Pipeline, aber die Ausgabevideos sind **stumm** und spielen im Browser nicht.++## Vor dem Lauf: drei Dinge nach `assets/`++Dieses Repository enthält diese Dateien nicht; sie müssen selbst besorgt werden. Der SMPL-X-Dateiname muss exakt zur Tabelle passen; FBX- und Videonamen sind frei.++| Was | Wohin | Woher |+|---|---|---|+| SMPL-X-Körpermodell | `assets/body_models/smplx/SMPLX_NEUTRAL.npz` | Bei [SMPL-X](https://smpl-x.is.tue.mpg.de/) registrieren und herunterladen |+| Mixamo-Charakter-FBX | `assets/mixamo/Y_Bot.fbx` | Mit Adobe-Konto Y Bot (oder einen anderen Mixamo-geriggten Charakter) von [Mixamo](https://www.mixamo.com) laden |+| Bewegungsvideo | `assets/video/<your_clip>.mp4` | Clip mit **genau einer** klar sichtbaren Person, **Kopf bis Fuß die ganze Zeit im Bild** (mehrere Dateien möglich; jeder Lauf nimmt die zuletzt hinzugefügte) |++Hinweis: Der Download von Mixamo heißt `Y Bot.fbx` (**Leerzeichen**) und weicht um ein Zeichen von `Y_Bot.fbx` (**Unterstrich**) in der Tabelle ab.+Umbenennen zum Unterstrich macht es zum Standard-Rig (`m2mr run` ohne `--rig`). Der Name mit Leerzeichen ist ebenfalls in Ordnung — fehlt `Y_Bot.fbx`, wird die erste `.fbx` in `assets/mixamo/` verwendet.++In `assets/video/` können mehrere Videos liegen. Ohne `--video` nimmt der Lauf die **zuletzt in diesen Ordner gelegte** Datei.+Jeder Clip darf nur eine Person zeigen, **Kopf bis Fuß die ganze Zeit im Bild** — nichts am Rand abgeschnitten. `m2mr doctor` / `m2mr run` prüfen Frames stichprobenartig und stoppen vor der Extraktion, wenn zwei Personen zu sehen sind.++## Schnellstart++Ergebnisse liegen in `outputs/<Laufzeit>_<Video>/`. Videos im Unterordner `videos/` ansehen.++### 1. Assets und Umgebung prüfen++Fehlendes wird mit Download-Ort und Zielpfad ausgegeben.++```bash+m2mr doctor+```++### 2. Erster Lauf: etwas auf dem Bildschirm++Ohne Flags: die **neueste Datei in `assets/video/`** und `assets/mixamo/Y_Bot.fbx`.++```bash+m2mr run+```++Das ist der langsame Schritt. Der erste Lauf lädt ~5 GB Inferenzgewichte (nur einmal), dann extrahiert er die menschliche Bewegung.+Auf CPU dauert ein ~30-Sekunden-Clip etwa 8–15 Minuten; spätere Läufe ähnlicher Länge mit vorhandenen Gewichten etwa 3–5 Minuten.+Retargeting und Rendering dauern meist ein bis zwei Minuten. Mit `--skeleton` im nächsten Abschnitt entfällt die Extraktion komplett, fertig in wenigen zehn Sekunden.++### 3. Gleiche Bewegung, anderer Charakter++Einen weiteren Charakter von Mixamo nach `assets/mixamo/` legen. **Nicht nur mit `--rig` neu starten** — das wiederholt die langsame Extraktion.+`--skeleton` verwendet das Skelett eines früheren Laufs; Minuten werden zu wenigen zehn Sekunden:++```bash+m2mr run --skeleton outputs/<previous-run-dir>/skeleton_motion.npz --rig assets/mixamo/Vampire.fbx+```++### 4. Ein anderes Video++`--video` wählt den Clip. Kombinierbar mit `--rig`.++```bash+m2mr run --video assets/video/dance.mp4 --rig assets/mixamo/Vampire.fbx+```++## Ausgaben++Jeder `m2mr run` legt ein Verzeichnis an, benannt nach **Startzeit des Befehls**:++```+outputs/20260829_193205_dance/+├── run.json # Startzeit, verwendetes Video / Rig, vollständiger Befehl+├── skeleton_motion.npz # 3D-Körperskelett (beim Rig-Wechsel wiederverwenden; keine Neu-Extraktion)+├── mixamo_rotations.npz # Mixamo-Rotationen pro Bone+├── mixamo_character.glb # Charakterdatei mit Skinning + Animation, Import in Blender / Unity+└── videos/ # gleiches Seitenverhältnis wie das Eingangsvideo+ ├── human_skeleton.mp4 # Körperskelett+ ├── mixamo_skeleton.mp4 # Mixamo-Rig-Skelett+ ├── mixamo_character.mp4 # Mixamo-Rig-Charakter+ └── compare.mp4 # 2×2: Original (oben links) / Mixamo-Skelett (oben rechts) / Körperskelett (unten links) / Charakter (unten rechts)+```++`mixamo_character.glb` in Blender öffnen: File → Import → glTF 2.0 (.glb/.gltf). Zeigt die Kamera ins Leere, den Charakter wählen und View → Frame Selected. Die Kugeln an Kopf und Händen sind die Knochenanzeige, nicht das Mesh: Armature wählen und unter Armature → Viewport Display die Shapes ausschalten. Das letzte Timeline-Frame auf die Cliplänge setzen, dann abspielen. Mit `videos/mixamo_character.mp4` desselben Laufs vergleichen.++## Lizenz++Der Code dieses Repositories ist Apache-2.0. Die selbst beschafften Assets haben eigene Bedingungen und dürfen nicht mit diesem Repo weitergegeben werden:++- **SMPL-X**: MPI-Zugang; Standard nichtkommerziell Forschung / Bildung / Kunst; kommerzielle Nutzung braucht eine eigene Vereinbarung+- **Mixamo FBX**: in einem Produkt erlaubt; das rohe FBX nicht als Asset-Pack weitergeben+- **GVHMR und andere Inferenzgewichte**: beim ersten `m2mr run` automatisch nach `weights/`, jeweils unter der Upstream-Lizenz++## Kontakt++Bei Problemen, wenn Hilfe beim lokalen Setup nötig ist oder Sie über eine Zusammenarbeit sprechen möchten, schreiben Sie an:+[[email protected]](mailto:[email protected])diff --git a/README.ja.md b/README.ja.mdnew file mode 100644index 0000000..6af8504--- /dev/null+++ b/README.ja.md@@ -0,0 +1,136 @@+# Motion2MixamoRig++++<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.de.md">Deutsch</a> · <a href="README.ru.md">Русский</a>+</p>++動画の人物の動きを、Adobe Mixamo rig の 3D キャラクターに移します。++ゲーム開発者向け:入力は**一人**の動作動画と Mixamo キャラクター。プレビュー動画と、Blender / Unity にそのまま入れられるスキン付きキャラクターファイル(`.glb`)を書き出します。++Agent は先に [`AGENTS.md`](AGENTS.md) を読んでください。++https://github.com/user-attachments/assets/37c67642-f36c-4815-bcf3-028ed9546a2f++<p align="center">+ <sub>このリポジトリの <a href="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 を import するため、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 GB、一度だけ)。++ffmpeg も推奨です(macOS: `brew install ffmpeg`、Ubuntu: `apt install ffmpeg`)。+なくても動きますが、出力動画は**無音**になり、ブラウザでは再生できません。++## 実行前:`assets/` に 3 つのファイルを入れてください++このリポジトリにはこれらのファイルは入っていません。自分で用意してください。SMPL-X のファイル名は下表と一字一句同じである必要があります。FBX と動画の名前は何でも構いません。++| 何を | どこへ | どこから |+|---|---|---|+| SMPL-X ボディモデル | `assets/body_models/smplx/SMPLX_NEUTRAL.npz` | [SMPL-X](https://smpl-x.is.tue.mpg.de/) で登録してダウンロード |+| Mixamo キャラクター FBX | `assets/mixamo/Y_Bot.fbx` | Adobe アカウントで [Mixamo](https://www.mixamo.com) から Y Bot(または他の Mixamo rig キャラクター)をダウンロード |+| 動作動画 | `assets/video/<your_clip>.mp4` | **一人だけ**、はっきり見え、**頭から足まで全編フレーム内**(複数可、実行ごとに最後に入れたファイルを使用) |++注意:Mixamo のダウンロード名は `Y Bot.fbx`(**スペース**)で、表の `Y_Bot.fbx`(**アンダースコア**)と一字違います。+アンダースコアにすればデフォルト rig になり、`m2mr run` は `--rig` なしでそれを使います。名前を変えなくても構いません——`Y_Bot.fbx` が無いときは `assets/mixamo/` の最初の `.fbx` を使います。++`assets/video/` には動画を複数置けます。`--video` を指定しないと、**このフォルダに最後に入れた**ファイルを使います。+各クリップは一人だけ、**頭から足まで全編フレーム内**に収まっている必要があります。はみ出してはいけません。`m2mr doctor` / `m2mr run` はフレームをサンプリングし、二人が写っていれば抽出に入らず止まります。++## クイックスタート++結果は `outputs/<実行時刻>_<動画名>/` です。動画を見るにはその中の `videos/` を開きます。++### 1. アセットと環境を確認++足りないものは、どこから取ってどこに置くかと一緒に出ます。++```bash+m2mr doctor+```++### 2. 初回実行:まず画面に出す++フラグなしでは **`assets/video/` に最後に入れたファイル** と `assets/mixamo/Y_Bot.fbx` を使います。++```bash+m2mr run+```++この段階が最も遅いです。初回は約 5 GB の推論ウェイトをダウンロードしてから(一度だけ)、動画から人体モーションを抽出します。+約 30 秒のクリップは CPU で抽出にだいたい 8–15 分、ウェイト済みの同程度なら 3–5 分です。+リターゲットとレンダリングは通常 1–2 分です。次節の `--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+```++## 出力++各 `m2mr run` は**コマンド開始時刻**でディレクトリを作ります:++```+outputs/20260829_193205_dance/+├── run.json # 開始時刻、使った動画 / rig、完全なコマンド+├── skeleton_motion.npz # 人体 3D スケルトン(rig 差し替え時に再利用、再抽出不要)+├── mixamo_rotations.npz # Mixamo ボーンごとの回転+├── mixamo_character.glb # スキン付きキャラクター + アニメーション、Blender / Unity に直接インポート+└── videos/ # 入力動画と同じアスペクト比+ ├── human_skeleton.mp4 # 人体スケルトン+ ├── mixamo_skeleton.mp4 # Mixamo rig スケルトン+ ├── mixamo_character.mp4 # Mixamo rig キャラクター+ └── compare.mp4 # 2×2:元映像(左上)/ Mixamo スケルトン(右上)/ 人体スケルトン(左下)/ キャラクター(右下)+```++`mixamo_character.glb` は Blender で File → Import → glTF 2.0 (.glb/.gltf) で開きます。カメラが空を向いているときはキャラクターを選び、View → Frame Selected。頭と手の球の塊はメッシュではなくボーン表示です:アーマチュアを選び、Armature → Viewport Display で Shapes をオフにします。タイムラインの終了フレームをクリップ長に合わせて再生。同じ実行の `videos/mixamo_character.mp4` と見比べてください。++## ライセンス++このリポジトリのコードは Apache-2.0 です。自分で取得したアセットにはそれぞれの条件があり、このリポジトリと一緒に再配布してはいけません:++- **SMPL-X**:MPI による提供制限。既定は非商用の研究 / 教育 / 芸術;商用は別契約+- **Mixamo FBX**:製品に入れてよい;元の FBX をアセットパックとして再配布してはいけない+- **GVHMR および他の推論ウェイト**:初回 `m2mr run` で `weights/` に自動ダウンロード、各アップストリームのライセンス++## 連絡先++ご不明点がある場合、ローカル環境の構築でお手伝いが必要な場合、または協業をご相談したい場合は、メールでご連絡ください:+[[email protected]](mailto:[email protected])diff --git a/README.ko.md b/README.ko.mdnew file mode 100644index 0000000..1ed1e08--- /dev/null+++ b/README.ko.md@@ -0,0 +1,136 @@+# Motion2MixamoRig++++<p align="center">+ <a href="README.zh-CN.md">中文</a> · <a href="README.md">English</a> · 한국어 · <a href="README.ja.md">日本語</a> · <a href="README.de.md">Deutsch</a> · <a href="README.ru.md">Русский</a>+</p>++영상 속 사람의 동작을 Adobe Mixamo rig 3D 캐릭터로 옮깁니다.++게임 개발자를 위한 도구입니다. **한 사람만** 나오는 동작 영상과 Mixamo 캐릭터를 넣으면 미리보기 영상과, Blender / Unity에 바로 넣을 수 있는 스키닝된 캐릭터 파일(`.glb`)을 생성합니다.++Agent는 먼저 [`AGENTS.md`](AGENTS.md)를 읽어 주세요.++https://github.com/user-attachments/assets/37c67642-f36c-4815-bcf3-028ed9546a2f++<p align="center">+ <sub>이 저장소의 <a href="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를 import하는데, 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 GB, 한 번만).++ffmpeg도 권장합니다(macOS: `brew install ffmpeg`, Ubuntu: `apt install ffmpeg`).+없어도 실행되지만, 출력 영상에 **소리가 없고** 브라우저에서 바로 재생되지 않습니다.++## 실행 전: `assets/`에 세 가지를 넣으세요++이 저장소는 해당 파일을 포함하지 않습니다. 직접 준비해야 합니다. SMPL-X 파일명은 아래 표와 한 글자도 같아야 합니다. FBX와 영상 이름은 상관없습니다.++| 무엇 | 어디에 | 어디서 |+|---|---|---|+| SMPL-X 바디 모델 | `assets/body_models/smplx/SMPLX_NEUTRAL.npz` | [SMPL-X](https://smpl-x.is.tue.mpg.de/)에서 등록한 뒤 다운로드 |+| Mixamo 캐릭터 FBX | `assets/mixamo/Y_Bot.fbx` | Adobe 계정으로 [Mixamo](https://www.mixamo.com)에서 Y Bot(또는 다른 Mixamo rig 캐릭터) 다운로드 |+| 동작 영상 | `assets/video/<your_clip>.mp4` | **사람 한 명만**, 잘 보이고, **머리부터 발끝까지 영상 내내 화면 안에** (여러 파일 가능, 실행마다 가장 최근에 넣은 것 사용) |++주의: Mixamo에서 받은 파일은 `Y Bot.fbx`(**공백**)이고, 표의 `Y_Bot.fbx`(**밑줄**)과 한 글자 다릅니다.+밑줄로 바꾸면 기본 rig가 되어 `m2mr run`에 `--rig` 없이 씁니다. 이름을 안 바꿔도 됩니다 — `Y_Bot.fbx`가 없으면 `assets/mixamo/`의 첫 `.fbx`를 씁니다.++`assets/video/`에는 영상을 여러 개 넣을 수 있습니다. `--video`를 지정하지 않으면 **이 폴더에 가장 마지막에 넣은** 파일을 씁니다.+각 영상에는 사람이 한 명만 나와야 하고, **머리부터 발끝까지 영상 내내 화면 안**에 있어야 하며 화면 밖으로 나가면 안 됩니다. `m2mr doctor` / `m2mr run`이 프레임을 샘플링해 두 명이 보이면 추출 전에 멈춥니다.++## 빠른 시작++결과는 `outputs/<실행시각>_<영상명>/`에 있습니다. 영상은 그 안의 `videos/`를 여세요.++### 1. 자산과 환경 확인++빠진 것은 어디서 받고 어디에 넣을지 함께 출력합니다.++```bash+m2mr doctor+```++### 2. 첫 실행: 화면에 결과 띄우기++플래그 없이 실행하면 **`assets/video/`에서 가장 최근 파일**과 `assets/mixamo/Y_Bot.fbx`를 씁니다.++```bash+m2mr run+```++이 단계가 가장 느립니다. 첫 실행은 약 5 GB 추론 가중치를 받은 뒤(한 번만) 영상에서 사람 동작을 추출합니다.+약 30초 영상은 CPU에서 추출에 대략 8–15분, 가중치가 이미 있으면 비슷한 길이에 3–5분입니다.+리타게팅과 렌더링은 보통 1–2분입니다. 다음 절의 `--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+```++## 출력++각 `m2mr run`은 **명령이 시작된 시각**으로 디렉터리를 만듭니다:++```+outputs/20260829_193205_dance/+├── run.json # 시작 시각, 사용한 영상 / rig, 전체 명령+├── skeleton_motion.npz # 인체 3D 스켈레톤 (rig 교체 시 재사용, 추출 생략)+├── mixamo_rotations.npz # Mixamo 본별 회전+├── mixamo_character.glb # 스키닝된 캐릭터 + 애니메이션, Blender / Unity에 바로 임포트+└── videos/ # 입력 영상과 같은 화면비+ ├── human_skeleton.mp4 # 인체 스켈레톤+ ├── mixamo_skeleton.mp4 # Mixamo rig 스켈레톤+ ├── mixamo_character.mp4 # Mixamo rig 캐릭터+ └── compare.mp4 # 2×2: 원본(좌상) / Mixamo 스켈레톤(우상) / 인체 스켈레톤(좌하) / 캐릭터(우하)+```++`mixamo_character.glb`는 Blender에서 File → Import → glTF 2.0 (.glb/.gltf)로 엽니다. 카메라가 빈 곳을 보고 있으면 캐릭터를 선택한 뒤 View → Frame Selected. 머리와 손의 구체들은 메시가 아니라 본 표시입니다. Armature를 선택하고 Armature → Viewport Display에서 Shapes를 끄세요. 타임라인 끝 프레임을 클립 길이에 맞춘 뒤 재생하세요. 같은 실행의 `videos/mixamo_character.mp4`와 비교하면 됩니다.++## 라이선스++이 저장소의 코드는 Apache-2.0입니다. 직접 받은 자산은 각 조항이 있으며 이 저장소와 함께 재배포하면 안 됩니다:++- **SMPL-X**: MPI에서 배포가 제한됨. 기본은 비상업 연구 / 교육 / 예술; 상업 이용은 별도 계약+- **Mixamo FBX**: 제품에 넣어도 됨; 원본 FBX를 에셋 팩으로 재배포하면 안 됨+- **GVHMR 및 기타 추론 가중치**: 첫 `m2mr run` 때 `weights/`로 자동 다운로드, 각 업스트림 라이선스++## 문의++문제가 있으시거나, 로컬 설치에 도움이 필요하시거나, 협업을 논의하고 싶으시면 이메일로 연락해 주세요:+[[email protected]](mailto:[email protected])diff --git a/README.md b/README.mdindex 9125604..e766998 100644--- a/README.md+++ b/README.md@@ -3,7 +3,7 @@<p align="center">- <a href="README.zh-CN.md">中文</a> · English+ <a href="README.zh-CN.md">中文</a> · English · <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></p>Transfer the motion of a person in a video onto an Adobe Mixamo-rigged 3D character.diff --git a/README.ru.md b/README.ru.mdnew file mode 100644index 0000000..5d48a46--- /dev/null+++ b/README.ru.md@@ -0,0 +1,136 @@+# Motion2MixamoRig++++<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> · Русский+</p>++Переносит движение человека из видео на 3D-персонажа с ригом Adobe Mixamo.++Для разработчиков игр: видео с **одним человеком** и персонаж Mixamo; на выходе превью-видео и файл персонажа со скином (`.glb`) для Blender или Unity.++Агентам следует начать с [`AGENTS.md`](AGENTS.md).++https://github.com/user-attachments/assets/37c67642-f36c-4815-bcf3-028ed9546a2f++<p align="center">+ <sub>Откройте <a href="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 в setup-скрипте; в изолированной сборке 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 | `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` | Ролик с **ровно одним** хорошо видимым человеком, **с головы до ног весь ролик в кадре** (можно несколько файлов; каждый запуск берёт последний добавленный) |++Замечание: скачанный файл Mixamo называется `Y Bot.fbx` (**пробел**), на один символ отличается от `Y_Bot.fbx` (**подчёркивание**) в таблице.+Переименуйте с подчёркиванием — это станет ригом по умолчанию (`m2mr run` без `--rig`). Можно не переименовывать: если `Y_Bot.fbx` нет, берётся первый `.fbx` в `assets/mixamo/`.++В `assets/video/` можно класть несколько видео. Без `--video` запуск берёт файл, **последним положенный в эту папку**.+В каждом ролике должен быть один человек, **с головы до ног весь ролик в кадре** — ничего не обрезано по краям. `m2mr doctor` / `m2mr run` выборочно проверяют кадры и останавливаются до извлечения, если в кадре двое.++## Быстрый старт++Результаты в `outputs/<время-запуска>_<видео>/`. Видео смотреть в `videos/`.++### 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+```++## Результаты++Каждый `m2mr run` создаёт каталог по **времени старта команды**:++```+outputs/20260829_193205_dance/+├── run.json # время старта, видео / риг, полная команда+├── skeleton_motion.npz # 3D-скелет человека (переиспользовать при смене рига; без повторного извлечения)+├── mixamo_rotations.npz # вращения костей Mixamo+├── mixamo_character.glb # персонаж со скином + анимация, импорт в Blender / Unity+└── videos/ # то же соотношение сторон, что у входного видео+ ├── human_skeleton.mp4 # скелет человека+ ├── mixamo_skeleton.mp4 # скелет рига Mixamo+ ├── mixamo_character.mp4 # персонаж с ригом Mixamo+ └── compare.mp4 # 2×2: оригинал (верхний левый) / скелет Mixamo (верхний правый) / скелет человека (нижний левый) / персонаж (нижний правый)+```++`mixamo_character.glb` в Blender: File → Import → glTF 2.0 (.glb/.gltf). Если камера смотрит в пустоту, выберите персонажа и View → Frame Selected. Скопление сфер на голове и руках — отображение костей, не меш: выберите арматуру и отключите Shapes в Armature → Viewport Display. Конечный кадр таймлайна поставьте по длине клипа, затем воспроизведите. Сверяйте с `videos/mixamo_character.mp4` того же запуска.++## Лицензия++Код репозитория — Apache-2.0. Скачанные вами ассеты имеют свои условия и не должны распространяться вместе с этим репо:++- **SMPL-X**: доступ через MPI; по умолчанию некоммерческие исследования / образование / искусство; коммерческое использование — отдельный договор+- **Mixamo FBX**: можно в готовом продукте; сырой FBX нельзя раздавать как пак ассетов+- **GVHMR и другие веса инференса**: при первом `m2mr run` автоматически в `weights/`, по лицензии каждого апстрима++## Контакты++Если возникла проблема, нужна помощь с локальной установкой или вы хотите обсудить сотрудничество, напишите на:+[[email protected]](mailto:[email protected])diff --git a/README.zh-CN.md b/README.zh-CN.mdindex 70749f0..82b3fa7 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -3,7 +3,7 @@<p align="center">- 中文 · <a href="README.md">English</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></p>把视频里人物的动作,转到 Adobe Mixamo rig 的 3D 角色上。@@ -111,7 +111,7 @@ m2mr run --video assets/video/dance.mp4 --rig assets/mixamo/Vampire.fbxoutputs/20260829_193205_dance/├── run.json # 启动时间、用的视频 / rig、完整命令├── skeleton_motion.npz # 人体 3D 骨架(换 rig 可复用,不必重跑提取)-├── mixamo_rotations.npz # Mixamo 骨逐帧旋转+├── mixamo_rotations.npz # Mixamo 骨骼逐帧旋转├── mixamo_character.glb # 带皮角色 + 动画,Blender / Unity 可直接导入└── videos/ # 比例跟输入视频一致├── human_skeleton.mp4 # 人体骨架