README.md

   1 # Facial Landmarks for Cubism
   2
   3 A library that extracts facial landmarks from a webcam feed 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 ## Spin-off: Mouse Tracking for Cubism
  19
  20 An alternative version using mouse cursor tracking and audio based lip
  21 syncing instead of face tracking is available at
  22 <https://github.com/adrianiainlam/mouse-tracker-for-cubism>.
  23
  24 The main advantage is a much lower CPU load.
  25
  26 ## Supporting environments
  27
  28 This library was developed and tested only on Ubuntu 18.04 using GCC 7.5.0.
  29 However I don't think I've used anything that prevents it from being
  30 cross-platform compatible -- it should still work as long as you have a
  31 recent C/C++ compiler. The library should only require C++11. The Cubism
  32 SDK requires C++14. I have made use of one C++17 library (`<filesystem>`)
  33 in the example program, but it should be straightforward to change this
  34 if you don't have C++17 support.
  35
  36 I have provided some shell scripts for convenience when building. In an
  37 environment without a `/bin/sh` shell you may have to run the commands
  38 manually. Hereafter, all build instructions will assume a Linux environment
  39 where a shell is available.
  40
  41 If your CPU does not support AVX instructions you may want to edit "build.sh"
  42 and "example/demo.patch" to remove the `-D USE_AVX_INSTRUCTIONS=1` variable
  43 (or change AVX to SSE4 or SSE2). However there could be a penalty in
  44 performance.
  45
  46 ## Build instructions
  47
  48 1. Install dependencies.
  49
  50    You will require a recent C/C++ compiler, `make`, `patch`, CMake >= 3.16,
  51    and the OpenCV library (I'm using version 4.3.0). To compile the example
  52    program you will also require the OpenGL library (and its dev headers)
  53    among other libraries required for the example program. The libraries I
  54    had to install on Ubuntu 18.04 (this list may not be exhaustive) are:
  55
  56        libgl1-mesa-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libglu1-mesa-dev
  57
  58    A Debian Bullseye user has [reported](https://github.com/adrianiainlam/facial-landmarks-for-cubism/issues/2)
  59    the following extra requirements:
  60
  61        libopencv-dev libopenblas-dev liblapack-dev
  62
  63 2. Clone this repository including its submodule (dlib)
  64
  65        git clone --recurse-submodules https://github.com/adrianiainlam/facial-landmarks-for-cubism.git
  66
  67 3. To build the library only: (Skip this step if you want to build the example
  68    program. It will be done automatically.)
  69
  70        cd <path of the git repo>
  71        ./build.sh
  72
  73 4. You will require a facial landmark dataset to use with dlib. I have
  74    downloaded mine from
  75    <http://dlib.net/files/shape_predictor_68_face_landmarks.dat.bz2>.
  76    Extract the file and edit the "config.txt" file to point to the
  77    path to this file.
  78
  79    Note: The license for this dataset excludes commercial use. If you want
  80    to use this library in a commercial product you will need to obtain a
  81    dataset in some other way.
  82
  83 To build the example program:
  84
  85 5. Copy the extracted dlib dataset from step 4 to the "example" folder
  86    of this repo.
  87
  88 6. Download "Cubism 4 SDK for Native R2" from the Live2D website:
  89    <https://www.live2d.com/en/download/cubism-sdk/download-native/>.
  90
  91    Extract the archive -- put the "CubismSdkForNative-4-r.2" folder under
  92    the "example" folder of this repo.
  93
  94    Note: The Cubism SDK is the property of Live2D and is not part of this
  95    project. You must agree to Live2D's license agreements to use it.
  96
  97 7. Go into the
  98    "example/CubismSdkForNative-4-r.2/Samples/OpenGL/thirdParty/scripts"
  99    directory and run
 100
 101        ./setup_glew_glfw
 102
 103 8. Go back to the "example" directory and run
 104
 105        ./build.sh
 106
 107 9. Now try running the example program. From the "example" directory:
 108
 109        cd ./demo_build/build/make_gcc/bin/Demo/
 110        ./Demo
 111
 112
 113 ## Command-line arguments for the example program
 114
 115 Most command-line arguments are to control the Cubism side of the program.
 116 Only one argument (`--config`) is used to specify the configuration file
 117 for the Facial Landmarks for Cubism library.
 118
 119  * `--window-width`, `-W`: Specify the window width
 120  * `--window-height`, `-H`: Specify the window height
 121  * `--window-title`, `-t`: Specify the window title
 122  * `--root-dir`, `-d`: The directory at which the "Resources" folder will
 123    be found. This is where the model data will be located.
 124  * `--scale-factor`, `-f`: How the model should be scaled
 125  * `--translate-x`, `-x`: Horizontal translation of the model within the
 126    window
 127  * `--translate-y`, `-y`: Vertical translation of the model within the window
 128  * `--model`, `-m`: Name of the model to be used. This must be located inside
 129    the "Resources" folder.
 130  * `--old-param-id`, `-o`: If set to 1, translate new (Cubism 3+) parameter
 131    IDs to old (Cubism 2.1) IDs. This is necessary, for example, for
 132    [the Chitose model available from Live2D](https://www.live2d.com/en/download/sample-data/).
 133  * `--config`, `-c`: Path to the configuration file for the Facial Landmarks
 134    for Cubism library. See below for more details.
 135
 136
 137 ## Configuration file
 138
 139 Due to the differences in hardware and differences in each person's face,
 140 I have decided to make pretty much every parameter tweakable. The file
 141 "config.txt" lists and documents all parameters and their default values.
 142 You can change the values there and pass it to the example program using
 143 the `-c` argument. If using the library directly, the path to this file
 144 should be passed to the constructor (or pass an empty string to use
 145 default values).
 146
 147 ## Troubleshooting
 148
 149 1. Example program crashes with SIGILL (Illegal instruction).
 150
 151    Your CPU probably doesn't support AVX instructions which is used by dlib.
 152    You can confirm this by running
 153
 154        grep avx /proc/cpuinfo
 155
 156    If this is the case, try to find out if your CPU supports SSE4 or SSE2,
 157    then edit "build.sh" and "example/demo.patch" to change
 158    `USE_AVX_INSTRUCTIONS=1` to `USE_SSE4_INSTRUCTIONS=1` or
 159    `USE_SSE2_INSTRUCTIONS=1`.
 160
 161 ## License
 162
 163 The library itself is provided under the MIT license. By "the library itself"
 164 I refer to the following files that I have provided under this repo:
 165
 166  * src/facial_landmark_detector.cpp
 167  * src/math_utils.h
 168  * include/facial_landmark_detector.h
 169  * and if you decide to build the binary for the library, the resulting
 170    binary file (typically build/libFacialLandmarksForCubism.a)
 171
 172 The license text can be found in LICENSE-MIT.txt, and also at the top of
 173 the .cpp and .h files.
 174
 175 The library makes use of the dlib library, provided here as a Git
 176 submodule, which is used under the Boost Software License, version 1.0.
 177 The full license text can be found under lib/dlib/dlib/LICENSE.txt.
 178
 179 The example program is a patched version of the sample program provided
 180 by Live2D (because there's really no point in reinventing the wheel),
 181 and as such, as per the licensing restrictions by Live2D, is still the
 182 property of Live2D.
 183
 184 The patch file (example/demo.patch) contains lines showing additions by
 185 me, as well as deleted lines and unchanged lines for context. The deleted
 186 and unchanged lines are obviously still owned by Live2D. For my additions,
 187 where substantial enough for me to claim ownership, I release them under
 188 the Do What the Fuck You Want to Public License, version 2. The full license
 189 text can be found in LICENSE-WTFPL.txt.
 190
 191 All other files not mentioned above that I have provided in this repo
 192 (i.e. not downloaded and placed here by you), *excluding* the two license
 193 documents and files generated by Git, are also released under the Do What
 194 the Fuck You Want to Public License, version 2, whose full license text
 195 can be found in LICENSE-WTFPL.txt.
 196
 197 In order to use example program, or in any other way use this library
 198 with the Live2D® Cubism SDK, you must agree to the license by Live2D Inc.
 199 Their licenses can be found here:
 200 <https://www.live2d.com/en/download/cubism-sdk/download-native/>.
 201
 202 The library requires a facial landmark dataset, and the one provided by
 203 dlib (which is derived from a dataset owned by Imperial College London)
 204 has been used in development. The license for this dataset excludes
 205 commercial use. You must obtain an alternative dataset if you wish to
 206 use this library commercially.
 207
 208 This is not a license requirement, but if you find my library useful,
 209 I'd love to hear from you! Send me an email at spam(at)adrianiainlam.tk --
 210 replacing "spam" with the name of this repo :).
 211
 212 ## Contributions
 213
 214 Contributions welcome! This is only a hobby weekend project so I don't
 215 really have many environments / faces to test it on. Feel free to submit
 216 issues or pull requests on GitHub, or send questions or patches to me
 217 (see my email address above) if you prefer email. Thanks :)
 218