{"id":16866127,"url":"https://github.com/elliottzheng/batch-face","last_synced_at":"2025-10-08T18:36:47.980Z","repository":{"id":54761014,"uuid":"313260950","full_name":"elliottzheng/batch-face","owner":"elliottzheng","description":"⚡Batch Face Processing for Fast Modern Research, including face detection, face alignment, face reconstruction, head pose estimation, face parsing","archived":false,"fork":false,"pushed_at":"2025-03-15T01:22:24.000Z","size":33906,"stargazers_count":89,"open_issues_count":3,"forks_count":20,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-21T00:54:49.453Z","etag":null,"topics":["face-alignment","face-detection","face-parsing","face-reconstruction","head-pose-estimation"],"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/elliottzheng.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","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-11-16T10:09:14.000Z","updated_at":"2025-04-12T10:09:59.000Z","dependencies_parsed_at":"2024-04-29T10:05:22.471Z","dependency_job_id":null,"html_url":"https://github.com/elliottzheng/batch-face","commit_stats":{"total_commits":18,"total_committers":2,"mean_commits":9.0,"dds":0.05555555555555558,"last_synced_commit":"f287028c9329babb8d4a2b997323b3e6fe257ed1"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elliottzheng%2Fbatch-face","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elliottzheng%2Fbatch-face/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elliottzheng%2Fbatch-face/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elliottzheng%2Fbatch-face/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elliottzheng","download_url":"https://codeload.github.com/elliottzheng/batch-face/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250119936,"owners_count":21378116,"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":["face-alignment","face-detection","face-parsing","face-reconstruction","head-pose-estimation"],"created_at":"2024-10-13T14:49:33.939Z","updated_at":"2025-10-08T18:36:47.973Z","avatar_url":"https://github.com/elliottzheng.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Batch Face for Modern Research\n\nThis repo provides the out-of-box face detection, face alignment, head pose estimation and face parsing with batch input support and enables real-time application on CPU.\n\n\n## Features\n1. Batch input support for faster data processing.\n2. Smart API.\n3. Ultrafast with inference runtime acceleration.\n4. Automatically download pre-trained weights.\n5. Minimal dependencies.\n6. Unleash the power of GPU for batch processing.\n\n### Requirements\n\n- Linux, Windows or macOS\n- Python 3.5+ (it may work with other versions too)\n- opencv-python\n- PyTorch (\u003e=1.0) \n- ONNX (optional)\n\nWhile not required, for optimal performance it is highly recommended to run the code using a CUDA enabled GPU.\n\n## Install\n\nThe easiest way to install it is using pip:\n\n```bash\npip install git+https://github.com/elliottzheng/batch-face.git@master\n```\nNo extra setup needs, most of the pretrained weights will be downloaded automatically.\n\nIf you have trouble install from source, you can try install from PyPI:\n\n```bash\npip install batch-face\n```\nthe PyPI version is not guaranteed to be the latest version, but we will try to keep it up to date.\n\n## Usage\nYou can clone the repo and run tests like this\n```\npython -m tests.camera\n```\n### Face Detection\n\nWe wrap the [RetinaFace](https://github.com/biubug6/Pytorch_Retinaface) model and provide a simple API for batch face detection.\n\n#### Detect face and five landmarks on single image\n```python\nimport cv2\nfrom batch_face import RetinaFace\n\ndetector = RetinaFace(gpu_id=0)\nimg = cv2.imread(\"examples/obama.jpg\")\nimg = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)\n\nmax_size = 1080 # if the image's max size is larger than 1080, it will be resized to 1080, -1 means no resize\nresize = 1 # resize the image to speed up detection, default is 1, no resize\nthreshold = 0.95 # confidence threshold\n\n# now we recommand to specify return_dict=True to get the result in a more readable way\nfaces = detector(img, threshold=threshold, resize=resize, max_size=max_size, return_dict=True)\nface = faces[0]\nbox = face['box']\nkps = face['kps']\nscore = face['score']\n\n# the old way to get the result\nfaces = detector(img, threshold=threshold, resize=resize, max_size=max_size)\nbox, kps, score = faces[0]\n\n```\n#### Running on CPU/GPU\n\nIn order to specify the device (GPU or CPU) on which the code will run one can explicitly pass the device id.\n```python\nfrom batch_face import RetinaFace\n# 0 means using GPU with id 0 for inference\n# default -1: means using cpu for inference\nfp16 = True # use fp16 to speed up detection and save GPU memory\n\ndetector = RetinaFace(gpu_id=0, fp16=True)\n```\n|      | GPU(GTX 1080TI,batch size=1) | GPU(GTX 1080TI，batch size=750) | CPU(Intel(R) Core(TM) i7-7800X CPU @ 3.50GHz) |\n| ---- | ---------------------------- | ------------------------------- | --------------------------------------------- |\n| FPS  | 44.02405810720893            | 96.64058005582535               | 15.452635835550483                            |\n| SPF  | 0.022714852809906007         | 0.010347620010375976            | 0.0647138786315918                            |\n\n\n#### Batch input for faster detection\n\n**Detector with CUDA process batch input faster than the same amount of single input.** \n\n```python\nimport cv2\nfrom batch_face import RetinaFace\n\ndetector = RetinaFace()\nimg= cv2.imread('examples/obama.jpg')\nimg = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)\n\nmax_size = 1080 # if the image's max size is larger than 1080, it will be resized to 1080, -1 means no resize\nresize = 1 # resize the image to speed up detection, default is 1, no resize\nresize_device = 'cpu' # resize on cpu or gpu, default is gpu\nthreshold = 0.95 # confidence threshold for detection\nbatch_size = 100 # batch size for detection, the larger the faster but more memory consuming, default is -1, which means batch_size = number of input images\nbatch_images = [img,img] # pseudo batch input\n\nall_faces = detector(batch_images, threshold=threshold, resize=resize, max_size=max_size, batch_size=batch_size) \nfaces = all_faces[0] # the first input image's detection result\nbox, kps, score = faces[0] # the first face's detection result\n```\n\n![](./images/gpu_batch.png)\n\n#### Batch input for different size images\n\nIn v1.5.2, we enhanced the batch support for different size images, so you can just pass a list of np.array to the detector, and the detector will resize the all images to the same size(specified by `max_size`, default is 640) and then do the detection, which makes it even faster the the previous implementation of `pseudo_batch_detect`, see [tests/detection_on_pseudo_batch.py](tests/detection_on_pseudo_batch.py) for more details.\n\n\n\n\n### Face Alignment\n\nWe wrap the [Face Landmark](https://github.com/cunjian/pytorch_face_landmark) model and provide a simple API for batch face alignment.\n\n#### face alignment on single image\n\n```python \nfrom batch_face import drawLandmark_multiple, LandmarkPredictor, RetinaFace\n\npredictor = LandmarkPredictor(0)\ndetector = RetinaFace(0)\n\nimgname = \"examples/obama.jpg\"\nimg = cv2.imread(imgname)\nimg = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)\n\nfaces = detector(img)\n\nif len(faces) == 0:\n    print(\"NO face is detected!\")\n    exit(-1)\n\n# the first input for the predictor is a list of face boxes. [[x1,y1,x2,y2]]\nresults = predictor(faces, img, from_fd=True) # from_fd=True to convert results from our detection results to simple boxes\n\nfor face, landmarks in zip(faces, results):\n    img = drawLandmark_multiple(img, face[0], landmarks)\n```\n### Head Pose Estimation\n\nWe wrap the [SixDRepNet](https://github.com/jahongir7174/SixDRepNet) model and provide a simple API for batch head pose estimation.\n\n#### Head pose estimation on video\n```python\nfrom batch_face import RetinaFace, SixDRep, draw_landmarks, load_frames_rgb, Timer\n\nvis = True\ngpu_id = 0\nbatch_size = 100\nthreshold = 0.95\ndetector = RetinaFace(gpu_id=gpu_id)\nhead_pose_estimator = SixDRep(gpu_id=gpu_id)\nvideo_file = 'examples/ross.mp4'\nframes = load_frames_rgb(video_file) # simple wrapper to load video frames with opencv and convert to RGB, 0~255, UInt8, HWC\nprint(f'Loaded {len(frames)} frames')\nprint('image size:', frames[0].shape)\n# it might take longer time to detect since is first time to run the model\nall_faces = detector(frames, batch_size=batch_size, return_dict=True, threshold=threshold, resize=0.5)\nhead_poses = head_pose_estimator(all_faces, frames, batch_size=batch_size, update_dict=True, input_face_type='dict')\n# the head pose will be updated in the all_faces dict\nout_frames = []\nfor faces, frame in zip(all_faces, frames):\n    for face in faces:\n        head_pose_estimator.plot_pose_cube(frame, face['box'], **face['head_pose'])\n    out_frames.append(frame)\n\nif vis:\n    import imageio\n    out_file = 'examples/head_pose.mp4'\n    imageio.mimsave(out_file, out_frames, fps=8)\n```\ncheck out the result video [here](./examples/head_pose.mp4)\nyou can run the script `python -m tests.video_head_pose` to see the result.\n\n### Face Parsing\n\nWe wrap the [FaRL](https://github.com/FacePerceiver/farl) model from [facer](https://github.com/FacePerceiver/facer) and provide a simple API for batch face parsing.\n\nIf you want to use the face parsing model, you need to install the `pyfacer\u003e=0.0.5` package.\n```bash\npip install pyfacer\u003e=0.0.5 -U\n```\n\n#### Face Parsing on video\n\n```python\nimport numpy as np\nimport cv2\nfrom batch_face import RetinaFace, FarlParser, load_frames_rgb\ngpu_id = 0\nvideo_file = 'examples/ross.mp4'\nretinaface = RetinaFace(gpu_id)\nface_parser = FarlParser(gpu_id=gpu_id, name='farl/lapa/448') # you can choose different model from [farl/celebm/448, farl/lapa/448]\nframes = load_frames_rgb(video_file)\nall_faces = retinaface(frames, return_dict=True, threshold=0.95)\n# optional, you can do some face filtering here, for example you can filter out \nall_faces = face_parser(frames, all_faces)\nlabel_names = face_parser.label_names\n\nprint(label_names)\nfor frame_i, (faces, frame) in enumerate(zip(all_faces, frames)):\n    for face_i, face in enumerate(faces):\n        seg_logits = face['seg_logits']\n        seg_preds = face['seg_preds']\n        vis_seg_preds = face_parser.color_lut[seg_preds]\n        # blend with input frame\n        frame = cv2.addWeighted(frame, 0.5, vis_seg_preds, 0.5, 0)\n        vis_frame = np.concatenate([vis_seg_preds, frame], axis=1)\n        cv2.imwrite(f'vis_{frame_i}_{face_i}.png', vis_frame[...,::-1])\n\n```\ncheck out the result images [here](./examples/ross_seg.png)\nyou can run the script `python -m tests.parsing_on_video` to see the result.\n\n## References\n\n- Face Detection Network and pretrained model are from [biubug6/Pytorch_Retinaface](https://github.com/biubug6/Pytorch_Retinaface)\n- Face Alignment Network and pretrained model are from [cunjian/pytorch_face_landmark](https://github.com/cunjian/pytorch_face_landmark)\n- Face Reconstruction Network and pretrained model are from [cleardusk/3DDFA](https://github.com/cleardusk/3DDFA)\n- Head Pose Estimation Network and pretrained model are from [jahongir7174/SixDRepNet](https://github.com/jahongir7174/SixDRepNet)\n- Face Parsing Network and pretrained model are from [FacePerceiver/farl](https://github.com/FacePerceiver/farl) and [FacePerceiver/facer](https://github.com/FacePerceiver/facer)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felliottzheng%2Fbatch-face","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felliottzheng%2Fbatch-face","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felliottzheng%2Fbatch-face/lists"}