{"id":20906066,"url":"https://github.com/sashacmc/face-rec-tools","last_synced_at":"2025-05-13T05:31:26.198Z","repository":{"id":171352754,"uuid":"222993606","full_name":"sashacmc/face-rec-tools","owner":"sashacmc","description":"Media library face recognition tools","archived":false,"fork":false,"pushed_at":"2021-05-01T23:17:22.000Z","size":621,"stargazers_count":22,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-01T18:50:16.630Z","etag":null,"topics":["cuda-support","dlib","face-recognition"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sashacmc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2019-11-20T17:40:17.000Z","updated_at":"2025-02-17T10:51:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"0115f5bb-d794-44aa-8e35-060a746d4c9f","html_url":"https://github.com/sashacmc/face-rec-tools","commit_stats":null,"previous_names":["sashacmc/face-rec-tools"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sashacmc%2Fface-rec-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sashacmc%2Fface-rec-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sashacmc%2Fface-rec-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sashacmc%2Fface-rec-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sashacmc","download_url":"https://codeload.github.com/sashacmc/face-rec-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253883026,"owners_count":21978593,"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":["cuda-support","dlib","face-recognition"],"created_at":"2024-11-18T13:28:51.225Z","updated_at":"2025-05-13T05:31:26.192Z","avatar_url":"https://github.com/sashacmc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Face Rec Tools\n[![Total alerts](https://img.shields.io/lgtm/alerts/g/sashacmc/face-rec-tools.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/sashacmc/face-rec-tools/alerts/)\n[![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/sashacmc/face-rec-tools.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/sashacmc/face-rec-tools/context:javascript)\n[![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/sashacmc/face-rec-tools.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/sashacmc/face-rec-tools/context:python)\n\nMedia library face recognition tools\n## Features\n  * Detect faces in photo/video files\n  * Match faces to face patterns\n  * Patterns manipulation\n  * Face database search\n  * Tagging faces in the Plex Media Server library \n\n## Requirements\n  * Debian based Linux (Other Linux versions not officially supported, but might work)\n  * Python 3.6+\n  * NVIDIA GPU (optional)\n  * Plex Media Server (optional)\n\n## Dependencies\n  * OpenCV + python3 bindings (better with CUDA support)\n  * DLib + python3 bindings (better with CUDA support)\n  * TensorFlow + python3 binding (optional)\n  * deepface python3 library (optional)\n  * numpy python3 library\n  * face_alignment python3 library\n  * face_recognition python3 library\n  * python3-piexif python3 library\n\n## Installation\n\n### Dependencies installation\n\n#### Build tools and install tools\nFor building dlib and others\n```bash\nsudo apt-get install build-essential cmake python3-pip\n```\n\n#### OpenCV (skip if you have NVIDIA GPU)\n```bash\nsudo apt-get install python3-opencv\n```\n\n#### CUDA, OpenCV and TensorFlow installation (skip if don't have NVIDIA GPU)\nInstallation of libraries with CUDA is not so easy and may be differ for different OS versions.\nSome useful links for CUDA setup\n\nhttps://developer.nvidia.com/cuda-downloads\n\nhttps://medium.com/@sb.jaduniv/how-to-install-opencv-4-2-0-with-cuda-10-1-on-ubuntu-20-04-lts-focal-fossa-bdc034109df3\n\nhttps://www.pyimagesearch.com/2019/12/09/how-to-install-tensorflow-2-0-on-ubuntu/\n\n#### Deep Face library installation (skip if don't use deepface encoding, default)\n```bash\npip3 install deepface\n```\n\n#### Face Recognition library\nInstall my face_recognition clone (there are some modification to support exteranal matched faces)\n```bash\ngit clone https://github.com/sashacmc/face_recognition.git; cd face_recognition; pip3 install .; cd ..\n```\n\n### Face Rec Tools installation\n```bash\ngit clone https://github.com/sashacmc/face-rec-tools.git; cd face-rec-tools; pip3 install .; cd ..\n```\n\n## Usage\n\n### Config file\nUse one from predefined config files or prepare you own.\n\nPredefined config files located in package's cfg folder (e.g. ~/.local/lib/python3.6/site-packages/face_rec_tools/cfg/)\n\nCopy it to default config location (~/.face-rec.cfg) or specify with command line switch \"-c\"\n```bash\ncp ~/.local/lib/python3.?/site-packages/face_rec_tools/cfg/frontal.cfg ~/.face-rec.cfg\n```\n\n### Command-Line Interface\n\n```bash\n# recognize single image and print output (useful for debug)\nface-rec-cli -a recognize_image -i imagefile.jpg\n\n# recognize single video and print summary output (useful for debug)\nface-rec-cli -a recognize_video -i videofile.mp4\n\n# recognize folder and store the result in the database\nface-rec-cli -a recognize_folder -i /folder/with/images\n\n# remove folder recognition the result from the database\nface-rec-cli -a remove_folder -i /folder/with/images\n\n# match/rematch unmatched faces in database\nface-rec-cli -a match_unmatched\n\n# match/rematch all faces in database\nface-rec-cli -a match_all\n\n# match/rematch faces from folder in database\nface-rec-cli -a match_folder -i /folder/with/images\n\n# save faces from folder (must be previously recognized)\n# cachedb must be disabled (otherwise they will saved inside cachedb)\nface-rec-cli -a save_faces -i /folder/with/images -o /folder/for/faces\n\n# find face from image in database and save them in folder\n# cachedb must be disabled (otherwise they will saved inside cachedb)\nface-rec-cli -a get_faces_by_face -i image_with_one_face.jpg -o /folder/for/faces\n```\n\n### Web Interface\nRun the server from the command line\n```bash\nface-rec-server \n```\nOpen the browser with you hostname/ip_adress and port 8081\n\nFor recognize a new folder click to \"Recognition\"-\u003e\"Add new files...\".\nAnd specify a folder which you want to recognize.\n![face_rec_screen_1](https://user-images.githubusercontent.com/28735879/104759965-fa22e580-5760-11eb-9e18-e20cc340c96f.png)\n\nFirst time the recognition will take a while, because of loading necessary models.\n\nAfter first recognition you will get all faces as unknown.\n![face_rec_screen_3](https://user-images.githubusercontent.com/28735879/104760428-a1a01800-5761-11eb-9765-cf036d2639f7.png)\n\nClick to the face (or select several with Shift/Ctrl) to add it as a pattern.\n![face_rec_screen_4](https://user-images.githubusercontent.com/28735879/104760644-edeb5800-5761-11eb-9e92-e91c159e28d6.png)\n\nPreviously added names will be saved, and you don't need to input it again.\nIf you want to change the default face logo you can add it as 0_face.jpg for each person subfolder.\n![face_rec_screen_5](https://user-images.githubusercontent.com/28735879/104760969-75d16200-5762-11eb-8e8e-0cdc55f38eb3.png)\n\nAfter patterns adding, start the match again (e.g. \"Match\"-\u003e\"Rematch folder...\")\n![face_rec_screen_6](https://user-images.githubusercontent.com/28735879/104761100-ad400e80-5762-11eb-96eb-616d1dd969f3.png)\n\nAfter matching with patterns you will have matched persons and \"weak\" matched persons, it means that it not fully matched and will not be used for sync or search.\nYou need to check them and add to patterns.\n![face_rec_screen_7](https://user-images.githubusercontent.com/28735879/104761475-3f481700-5763-11eb-843d-4e59fc49e97a.png)\n\nIf you need some additional info about the face you can click the ![srclink](https://user-images.githubusercontent.com/28735879/104761676-8c2bed80-5763-11eb-8d53-bae7abd7573c.png) icon to see the source file, or the ![pattlink](https://user-images.githubusercontent.com/28735879/104761761-a239ae00-5763-11eb-9f5a-9ec4d7189ee6.png) to see the pattern which it has been matched to.\n\nIf you have a big amount of faces you can simplify patterns separation by mean of clusterization in menu Clustering it will separate near faces to groups and will allow to add it to patterns together.\n\n### Plex Media Server synchronisation\nFace Recognition Tools allow syncing recognition results with Plex Media Server by means of tags.\nRecognized files will tagged with tags \"person:[PERSON_NAME]\"\n\n```bash\n# set all tags to the Plex database \nface-rec-plexsync -a set_tags\n\n# clear all tags from the Plex database\nface-rec-plexsync -a remove_tags\n\n# recognize all files which present in the Plex database\n# but not recognized yet and store the result in the database \nface-rec-plexsync -a sync_new\n\n# delete from database all files which not present in the Plex database\nface-rec-plexsync -a sync_deleted\n```\n\n### Seach in DB without Plex\nIf you have no Plex, or want to use some more complex search you can use follow command \n\n(it will search all files in folder 2020 which contains faces of persons Name1 and Name2)\n\n```bash\nface-rec-db -a find_files_by_names -f 2020 -n Name1,Name2\n```\n\n## Acknowledgements\nThanks to everyone who tested and gave advice.\n\n**Bug reports, suggestions and pull request are welcome!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsashacmc%2Fface-rec-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsashacmc%2Fface-rec-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsashacmc%2Fface-rec-tools/lists"}