{"id":13733287,"url":"https://github.com/ina-foss/inaFaceAnalyzer","last_synced_at":"2025-05-08T09:31:57.481Z","repository":{"id":43730736,"uuid":"239547317","full_name":"ina-foss/inaFaceAnalyzer","owner":"ina-foss","description":"INA's library with pretrained models for gender and age prediction from faces.","archived":false,"fork":false,"pushed_at":"2024-10-07T18:06:59.000Z","size":9094,"stargazers_count":21,"open_issues_count":10,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-06T20:41:04.606Z","etag":null,"topics":["age","age-bias","age-estimation","age-gender-estimation","ass-subtitles","deeplearning","digital-humanities","face","face-analysis","face-classification","face-detection","face-tracking","gender","gender-bias","gender-classification","gender-classifier","pretrained-models","python","racial-bias","video"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ina-foss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-10T15:39:57.000Z","updated_at":"2025-03-19T02:28:58.000Z","dependencies_parsed_at":"2024-01-14T22:50:21.726Z","dependency_job_id":"70ed25e8-3f4c-4518-87fb-9fa9f962552b","html_url":"https://github.com/ina-foss/inaFaceAnalyzer","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ina-foss%2FinaFaceAnalyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ina-foss%2FinaFaceAnalyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ina-foss%2FinaFaceAnalyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ina-foss%2FinaFaceAnalyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ina-foss","download_url":"https://codeload.github.com/ina-foss/inaFaceAnalyzer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253036563,"owners_count":21844235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["age","age-bias","age-estimation","age-gender-estimation","ass-subtitles","deeplearning","digital-humanities","face","face-analysis","face-classification","face-detection","face-tracking","gender","gender-bias","gender-classification","gender-classifier","pretrained-models","python","racial-bias","video"],"created_at":"2024-08-03T03:00:40.662Z","updated_at":"2025-05-08T09:31:57.460Z","avatar_url":"https://github.com/ina-foss.png","language":"Python","funding_links":[],"categories":["Tools and Frameworks\u003ca title=\"Suggest an addition to the list!\" href=\"https://forms.gle/aPA41GT5AmbxrTwq5\"\u003e\u003cimg alt=\"Click button to suggest an addition\" align=\"right\" src=\"https://raw.githubusercontent.com/AI4LAM/awesome-ai4lam/main/.graphics/suggest-addition-small.svg\"\u003e\u003c/a\u003e"],"sub_categories":["Audio and video analysis, transcription, and labeling"],"readme":"# inaFaceAnalyzer: a Python toolbox for large-scale face-based description of gender representation in media with limited gender, racial and age biases\n[![test py 3.7](https://github.com/ina-foss/inaFaceAnalyzer/actions/workflows/test_py3-7.yml/badge.svg)](https://github.com/ina-foss/inaFaceAnalyzer/actions/workflows/test_py3-7.yml)\n[![test py 3.8](https://github.com/ina-foss/inaFaceAnalyzer/actions/workflows/test_py3-8.yml/badge.svg)](https://github.com/ina-foss/inaFaceAnalyzer/actions/workflows/test_py3-8.yml)\n[![test py 3.9](https://github.com/ina-foss/inaFaceAnalyzer/actions/workflows/test_py3-9.yml/badge.svg)](https://github.com/ina-foss/inaFaceAnalyzer/actions/workflows/test_py3-9.yml)\n\u003c!-- [![test py 3.10](https://github.com/ina-foss/inaFaceAnalyzer/actions/workflows/test_py3-10.yml/badge.svg)](https://github.com/ina-foss/inaFaceAnalyzer/actions/workflows/test_py3-10.yml) --\u003e\n[![PyPI version](https://badge.fury.io/py/inaFaceAnalyzer.svg)](https://badge.fury.io/py/inaFaceAnalyzer)\n[![Docker Pulls](https://img.shields.io/docker/pulls/inafoss/inafaceanalyzer)](https://hub.docker.com/r/inafoss/inafaceanalyzer)\n[![status](https://joss.theoj.org/papers/47086151f746f32165c72870978c1398/status.svg)](https://joss.theoj.org/papers/47086151f746f32165c72870978c1398)\n[![Documentation Status](https://readthedocs.org/projects/inafaceanalyzer/badge/?version=latest)](https://inafaceanalyzer.readthedocs.io/en/latest/?badge=latest)\n\n\n## About\n\n`inaFaceAnalyzer` is a Python toolbox designed for large-scale analysis of faces in image or video streams.\nIt provides a modular processing pipeline allowing to predict age and gender from faces.\nResults can be exported as tables, augmented video streams, or rich ASS subtitles.\n`inaFaceAnalyzer` is designed with speed in mind to perform large-scale media monitoring campaigns.\nThe trained age and gender classification model provided is based on a `ResNet50` architecture.\nEvaluation results are highly competitive with respect to the current state-of-the-art, and appear to reduce gender, age and racial biases.\n\nShould you need further details regarding this work, please refer to the following [paper](https://github.com/openjournals/joss-papers/blob/joss.04210/joss.04210/10.21105.joss.04210.pdf):\n\n```bibtex\n@journal{doukhan2022joss,\n  author = {David Doukhan and Thomas Petit},\n  title = {inaFaceAnalyzer: a Python toolbox for large-scale face-based description of gender representation in media with limited gender, racial and age biases},\n  journal = {JOSS - The journal of Open Source Software (currently being reviewed)},\n  year = {submission in progress}\n}\n```\n\nHave a look to sibling project [inaSpeechSegmenter](https://github.com/ina-foss/inaSpeechSegmenter).\n\n## Statement of need\n\n`inaFaceAnalyzer` is a Python framework aimed at extracting facial attribute information from massive video and image streams.\nThis information can be used in a wide range of applications including biometrics, human-computer interaction, multimedia indexation, digital humanities and media monitoring.\n\n`inaFaceAnalyzer` was realized to meet the needs of French National Audiovisual Institute ([INA](https://www.ina.fr)), in charge of archiving and providing access to more than 22 million hours of TV and radio programs.\nThe emergence of computational digital humanities and data journalism has increased the need of INA's users to access meta-data obtained from automatic information extraction methods.\n\nSince 2018, INA has realized several large-scale studies (up to 1 million hours of program analyzed) in the context of Gender Equality Monitor project, which aims at describing men and women representation differences in media based on [speech time](http://doi.org/10.18146/2213-0969.2018.jethc156), [TV text incrustations](https://larevuedesmedias.ina.fr/etude-coronavirus-information-television-bandeaux-femmes-hommes) or [facial attributes](https://inatheque.hypotheses.org/20616).\n\nSince 2022, `inaFaceAnalyzer` is used in [ARCOM](https://en.wikipedia.org/wiki/Regulatory_Authority_for_Audiovisual_and_Digital_Communication)'s (French Regulatory Authority for Audiovisual and Digital Communication) annual [report on Women representation in TV and radio](https://www.arcom.fr/mediatheque/la-representation-des-femmes-la-television-et-la-radio-rapport-sur-lexercice-2021).\nChannels statements are described jointly with `inaFaceAnalyzer`'s automatic facial attribute estimates and [inaSpeechSegmenter](https://github.com/ina-foss/inaSpeechSegmenter)'s speech-time estimates.\n\nWith respect to the high social impact associated to the studies using this software, `inaFaceAnalyzer` provide high accuracy prediction models.\nBeing aimed at describing the representation of under-represented categories of people in media, it should minimize gender, age or racial biases that are known to also affect machine learning datasets and softwares.\nIt is highly configurable, allowing to define trade-offs between accuracy and processing time depending on the scale of the analyses to be performed and on the available computational resources.\n\n\n## Installation\n`inaFaceAnalyzer` requires Python version between 3.7 and 3.9.\nPython 3.10 is not yet supported due to `onnxruntime-gpu` dependency.\n\n### Installing from sources\n```\napt-get install cmake ffmpeg libgl1-mesa-glx\ngit clone https://github.com/ina-foss/inaFaceAnalyzer.git\ncd inaFaceAnalyzer\npip install .\n./test_inaFaceAnalyzer.py # to check that the installation is ok\n```\n### Installing from pypi on ubuntu\n```\n# for GPU support, cuda, cudnn and nvidia drivers should be already installed\napt-get install cmake ffmpeg libgl1-mesa-glx\npip install inaFaceAnalyzer\n```\n\n### Using docker image\n```\n# download latest docker image from dockerhub\ndocker pull inafoss/inafaceanalyzer\n# run docker image. setting --gpu argument allows to take advantage of\n# GPU acceleration (non mandatory)\ndocker run -it --gpus=all inafoss/inafaceanalyzer /bin/bash\n# lauch unit tests (non mandatory but recommended)\npython test_inaFaceAnalyzer.py\n# use any program or API\nina_face_analyzer.py -h\n```\n\n\n## Using inaFaceAnalyzer command line programs\nSeveral scripts are provided with the distribution:\n* \u003ccode\u003eina_face_analyzer.py\u003c/code\u003e : can perform the most common processings provided by the framework\n* \u003ccode\u003eina_face_analyzer_webcam_demo.py\u003c/code\u003e : a demo script using webcam\n* \u003ccode\u003eina_face_analyzer_distributed_server.py\u003c/code\u003e and \u003ccode\u003eina_face_analyzer_distributed_worker\u003c/code\u003e : a set of scripts allowing to perform distributed analyses on a heterogeneous cluster.\n\nA detailed listing of all the options from the command line programs is available using the \u003ccode\u003e-h\u003c/code\u003e argument. We guess you don't want to read the whole listing at this point, but you can have a look at it later 😉.\n\n### Displaying detailed manual\n\n```bash\nina_face_analyzer.py -h\n```\n### Process all frames from a list of video (without tracking)\nVideo processing uses the \u003ccode\u003evideo\u003c/code\u003e engine and requires a list of input video paths, together with a directory used to store results in CSV.\nProgram initialization time requires several seconds, and we recommend using large list of files instead of calling the program for each file to process.\n```bash\n# directory storing result must exist\nmkdir my_output_directory\n# -i is followed by the list of video to analyze, and -o is followed by the name of the output_directory\nina_face_analyzer.py --engine video -i ./media/pexels-artem-podrez-5725953.mp4 -o ./my_output_directory\n# displaying the first 2 lines of the resulting CSV\nhead -n 2 ./my_output_directory/pexels-artem-podrez-5725953.csv\n\u003e\u003e frame,bbox,detect_conf,sex_decfunc,age_decfunc,sex_label,age_label\n\u003e\u003e 0,\"(945, -17, 1139, 177)\",0.999998927116394,8.408014,3.9126961,m,34.12696123123169\n# using remote urls is also an option\nina_face_analyzer.py --engine video -i 'https://github.com/ina-foss/inaFaceAnalyzer/raw/master/media/pexels-artem-podrez-5725953.mp4' -o ./my_output_directory\n```\n\nThe resulting CSV contains several columns:\n* frame: frame position in the video (here we have 5 lines corresponding to frame 0 - so 5 detected faces)\n* bbox: face bounding box\n* detect_conf: face detection confidence (dependent on the detection system used)\n* sex_decfunc and age_decfunc: raw classifier output. Can be used to smooth results or ignored.\n* sex_label: m for male and f for female\n* age_label: age prediction\n\n\n### Faster processing of a video\nIf computation time is an issue, we recommend using \u003ccode\u003e--fps 1\u003c/code\u003e which will process a single frame per second, instead of the whole amount of video frames. When using GPU architectures, we also recommend setting large \u003ccode\u003ebatch_size\u003c/code\u003e values.\n```bash\n# here we process a single frame per second, which is 25/30 faster than processing the whole video\nina_face_analyzer.py --engine video --fps 1 --batch_size 128 -i ./media/pexels-artem-podrez-5725953.mp4 -o ./my_output_directory\n```\n### Using Tracking\nTracking allows to lower computation time, since it is less costly than a face detection procedure.\nIt also allows to smooth prediction results associated to a tracked face and obtain more robust estimates.\nIt is activated with the \u003ccode\u003evideotracking\u003c/code\u003e engine and requires to define \u003ccode\u003edetect_period\u003c/code\u003e, the time period (in frames) at which the face detector will be applied.\n```bash\n# Process 5 frames per second, use face detection for 1/3 and face tracking for 2/3 frames\nina_face_analyzer.py --engine videotracking --fps 5 --detect_period 3 -i ./media/pexels-artem-podrez-5725953.mp4 -o ./my_output_directory\n# displaying the first 2 lines of the resulting CSV\nhead -n 2 ./my_output_directory/pexels-artem-podrez-5725953.csv\n\u003e\u003e frame,bbox,face_id,detect_conf,track_conf,sex_decfunc,age_decfunc,sex_label,age_label,sex_decfunc_avg,age_decfunc_avg,sex_label_avg,age_label_avg\n\u003e\u003e 0,\"(945, -17, 1139, 177)\",0,0.999998927116394,,8.408026,3.9126964,m,34.12696361541748,8.391026,3.8831162,m,33.831162452697754\n```\nResulting CSV will contain additional columns with \u003ccode\u003e_avg\u003c/code\u003e suffixes, corresponding to the smoothed estimates obtained for each tracked face. It will also contain a \u003ccode\u003eface_id\u003c/code\u003e with a numeric identifier associated to each tracked face.\n\n### Exporting results\nResults visualization allows to validate if a given processing pipeline is suited to a specific material.\n\u003ccode\u003e--mp4_export\u003c/code\u003e generate a new video with embedded bounding boxes and classification information.\n\u003ccode\u003e--ass_subtitle_export\u003c/code\u003e generate a ASS subtitle file allowing to display bounding boxes and classification results in vlc or ELAN, and which is more convenient to share..\n\n```bash\n# Process 10 frames per second, use face detection for 1/2 and face tracking for 1/2 frames\n# results are exported to a newly generated MP4 video and ASS subtitle\nina_face_analyzer.py --engine videotracking --fps 10 --detect_period 2 --mp4_export --ass_subtitle_export  -i ./media/pexels-artem-podrez-5725953.mp4 -o ./my_output_directory\n# display the resulting video\nvlc ./my_output_directory/pexels-artem-podrez-5725953.mp4\n# display the original video with the resulting subtitle files\nvlc media/pexels-artem-podrez-5725953.mp4 --sub-file my_output_directory/pexels-artem-podrez-5725953.ass\n```\n\n### Processing list of images\nThe processing of a list of images requires to use the \u003ccode\u003eimage\u003c/code\u003e engine.\nA single resulting CSV will be generated with entries for each detected faces, together with a reference to their original filename.\n```bash\n# process all images stored in directory media, outputs a single csv file\nina_face_analyzer.py --engine image -i media/* -o ./myresults.csv\n# display first 2 lines of the result file\nhead -n 2 myresults.csv\n\u003e\u003e frame,bbox,detect_conf,sex_decfunc,age_decfunc,sex_label,age_label\n\u003e\u003e media/1546923312_7cc94957e8_o.jpg,\"(57, 104, 435, 483)\",1.0,14.436495,3.5770981,m,30.770981311798096\n```\n\n### Distributing analyses over a network\n\nWe provide two scripts allowing to perform distributed large-scale analyses.\n\n\u003ccode\u003eina_face_analyzer_distributed_server.py\u003c/code\u003e is in charge of distributing a list of documents to analyze to workers distributed over the network, and to define analysis options (fps, tracking, etc..).\nThe server requires 2 positional arguments: its host name (or IP) and the path to a CSV containing one line per file to process together with the destination path of the results.\nWorkers need to have writing permissions in the destination paths (mounted with NFS, sshfs, ...). Output directories are created on the fly if they don't exist. Jobs order is randomized before being distributed to the workers. When a destination file already exists, the corresponding analysis is skipped.\n\n```bash\n# a sample job list csv with 2 records and 4 columns\n# source_path (mandatory input file path or url)\n# dest_csv (mandatory output csv)\n# dest_ass: to be used for exporting results to ass subtitles\n# dest_mp4: to be used for exporting incrusted MP4 video\ncat test.csv\n\u003e\u003e source_path,dest_csv,dest_ass,dest_mp4\n\u003e\u003e /home/ddoukhan/git_repos/inaFaceAnalyzer/media/pexels-artem-podrez-5725953.mp4,/tmp/csv/test1.csv,/tmp/ass/test1.ass,/tmp/mp4/test1.mp4\n\u003e\u003e https://github.com/ina-foss/inaFaceAnalyzer/raw/master/media/pexels-artem-podrez-5725953.mp4,/tmp/csv/test2.csv,,\n# the server define an analysis procedure at 1 FPS\n# after initialization, it display a network adress to be passed to the workers\nina_face_analyzer_distributed_server.py blahtop.ina.fr test.csv --engine video --fps 1\n\u003e\u003e parsing joblist test.csv\n\u003e\u003e Total number of files to process: 2\nProvide the following objet URI to remote ina_face_analyzer_distributed_workers:  PYRO:obj_4c027f06be5b40e7bcf2f3f1e235b68c@blahtop.ina.fr:33825\n```\n\n\u003ccode\u003eina_face_analyzer_distributed_worker.py\u003c/code\u003e is in charge of computing analyses and writing results to a centralized storage directory.\nIt requires the network adress displayed by the server in order to communicate. A good practice is to launch one worker per available GPU and set \u003ccode\u003eCUDA_AVAILABLE_DEVICES\u003c/code\u003e. Several workers can process the list of the server in parallel.\n```bash\n# CUDA_AVAILABLE_DEVICES=2 is non mandatory and tells the worker\n# to use a single GPU with id 2.\n# the PYRO:obj_ adress is displayed when lauching the server and\n# should copy/pasted when launching the worker\nCUDA_AVAILABLE_DEVICES=2 ina_face_analyzer_distributed_worker.py PYRO:obj_4c027f06be5b40e7bcf2f3f1e235b68c@blahtop.ina.fr:33825\n\u003e\u003e received job https://github.com/ina-foss/inaFaceAnalyzer/raw/master/media/pexels-artem-podrez-5725953.mp4 /tmp/test2.csv nan nan\n\u003e\u003e received job /home/ddoukhan/git_repos/inaFaceAnalyzer/media/pexels-artem-podrez-5725953.mp4 /tmp/test1.csv /tmp/test1.ass /tmp/test1.mp4\n\u003e\u003eall jobs are done\n```\n\n## Using inaFaceAnalyzer API\n\n`inaFaceAnalyzer`'s API documentation is available on [readthedocs.io](https://readthedocs.org/projects/inafaceanalyzer/).\n\nSeveral tutorial notebooks stored in directory [`tutorial_API_notebooks`](https://github.com/ina-foss/inaFaceAnalyzer/tree/master/tutorial_API_notebooks):\n\nWe provide below a brief description of these notebooks, together with links allowing to run them remotely in Google's colab platform.\nWhen using colab platform, we recommend to [take advantage of GPU acceleration](https://www.tutorialspoint.com/google_colab/google_colab_using_free_gpu.htm).\n\n* [Video Analysis Quick-Start](https://colab.research.google.com/github/ina-foss/inaFaceAnalyzer/blob/master/tutorial_API_notebooks/quick_start.ipynb): inaFaceAnalyzer is used to process video with default analysis parameters and export results to CSV, rich ASS subtitles and incrusted MP4. We also introduce FPS runtime argument allowing to speed-up analyses.\n* [Image Analysis Quick-Start](https://colab.research.google.com/github/ina-foss/inaFaceAnalyzer/blob/master/tutorial_API_notebooks/quick_start-image.ipynb): inaFaceAnalyzer is used to process image files. Final and intermediate results are displayed and exported to CSV.\n* [Advanced tutorial](https://colab.research.google.com/github/ina-foss/inaFaceAnalyzer/blob/master/tutorial_API_notebooks/advanced_tutorial.ipynb): define a custom analysis pipeline by defining 3 core parametric elements: face detection, face classification and image or video processing engine.\n\n## Contributing\nPlease feel free to open issues if you have any questions or suggestions, or if you want to contribute to `inaFaceAnalyzer` development.\nEvery contribution is very welcome!\nPlease read [CONTRIBUTING.md](https://github.com/ina-foss/inaFaceAnalyzer/blob/master/.github/CONTRIBUTING.md) for more details.\n\n## CREDITS\nThis work has been partially funded by the French National Research Agency (project GEM : Gender Equality Monitor : ANR-19-CE38-0012) and by European Union's Horizon 2020 research and innovation programme (project [MeMAD](https://memad.eu) : H2020 grant agreement No 780069).\n\nWe acknowledge contributions from [Zohra Rezgui](https://github.com/ZohraRezgui) who trained first models and wrote the first piece of code that lead to `inaFaceAnalyzer` during her internship at INA.\n```bibtex\n@techreport{rezgui2019carthage,\n  type = {Msc. Thesis},\n  author = {Zohra Rezgui},\n  title = {Détection et classification de visages pour la description de l’égalité femme-homme dans les archives télévisuelles},\n  submissiondate = {2019/11/19},\n  year = {2019},\n  url = {https://www.researchgate.net/publication/337635267_Rapport_de_stage_Detection_et_classification_de_visages_pour_la_description_de_l'egalite_femme-homme_dans_les_archives_televisuelles},\n  institution = {Higher School of Statistics and Information Analysis, University of Carthage}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fina-foss%2FinaFaceAnalyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fina-foss%2FinaFaceAnalyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fina-foss%2FinaFaceAnalyzer/lists"}