{"id":21889394,"url":"https://github.com/peizhuoli/ganimator","last_synced_at":"2025-04-05T17:08:45.538Z","repository":{"id":37760498,"uuid":"488601986","full_name":"PeizhuoLi/ganimator","owner":"PeizhuoLi","description":"A motion generation model learned from a single example [SIGGRAPH 2022]","archived":false,"fork":false,"pushed_at":"2024-06-28T09:29:35.000Z","size":3218,"stargazers_count":400,"open_issues_count":10,"forks_count":45,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-03-29T16:08:56.308Z","etag":null,"topics":["character-animation","computer-animation","computer-graphics","deep-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PeizhuoLi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-04T13:35:09.000Z","updated_at":"2025-03-16T00:06:32.000Z","dependencies_parsed_at":"2024-01-14T03:49:53.138Z","dependency_job_id":"9d8ff4cb-c309-402e-90ed-76b262dba153","html_url":"https://github.com/PeizhuoLi/ganimator","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeizhuoLi%2Fganimator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeizhuoLi%2Fganimator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeizhuoLi%2Fganimator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeizhuoLi%2Fganimator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PeizhuoLi","download_url":"https://codeload.github.com/PeizhuoLi/ganimator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369952,"owners_count":20927928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["character-animation","computer-animation","computer-graphics","deep-learning"],"created_at":"2024-11-28T11:24:07.835Z","updated_at":"2025-04-05T17:08:45.517Z","avatar_url":"https://github.com/PeizhuoLi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GANimator: Neural Motion Synthesis from a Single Sequence\n\n![Python](https://img.shields.io/badge/Python-\u003e=3.8-Blue?logo=python)  ![Pytorch](https://img.shields.io/badge/PyTorch-\u003e=1.10.0-Red?logo=pytorch)\n\nThis repository provides a library for novel motion synthesis from a single example, as well as applications including style transfer, motion mixing, key-frame editing and conditional generation. It is based on our work [GANimator: Neural Motion Synthesis from a Single Sequence](https://peizhuoli.github.io/ganimator/index.html) that is published in SIGGRAPH 2022.\n\n\u003cimg src=\"https://peizhuoli.github.io/ganimator/images/video_teaser_small.gif\" slign=\"center\"\u003e\n\n\n## Prerequisites\n\nThis code has been tested under Ubuntu 20.04. Before starting, please configure your Anaconda environment by\n~~~bash\nconda env create -f environment.yaml\nconda activate ganimator\n~~~\n\nIn case you encounter a `GLIBCXX-3.4.29 not found` issue, please link your existing `libstdc++.so` file to the anaconda environment by `ln -sf /usr/lib/x86_64-linux-gnu/libstdc++.so.6  {path to anaconda}/envs/ganimator/bin/../lib/libstdc++.so.6`.\n\nAlternatively, you may install the following packages (and their dependencies) manually:\n\n- pytorch == 1.10\n- tensorboard \u003e= 2.6.0\n- tqdm \u003e= 4.62.3\n- scipy \u003e= 1.7.3\n\n## Quick Start\n\nWe provide several pretrained models for various characters. Download the pretrained model from [Google Drive](https://drive.google.com/file/d/1EnKE2B46sYWmRIdywNubJalzxzbvqvo-/view?usp=sharing). Please extract the downloaded file and put the `pre-trained` directory directly under the root of the ganimator directory. \n\n### Novel motion synthesis\n\nRun `demo.sh`. The result for Salsa and Crab Dace will be saved in `./results/pre-trained/{name}/bvh`. The result after foot contact fix will be saved as `result_fixed.bvh`. You may visualize the generated bvh files with [Blender](https://www.blender.org).\n\nSimilarly, use command `python demo.py --save_path=./pre-trained/{name of pre-trained model}` will generate the result for the given pretrained model.\n\n\n### Evaluation\n\nA separate module for evaluation is *required*. Before starting with evaluation, please refer to the instruction of installation [here](https://github.com/PeizhuoLi/ganimator-eval-kernel).\n\nUse the following command to evaluate a trained model:\n\n~~~bash\npython evaluate.py --save_path={path to trained model}\n~~~\n\nParticularly, `python evaluate.py --save_path=./pre-trained/gangnam-style` yields the quantitative result of our method with full approach reported in Table 1 and 2 of the paper.\n\n## Train from scratch\n\nWe provide instructions for retraining our model.\n\nWe include several animations under `./data` directory.\n\nHere is an example for training the crab dance animation:\n\n~~~bash\npython train.py --bvh_prefix=./data/Crabnew --bvh_name=Crab-dance-long --save_path={save_path}\n~~~\n\nYou may specify training device by `--device=cuda:0` using pytorch's device convention.\n\n\nFor customized bvh file, specify the joint names that should be involved during the generation and the contact name in `./bvh/skeleton_databse.py`, and set corresponding `bvh_prefix` and `bvh_name` parameter for `train.py`.\n\n\n### Training a Conditional Generator\n\nA conditional generator takes the motion of one or several given joints as constraints and generate animation complying with the constraints. Before training a conditional generator, a regular generator must be trained on the same training sequence.\n\nHere is an example for training a conditional generator for the walk-in-circle motion:\n\n~~~bash\npython train.py --bvh_prefix=./data/Joe --bvh_name=Walk-In-Circle --save_path={save_path} --skeleton_aware=1 --path_to_existing=./pre-trained/walk-in-circle --conditional_generator=1\n~~~\n\nThis example assumes that a pre-trained regular generator is stored in `./pre-trained/walk-in-circle`, which is specified by the `--path_to_existing` parameter.\n\nThis repository contains the code using the motion of root joint as condition. However, it is also possible to customize the conditional joints. It can be done by modify the `get_layered_mask()` function in `models/utils.py`. It takes the `--conditional_mode` parameter as its first parameter and returns the corresponding channel indices in the tensor representation.\n\n## Applications\n\n### Motion Mixing\n\nWhen trained with two or more sequences, our framework generates a mixed motion of the input animations.\n\nThis is an example for training on multiple sequences using `--multiple_sequence=1`:\n\n~~~bash\npython --bvh_prefix=./data/Elephant --bvh_name=list.txt --save_path={save_path} --multiple_sequence=1\n~~~\n\nThe `list.txt` in `./data/Elephant` contains the names of the sequences to be trained.\n\nWe also provide a pre-trained model for the motion mixing of the elephant motions:\n\n\n~~~bash\npython demo.py --save_path=./pre-trained/elephant\n~~~\n\n### Key-frame Editing\n\nInstead of generating the motion from random noise, we can perform key-frame editing by providing the edited key-frames in the coarsest level.\n\nThis is an example for keyframe editing:\n\n~~~bash\npython demo.py --save_path=./pre-trained/baseball-milling --keyframe_editing=./data/Joe/Baseball-Milling-Idle-edited-keyframes.bvh\n~~~\n\nThe `--keyframe_editing` parameter points to the bvh file containing the edited key-frames, which should be as the same temporal resolution as the coarsest level. Note that in this specific example, the `--ratio` parameter for the model is set to `1/30`, leading to a sparser key-frame setting that makes editing easier.\n\n\n### Style Transfer\n\nSimilarly, when the model is trained on *style* input and the coarsest level is given by the *content* input, our model can achieve style transfer.\n\nThis is an example for style transfer:\n\n~~~bash\npython demo.py --save_path=./pre-trained/proud-walk --style_transfer=./data/Xia/normal.bvh\n~~~\n\nNote the content of *content* input is required to be similar to the content of *style* input, in order to generate high-quality results as discussed in the paper.\n\n### Conditional Generation\n\nWhen a pre-defined motion of part of the skeleton (e.g., root trajectory) is given, a conditional generation model can produce animation complying with given constraints. \n\nThis is an example for conditional generation:\n\n~~~bash\npython demo.py --save_path=./pre-trained/conditional-walk --conditional_generation=./data/Joe/traj-example.bvh\n~~~\n\nThis pre-trained model takes the position and orientation of root joint from `traj-example.bvh`. If the conditional source file is not specified, the script will sample a trajectory from a pre-traiend regular generator as the condition. \n\nAdditionally, `--interactive=1` option will generate the animation with interactive mode. In this mode, the condition information will be fed into the generator gradually. It is conceptually an interactive generation, but not an interactive demo that can be controlled with a keyboard or gamepad. \n\nFor more details about specifying conditional joints, please refer to [Training a Conditional Generator](https://github.com/PeizhuoLi/ganimator#training-a-conditional-generator).\n\n## Acknowledgements\n\nThe code in `models/skeleton.py` is adapted from [deep-motion-editing](https://github.com/DeepMotionEditing/deep-motion-editing) by [@kfiraberman](https://github.com/kfiraberman), [@PeizhuoLi](https://github.com/PeizhuoLi) and [@HalfSummer11](https://github.com/HalfSummer11).\n\nPart of the code in `bvh` is adapted from the [work](https://theorangeduck.com/media/uploads/other_stuff/motionsynth_code.zip) of [Daniel Holden](https://theorangeduck.com/page/publications).\n\nPart of the training examples is taken from [Mixamo](http://mixamo.com) and [Truebones](https://truebones.gumroad.com).\n\n\n## Citation\n\nIf you use this code for your research, please cite our paper:\n\n~~~bibtex\n@article{li2022ganimator,\n  author = {Li, Peizhuo and Aberman, Kfir and Zhang, Zihan and Hanocka, Rana and Sorkine-Hornung, Olga },\n  title = {GANimator: Neural Motion Synthesis from a Single Sequence},\n  journal = {ACM Transactions on Graphics (TOG)},\n  volume = {41},\n  number = {4},\n  pages = {138},\n  year = {2022},\n  publisher = {ACM}\n}\n~~~\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeizhuoli%2Fganimator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeizhuoli%2Fganimator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeizhuoli%2Fganimator/lists"}