README.md

   1 # Facial Landmarks for Cubism
   2
   3 A library that extracts facial landmarks from a webcam feed (computed by [OpenSeeFace](https://github.com/emilianavt/OpenSeeFace)) and converts them
   4 into Live2D® Cubism SDK parameters.
   5
   6 *Disclaimer: This library is designed for use with the Live2D® Cubism SDK.
   7 It is not part of the SDK itself, and is not affiliated in any way with Live2D
   8 Inc. The Live2D® Cubism SDK belongs solely to Live2D Inc. You will need to
   9 agree to Live2D Inc.'s license agreements to use the Live2D® Cubism SDK.*
  10
  11 This block diagram shows the intended usage of this library:
  12
  13 ![Block diagram showing interaction of this library with other components](block_diagram.png)
  14
  15 Video showing me using the example program:
  16 <https://youtu.be/SZPEKwEqbdI>
  17
  18 ## Old version using dlib
  19 The old version using dlib is no longer actively maintained, but if
  20 you want to use it, you can get it on the [dlib-stable branch](https://github.com/adrianiainlam/facial-landmarks-for-cubism/tree/dlib-stable).
  21
  22 ## Spin-off: Mouse Tracking for Cubism
  23
  24 An alternative version using mouse cursor tracking and audio based lip
  25 syncing instead of face tracking is available at
  26 <https://github.com/adrianiainlam/mouse-tracker-for-cubism>.
  27
  28 The main advantage is a much lower CPU load.
  29
  30 ## Supporting environments
  31
  32 This library was tested on Ubuntu 18.04 using GCC 7.5.0, and on
  33 Windows 10 using Visual Studio 2019.
  34
  35 The library should only require C++11. The Cubism
  36 SDK requires C++14. I have made use of one C++17 library (`<filesystem>`)
  37 in the example program, but it should be straightforward to change this
  38 if you don't have C++17 support.
  39
  40 ## Build instructions
  41
  42 1. Clone OpenSeeFace from <https://github.com/emilianavt/OpenSeeFace>,
  43    refer to its documentation and install its dependencies.
  44
  45 2. Install dependencies.
  46
  47    On Linux:
  48
  49    You will require a recent C/C++ compiler, `make`, `patch`, and CMake >= 3.16. To compile the example
  50    program you will also require the OpenGL library (and its dev headers)
  51    among other libraries required for the example program. The libraries I
  52    had to install on Ubuntu 18.04 (this list may not be exhaustive) are:
  53
  54        libgl1-mesa-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libglu1-mesa-dev
  55
  56    On Windows:
  57
  58    You will need a recent C/C++ compiler (I've tested Visual Studio 2019),
  59    `patch`, CMake >= 3.16, and a `sh` shell (Git Bash works fine). I did not
  60    need to install any other library, but I have not tested on a clean machine.
  61
  62 3. Clone this repository
  63
  64        git clone https://github.com/adrianiainlam/facial-landmarks-for-cubism.git
  65
  66 4. To build the library only: (Skip this step if you want to build the example
  67    program. It will be done automatically.)
  68
  69        cd <path of the git repo>
  70        ./build.sh
  71
  72 To build the example program:
  73
  74 5. Download "Cubism 4 SDK for Native R6" from the Live2D website:
  75    <https://www.live2d.com/en/download/cubism-sdk/download-native/>.
  76
  77    Extract the archive -- put the "CubismSdkForNative-4-r.6" folder under
  78    the "example" folder of this repo.
  79
  80    Note: The Cubism SDK is the property of Live2D and is not part of this
  81    project. You must agree to Live2D's license agreements to use it.
  82
  83 6. Go into the
  84    "example/CubismSdkForNative-4-r.6/Samples/OpenGL/thirdParty/scripts"
  85    directory and run
  86
  87        ./setup_glew_glfw
  88
  89 7. Go back to the "example" directory and run
  90
  91        ./build.sh
  92
  93    On Linux, the build should be complete after running this script.
  94    On Windows, you will also need to go into "./demo_build/scripts"
  95    and run one of the scripts corresponding to your MSVC version.
  96    The script will ask for your configurations. I've tried "1 2 1"
  97    which works fine for me.
  98
  99 8. Now try running the example program.
 100
 101    First, (in a separate terminal) go to where you have downloaded
 102    OpenSeeFace, and run
 103
 104        ./python3 ./facetracker.py -v 4 --model 3 -M
 105
 106    I tried models 3 and 4, and I think both work reasonably well.
 107    Please feel free to explore other options provided by OSF.
 108
 109    Back to the original terminal, from the "example" directory:
 110    (for Windows, replace "make_gcc" with your MSVC version)
 111
 112        cd ./demo_build/build/make_gcc/bin/Demo/
 113        ./Demo
 114
 115
 116 ## Command-line arguments for the example program
 117
 118 Most command-line arguments are to control the Cubism side of the program.
 119 Only one argument (`--config`) is used to specify the configuration file
 120 for the Facial Landmarks for Cubism library.
 121
 122  * `--window-width`, `-W`: Specify the window width
 123  * `--window-height`, `-H`: Specify the window height
 124  * `--window-title`, `-t`: Specify the window title
 125  * `--root-dir`, `-d`: The directory at which the "Resources" folder will
 126    be found. This is where the model data will be located.
 127  * `--scale-factor`, `-f`: How the model should be scaled
 128  * `--translate-x`, `-x`: Horizontal translation of the model within the
 129    window
 130  * `--translate-y`, `-y`: Vertical translation of the model within the window
 131  * `--model`, `-m`: Name of the model to be used. This must be located inside
 132    the "Resources" folder.
 133  * `--old-param-id`, `-o`: If set to 1, translate new (Cubism 3+) parameter
 134    IDs to old (Cubism 2.1) IDs. This is necessary, for example, for
 135    [the Chitose model available from Live2D](https://www.live2d.com/en/download/sample-data/).
 136  * `--config`, `-c`: Path to the configuration file for the Facial Landmarks
 137    for Cubism library. See below for more details.
 138
 139
 140 ## Configuration file
 141
 142 Due to the differences in hardware and differences in each person's face,
 143 I have decided to make pretty much every parameter tweakable. The file
 144 "config.txt" lists and documents all parameters and their default values.
 145 You can change the values there and pass it to the example program using
 146 the `-c` argument. If using the library directly, the path to this file
 147 should be passed to the constructor (or pass an empty string to use
 148 default values).
 149
 150 ## License
 151
 152 The library itself is provided under the MIT license. By "the library itself"
 153 I refer to the following files that I have provided under this repo:
 154
 155  * src/facial_landmark_detector.cpp
 156  * src/math_utils.h
 157  * include/facial_landmark_detector.h
 158  * and if you decide to build the binary for the library, the resulting
 159    binary file (typically build/libFacialLandmarksForCubism.a)
 160
 161 The license text can be found in LICENSE-MIT.txt, and also at the top of
 162 the .cpp and .h files.
 163
 164 The example program is a patched version of the sample program provided
 165 by Live2D (because there's really no point in reinventing the wheel),
 166 and as such, as per the licensing restrictions by Live2D, is still the
 167 property of Live2D.
 168
 169 The patch file (example/demo.patch) contains lines showing additions by
 170 me, as well as deleted lines and unchanged lines for context. The deleted
 171 and unchanged lines are obviously still owned by Live2D. For my additions,
 172 where substantial enough for me to claim ownership, I release them under
 173 the Do What the Fuck You Want to Public License, version 2. The full license
 174 text can be found in LICENSE-WTFPL.txt.
 175
 176 All other files not mentioned above that I have provided in this repo
 177 (i.e. not downloaded and placed here by you), *excluding* the two license
 178 documents and files generated by Git, are also released under the Do What
 179 the Fuck You Want to Public License, version 2, whose full license text
 180 can be found in LICENSE-WTFPL.txt.
 181
 182 In order to use example program, or in any other way use this library
 183 with the Live2D® Cubism SDK, you must agree to the license by Live2D Inc.
 184 Their licenses can be found here:
 185 <https://www.live2d.com/en/download/cubism-sdk/download-native/>.
 186
 187 This is not a license requirement, but if you find my library useful,
 188 I'd love to hear from you! Send me an email at spam(at)adrianiainlam.tk --
 189 replacing "spam" with the name of this repo :).
 190
 191 ## Contributions
 192
 193 Contributions welcome! This is only a hobby weekend project so I don't
 194 really have many environments / faces to test it on. Feel free to submit
 195 issues or pull requests on GitHub, or send questions or patches to me
 196 (see my email address above) if you prefer email. Thanks :)
 197
 198 Special thanks to GitHub user @Arkueid for adding Windows support!