Medusa installation#

Medusa is a Python package which works with Python version 3.10 and on Linux and and Mac (x86_64 architectures only). Most of Medusa’s functionality will in fact also work on Windows and M1/M2 Macs (arm64 architecture), with the exception of rendering (as pytorch3d cannot be automatically installed on Windows and Mac M1/M2).

We strongly recommend to install the medusa package in a separate Python environment, using for example conda. If you’d use conda, you can create a new environment named “medusa” with Python 3.10 as follows:

conda create -n medusa python=3.10

Then, to activate the environment, run:

conda activate medusa

The next step is to install Medusa. Medusa’s install will be relatively large (~2GB) as it will also install PyTorch with CUDA support, even if your system does not have access to a GPU (which makes automatic installation a lot easier); Medusa will make sure set the default ‘device’ to ‘cpu’ so PyTorch will work as expected.

Medusa can be installed using pip as follows:

pip install https://github.com/SchynsLab/medusa/releases/download/v0.0.6/medusa-0.0.6-py3-none-any.whl

Note

While installing Python packages/wheels from other locations than PyPI is generally discouraged, Medusa actually hosts its builds in its own Github repository (as you can see in the install commands above). The reason for doing so (instead of on PyPI) is that Medusa depends on a specific version of PyTorch, which itself is not available on PyPI (only as a wheel). Listing non-PyPI dependencies in packages is not permitted by PyPI, which is why Medusa wheels are hosted on Github.

If you want to build Medusa yourself, you can clone the repository and run the build_wheel script, which will create a directory dist with a wheel file that can then be installed using pip as usual.

Downloading external data#

At this point, medusa can be used, but only the Mediapipe reconstruction model will be available. To be able to use the FLAME-based [Li et al., 2017] reconstruction models such as DECA [Feng et al., 2021], and EMOCA [Daněček et al., 2022], you need to download some additional data. Importantly, before you do, you need to register on the FLAME website and accept their license terms.

After creating an account, you can download all external data with the medusa_download_ext_data command. To download all data to new directory (default location: ~/.medusa_ext_data), you’d run:

medusa_download_ext_data --directory medusa_ext_data --username your_flame_username --password your_flame_passwd

where your_flame_username and your_flame_passwd are the username and password associated with the account you created on the FLAME website. After all data has been downloaded (~1.8GB), all Medusa functionality should be available!

Installation from source#

If you want to install Medusa from source, check out the for developers page.

Install pytorch3d on Mac M1#

  • clone pytorch3d

  • cd pytorch3d

  • rm -rf build/ **/*.so

  • MACOSX_DEPLOYMENT_TARGET=10.14 CC=clang CXX=clang++ ARCHFLAGS="-arch arm64" pip install -e .