FFHQ-UV is 50,000 aligned facial UV maps for 3D reconstruction

What the dataset actually contains

FFHQ-UV is described as a large-scale facial UV-texture dataset containing over 50,000 high-quality texture UV-maps with even illuminations, neutral expressions and cleaned facial regions, and those three properties are exactly what makes it useful for rendering realistic 3D face models under different lighting conditions.

That last clause is the reason the dataset exists. A UV-texture map is the flattened image that is wrapped onto a 3D face mesh, and for relighting and rendering research you want a texture where the only thing varying between samples is identity, not expression, not lighting and not the shadow under the chin. Even illumination and neutral expression are not cosmetic properties of the dataset, they are the controlled variables.

The dataset is derived from FFHQ, the large-scale face image dataset from NVIDIA, and the pipeline that produced it is described as fully automatic. The paper is FFHQ-UV: Normalized Facial UV-Texture Dataset for 3D Face Reconstruction, from CVPR 2023, available as arXiv 2211.13874, with rendering demos linked from the repository. The authors are Haoran Bai, Di Kang, Haoxian Zhang, Jinshan Pan and Linchao Bao.

The mechanism is worth understanding because it explains both the quality and the limits. The pipeline uses recent advances in StyleGAN-based facial image editing to generate multi-view normalized face images from single-image inputs, and then an elaborated UV-texture extraction, correction and completion procedure produces the high-quality UV maps from those normalized images.

So the pipeline does not photograph a face from several angles. It inverts the GAN to recover a latent code, edits the latent to produce the same identity under a set of normalized lighting and viewing conditions, and then stitches the views into a single texture. The normalisation is what makes the textures align.

The project is Python and MIT licensed, with the last push on 2026-04-16 and no GitHub releases published, so the repository tracks a paper rather than a released package.

The creation pipeline as four directories

The repository layout is the pipeline, because the top level is organised as four numbered steps plus the supporting projects.

`DataSet_Step1_Inversion/` is the GAN inversion stage, recovering a latent code from a face image. `DataSet_Step2_Det_Attributes/` is the attribute detection stage. `DataSet_Step3_Editing/` is the StyleGAN-based editing stage that produces the multi-view normalized face images. `DataSet_Step4_UV_Texture/` is where the extraction, correction and completion of the UV maps happens.

The README describes those steps as including GAN inversion, attribute detection, StyleGAN-based editing and texture unwrapping, and the whole pipeline is driven by a script named `run_ffhq_uv_dataset.sh`.

The attribute detection step is the fragile one, and the README flags it in two places. Creating the dataset requires the Microsoft Face API, and the README states plainly that the Microsoft Face API is not accessible for new users, with the alternatives being to find another API or to manually fill in the json file at `examples/dataset_examples/attributes/01223.json` to avoid the step.

That last option is the useful one, because the project also provides the detected facial attributes of the FFHQ dataset it used, described in the dataset project details section of `README_dataset.md`. So a new user with no API access does not have to detect attributes from scratch: they can fill in the provided attributes.

The other pipeline outputs are published too. The latent codes of the multi-view normalized face images are available, and there is a script for generating face images from latent codes, `run_gen_face_from_latent.sh`. The FFHQ-UV-Interpolate dataset is available as well, which is the set used by the newer RGB fitting route.

So the repository offers both the finished data and the means to reproduce it, and the reproduction path is where the API dependency bites.

Two routes to a UV map, and their trade-off

The README gives two ways to generate a UV-texture map from a given facial image, and it is honest about the advantages and the disadvantages of each.

The first is facial editing plus texture unwrapping, which is Section 3.1 of the paper, and it is the way the FFHQ-UV dataset itself was created. Its advantage is that the generated textures are directly extracted from facial images, which are detailed and of high quality. Its disadvantages are three, and they are specific.

The GAN inversion step would fail for some samples. The attribute detection step requires the Microsoft Face API, which is no longer accessible. And the StyleGAN-based editing would change the ID of the faces, resulting in textures with low fidelity.

That last one is the important technical objection. If the editing step changes the identity of the face, then the texture no longer belongs to the person in the input image, which defeats the purpose when you are trying to reconstruct a specific face.

The second route is RGB fitting, which the README calls the proposed 3D face reconstruction algorithm, and which uses the FFHQ-UV dataset to train a nonlinear texture basis. The code is in `RGB_Fitting/` with the scripts `run_rgb_fitting.sh`, `run_rgb_fitting_cropface630resize1024.sh` and `run_rgb_fitting_realy.sh`, and there is a separate document, `README_rgb_fitting.md`, with a more detailed description and a new version of the process.

The new version is described precisely: the FFHQ-UV-Interpolate dataset is used and the GAN-based texture decoder only generates facial textures. So in the newer fitting, the decoder is not doing the face reconstruction, it is only producing the texture, and the geometry comes from elsewhere.

The difference in approach between the two routes is where the face information comes from. The editing route recovers it from the GAN, which gives detail and high quality but perturbs identity. The fitting route recovers it through a fitted model, which is the paper's own contribution and the one that does not depend on the GAN inversion succeeding.

