{"id":13440394,"url":"https://github.com/peiyunh/tiny","last_synced_at":"2025-04-12T15:44:08.368Z","repository":{"id":73023655,"uuid":"76074780","full_name":"peiyunh/tiny","owner":"peiyunh","description":"Tiny Face Detector, CVPR 2017","archived":false,"fork":false,"pushed_at":"2020-03-21T02:04:30.000Z","size":51596,"stargazers_count":1137,"open_issues_count":5,"forks_count":317,"subscribers_count":77,"default_branch":"master","last_synced_at":"2025-04-03T16:13:57.942Z","etag":null,"topics":["detection","detector","face-detection","face-detector","scale-invariance"],"latest_commit_sha":null,"homepage":"https://cs.cmu.edu/~peiyunh/tiny","language":"MATLAB","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peiyunh.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":"2016-12-09T22:23:36.000Z","updated_at":"2025-03-20T15:35:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"b1c57d9e-9ff1-4464-b9fd-90c15e6d5ae1","html_url":"https://github.com/peiyunh/tiny","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/peiyunh%2Ftiny","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peiyunh%2Ftiny/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peiyunh%2Ftiny/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peiyunh%2Ftiny/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peiyunh","download_url":"https://codeload.github.com/peiyunh/tiny/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248590994,"owners_count":21129929,"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":["detection","detector","face-detection","face-detector","scale-invariance"],"created_at":"2024-07-31T03:01:22.388Z","updated_at":"2025-04-12T15:44:08.345Z","avatar_url":"https://github.com/peiyunh.png","language":"MATLAB","funding_links":[],"categories":["MATLAB"],"sub_categories":[],"readme":"![Demo result](https://raw.githubusercontent.com/peiyunh/tiny/master/selfie.png)\n\n# Finding Tiny Faces\nBy Peiyun Hu and Deva Ramanan at Carnegie Mellon University. \n\n## Introduction\nWe develop a face detector (Tiny Face Detector) that can find ~800 faces out of ~1000 reportedly present, by making use of novel characterization of scale, resolution, and context to find small objects. Can you confidently identify errors? \n\nTiny Face Detector was initially described in an [arXiv tech report](https://arxiv.org/abs/1612.04402). \n\nIn this repo, we provide a MATLAB implementation of Tiny face detector, including both training and testing code. A demo script is also provided. \n\n### Citing us\nIf you find our work useful in your research, please consider citing: \n```latex\n@InProceedings{Hu_2017_CVPR,\n  author = {Hu, Peiyun and Ramanan, Deva},\n  title = {Finding Tiny Faces},\n  booktitle = {The IEEE Conference on Computer Vision and Pattern Recognition (CVPR)},\n  month = {July},\n  year = {2017}\n}\n```\n\n## Installation \nClone the repo recursively so you have [my fork of MatConvNet](https://github.com/peiyunh/matconvnet/tree/9822ec97f35cf5a56ae22707cc1c04e0d738e7db). \n```zsh\ngit clone --recursive git@github.com:peiyunh/tiny.git\n```\n\nCompile MatConvNet by running following commands in MATLAB (see [Installing - MatConvNet](http://www.vlfeat.org/matconvnet/install/) for more details): \n```Matlab\n\u003e\u003e cd matconvnet/;\n\u003e\u003e addpath matlab/; \n\u003e\u003e vl_compilenn('enableImreadJpeg', true, 'enableGpu', true, 'cudaRoot', [cuda_dir],...\n                'cudaMethod', 'nvcc', 'enableCudnn', true, 'cudnnRoot', [cudnn_dir]);\n\u003e\u003e vl_testnn('gpu', true);  % vl_testnn('gpu', false) for cpu-only \n```\n\nCompile our MEX function in MATLAB and test if it works as expected: \n```Matlab\n\u003e\u003e cd utils/;\n\u003e\u003e compile_mex;\n\u003e\u003e test_compute_dense_overlap;\n```\n\n\nDownload [WIDER FACE](http://mmlab.ie.cuhk.edu.hk/projects/WIDERFace/) and unzip data and annotation files to `data/widerface` such that: \n```zsh\n$ ls data/widerface\nwider_face_test.mat   wider_face_train.mat    wider_face_val.mat\nWIDER_test/           WIDER_train/            WIDER_val/\n```\n\n## Demo\nWe provide a minimal demo `tiny_face_detector.m` that runs our detector on an single input image and output face detections: \n```Matlab\nfunction bboxes = tiny_face_detector(image_path, output_path, prob_thresh, nms_thresh, gpu_id)\n```\n\nHere is a command you can run to reproduce our detection results on the world's largest selfie: \n```Matlab \n\u003e\u003e bboxes = tiny_face_detector('data/demo/selfie.jpg', './selfie.png', 0.5, 0.1, 1)\n```\n\nThe demo script will start by downloading an off-the-shelf ResNet101-based model, if it does not find one. Models based on other architecture are also available below:\n- [ResNet101](https://drive.google.com/file/d/1YO8zTXGCACRZvHDxtW8dEZL7CE8HVFJ8/view?usp=sharing)\n- [ResNet50](https://drive.google.com/file/d/1RFcSglvtasctXJQI1BS3laENXNvP8mwl/view?usp=sharing)\n- [VGG16](https://drive.google.com/file/d/1cOm-AiZFulruQpb9gRmFlRhsdL9bXJZZ/view?usp=sharing)\n\n## Training \nTo train a ResNet101-based Tiny Face Detector, run following command in MATLAB: \n```Matlab\n\u003e\u003e hr_res101('train');           % which calls cnn_widerface.m\n```\n\nAfter training, run the following command to test on the validation set: \n```Matlab\n\u003e\u003e hr_res101('test');            % which calls cnn_widerface_test_AB.m \n```\n\nFinally, run the following command to evaluate the trained models: \n```Matlab\n\u003e\u003e hr_res101('eval');            % which calls cnn_widerface_eval.m\n```\n\nPlease refer to `scripts/hr_res101.m` for more details on how training/testing/evaluation is configured. \n\n### Clustering\nWe derive canonical bounding box shapes by K-medoids clustering (`cluster_rects.m`). For reproducibility, we provide our clustering results in `data/widerface/RefBox_N25.mat`. We also provide the version after template resolution analysis in `data/widerface/RefBox_N25_scaled.mat` (Fig. 8 in our paper).\n\n### Evaluation\nWe provide both our own version of evaluation script (`cnn_widerface_eval.m`) and official evaluation script (`eval_tools/`). Our implementation runs much faster and is easier to customize. However, our version produces slightly lower numbers comparing to the official one. We use our evaluation script only for prototyping. All numbers in the paper are based on the official evaluation script. \n\n## FAQ\n\n### How do I train it on my own datasets? \nTraining a `tiny-X-detector` on your own dataset takes just a little bit of coding and it is certainly doable. I would suggest start from the script named `cnn_setup_imdb.m`. The script produces a `imdb.mat` file which contains information about the path of images and the ground truth bounding boxes. Try modifying `cnn_setup_imdb.m` to make sure such information of your dataset goes into `imdb.mat`. \n\n## Third-party re-implementations\n- PyTorch version by Varun Agarwal (@varunagrawal) at https://github.com/varunagrawal/tiny-faces-pytorch\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeiyunh%2Ftiny","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeiyunh%2Ftiny","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeiyunh%2Ftiny/lists"}