Getting Started¶
facelift
package installed so you can start detecting face features.
If you run into any issues with installation, please create a Bug Report
with details about your current operating system and package version and we can try to
improve our setup documentation.System Requirements¶
There are several required system requirements necessary for this package to work which we unfortunately cannot bundle in this package. The following sections will lead you through the installation of the necessary system requirements.
cmake¶
This tool is necessary as dlib needs to be built upon install.
Debian / Ubuntu
apt install cmake
Homebrew
brew install cmake
Macports
port install cmake
Download the CMake installer and make sure to enable the setting to “Add CMake to the system PATH for all users” when installing. You may need to restart your shell depending on what terminal emulator you are using in Windows.
Make sure that you can run cmake --version in your shell without recieving a
non-zero exit status code to verify your installation.
libmagic¶
This library helps us to determine the type of content we are attempting to process. We need this to be able to optimally determine how to consume the data for an arbitrary media file since OpenCV is pretty lacking in this area.
Debian / Ubuntu
apt install libmagic1
Homebrew
brew install libmagic
Macports
port install file
We install python-magic-bin
as a dependency if you are installing from a Windows environment.
This package should contain working binaries for libmagic built for
Windows.
If you encounter unhandled errors using libmagic on Windows, please create an
issue to let us know what you
are experiencing.
Package Installation¶
Installing the package should be super duper simple as we utilize Python’s setuptools.
$ poetry add facelift
$ # or if you're old school...
$ pip install facelift
Or you can build and install the package from the git repo.
$ git clone https://github.com/stephen-bunn/facelift.git
$ cd ./facelift
$ python setup.py install
Installing opencv-python should be quick for many environments as prebuilt
packages are provided from PyPi.
If you find that you are building OpenCV on installation, it’s likely that you are
installing an old version from pythonhosted.org which does not include prebuilt
binaries.
This will likely cause many issues with OpenCV not being built with proper support for
GTK X11 support which is necessary for reading media and opening windows.
If you run into this, try updating your local pip to the newest version (which
should install the dependency from PyPi).
Note that this dependency doesn’t come prebuilt with any GPU support.
The dlib dependency will always need to be built when installing facelift.
This requires that cmake is available on the system and doesn’t build with any GPU
support.
Model Installation¶
Due to PyPi’s upload limits, we cannot bundle the associated landmark and ResNet models
for face detection or face encoding.
Similar to how other projects have dealt with this issue in the past, we have supplied a
special module _data to programmatically fetch the necessary pre-trained models
for using this package.
The download_data() function will attempt to fetch the models uploaded to
the latest GitHub release.
from facelift._data import download_data
download_data()
If for some reason we mess up and forget to upload the models to the GitHub release, you
can manually specify the release tag using the release_tag parameter.
This will attempt to fetch the models from a very release instead of the very latest.
from facelift._data import download_data
download_data(release_tag="v0.1.0")
You can also see the basic download status written out to stdout by setting the
display_progress parameter to True.
from facelift._data import download_data
download_data(display_progress=True)
I would prefer to be able to bundle the models along with the package since we are building a project revolving around very specific feature models and frameworks (rather than providing an open-ended framework for face detection). However, this is just something we need to do to satisfy PyPi.
Important
At the moment, the downloaded models will be placed in a data directory within
the facelift package.
This means that your system or virtual environment will contain the downloaded
models.
If you are interested in the absolute path that the downloaded models are being
written to, you should set the display_progress flag to True as we write out
where files are being stored.
GPU Support¶
To drastically speed up the processing and detection of face features we need to manually build both OpenCV and dlib for the machine’s GPU. To do this we need to override the prebuilt CPU-only libraries included in the default installation of the package.
Tip
I’m going to try and get a guide together for building opencv-python and dlib
with GPU support after a v1.0.0 release as it is a secondary milestone for this
project.