{"id":13857078,"url":"https://github.com/iitzco/faced","last_synced_at":"2025-10-20T00:33:38.243Z","repository":{"id":100459796,"uuid":"145873427","full_name":"iitzco/faced","owner":"iitzco","description":"🚀 😏 Near Real Time CPU Face detection using deep learning","archived":false,"fork":false,"pushed_at":"2019-12-22T16:35:52.000Z","size":89651,"stargazers_count":551,"open_issues_count":29,"forks_count":145,"subscribers_count":39,"default_branch":"master","last_synced_at":"2025-03-29T12:08:46.052Z","etag":null,"topics":["computer-vision","convolutional-neural-networks","deep-learning","face-detection","fully-convolutional-networks","python","python-library","tensorflow"],"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/iitzco.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}},"created_at":"2018-08-23T15:33:53.000Z","updated_at":"2025-01-22T06:23:48.000Z","dependencies_parsed_at":"2023-05-14T20:45:24.635Z","dependency_job_id":null,"html_url":"https://github.com/iitzco/faced","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/iitzco%2Ffaced","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iitzco%2Ffaced/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iitzco%2Ffaced/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iitzco%2Ffaced/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iitzco","download_url":"https://codeload.github.com/iitzco/faced/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339158,"owners_count":20923014,"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","convolutional-neural-networks","deep-learning","face-detection","fully-convolutional-networks","python","python-library","tensorflow"],"created_at":"2024-08-05T03:01:25.171Z","updated_at":"2025-10-20T00:33:33.218Z","avatar_url":"https://github.com/iitzco.png","language":"Python","readme":"# *faced*\n\n🚀 😏 CPU (Near) Real Time face detection\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"examples/demo_yolo.gif\"/\u003e\n\u003c/p\u003e\n\n## How to install\n\n```bash\n$ pip install git+https://github.com/iitzco/faced.git\n```\n\n\u003e Soon to be available on `PyPI`.\n\n## How to use\n\n### As library\n\n```python\nimport cv2\n\nfrom faced import FaceDetector\nfrom faced.utils import annotate_image\n\nface_detector = FaceDetector()\n\nimg = cv2.imread(img_path)\nrgb_img = cv2.cvtColor(img.copy(), cv2.COLOR_BGR2RGB)\n\n# Receives RGB numpy image (HxWxC) and\n# returns (x_center, y_center, width, height, prob) tuples. \nbboxes = face_detector.predict(rgb_img, thresh)\n\n# Use this utils function to annotate the image.\nann_img = annotate_image(img, bboxes)\n\n# Show the image\ncv2.imshow('image',ann_img)\ncv2.waitKey(0)\ncv2.destroyAllWindows()\n```\n\n### As command-line program\n\n```bash\n# Detection on image saving the output\n$ faced --input imgs/demo.png --save\n```\n\nor\n\n```bash\n# Live webcam detection\n$ faced --input webcam\n```\n\nor\n\n```bash\n# Detection on video with low decision threshold\n$ faced --input imgs/demo.mp4 --threshold 0.5\n```\n\nSee `faced --help` for more information.\n\n## Examples\n\n\u003cp float=\"left\"\u003e\n  \u003cimg src=\"examples/arg-faced.png\" width=\"400\" /\u003e\n  \u003cimg src=\"examples/gino-faced.png\" width=\"400\" /\u003e\n\u003c/p\u003e\n\u003cp float=\"left\"\u003e\n  \u003cimg src=\"examples/foo-faced.png\" width=\"400\" /\u003e\n  \u003cimg src=\"examples/tri-faced.png\" width=\"200\" /\u003e\n\u003c/p\u003e\n\u003cp float=\"left\"\u003e\n  \u003cimg src=\"examples/phelps-faced.png\" width=\"400\" /\u003e\n  \u003cimg src=\"examples/will-faced.png\" width=\"400\" /\u003e\n\u003c/p\u003e\n\n## Performance\n\nCPU (i5 2015 MBP)          |  GPU (Nvidia TitanXP)\n:-------------------------:|:-------------------------:\n~5 FPS  | \u003e 70 FPS\n\n## Comparison with Haar Cascades\n\nHaar Cascades are one of the most used face detections models. Here's a comparison with OpenCV's implementation showing *faced* robustness.\n\n*faced*             |  Haar Cascade\n:-------------------------:|:-------------------------:\n![](examples/demo_yolo.gif)  |  ![](examples/demo_haar.gif)\n![](examples/foo-faced.png)  |  ![](examples/foo-haar.png)\n![](examples/gino-faced.png)  |  ![](examples/gino-haar.png)\n\n## About *faced*\n\n*faced* is an ensemble of 2 deep neural networks (implemented using **tensorflow**) designed to run at Real Time speed in CPUs.\n\n#### Stage 1:\n\nA custom fully convolutional neural network (FCNN) implementation based on [YOLO](https://pjreddie.com/darknet/yolo/). Takes a 288x288 RGB image and outputs a 9x9 grid where each cell can predict bounding boxes and probability of one face.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"examples/cnn-scheme.png\"/\u003e\n\u003c/p\u003e\n\n\n#### Stage 2:\n\nA custom standard CNN (Convolutions + Fully Connected layers) is used to take a face-containing rectangle and predict the face bounding box. This is a fine-tunning step. (outputs of Stage 1 model is not so accurate by itself, this is a *corrector* step that takes the each bouding box predicted from the previous step to improve bounding box quality.)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"examples/face-corrector-scheme.png\"/\u003e\n\u003c/p\u003e\n\n\n### Why not just perform transfer learning on trained YOLO (or MobileNet+SSD) ?\n\nThose models were designed to support multiclass detection (~80 classes). Because of this, these networks have to be powerfull enough to capture many different low and high level features that allow them to understand the patterns of very different classes. Powerful in this context means large amount of learnable parameters and hence big networks. These big networks cannot achieve real time performance on CPUs. [1]\n\nThis is an overkill for the simple task of just detecting faces. This work is a proof of concept that lighter networks can be designed to perform simpler tasks that do not require relatively large number of features.\n\n[1] Those models cannot perform Real Time on CPU (YOLO at least). Even tiny-yolo version cannot achieve 1 fps on CPU (tested on 2015 MacBook Pro with 2.6 GHz Intel Core i5).\n\n### How was it trained?\n\nTraining was done with [WIDER FACE](http://mmlab.ie.cuhk.edu.hk/projects/WIDERFace/) dataset on Nvidia Titan XP GPU.\n\n\u003e If you are interested in the training process and/or data preprocessing, just raise an `issue` and we'll discuss it there.\n\n### How to run on GPU?\n\nJust install `tensorflow-gpu` instead of `tensorflow`.\n\n### Status\n\n🚧 Work in progress 🚧\nModels will be improved and uploaded.\n\n**This is not a Production ready system. Use it at your own risk.**\n\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiitzco%2Ffaced","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiitzco%2Ffaced","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiitzco%2Ffaced/lists"}