{"id":19184032,"url":"https://github.com/mnjm/facial-landmarks-cnn","last_synced_at":"2025-09-11T10:39:19.853Z","repository":{"id":242745286,"uuid":"810440821","full_name":"mnjm/facial-landmarks-cnn","owner":"mnjm","description":"Facial Landmark Detection using CNN with Face Pose Estimation","archived":false,"fork":false,"pushed_at":"2024-08-01T09:11:05.000Z","size":23823,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-31T13:05:25.084Z","etag":null,"topics":["face-alignment","facial-landmarks"],"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/mnjm.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,"zenodo":null}},"created_at":"2024-06-04T17:47:51.000Z","updated_at":"2025-04-02T10:08:13.000Z","dependencies_parsed_at":"2024-08-01T10:52:27.634Z","dependency_job_id":null,"html_url":"https://github.com/mnjm/facial-landmarks-cnn","commit_stats":null,"previous_names":["mnjm/facial-landmarks-cnn"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mnjm/facial-landmarks-cnn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnjm%2Ffacial-landmarks-cnn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnjm%2Ffacial-landmarks-cnn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnjm%2Ffacial-landmarks-cnn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnjm%2Ffacial-landmarks-cnn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mnjm","download_url":"https://codeload.github.com/mnjm/facial-landmarks-cnn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnjm%2Ffacial-landmarks-cnn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274616718,"owners_count":25318215,"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","status":"online","status_checked_at":"2025-09-11T02:00:13.660Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-alignment","facial-landmarks"],"created_at":"2024-11-09T11:05:55.292Z","updated_at":"2025-09-11T10:39:19.826Z","avatar_url":"https://github.com/mnjm.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Facial Landmark Detection using CNN\n\n\nHere is a quick demo\n\n**8 Points with Face alignment / Head Pose**\n\n![Demo with hs](./demos/demo_8pts_hs.gif?raw=true)\n\n**6 Points**\n\n![Demo](./demos/demo_6pts.gif?raw=true)\n\n**Prerequisites**\n\n![TensorFlow](https://img.shields.io/badge/TensorFlow-v2.16-blue)\n![NumPy](https://img.shields.io/badge/NumPy-1.26-blue)\n![OpenCV](https://img.shields.io/badge/OpenCV-4.9-blue)\n\n## Datasets\n\n| Sources |\n| -------- |\n| [300-VW](https://ibug.doc.ic.ac.uk/resources/300-VW/) |\n| [300-W](https://ibug.doc.ic.ac.uk/resources/300-W/) |\n| [AFW](https://www.ics.uci.edu/~xzhu/face/) |\n| [HELEN](http://www.ifp.illinois.edu/~vuongle2/helen/) |\n| [IBUG](https://ibug.doc.ic.ac.uk/resources/facial-point-annotations/) |\n| [LFPW](https://neerajkumar.org/databases/lfpw/) |\n\n- *Some* datasets mentioned above came pre-split into training and test sets. Others I manually split them randomly.\n- Prepared dataset is stored and served to the model as tfrecord files in sharded fashion\n\n### Datasets file structure\n\n```\n { dataset }\n ├── testset\n │   ├── {img}.(jpg|png)\n │   ├── {img}.pts\n └── trainset\n     ├── {img}.(jpg|png)\n     ├── {img}.pts\n```\n\n**[300-VW](https://ibug.doc.ic.ac.uk/resources/300-VW/)**\n\nSince this dataset is composed of (.avi) video files (unlike the others), It should be served in this format.\n\n```\n300VW\n├── testset\n│   ├── {sample name}\n│   │   ├── annot / {frame_no}.pts\n│   │   └── vid.avi\n└── trainset\n    ├── {sample name}\n    │   ├── annot / {frame_no}.pts\n    │   └── vid.avi\nframe_no format \"%06d\"\n```\n\nNote: Dataset base dir name `300VW`, this is hardcoded in `prep_tfrecords.py`.\n\n## Generate TFRecord files\n\nProvide the dataset directory and the path to store the TFRecord files\n\n```bash\npython prep_tfrecords.py \u003cdataset_loc\u003e \u003ctfrecord_save_loc\u003e (--test_set) --n_points \u003c6 (or) 8\u003e\n```\n\n## Training\n\nCommand to train the model.\n\n```bash\npython train.py \u003cmodel_type\u003e \\\n --n_points \u003c6 (or) 8\u003e \\\n --tfrecords_dir \u003ctfrecords_dir\u003e \\\n --load_from \u003cbest_checkpoint_to_start_from\u003e \\ # This can be skipped\n --epochs 10 --batch_size 1024 --learning_rate 0.001\n```\n- Check [here](https://github.com/mnjm/facial-landmarks-cnn/blob/main/train.py#L10C1-L10C57) for model types\n\n## Evaluate\n\n```bash\npython train.py \u003cmodel_type\u003e \\\n --n_points \u003c6 (or) 8\u003e \\\n --tfrecords_dir \u003ctfrecords_dir\u003e \\\n --load_from \u003cmodel_checkpoint_to_eval\u003e \\\n --eval_model\n```\n\n## Export\n\nBest model can be exported to Keras native `.keras` format\n```bash\npython train.py \u003cmodel_type\u003e \\\n --load_from \u003ccheckpoint_to_export\u003e \\\n --export_model \u003cexport_as\u003e\n```\n\n## Visual Test\n\nTo visually test the model on a video file or directory containing images, run the below command\n```\npython visual_test.py \u003cexported_model_file\u003e \u003cavi_(or)_dir_loc\u003e (--save_video) --n_points \u003c6 (or) 8\u003e\n```\n*`--save_video` will save the visual output to `output.mp4`*\n\n### Visual Test with Face alignment / Head Pose\n\n**Only works on 8pts**\n\nTo visually test the model on a video file or directory containing images, run the below command\n```\npython visual_test.py \u003cexported_model_file\u003e \u003cavi_(or)_dir_loc\u003e (--save_video) --n_points 8 --draw_headpose\n```\n\n## Addendum\n\n- Model provided [here](https://github.com/mnjm/facial-landmarks-cnn/blob/main/models/from_github.py) is from [ccn-facial-landmark](https://github.com/yinguobing/cnn-facial-landmark).\n\n## License\n![License](https://img.shields.io/badge/GNU-v3.0-brightgreen)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmnjm%2Ffacial-landmarks-cnn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmnjm%2Ffacial-landmarks-cnn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmnjm%2Ffacial-landmarks-cnn/lists"}