Skip to content

Commit

Permalink
Clearer Quickstart instructions :)
Browse files Browse the repository at this point in the history
  • Loading branch information
@NumesSanguis
NumesSanguis committed Jan 9, 2019
1 parent 1fef98c commit 483a26b
Show file tree
Hide file tree
Showing 5 changed files with 46 additions and 77 deletions.
35 changes: 22 additions & 13 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,29 +14,38 @@ ISBN: 978-1-4503-6013-5/18/11
FACSvatar is tested on Ubuntu and Windows, but should work on MacOS.
More [detailed quickstart](https://facsvatar.readthedocs.io/en/latest/quickstart.html).

0. Download this repository: `git clone https://github.com/NumesSanguis/FACSvatar.git` / press the green `Clone or Download` button --> `Download ZIP`
1. With a terminal openend in folder `FACSvatar/modules` and execute: `docker-compose pull && docker-compose up`
0. Downloads - Go to the [release page of this GitHub repo](https://github.com/NumesSanguis/FACSvatar/releases) and download:
* openface_2.1.0_zeromq.zip
* Unzip and execute `download_models.sh or .ps1` to download trained models
* Windows 7 / 8 / 10 Home: unity_FACSvatar_standalone_docker-ip.zip
* Windows 10 Pro / Enterprise / Education: unity_FACSvatar_standalone.zip
* Windows / Linux / Mac: [Unity3D editor (documentation)](https://facsvatar.readthedocs.io/en/latest/defaultsetup.html#unity3d-game-engine)
* Source code (zip / tar.gz) or download this repository with:
* `git clone https://github.com/NumesSanguis/FACSvatar.git`
* Press the green `Clone or Download` button on this page --> `Download ZIP`

1. Docker Install - Let's you execute applications without worrying about OS or programming language.
* [General Docker instructions](https://docs.docker.com/install/#supported-platforms)
* [Docker Toolbox for Windows 7/8/10 Home](https://docs.docker.com/toolbox/overview/)
* [Docker for Windows 10 Pro, Enterprise or Education](https://docs.docker.com/docker-for-windows/install/#what-to-know-before-you-install)
* Ubuntu: [Docker](https://docs.docker.com/install/linux/docker-ce/ubuntu/) and [docker-compose](https://docs.docker.com/compose/install/) and `sudo usermod -a -G docker $USER`
2. Download unity_FACSvatar compiled / run with editor:
* [unity_FACSvatar.exe (Windows 7, 8 10 Home?)](https://numessanguis.stackstorage.com/s/5IyeOu8VxlTRrCh)
* [unity_FACSvatar.exe (Windows Pro, Enterprise or Education (10 Home?))](https://numessanguis.stackstorage.com/s/ZUhJGCItnSp14u1)
* [Unity3D editor (documentation)](https://facsvatar.readthedocs.io/en/latest/defaultsetup.html#unity3d-game-engine) (Windows / Linux / Mac)
3. Double click .exe / Press play button in Unity3D editor

2. Docker Modules - Open a terminal (W7/8: cmd.exe / W10: PowerShell) and navigate to folder `FACSvatar/modules`, then execute:
1. `docker-compose pull` (Downloads FACSvatar Docker containers)
2. `docker-compose up` (Starts downloaded Docker containers)

3. Facial Animation with Unity3D - Navigate inside folder unity_FACSvatar_standalone(_docker-ip) and Double-click `unity_FACSvatar.exe` / Press play button in Unity3D editor

### Offline version:

3. Open a 2nd terminal in folder `FACSvatar/modules` and execute: `docker-compose exec facsvatar_facsfromcsv bash`
4. Start facial animation with: `python main.py --pub_ip facsvatar_bridge`
4. Open a 2nd terminal in folder `FACSvatar/modules` and execute: `docker-compose exec facsvatar_facsfromcsv bash`
5. Inside Docker container - Start facial animation with: `python main.py --pub_ip facsvatar_bridge`

### With webcam for real-time (Windows only for now):

3. Download a [modified OpenFace with ZeroMQ (v2.1.0)](https://numessanguis.stackstorage.com/s/MkifmnI6LltflOI) ([see copyright](https://github.com/TadasBaltrusaitis/OpenFace/blob/master/Copyright.txt))
4. Unpack .zip and open folder `openface_x.x.x_zeromq`
5. (Windows 7/8 only (maybe 10 Home too)) Get Docker machine ip by opening a 2nd terminal and execute: `docker-machine ip` (likely to be 192.168.99.100)
6. (Windows 7/8 only (maybe 10 Home too)) Open `config.xml`, change `<IP>127.0.0.1</IP>` to `<IP>machine ip from step 3</IP>` (`<IP>192.168.99.100</IP>`) and save and close.
4. Navigate inside folder `openface_x.x.x_zeromq`
5. (Windows 7/8/10 Home - only) Get Docker machine ip by opening a 2nd terminal and execute: `docker-machine ip` (likely to be 192.168.99.100)
6. (Windows 7/8/10 Home - only) Open `config.xml`, change `<IP>127.0.0.1</IP>` to `<IP>machine ip from step 3</IP>` (`<IP>192.168.99.100</IP>`) and save and close.
7. Double click `OpenFaceOffline.exe` –> menu: File –> Open Webcam

### Unity3D
Expand Down
12 changes: 12 additions & 0 deletions docs/source/contribute.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
====================
Contribute
====================

The main idea is that researchers/developers write their own micro modules with ZeroMQ and wrap them up as Docker containers.
Docker will make the modules OS independent and a default ZeroMQ interface let's these modules communicate with each other.
The ideal case is where a researcher/developer uploads a module, an other user downloads it, and he/she only has to add a few lines to ``docker-compose.yml`` to start using it.

* Image that you have created a better FACS value extracter. You only have to add a ZeroMQ component, and no modification is needed in the other modules or visualization. or
* You want to enable facial animation in Unreal. You only need to include a ZeroMQ subscriber component to your Unreal project and you can use the other modules as is.

By creating a repository of FACSvatar compatible modules, we can make more advanced Human-Agent Interaction (HAI) systems and don't have to start a project from scratch if we only want to focus on 1 component.
9 changes: 9 additions & 0 deletions docs/source/docker.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,15 @@ Docker machine bash completion:
do
sudo wget "$base/contrib/completion/bash/${i}" -P /etc/bash_completion.d
done
-----------------------------------
Docker own OpenFace .csv (untested)
-----------------------------------
If you want to use your own OpenFace .csv, you've obtained by running some video through OpenFace, in combination with Docker, you will need to do:
* Copy file from host to container: ``docker cp foo.csv facsvatar_facsfromcsv:/openface/*your_folder/foo.csv``
* Go inside Docker container: ``docker-compose exec facsvatar_facsfromcsv bash``
* Inside container: python main.py --pub_ip facsvatar_bridge --csv_folder openface/*your_folder* --csv_arg -1


-------------------------
Expand Down
1 change: 1 addition & 0 deletions docs/source/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ Links
firstrun
docker
deeplearning
contribute
license

Indices and tables
Expand Down
66 changes: 2 additions & 64 deletions docs/source/quickstart.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,74 +5,12 @@ See :doc:`defaultsetup` for FACSvatar setup without Docker.

FACSvatar is tested on Ubuntu and Windows, but should work on MacOS as well.

------------------------
0. Get the code
------------------------
Download the FACSvatar repository:

* ``git clone https://github.com/NumesSanguis/FACSvatar.git``
* Go to `FACSvatar GitHub page <https://github.com/NumesSanguis/FACSvatar>`_ and press the green ``Clone or Download`` button --> ``Download ZIP``

------------------------
1. Docker install
------------------------
It is best to follow the `official Docker instructions <https://docs.docker.com/install/#supported-platforms>`_ for installation.

^^^^^^^^^^^^^^^^^^^^^
Windows 7/8/10 Home
^^^^^^^^^^^^^^^^^^^^^
Docker Toolbox: https://docs.docker.com/toolbox/overview/

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Windows 10 Pro, Enterprise or Education
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Docker Community Edition: https://docs.docker.com/docker-for-windows/install/

^^^^^^^^^^^^^^^^^
Ubuntu
^^^^^^^^^^^^^^^^^
Direct links:

* Docker install: https://docs.docker.com/install/linux/docker-ce/ubuntu/
* Docker compose (run all Docker images and link them with 1 command): https://docs.docker.com/compose/install/
* No ``sudo`` needed anymore for Docker commands: ``sudo usermod -a -G docker $USER``

------------------------------------------------
2. Start FACSvatar Docker images
------------------------------------------------
With a terminal opened in folder `FACSvatar/modules`:

* ``docker-compose pull && docker-compose up`` (This will download and then start all FACSvatar modules as Docker container using the file `docker-compose.yml`)

------------------------
3. Start Unity3D
------------------------
1. Download unity_FACSvatar compiled / run with editor:

* `unity_FACSvatar.exe (Windows) <https://>`_
* :ref:`Linux / Mac / Unity3D editor (documentation) <unity3d-setup>`.

2. Double click .exe / Press play button in Unity3D editor

------------------------
4. FACSvatar Offline
------------------------

1. Open 2nd terminal in folder `FACSvatar/modules` and execute: ``docker-compose exec facsvatar_facsfromcsv bash``
2. (Now inside Docker containter) Start facial animation with: ``python main.py --pub_ip facsvatar_bridge``


-------------------------------------------------
4. FACSvatar real-time with webcam (Windows only)
-------------------------------------------------

1. Download a `modified OpenFace with ZeroMQ (v2.0.6) <https://numessanguis.stackstorage.com/s/qHqzGSi5zxC73rk/>`_ (`see copyright <https://github.com/TadasBaltrusaitis/OpenFace/blob/master/Copyright.txt>`_) –> menu: File –> Open Webcam

Please see the `FACSvatar GitHub page <https://github.com/NumesSanguis/FACSvatar>`_ for the Quickstart instructions.

------------------------------------------------
Quickstart video
------------------------------------------------
See the quickstart video:
See the quickstart video: SOON


------------------------------------------------
Expand Down

0 comments on commit 483a26b

Please sign in to comment.