{"id":17594985,"url":"https://github.com/andreaconti/face_recognition_cam","last_synced_at":"2025-03-30T15:13:39.658Z","repository":{"id":73012622,"uuid":"247375325","full_name":"andreaconti/face_recognition_cam","owner":"andreaconti","description":"Face recognition camera package","archived":false,"fork":false,"pushed_at":"2020-06-26T13:31:37.000Z","size":159498,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-02-05T16:38:06.504Z","etag":null,"topics":["computer-vision","face-detection","face-recognition","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andreaconti.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":"2020-03-15T00:28:45.000Z","updated_at":"2020-06-30T14:06:12.000Z","dependencies_parsed_at":"2023-02-23T16:01:32.903Z","dependency_job_id":null,"html_url":"https://github.com/andreaconti/face_recognition_cam","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreaconti%2Fface_recognition_cam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreaconti%2Fface_recognition_cam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreaconti%2Fface_recognition_cam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreaconti%2Fface_recognition_cam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andreaconti","download_url":"https://codeload.github.com/andreaconti/face_recognition_cam/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246334430,"owners_count":20760644,"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":["computer-vision","face-detection","face-recognition","python3"],"created_at":"2024-10-22T07:25:37.022Z","updated_at":"2025-03-30T15:13:39.635Z","avatar_url":"https://github.com/andreaconti.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Face Recognition Cam\n\nThis project aims to implement a simple API for a camera with face recognition features mainly for didactic purposes but\nI hope it'll be useful to someone.\n\nTo accomplish this task some steps are required:\n\n1. find faces\n2. find facial landmarks\n3. warp faces to standard landmark positions\n4. encode faces into vectors\n5. search of similarities into a database of known faces\n\n`face_recognition_cam` takes takes care of all of them.\n\n## API Usage\n\n`face_recognition_cam` can be used as a python library, at the core of the library there are two main classes:\n\n- `FaceDetector`, used to detect a faces in the image, crop them, identify facial landmarks and align faces\n- `FaceRecognizer`, used to assign a label to each known face or classify them as unknown\n\nFinally some utilities are contained into `util` module:\n\n- `Camera` provides a way to retrieve frames from a camera.\n- `CameraAlert` class can be used to monitor a camera and execute custom functions when a face is recognized.\n\n### FaceDetector\n\n```python\nimport face_recognition_cam as fc\n\n# here we detect all faces contained in the image, this function takes care to:\n# - find each face\n# - find 5 facial landmarks and use them to align the face\n# - resize each face\n# - stack them into a numpy ndarray of shape N x H x W x C\nface_detector = fc.FaceDetector()\nfaces = face_detector.crop_aligned_faces(img, resize=(250, 250))\n```\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"readme_files/sample.jpg\" alt=\"sample image\" width=\"200\"/\u003e\n    \u003cimg src=\"readme_files/sample_crop_face.jpg\" alt=\"sample crop face\" width=\"200\"/\u003e\n\u003c/p\u003e\n\n### FaceRecognizer\n\nThis class takes care to label each face with a name, to do that a dataset of known faces is needed, such dataset can be\ngenerated using `generate_dataset`. `assign_names` method is then used to label faces.\n\n```python\nimport face_recognition_cam as fc\n\nrecognizer = fc.FaceRecognizer()\n\n# dataset generation, people is a dictionary containing as key names and as value a\n# set of N faces of that person stacked into an ndarry of shape N x 112 x 112 x 3.\n# In `util` module see `load_faces` function to generate people dictionary.\n\npeople = {\n    \"andrea\": np.random.randn(3, 112, 112, 3).astype(np.uint8)\n}\ndataset = recognizer.generate_dataset(people)\n\n# then is possible to identify faces, `min_confidence` is used to choose a threshold\n# for unknown labeling\n\nmin_confidence = 0.7\nnames = recognizer.assign_names(dataset, faces, min_confidence)\n```\n\n### CameraAlert\n\nThis class is useful when you simply want to execute some code when a face is recognized.\n\n```python\nimport face_recognition_cam as fc\n\nalert = fc.util.CameraAlert()\n\n@alert.register(\"andrea\"):\ndef say_hello():\n    print(\"Welcome Andrea!\")\n\nalert.watch(dataset)\n```\n\n## CLI Usage\n\nA simple CLI interface is also available through the `facecam` tool.\n\n```bash\n$ facecam\nusage: face detection camera [-h] {embed,trigger,show,recognize} ...\n\npositional arguments:\n  {embed,trigger,show,recognize}\n                        sub-command help\n    embed               embed a folder of faces in known faces\n    trigger             trigger from the camera and call scripts when\n                        recognize someone\n    show                watch from cam and show a window with labeled faces,\n                        for fun and debug\n    recognize           writes the name of all recognized people in the\n                        provided image\n\noptional arguments:\n  -h, --help            show this help message and exit\n```\n\n`facecam embed` can be used to generate the dataset and `facecam show` can be used\nto grasp visually the quality of recognition but the most interesting command is\n`facecam recognize` which can be used to execute bash command on recognition events.\n\n```bash\n$ facecam recognize dataset \\\n        --on \"andrea\" 'echo \"Hello Andrea\"'\n        --on \"unknown\" 'echo \"go away please\"'\n```\n\n## Implementation Details\n\nEach step in the face recognition process is quite complex and is plenty of different\nsolutions for these tasks, here a brief of used technologies and some reference:\n\n### Face Detection\n\nFor face detection there are many robust solutions such as Viola Jones [1], HoG + SVM [2]\nand many different kind of Convolutional Neural Networks. Here is used a pretrained model\nbased on the architecture called  _Single Shot Multi Box Detector_ (SSD) [3] which can\nbe found [here](https://github.com/opencv/open_model_zoo/tree/master/models/public/face-detection-retail-0044)\nunder [Apache License Version 2.0](https://github.com/opencv/open_model_zoo/blob/master/LICENSE).\n\n### Facial Landmarks Detection\n\nFacial landmarks are used to localize salient regions of the face such as eyes, nose, mouth and so\non and can be used for many purposes, such as to perform face alignment.\nAn example of 68 facial landmarks can be found into the\n[iBUG 300-W dataset](https://ibug.doc.ic.ac.uk/resources/facial-point-annotations/)\n\nMany different implementations of landmark detection exist, in this project is used the implementation\ncontained into [dlib](http://dlib.net) using only a subset of 5 landmarks to perform face.\n\n### Face Embedding\n\nFace embedding consists into the transformation of a face into a vector, such process is usually carried\nout by a proper trained neural networks and as usual many different ways to accomplish that are avaiable.\nA light and effective implementation of MobileFaceNet [4] is used here: a pretrained model can be found\nin the [OpenVINO Toolkit](https://github.com/opencv/open_model_zoo). To compare embedded faces\nis used _cosine distance_.\n\n## Performances\n\nHere a visual brief about per `face_recognition_cam` recognition performances, face detection is really effective and is robust versus different point of view, scale and rotations.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"readme_files/visual_performances/sample_1.png\" alt=\"sample image\" width=\"150\"/\u003e\n  \u003cimg src=\"readme_files/visual_performances/sample_2.png\" alt=\"sample image\" width=\"150\"/\u003e\n  \u003cimg src=\"readme_files/visual_performances/sample_3.png\" alt=\"sample image\" width=\"150\"/\u003e\n  \u003cimg src=\"readme_files/visual_performances/sample_4.png\" alt=\"sample image\" width=\"150\"/\u003e\n  \u003cimg src=\"readme_files/visual_performances/sample_5.png\" alt=\"sample image\" width=\"150\"/\u003e\n\u003c/p\u003e\n\nFace recognition is robust versus rotation and scale but it does not really handle well different points of view, below misclassified examples:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"readme_files/visual_performances/sample_3.png\" alt=\"sample image\" width=\"250\"/\u003e\n  \u003cimg src=\"readme_files/visual_performances/sample_4.png\" alt=\"sample image\" width=\"250\"/\u003e\n\u003c/p\u003e\n\nMaybe in further releases robustness will be improved.\n\nFinally occlusion is partially well handled, again face detection is quite effective and face recognition instead becames instable.\n\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"readme_files/visual_performances/sample_6.png\" alt=\"sample image\" width=\"250\"/\u003e\n  \u003cimg src=\"readme_files/visual_performances/sample_7.png\" alt=\"sample image\" width=\"250\"/\u003e\n\u003c/p\u003e\n\n\n\n---\n\n[1] P. Viola and M. J. Jones, \"Robust real-time face detection\", 2004\n\n[2] N. Dalal and B. Triggs, \"Histograms of oriented gradients for human detection\", 2005\n\n[3] W. Liu et al., \"SSD: single shot multibox detector\", 2015\n\n[4] S. Chen, Y. Liu et al., \"Mobilefacenets: Efficient cnns for accurate real-time face verification on mobile devices\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreaconti%2Fface_recognition_cam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandreaconti%2Fface_recognition_cam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreaconti%2Fface_recognition_cam/lists"}