{"id":20698921,"url":"https://github.com/twcbe/known_face_detector","last_synced_at":"2026-05-15T23:11:30.311Z","repository":{"id":75889912,"uuid":"141970970","full_name":"twcbe/known_face_detector","owner":"twcbe","description":"Detect and Identify people, and emit events. Uses a modular design, can be connected to other apps using MQTT events.","archived":false,"fork":false,"pushed_at":"2018-09-07T12:59:59.000Z","size":1181,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":6,"default_branch":"master","last_synced_at":"2026-04-21T04:00:00.803Z","etag":null,"topics":["face-recognition","modular","openface","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/twcbe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2018-07-23T06:27:03.000Z","updated_at":"2020-08-16T13:07:56.000Z","dependencies_parsed_at":"2023-07-12T00:01:17.949Z","dependency_job_id":null,"html_url":"https://github.com/twcbe/known_face_detector","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/twcbe/known_face_detector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twcbe%2Fknown_face_detector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twcbe%2Fknown_face_detector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twcbe%2Fknown_face_detector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twcbe%2Fknown_face_detector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/twcbe","download_url":"https://codeload.github.com/twcbe/known_face_detector/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twcbe%2Fknown_face_detector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33082947,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T20:25:35.270Z","status":"ssl_error","status_checked_at":"2026-05-15T20:25:34.732Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["face-recognition","modular","openface","python"],"created_at":"2024-11-17T00:27:24.008Z","updated_at":"2026-05-15T23:11:30.295Z","avatar_url":"https://github.com/twcbe.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Known Face Detector\n\n[![CircleCI](https://circleci.com/gh/twlabs/face-recognition-workspace.svg?style=svg\u0026circle-token=a7216b8a8bcb8065391871ca619301bcbefcda75)](https://circleci.com/gh/twlabs/face-recognition-workspace)\n\nDetect and Identify people, and emit events. Uses a modular design, can be connected to other apps using MQTT events.\n\nThis program is easier to setup on a linux machine using docker and a camera attached to the system. There are several customizable options detailed below. To quickly get started jump to the [getting started](#getting-started) section below.\n\nIn OS X, only network cameras are supported.\n\nThe program can be run in headless mode or with display attached. The display shows the recognized person visually. In case the system doesn't recognize a person correctly it will show the next closest matching person in paranthesis. This is not a match, just shown for debugging.\n\n* Enable or disable display: \n  * `-e enable_display=True` (default False, ie. headless)\n\n* The following flags specify to store the state file containing people identities in `./data/people_identifier.json file`.\n  * `-v ./data:/data -e state_file=/data/people_identifier.json`\n\nThe source of the video feed can be anything that [OpenCV](https://opencv.org/) supports as video source! It could be a camera attached to the computer, a network camera reachable using an rtsp URI, a pre-recorded video file at a given path.\n\n* To specify the source:\n  * `-e video_device=-1 --device /dev/video0` choose the first camera attached to the machine.\n  * `-e video_device=-1 --device /dev/video1` choose the second camera attached to the machine.\n  * `-e video_device=\"rtsp://\u003cusername\u003e:\u003cpassword\u003e@\u003cip\u003e/\u003cchannel_number\u003e\"` choose a network camera reachable using the given URI. Make sure to enter the username, password, ip and channel_number.\n  * `-e video_device=\"/data/video_filename.mp4\"` make sure to put the video file in the `./data` folder.\n\n* Specify the mqtt credentials:\n  * `Host : -e mqtt_host=\u003chostname\u003e` (default docker.for.mac.localhost)\n  * `Port : -e mqtt_port=\u003cport\u003e` (default 1883)\n  * `Topic : -e mqtt_topic=\u003ctopic\u003e` (default face_recognition)\n  * `Username : -e mqtt_username=\u003cusername` (optional)\n  * `Password : -e mqtt_password=\u003cpassword\u003e` (optional)\n\n## Linux:\n### Prerequisites:\n* docker\n* mosquitto server running in local\n\n### Getting Started:\nRun the detector in headless mode with camera attached: (no need to clone this repo)\n```bash\nmkdir data\ndocker run -it --rm --name=\"known_face_detector\" -v ./data:/data --device /dev/video0 -e video_device=-1 -e state_file=/data/people_identifier.json twcbe/known_face_detector:master\n```\n(this will start running the recognizer, the logs will be printed on screen)\n\nRun the detector with display and camera attached: (no need to clone this repo)\n```bash\nmkdir data\nDISPLAY=:0 xhost + 127.0.0.1  # enable remote connections to XServer\ndocker run -it --rm --name=\"known_face_detector\" -v ./data:/data --device /dev/video0 -e enable_display=true --net=host --ipc=host -v /tmp/X11-unix:/tmp/X11-unix -e DISPLAY=:0 -e video_device=-1 -e state_file=/data/people_identifier.json twcbe/known_face_detector:master\n```\n\n## OSX:\n### Prerequisites:\n* [docker](https://www.docker.com/)\n* [xquartz](https://www.xquartz.org/) - for displaying video on screen, not necessary for headless mode.\n* xquartz -\u003e preferences -\u003e security -\u003e enable `allow connections from network clients` and restart xquartz.\n* network camera - required, since OSX does not provide a raw video device, it cannot be forwarded inside the container. One can run the program like a demo using a pre-captured video file too, in which case the network camera is not necessary.\n* mosquitto server running in local\n\n### Getting Started:\nRun the detector in headless mode with network camera: (no need to clone this repo)\n```bash\nmkdir data\ndocker run -it --rm --name=\"known_face_detector\" -v $(pwd)/data:/data -e state_file=/data/people_identifier.json -e video_device=\"rtsp://\u003cusername\u003e:\u003cpassword\u003e@\u003cip.ip.ip.ip\u003e/\u003cchannel_number\u003e\" twcbe/known_face_detector:master\n```\nRun the detector in headless mode with network camera: (no need to clone this repo)\n```bash\nmkdir data\nDISPLAY=:0 xhost + 127.0.0.1 # enable remote connections to XServer; required once after every restart of XQuartz\ndocker run -it --rm --name=\"known_face_detector\" -v ./data:/data -e state_file=/data/people_identifier.json -e video_device=\"rtsp://\u003cusername\u003e:\u003cpassword\u003e@\u003cip.ip.ip.ip\u003e/\u003cchannel_number\u003e\" -e DISPLAY=docker.for.mac.localhost:0 -e enable_display=true twcbe/known_face_detector:master\n```\n\nAll the above examples download the docker from docker hub. To build the image locally, run:\n```bash\ndocker build -t known_face_detector .\n```\n\nTo run using the local image, replace `twcbe/known_face_detector:master` in the above commands with `known_face_detector`.\n\n\nTo train new samples, make sure,\n* the person stands in front of the camera\n* the system is able to detect the face (probably recognized as `unknown`)\n* inform the system, who is standing in front of the camera using the below command:\n```\nmosquitto_pub -m \"{\\\"employee_id\\\":\\\"\u003cSOME_UNIQUE_ID_OF_THE_PERSON\u003e\\\", \\\"name\\\": \\\"\u003cNAME_OF_THE_PERSON\u003e\\\", \\\"add_current_person_detail\\\":true}\" -t 'add_person_detail'\n```\n* Now, the logs should show the training happening, and statistics about the new dataset.\n* Repeat the above command multiple times - at least 5 to 10 times.\n* The system trains while it is live, so it can start recognizing the person during the training itself\n* To reduce false positives, adjust the `MAX_DISTANCE_THRESHOLD` to 0.15 or slightly lower (default is 0.20)\n```\ndocker ... -e MAX_DISTANCE_THRESHOLD=0.15 ...\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwcbe%2Fknown_face_detector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwcbe%2Fknown_face_detector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwcbe%2Fknown_face_detector/lists"}