mirror of
https://github.com/barkeser2002/VMD-Motion-Optimizer.git
synced 2026-09-25 01:50:14 +03:00
Barış Keser
5423971fa7
READMEler koda uymayan davranışlar anlatıyordu: depth ve ground'un "tüm kemiklere global çeviri uyguladığı" yazıyordu, oysa kod yalnızca kök kemiğe uyguluyor (kod içi docstring de README ile çelişiyordu). Kamera/ışık bloklarının yazılmadığı notu artık geçersiz - korunuyorlar. Eklenenler: Releases indirme bağlantısı, tüm CLI seçeneklerinin tam tablosu (--no-preserve-end, --replace-xr-with, --flatten-interp, --force, --ground-exclude-ik/--ground-include-ik dahil), test çalıştırma talimatı ve ground stabilizasyonun neyi ölçtüğüne dair dürüst bir not (VMD iskelet içermez, mutlak yükseklik ondan türetilemez). CLI örneklerindeki "\" satır devamları kaldırıldı - Windows'a yönelik bir araçta ne cmd ne PowerShell bunu kabul ediyor, örnekler kopyalanınca çalışmıyordu. v1.1.0: --remove-depth ve --stabilize-ground çıktısı v1.0.4'ten farklı. Bu bilinçli - v1.0.4'ün çıktısı hatalıydı. Değişiklik notu üç READMEde de var.
4.7 KiB
4.7 KiB
VMD Motion Optimizer by Barış Keser (barkeser2002)
VMD Motion Optimizer is a tool to optimize MikuMikuDance (MMD) .vmd motion files using smart heuristics.
It reduces position/rotation keys, removes depth drift, and applies ground stabilization.
- Author: Barış Keser (barkeser2002)
- License: GNU General Public License v3.0 (GPL-3.0) — see
LICENSE - Version: see
version.txt
Download
Grab the latest portable Windows build from the
Releases page.
Extract the ZIP and run VMDOptimizer/VMDOptimizer.exe — no installation needed.
Each release ships a .sha256 file so you can verify the download.
Features
- RDP-like curve simplification for position
- Quaternion SLERP-based angular-error simplification for rotation
- Morph key reduction (constant holds are preserved, not ramped)
- Interpolation (bezier) curves are preserved — hand-authored easing survives
- Camera, light, self-shadow and IK/visibility blocks are carried through untouched
- Depth (Z) drift removal: measures the low-frequency trend of the root bone and subtracts it, so real forward/backward motion is kept
- Ground (Y) stabilization: measures the lowest foot-bone Y offset and moves the root bone so it lands on the target height
- PyQt6 GUI with profiles, drag & drop, and a working Cancel button
- Portable builds via PyInstaller (Windows)
Install (CLI)
- Python 3.11 / 3.12 recommended (3.10+ required)
- Virtualenv + deps:
py -3 -m venv .venv
.venv\Scripts\pip.exe install -r requirements.txt
CLI Usage
python scripts/optimize_vmd.py input.vmd -o output.vmd --pos-eps 0.05 --rot-eps-deg 0.5 --morph-eps 0.001
With depth-drift removal and ground stabilization:
python scripts/optimize_vmd.py input.vmd -o output.vmd --remove-depth --depth-smooth 30 --stabilize-ground --ground-target-y 0.0 --ground-smooth 5
Options
| Flag | Default | Description |
|---|---|---|
-o, --output |
<input>_optimized.vmd |
Output path |
--pos-eps |
0.05 |
Position tolerance (model units) |
--rot-eps-deg |
0.5 |
Rotation tolerance (degrees) |
--morph-eps |
0.001 |
Morph weight tolerance |
--key-step |
1 |
Coarse downsample: keep every Nth key |
--no-preserve-end |
off | Do not force-keep each channel's first/last key |
--flatten-interp |
off | Discard source easing, write the MMD default curve |
--force |
off | Allow writing over the input file (dangerous) |
--remove-depth |
off | Remove global Z drift from the root bone |
--depth-smooth |
0 |
Trend window for depth. Must be ≥ 2 (try 30) |
--depth-scale |
1.0 |
Multiplier for the removed drift |
--stabilize-ground |
off | Stabilize the character to the ground plane |
--ground-target-y |
0.0 |
Target ground height |
--ground-smooth |
0 |
Smoothing window for the ground offset |
--ground-scale |
1.0 |
Multiplier for the ground offset |
--ground-all-bones |
off | Measure from all bones instead of feet only |
--ground-exclude-ik |
on | Exclude IK bones from the ground measurement |
--ground-include-ik |
— | Include IK bones in the ground measurement |
--replace-xr-with |
Barış Keser |
Replace an XR Animator model name |
GUI
python scripts/app.py
Build
- CMD:
build_exe.bat(portable folder atdist/VMDOptimizer) - PowerShell:
build_exe.ps1
Tests
pip install -r requirements-dev.txt
python -m pytest tests -q
Notes
- Some VMD headers are non-standard (extra or missing padding between the signature and the model name); the reader detects and repairs this automatically.
- Both VMD 1.0 (10-byte model name) and VMD 2.0 (20-byte) headers are supported.
- Ground stabilization measures the translation offsets stored in the VMD, not true world-space height — a VMD contains no skeleton, so absolute heights cannot be derived from it. The offset is applied to the root/center bone, which moves the whole skeleton with it.
- If the model name is
XR Animator, it is replaced withBarış Keserby default (configurable via--replace-xr-with). - The GUI is currently Turkish-only.
Changed in v1.1.0
--remove-depth and --stabilize-ground now produce different output than v1.0.4.
In v1.0.4 --remove-depth subtracted the root bone's Z from itself, which zeroed all
forward/backward motion; interpolation curves were discarded; camera/light/shadow/IK
blocks were dropped; and constant morph holds were converted into long ramps. Those
were bugs — the new output is the intended behavior.
Credits
- VMD Motion Optimizer by Barış Keser (barkeser2002)
- GPL-3.0 — see
LICENSE