For a new user, that choice is not close. The editing route is how the dataset was made and it needs an API you may not be able to use; the fitting route is the proposed method and it trains on the published data.

The dependency stack, and how old it is

The dependencies section is a wall of pinned versions from a much earlier era, and anyone planning to run this needs to read it before touching anything.

The base requirements are Linux plus Anaconda, CUDA 10.0 with CUDNN 7.6.0, and Python 3.7. Then a set of individually installed components: dlib, PyTorch 1.7.1 with the matching torchvision and torchaudio, TensorBoard, TensorFlow 1.15.0 in its GPU build, and the MS Face API client.

The dependency block for the third-party rendering libraries is the part that takes real effort, because these are built from source:

mkdir thirdparty
cd thirdparty
git clone https://github.com/facebookresearch/iopath
git clone https://github.com/facebookresearch/fvcore
git clone https://github.com/facebookresearch/pytorch3d
git clone https://github.com/NVlabs/nvdiffrast
conda install -c bottler nvidiacub
pip install -e iopath
pip install -e fvcore
pip install -e pytorch3d
pip install -e nvdiffrast

PyTorch3D and nvdiffrast are the differentiable rendering and rasterisation libraries, and they are the reason the CUDA version is pinned so tightly, since both compile against a specific toolkit. The `conda install -c bottler nvidiacub` line installs the CUDA cub library that they need.

The README also carries one warning in bold that is worth repeating: the version of OpenCV needs to be higher than 4.5, otherwise it will not work well. That is the kind of detail that produces a confusing bug rather than a clean failure, so it is worth noting before you spend an afternoon on it.

The remaining packages are installed as one long line, and the list is a good indication of what the code touches: tqdm, scikit-image, opencv-python, pillow, imageio, matplotlib, mxnet, Ninja, the google auth libraries, click, requests, pyspng, imageio-ffmpeg at a pinned 0.4.3, scikit-learn, torchdiffeq at 0.0.1, flask, kornia at 0.2.0, lmdb, psutil, dominate and rtree.

The mixture of TensorFlow 1.15 and PyTorch 1.7 in one project is a sign of a codebase that grew across two eras of tooling, and the age of the stack is the main practical obstacle for anyone who wants to run the pipeline today rather than download the dataset.

Beyond the dataset: meshes, eyeballs and FLAME

Three side projects in the repository extend the dataset into usable 3D assets, and each has its own document.

`Mesh_Add_EyeBall/` adds eyeballs into a head mesh. The README explains that you prepare a head mesh with HiFi3D++ topology, which is a mesh without eyeballs, modify the configuration and then run a script, which it says refers to the script for detailed configuration:

sh run_mesh_add_eyeball.sh  # Please refer to this script for detailed configuration

`FLAME_Apply_HIFI3D_UV/` applies the UV maps to a FLAME mesh, and the update log records that a solution for using the UV-texture maps on a FLAME mesh became available on 2023-07-11, documented in `README_flame2hifi3d.md`. There is a matching script, `run_flame_apply_hifi3d_uv.sh`.

The FLAME model is the parametric face model, so this is the step that turns a texture map into something you can render, and it is the reason a texture dataset is useful for research in the first place.

The remaining pieces are the checkpoints and the topology assets, whose download is documented in `README_ckp_topo.md`, and the examples directories, which include `examples/dataset_examples/`, `examples/face_latent_examples/`, `examples/fitting_examples/`, `examples/fitting_realy/`, `examples/flame_apply_hifi3d_uv_examples/` and `examples/mesh_add_eyeball_examples/`.

The `topo_assets/` and `checkpoints/` directories at the top level confirm that both are part of the repository rather than being fetched, and the update log records that the OneDrive download link was updated and the file structures reorganised on 2023-03-16.

For getting the data itself, the README points at `README_dataset.md`, and the update log shows the download route has changed over time: the AWS CloudFront link went offline in December 2022, the OneDrive link became available, and on 2026-04-16 the dataset was mirrored on Hugging Face for easier access. That last entry is the current route, and it is the one to use.

Editorial conclusion

Adopt FFHQ-UV if you are training a 3D face reconstruction or rendering model and want aligned UV textures with controlled lighting rather than photographs, and if you intend to use the published dataset rather than regenerate it. Do not adopt it as a pipeline to run on new data without reading the dependency notes, since the stack is pinned to Python 3.7, CUDA 10.0 and TensorFlow 1.15, and the attribute detection step depends on a Microsoft Face API that is not open to new users. Verify first that the mirror on Hugging Face, added on 2026-04-16, serves the data you need, that the FFHQ-UV-Interpolate set and the latent codes are what your chosen route expects, and that the version of the repository you take matches the paper, given the last push was on 2026-04-16 and there are no published releases.

Frequently asked questions

Official sources

1. csbhr/FFHQ-UV on GitHub
2. Issues
3. License: MIT
4. README