{"id":15036016,"url":"https://github.com/aaronjackson/vrn","last_synced_at":"2025-05-14T20:05:48.736Z","repository":{"id":44371200,"uuid":"94889340","full_name":"AaronJackson/vrn","owner":"AaronJackson","description":":man:  Code for \"Large Pose 3D Face Reconstruction from a Single Image via Direct Volumetric CNN Regression\"","archived":false,"fork":false,"pushed_at":"2022-07-26T00:06:01.000Z","size":538,"stargazers_count":4518,"open_issues_count":7,"forks_count":746,"subscribers_count":213,"default_branch":"master","last_synced_at":"2025-04-13T14:06:37.427Z","etag":null,"topics":["3d","computer-vision","computervision","deeplearning","face","reconstruction","torch7"],"latest_commit_sha":null,"homepage":"http://aaronsplace.co.uk/papers/jackson2017recon/","language":"MATLAB","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/AaronJackson.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.bib","codeowners":null,"security":null,"support":null}},"created_at":"2017-06-20T12:35:33.000Z","updated_at":"2025-04-09T14:47:46.000Z","dependencies_parsed_at":"2022-08-12T11:10:28.608Z","dependency_job_id":null,"html_url":"https://github.com/AaronJackson/vrn","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/AaronJackson%2Fvrn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AaronJackson%2Fvrn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AaronJackson%2Fvrn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AaronJackson%2Fvrn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AaronJackson","download_url":"https://codeload.github.com/AaronJackson/vrn/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248724639,"owners_count":21151561,"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":["3d","computer-vision","computervision","deeplearning","face","reconstruction","torch7"],"created_at":"2024-09-24T20:29:56.375Z","updated_at":"2025-04-13T14:06:39.949Z","avatar_url":"https://github.com/AaronJackson.png","language":"MATLAB","funding_links":[],"categories":[],"sub_categories":[],"readme":"* Large Pose 3D Face Reconstruction from a Single Image via Direct Volumetric Regression\n\n*Aaron S. Jackson, Adrian Bulat, Vasileios Argyriou and Georgios Tzimiropoulos*\n\n*Try out the code without running it!* Check out our online demo [[https://vrn.aaronsplace.co.uk][here]]. Alternatively,\npull the DockerHub image `asjackson:vrn`, see docs in the [[https://github.com/AaronJackson/vrn-docker][vrn-docker]] repo. \n\n[[http://aaronsplace.co.uk/papers/jackson2017recon/preview.png]]\n\nPlease visit our [[http://aaronsplace.co.uk/papers/jackson2017recon/][project webpage]] for a link to the paper and an\nexample video run on 300VW. This code is licenses under the MIT\nLicense, as described in the LICENSE file.\n\nThis is an unguided version of the Volumetric Regression Network (VRN)\nfor 3D face reconstruction from a single image. This method approaches\nthe problem of reconstruction as a segmentation problem, producing a\n3D volume, spatially aligned with the input image. A mesh can then be\nobtained by taking the isosurface of this volume.\n\nSeveral example images are included in the examples folder. Most of\nthese are AFLW images taken from [[http://www.cbsr.ia.ac.cn/users/xiangyuzhu/projects/3DDFA/main.htm][3DDFA]].\n\nIf you are running the code to calculate error for a potential\npublication, please use the MATLAB version, as this is what was used\nto compute the error for the paper.\n\n** Prebuilt Docker Image for CPU version\n\nI have released an image on Docker Hub which has everything to get the\nCPU version running under Docker. I'll extend this to have CUDA\nsupport at some point.\n\n#+BEGIN_SRC\ndocker pull asjackson/vrn:latest\ndocker run -v $(pwd)/data:/data:Z vrn /runner/run.sh /data/turing.jpg\n#+END_SRC\n\nThe repo holding this is available at [[https://github.com/AaronJackson/vrn-docker][vrn-docker]] and the models (which\nhave been cast to CPU floats already) were stored in Git LFS but took too much space. If you\nhave an issue with this docker container, please use the vrn-docker\nissue tracker rather than the vrn issue tracker.\n\n\n** Software Requirements\n\nA working installation of Torch7 is required. This can be easily\ninstalled on most platforms using [[https://github.com/torch/distro][torch/distro]]. You will also require\na reasonable CUDA capable GPU.\n\nThis project was developed under Linux. I have no idea if it will work\non Windows and it is unlikely that I will be able to help you with\nthis. If you are running Mac OS, [[https://github.com/AaronJackson/vrn/issues/1][issue #1]] might be of interest to you.\n\nQuick overview of requirements:\n\n- Torch7 (+ nn, cunn, cudnn, image). See \"Installation Example\" below.\n- NVIDIA GPU, with a working CUDA (7.5 or 8.0) and CuDNN (5.1).\n- Either,\n  - MATLAB\n  - bash, ImageMagick, GNU awk, Python 2.7 (+ visvis, imageio, numpy)\n\nPlease be wary of the version numbers for CUDA, CuDNN and Python.\n\nBulat's [[https://github.com/1adrianb/2D-and-3D-face-alignment/][face alignment]] code is included as a submodule. Please check\nhis README for dependencies.\n\n** Getting Started\n\n#+BEGIN_SRC bash\ngit clone --recursive https://github.com/AaronJackson/vrn.git\ncd vrn\n./download.sh\n#+END_SRC\n\n*** Running with MATLAB\n\nMATLAB offers better functionality for taking the iso surface of the\nvolume. It also has some code to calculate per-vertex colouring on the\nmesh. If you have MATLAB I recommend this route.\n\nTo run, type \"run\" from MATLAB.\n\n*** Running with Python\n\nNo longer is MATLAB an absolute requirement! I've included a slightly\ncrazy (but don't worry, I had fun writing it) shell script which\nperforms the face normalisation, and runs the ~vis.py~ script to\nrender the regressed volume.\n\nUnfortunately this does not yet apply any colouring or texture to the\nmesh (you're welcome to contribute) and it has some issues if you\ndon't have a fully working OpenGL setup. Some GPUs won't like the\nbackground image not being a power of two, so it might make the\nresults look odd. I'll work on this sometime.\n\nTo run it on the included example images without MATLAB, make the\n~run.sh~ executable with ~chmod u+x run.sh~ and type ~./run.sh~ from\nyour terminal.\n\n*** Using your own images\n\nYou are, of course, welcome to try out this method on your own set of\nimages. ~dlib~, the face detector included with Bulat's face alignment\ncode struggles to find side poses. You are welcome to modify the code\nto provide bounding boxes.\n\n*** Available Options\n\nThe MATLAB \"run.m\" script contains a few options which you can\nchange. Here is a very quick description of them:\n\n- ~input_folder~, as the name suggests, the folder to glob for JPEG\n  images.\n- ~output_folder~, the directory to store the regressed volumes.\n- ~model_file~, the name of the Torch model to load.\n- ~gpunum~, specify which GPU to use, starting at 0.\n- ~texture~, rudimentary texture mapping by taking the 2D projections\n  nearest neighbour (MATLAB only).\n\n\n\n\n\n\n\n\n\n* Installation Example\n\nI've had a few requests to describe a little better how to configure\nTorch so that everything works correctly. I've tested this on Fedora 24\nand CentOS 7. I'm assuming it will also work on Ubuntu if you have the\ncorrect development packages installed.\n\n#+BEGIN_SRC bash\n# Install some dependencies for later. I might have missed some\nsudo yum install glog-devel boost-devel\npip install dlib matplotlib numpy visvis imageio\n\n# Install the Torch distribution.\nmkdir -p $HOME/usr/{local,src}\ncd $HOME/usr/local\ngit clone https://github.com/torch/distro.git\nmv distro torch\ncd torch\nsudo ./install-deps\n./install.sh\nsource $HOME/usr/local/torch/install/bin/torch-activate\n\n# Install THPP and fb.python for the face alignment code\ncd $HOME/usr/src\ngit clone https://github.com/1adrianb/thpp.git\ncd thpp/thpp\nTHPP_NOFB=1 ./build.sh\n\n# Install fb.python.\ncd $HOME/usr/src\ngit clone https://github.com/facebook/fblualib.git\ncd fblualib/fblualib/python\nluarocks make rockspec/*\n\ncd $HOME\ngit clone --recursive https://github.com/AaronJackson/vrn.git\ncd vrn\n./download.sh\n./run.sh\n#+END_SRC\n\n* Paper Citation\n\n#+BEGIN_SRC\n@article{jackson2017vrn,\n  title={Large Pose 3D Face Reconstruction from a Single Image via Direct Volumetric CNN Regression},\n  author={Jackson, Aaron S and Bulat, Adrian and Argyriou, Vasileios and Tzimiropoulos, Georgios},\n  journal={International Conference on Computer Vision},\n  year={2017}\n}\n#+END_SRC\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronjackson%2Fvrn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronjackson%2Fvrn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronjackson%2Fvrn/lists"}