mirror of
https://github.com/barkeser2002/VMD-Motion-Optimizer.git
synced 2026-09-25 01:10: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.
122 lines
4.7 KiB
Markdown
122 lines
4.7 KiB
Markdown
# 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](https://github.com/barkeser2002/VMD-Motion-Optimizer/releases).
|
|
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)
|
|
|
|
1. Python 3.11 / 3.12 recommended (3.10+ required)
|
|
2. Virtualenv + deps:
|
|
|
|
```bash
|
|
py -3 -m venv .venv
|
|
.venv\Scripts\pip.exe install -r requirements.txt
|
|
```
|
|
|
|
## CLI Usage
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
python scripts/app.py
|
|
```
|
|
|
|
## Build
|
|
|
|
- CMD: `build_exe.bat` (portable folder at `dist/VMDOptimizer`)
|
|
- PowerShell: `build_exe.ps1`
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
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 with `Barış Keser` by 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`
|