hyz317/HairDeck

选用指南

AI 根据 README 整理 · 2026/11/1 08:57:05

使用方式

通过命令行运行脚本生成头发并导出 VRM，也可启动本地 Web 演示界面。

查看 README 依据

[configs/paths.example.json](configs/paths.example.json) and [hairdeck/paths.py](hairdeck/paths.py). <a name="quick-start"></a> ### 🚀 Quick start Generate four variations from a character image, then export variation 0 as a VRM avatar and a head-turn video: ```bash python scripts/image_to_hair.py character.png --out results/my_character --n 4 python -m hairdeck.vrm.export results/my_character/character 0 ``` Results are written to `OUT/<image name>/`, here `results/my_character/character/`.

`--n` accepts 1–4 variations; `--seed` sets the first seed. Use `--no-chains` to generate cards only. For custom models, pass `--ckpt` and a matching `--chain_ckpt` trained with the same card VAE. <a name="local-demo"></a> ### 🖼️ Local demo ```bash python -m pip install -r requirements-demo.txt python demo/app.py --port 7860 ``` Open [http://127.0.0.1:7860](http://127.0.0.1:7860) to generate hair, inspect variations, and export a VRM or animation preview. You can also try the [hosted demo](https://huggingface.co/spaces/hyz317/HairDeck). <a name="outputs"></a> ## 📦 Outputs

部署要求

需要 Linux x86-64、Python 3.12、NVIDIA CUDA GPU，并需下载模型权重，部分模型需接受许可并登录 Hugging Face。

查看 README 依据

[🛠️ Installation](#installation) · [🤗 Model weights](#model-weights) · [🚀 Quick start](#quick-start) · [🖼️ Local demo](#local-demo) · [📦 Outputs](#outputs) · [📊 Evaluation](#test-set-evaluation) · [🏋️ Training](#training) · [📝 Citation](#citation) <a name="installation"></a> ### 🛠️ Installation Use Linux x86-64, Python 3.12 and one NVIDIA CUDA GPU. The release was tested with PyTorch 2.8 and CUDA 12.8. The video preview also needs `ffmpeg` on your `PATH`. ```bash git clone https://github.com/hyz317/HairDeck.git cd HairDeck python -m pip install -r requirements.txt

python -m pip install --no-deps pyrender==0.1.45 # without its old PyOpenGL pin ``` Run the commands below from the repository root, in the same Python environment. <a name="model-weights"></a> ### 🤗 Model weights Our checkpoints and supporting assets are hosted at [hyz317/HairDeck](https://huggingface.co/hyz317/HairDeck). SAM 3 and DINOv3 are gated: first accept their licences on [facebook/sam3](https://huggingface.co/facebook/sam3) and [facebook/dinov3-vitl16-pretrain-lvd1689m](https://huggingface.co/facebook/dinov3-vitl16-pretrain-lvd1689m), then log in: ```bash hf auth login

已知限制

当前图像训练配方包含合成外观增强，但发布模型使用的 restyled-render 池未包含在本次发布中。

查看 README 依据

python scripts/setup/download_weights.py --only dora test_data charm_test_pc python scripts/data.py DATASET_DIR VRM_DIR bash scripts/train/launch_vae.sh bash scripts/train/launch_pc_dit.sh && bash scripts/train/launch_img_dit.sh && bash scripts/train/launch_chain_dit.sh ``` The launchers write to `ckpt/train_*`, separately from the downloaded checkpoints. The current image-training recipe includes synthetic appearance augmentation; the restyled-render pool used for the released image model is not included in this release. <a name="citation"></a> ## 📝 Citation ```bibtex