{"id":20148179,"url":"https://github.com/yurzi/mtcnn-pytorch","last_synced_at":"2025-10-28T05:03:52.866Z","repository":{"id":156328673,"uuid":"632962555","full_name":"Yurzi/mtcnn-pytorch","owner":"Yurzi","description":"A PyTorch implementation for MTCNN","archived":false,"fork":false,"pushed_at":"2023-06-18T02:26:17.000Z","size":129,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-27T05:13:23.730Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/Yurzi.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":"2023-04-26T13:41:24.000Z","updated_at":"2023-04-27T10:43:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"d7b53db7-0ca8-43a9-9a3e-fff0ebbe6f5b","html_url":"https://github.com/Yurzi/mtcnn-pytorch","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Yurzi/mtcnn-pytorch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yurzi%2Fmtcnn-pytorch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yurzi%2Fmtcnn-pytorch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yurzi%2Fmtcnn-pytorch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yurzi%2Fmtcnn-pytorch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yurzi","download_url":"https://codeload.github.com/Yurzi/mtcnn-pytorch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yurzi%2Fmtcnn-pytorch/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263083561,"owners_count":23411162,"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":[],"created_at":"2024-11-13T22:34:51.371Z","updated_at":"2025-10-28T05:03:47.827Z","avatar_url":"https://github.com/Yurzi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MTCNN-PyTorch\n\nA pytorch implementation for mtcnn. It is based on the paper *Zhang, K et al.(2016)*[[ZHANG2016]](#Reference)\n\n## Preparing the Environment\n\n### Use virtual environment \n\nFirst, I recommend you to use virtual environment. So you need to install conda on your PC. If you don’t want it to eat a lot of your disk space, [Miniconda](https://docs.conda.io/en/latest/miniconda.html) is better.\n\nStep follow to create and activate a virtual environment with conda.\n```shell\n# python=3.10 will install latest 3.10.* python, you can try other python version.\nconda create --name mtcnn python=3.10\n```\n\nAccess to virtual environment named mtcnn.\n```shell\nconda activate mtcnn\n```\nThen you will be ready to proceed actual installation for environment.\n\n### Install dependencies\n\nFirst. You need to install PyTorch. Recommendly, using conda to do it.\n```shell\n# ref: https://pytorch.org/get-started/locally/\nconda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia\n```\n\nSecond. Install poetry with conda.\n```shell\n# ref: https://anaconda.org/conda-forge/poetry\nconda install -c conda-forge poetry\n```\n\n*Additional:* \n*1. if you are stuck in conda slowly installation process, your can try mamba to boost it.*\n*2. poetry is project mamager to help dependencies management, but it can not handle multi-version python*\n\n\nFinally. Use poetry to install all rest dependencies.\n```shell\npoetry install\n```\n\n## Dataset\n\n### Dataset Structure\n\nYou need to follow the appropriate structure to make the code run correctly.\n\n**Actually**, you can just provide `raw` folder with `annotations.txt`, the other folder will be generate automatically, but you can also generate them from `raw` manually by using script under the `tools` folder\n\nYou can configure the partition ratio by using a configuration file(described below) when you generate the dataset from `raw`.\n\n```shell\ndataset\n├── onet\n│   ├── eval.txt\n│   ├── images\n│   ├── test.txt\n│   └── train.txt\n├── pnet\n│   ├── eval.txt\n│   ├── images\n│   ├── test.txt\n│   └── train.txt\n├── raw\n│   ├── annotations.txt     (must have)\n│   ├── eval.txt\n│   ├── images              (must have)\n│   ├── test.txt\n│   └── train.txt\n└── rnet\n    ├── eval.txt\n    ├── images\n    ├── test.txt\n    └── train.txt\n```\n### Generate From Raw Manually\n\nYou can use the tool script to complete the dataset manually.\n\nThe script will manage to finish successfully with fallback mechanism\n- if raw folder don't has partition, the script will fallback to use configs/config_name.py's settings\n- if --config is not set, the script will fallback to default.py under configs folder\n- if --path is not set, the script will fallback to config.py 's settings\n- if default.py is not existed, a exception will be raised\n\n```shell\npython tools/dataset/completion.py [--config config_name] [--path path/to/dataset_dir]\n```\n\n### Dataset Annotation File Detail\n\nAll annotation files follow the similar format.\n\nFor raw.\n\nIf there are multi object in a picture, list them in multi line. If a picture don't have boundingbox or landmark, please left the place empty\n\n```shell\n# annotations.txt\n# image_name bbox[] landmark[]\n# boundingbox[]\n# left_top_x/y normalized by raw picture's width and height.\n# width and height are also normalized by raw picture's width and height.\n# landmark[]\n# l1_x/y is relative to bbox's left_top and normalized by bbox's width and height.\n# l[2-5]_x/y is offset relative to l1_x/y and normalized by bbox's width and height .\n\nxxxx.jpg left_top_x left_top_y width height l1_x l1_y l2_x l2_y l3_x l3_y l4_x l4_y l5_x l5_y\nxxxx.jpg left_top_x left_top_y width height l1_x l1_y l2_x l2_y l3_x l3_y l4_x l4_y l5_x l5_y\nyyyy.jpg left_top_x left_top_y width height l1_x l1_y l2_x l2_y l3_x l3_y l4_x l4_y l5_x l5_y\nzzzz.jpg\n\n```\n\nFor p|o|rnet.\n```shell\n# annotations.txt\n# image_name classification(0|1|2) gt_bbox[] gt_landmark[]\n# classification(0|1|2)\n# 0 = negative; 1 = positive; 2 = part\n# if classification is negative, the gt_bbox[] and gt_landmark[] will be ignored.\n# if classification is part, the gt_landmark[] will be ignored.\n# gt_bbox[]\n# left_top_x/y is relative offset to cropped picture's left_top normalized by raw picture's width and height.\n# width and height are normalized by raw picture's width and height.\n# landmark[]\n# l1_x/y is relative to gt_bbox's left_top and normalized by gt_bbox's width and height.\n# l[2-5]_x/y is offset relative to l1_x/y and normalized by gt_bbox's width and height.\n\n\nxxxx.jpg 2 left_top_x left_top_y width height l1_x l1_y l2_x l2_y l3_x l3_y l4_x l4_y l5_x l5_y\nyyyy.jpg 1 left_top_x left_top_y width height l1_x l1_y l2_x l2_y l3_x l3_y l4_x l4_y l5_x l5_y\nzzzz.jpg 0 left_top_x left_top_y width height l1_x l1_y l2_x l2_y l3_x l3_y l4_x l4_y l5_x l5_y\n```\n\n## Train\nIf your dataset has been perpared, you can use train.py to train all three net  sequentially.\n```shell\npython mtcnn/train.py --config config_name [--resume]\n```\nOr, you can use tran_(p|r|o)net.py to train each net seprately.\n\n```shell\npython mtcnn/train_(p|r|o)net.py --config config_name [--resume]\n```\n\n## Evaluation\n\nUse eval.py to eval your model.\n```shell\npython mtcnn/eval.py --config config_name\n```\n\n## Inference\nUse inference.py to get a predication result\n```shell\npython mtcnn/inference.py --config config_name\n```\n## Reference\n\n| KEY         | INFO                                                         |\n| ----------- | ------------------------------------------------------------ |\n| [ZHANG2016] | Zhang, K., Zhang, Z., Li, Z., and Qiao, Y. (2016). Joint face detection and alignment using multitask cascaded convolutional networks. IEEE  Signal Processing Letters, 23(10):1499–1503. [arXiv:1604.02878](https://arxiv.org/abs/1604.02878) |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyurzi%2Fmtcnn-pytorch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyurzi%2Fmtcnn-pytorch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyurzi%2Fmtcnn-pytorch/lists"}