Provide basic end-user documentation

[marco-eckstein]

I have been using InsightFace for face swapping via the Discord bot. It is super-easy to use and the results are amazing! (10/10)

Then I wanted to use InsightFace locally via the command line. Even as a software developer, I couldn't get it to run. Sorry, but the docs are a disaster and seem to be targeted at your own developers only. (0/10) The website says pip install -U insightface, which I did, but that was not sufficient.

The "documentation" does not even mention pip install -U insightface As the title and code examples suggest, this is aimed at Python developers who want to integrate InsightFace into their applications. Also, no explanation what the meaning of all these models is. Just in case, I ran pip install onnxruntime-gpu.

The wiki installation instructions are completely cryptic.

Before filing this issue, I found some hidden docs in the form of pinned issue #891. So I have downloaded antelope model files and saved them where I thought may be the model folder ~/.insightface/models/. I have saved them to both C:\Users\MyUsername\.insightface\models\antelope\*.onnx and installation directory C:\Program Files\Python310\Lib\site-packages\insightface\models\antelope\*.onnx. But insightface-cli.exe --help still gave me the error ModuleNotFoundError: No module named 'mxnet'.

After a web search, I did pip install mxnet. Now insightface-cli.exe --help gives me the error ImportError: cannot import name 'Mapping' from 'collections' (C:\Program Files\Python310\lib\collections\__init__.py)

This is too frustrating to waste more time on it.

On a related note, your discoverability of the project is very bad. I had spent hours searching for a software like yours, trying out many commercially available services and also spending many hours on https://github.com/deepfakes/faceswap, getting barely mediocre results. I only have access to your software now because a friend pointed me to a tutorial video that demonstrates how to use your Discord bot.

[phineas-pta]

in case u don't realize, this repo is oriented towards researchers (the authors have been writing several papers), so don't expect a ready-to-use software, nor discoverability/publicity for non-technical public

concerning deepfakes/faceswap (and its cousin iperov/DeepFaceLab) it requires days of training and adjusting, not several hours playing around

[nttstar]

This Python library is primarily designed for Linux systems, and if you're using Ubuntu or CentOS, you shouldn't have any issues with the installation. For Windows systems, you may encounter some installation problems, but I'm not entirely sure as I haven't used Windows for many years.

[dvjhr]

Honestly, the documentation for the basic usage (python-package) is pretty straightforward if you need something ready to use (dependencies problem aside). But yes, the documentation in general is pretty tangled as there are several pages that are not aligned or updated with each other like model details in python-package and model-zoo. I'm currently using the pretrained version of this for my research project and I found it pretty tricky but still difficult to guess or decrypt something like what function or method we could use, what parameters that we could use or change when calling a function, the meaning of some terms from output, which import to use when you want to use specific utils from the library, etc. I guess I shouldn't ask too much since I'm currently doing fine for my current project but maybe there are another people who need a more detailed and basic tutorial.

Apologize for my long write and thanks a lot for the author and friends for providing and maintaining such an amazing research repo 👍

[aidansmyth95]

Agreed, this repo is very challenging to use due to missing documentation or a getting started guide, for example how to install dependencies and run RetinaFace.