{"id":13564717,"url":"https://github.com/justusschock/shapenet","last_synced_at":"2025-09-10T16:43:34.396Z","repository":{"id":47077684,"uuid":"168544703","full_name":"justusschock/shapenet","owner":"justusschock","description":"PyTorch implementation of \"Super-Realtime Facial Landmark Detection and Shape Fitting by Deep Regression of Shape Model Parameters\" predicting facial landmarks with up to 400 FPS","archived":false,"fork":false,"pushed_at":"2020-05-24T20:28:09.000Z","size":149,"stargazers_count":343,"open_issues_count":5,"forks_count":59,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-20T00:04:44.344Z","etag":null,"topics":["deep-learning","delira","facial-keypoints","facial-keypoints-cnn","facial-landmarks","landmark-detection","pytorch","shape","shape-models","shape-prediction","shape-predictor"],"latest_commit_sha":null,"homepage":"https://shapenet.rtfd.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/justusschock.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}},"created_at":"2019-01-31T15:08:38.000Z","updated_at":"2024-11-18T02:40:34.000Z","dependencies_parsed_at":"2022-09-05T20:20:52.421Z","dependency_job_id":null,"html_url":"https://github.com/justusschock/shapenet","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/justusschock/shapenet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justusschock%2Fshapenet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justusschock%2Fshapenet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justusschock%2Fshapenet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justusschock%2Fshapenet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justusschock","download_url":"https://codeload.github.com/justusschock/shapenet/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justusschock%2Fshapenet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274488615,"owners_count":25294759,"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-10T02:00:12.551Z","response_time":83,"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":["deep-learning","delira","facial-keypoints","facial-keypoints-cnn","facial-landmarks","landmark-detection","pytorch","shape","shape-models","shape-prediction","shape-predictor"],"created_at":"2024-08-01T13:01:34.939Z","updated_at":"2025-09-10T16:43:34.350Z","avatar_url":"https://github.com/justusschock.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# shapenet\n\n[![Build Status](https://travis-ci.com/justusschock/shapenet.svg?token=GsT2RFaJJMxpqLAN3xuh\u0026branch=master)](https://travis-ci.com/justusschock/shapenet) [![Documentation Status](https://readthedocs.org/projects/shapenet/badge/?version=latest)](https://shapenet.readthedocs.io/en/latest/?badge=latest) [![PyPI version](https://badge.fury.io/py/shapenet.svg)](https://badge.fury.io/py/shapenet) [![codecov](https://codecov.io/gh/justusschock/shapenet/branch/master/graph/badge.svg?token=gpwVgQjw18)](https://codecov.io/gh/justusschock/shapenet) ![LICENSE](https://img.shields.io/github/license/justusschock/shapedata.svg)\n\nThis repository contains the [PyTorch](https://pytorch.org) implementation of [our Paper \"SUPER-REALTIME FACIAL LANDMARK DETECTION AND SHAPE FITTING BY DEEP REGRESSION OF SHAPE MODEL PARAMETERS\"](#our-paper).\n\n## Contents\n* [Installation](#installation)\n* [Demo](#demo)\n* [Usage](#usage)\n  * [By Scripts](#by-scripts)\n  * [From Python](#from-python)\n  * [Pretrained Weights](#pretrained-weights)\n * [Our Paper](#our-paper)\n\n## Installation\n\n### From Binary:\n`pip install shapenet`\n\n### From Source:\n`pip install git+https://github.com/justusschock/shapenet` \n\n## Demo\nDemonstration Videos comparing our method to [`dlib`](https://dlib.net) can be found [here as overlay](https://drive.google.com/open?id=1hLaNuWy8eC3xs9qcTRzVZfBjdlB7xZ8c) and [here as side-by-side view](https://drive.google.com/file/d/128ZnFSOAhKnhN7xpgi6FR5KircnwIxca/view?usp=sharing)\n\n## Usage\n### By Scripts\nFor simplicity we provide several scripts to preprocess the data, train networks, predict from networks and export the network via [`torch.jit`](https://pytorch.org/docs/stable/jit.html).\nTo get a list of the necessary and accepted arguments, run the script with the `-h` flag.\n\n#### Data Preprocessing\n* `prepare_all_data`: prepares multiple datasets (you can select the datasets to preprocess via arguments passed to this script)\n* `prepare_cat_dset`: Download and preprocesses the [Cat-Dataset](https://www.kaggle.com/crawford/cat-dataset)\n* `prepare_helen_dset`: Preprocesses an already downloaded ZIP file of the [HELEN Dataset](http://www.ifp.illinois.edu/~vuongle2/helen/) (Download is recommended from [here](https://ibug.doc.ic.ac.uk/download/annotations/helen.zip) since this already contains the landmarks)\n* `prepare_lfpw_dset`: Preprocesses an already downloaded ZIP file of the [LFPW Dataset](https://neerajkumar.org/databases/lfpw/) (Download is recommended from [here](https://ibug.doc.ic.ac.uk/download/annotations/lfpw.zip) since this already contains the landmarks)\n\n#### Training\n* `train_shapenet`: Trains the shapenet with the configuration specified in an extra configuration file (exemplaric configuration for all available datasets are provided in the [example_configs](example_configs) folder)\n\n#### Prediction\n* `predict_from_net`: Predicts all images in a given directory (assumes existing groundtruths for cropping, otherwise the cropping to groundtruth could be replaced by a detector)\n\n#### JIT-Export\n* `export_to_jit`: Traces the given model and saves it as jit-ScriptModule, which can be accessed via Python and C++\n\n### From Python\nThis implementation uses the [`delira`-Framework](https://github.com/justusschock/delira) for training and validation handling. It supports mixed precision training and inference via [NVIDIA/APEX](https://github.com/NVIDIA/apex) (must be installed separately). The data-handling is outsourced to [shapedata](https://github.com/justusschock/shapedata).\n\nThe following gives a short overview about the packages and classes.\n\n#### `shapenet.networks` \nThe `networks` subpackage contains the actual implementation of the shapenet with bindings to integrate the `ShapeLayer` and other feature extractors (currently the ones registered in `torchvision.models`).\n\n#### `shapenet.layer`\nThe `layer` subpackage contains the Python and C++ Implementations of the ShapeLayer and the Affine Transformations. It is supposed to use these Layers as layers in `shapenet.networks`\n\n#### `shapenet.jit`\nThe `jit` subpackage is a less flexible reimplementation of the subpackages `shapenet.networks` and `shapenet.layer` to export trained weights as jit-ScriptModule\n\n#### `shapenet.utils`\nThe `utils` subpackage contains everything that did not suit into the scope of any other package. Currently it is mainly responsible for parsing of configuration files.\n\n#### `shapenet.scripts`\nThe `scripts` subpackage contains all scipts described in [Scripts](#by-scripts) and their helper functions.\n\n### Pretrained Weights\nCurrently Pretrained Weights are available for [grayscale faces](https://drive.google.com/file/d/1QS2GUZK9xKWvpbDYgUCc-m0qI60TMnLj/view?usp=sharing) and [cats](https://drive.google.com/file/d/13S-4vLmmUBNy2XKJl_yR1u7Z283Iu1zB/view?usp=sharing).\n\nFor these Networks the image size is fixed to 224 and the pretrained weights can be loaded via `torch.jit.load(\"PATH/TO/NETWORK/FILE.ptj\")`. The inputs have to be of type `torch.Tensor` with dtype `torch.float` in shape `(BATCH_SIZE, 1, 224, 224)` and normalized in a range between (0, 1).\n\n\n## Our Paper\nIf you use our Code for your own research, please cite our paper:\n```\n@article{Kopaczka2019,\ntitle = {Super-Realtime Facial Landmark Detection and Shape Fitting by Deep Regression of Shape Model Parameters},\nauthor = {Marcin Kopaczka and Justus Schock and Dorit Merhof},\nyear = {2019},\njournal = {arXiV preprint}\n}\n```\nThe Paper is available as [PDF on arXiv](https://arxiv.org/abs/1902.03459).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustusschock%2Fshapenet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustusschock%2Fshapenet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustusschock%2Fshapenet/lists"}