CVLFace Toolkit

CVLFace uses .rec files (optimized for high-performance I/O) organized into directories. The directory name must match the rec field in your dataset configuration YAML file.

Example YAML configuration:

data_root: ${oc.env:DATA_ROOT}
rec: 'casia_webface'
color_space: 'RGB'
num_classes: 10572
num_image: 490623
repeated_sampling_cfg: null
semi_sampling_cfg: null

In this example, the toolkit expects the dataset files to be located at $DATA_ROOT/casia_webface/.

All experimental outputs are stored in the experiments/ directory. Results are organized hierarchically to allow for easy comparison between different code versions and individual trials.

Results Naming Convention

Results are saved using the following pattern: {folder_name}/{optional_prefix}_{Month}-{Date}_{Trial}

Example Structure

experiments/
    run_v1/
        run_02-15_0/
    new_loss_v1/
        optim_sgd_02-15_0/
        optim_adam_02-15_1/
        bugfix_02-16_0/
    new_loss_v2/
        batchsize100_03-12_0/

The app expects and maintains a directory structure similar to the following:

├── images/                 # Directory containing original unaligned images
│   ├── image1.jpg
│   ├── subfolder/image2.png
│   ...

└── aligned_images/         # Directory where the aligned images will be saved
│   ├── image1.jpg
│   ├── subfolder/image2.png
│   ...

Experimental results are stored in the experiments/ directory. To facilitate easy comparison and navigation, results must follow a specific naming convention that links them back to their source code folder.

Results Naming Convention: {folder_name}/{optional_prefix}_{Month}-{Date}_{Trial}

Example Structure: If you are running an experiment in the new_loss_v1 folder using the Adam optimizer, your results might be stored as experiments/new_loss_v1/optim_adam_02-15_1/.

experiments/
    run_v1/
        run_02-15_0/
    new_loss_v1/
        optim_sgd_02-15_0/
    new_loss_v1/
        optim_adam_02-15_1/
    new_loss_v1/
        bugfix_02-16_0/
    new_loss_v2/
        batchsize100_03-12_0/
    new_architecture_v1_04-14_0/

CVLFace uses .rec files (optimized for high-performance I/O) organized into directories. The directory name must match the rec field in your dataset's YAML configuration file.

For example, if your YAML config contains rec: 'casia_webface', the toolkit will look for the dataset in $DATA_ROOT/casia_webface/.

Example Directory Structure:

$DATA_ROOT
├── casia_webface
│   ├── train.rec
│   ├── train.idx
│   └── train.tsv
├── webface260m/WebFace4M
│   ├── train.rec
│   ├── train.idx
│   ├── train.tsv
│   └── ldmk_5points.csv
└── ...

data_root: ${oc.env:DATA_ROOT}
rec: 'casia_webface'
color_space: 'RGB'
num_classes: 10572
num_image: 490623
repeated_sampling_cfg: null
semi_sampling_cfg: null

To install the RPE (Relative Position Encoding) operations, navigate to the specific directory within the model structure and run the setup.py script with the --user flag to install it for the current user.

cd models/vit_kprpe/RPE/rpe_ops
python setup.py install --user

After installation, you must configure the environment variables in cvlface/.env. Required or recommended variables include:

• DATA_ROOT: Path to your datasets.
• HF_TOKEN: Your Hugging Face Hub token (for downloading models).
• WANDB_TOKEN: Your Weights & Biases token.

Edit the file using a text editor like vim:

cd cvlface
vim .env

cd cvlface
vim .env # edit the following environ variables

"""(content to add to .env)
DATA_ROOT="YOUR_PATH_TO_DATA"
HF_TOKEN="YOUR_HUGGINGFACE_HF_TOKEN"
WANDB_TOKEN="YOUR_WANDB_TOKEN"
"""

If you are using the CVLFace research code, you can download model files directly from Google Drive. After downloading, you must place the files in specific directories within your local CVLFace repository to ensure the toolkit can locate them.

Required Directory Structure:

• Recognition models: cvlface/pretrained_models/recognition
• Alignment models: cvlface/pretrained_models/alignment

# Example directory placement
# Move recognition models to:
cp path/to/downloaded/recognition_model.pth cvlface/pretrained_models/recognition/

# Move alignment models to:
cp path/to/downloaded/alignment_model.pth cvlface/pretrained_models/alignment/

For face recognition research, the project recommends the Copy-Folder Method instead of relying solely on Git for experimental iterations. This allows you to run multiple parallel experiments independently and compare them easily using IDE folder comparison tools.

Workflow Steps:

1. Initialize: Copy the research/recognition/code/run_v1 folder to a new directory named after your experiment (e.g., new_loss_v1).
2. Modify: Apply your changes (e.g., a new loss function or architecture) within that specific folder.
3. Version: Use semantic versioning for folder names (e.g., new_loss_v1, new_loss_v2) to track modifications.
4. Iterate: Repeat the process for each new experimental idea.

code/
    run_v1 (default)/
        ...
    new_loss_v1/
        ...
    new_loss_v2/
        ...
    new_architecture_v1/
        ...

Before running the toolkit, you must configure the environment variables in the cvlface/.env file. The following keys must be set:

• DATA_ROOT: The directory path where datasets will be stored.
• HF_TOKEN: Your Hugging Face authentication token.
• WANDB_TOKEN: Your Weights & Biases authentication token.

DATA_ROOT="path where datasets will be stored"
HF_TOKEN="token for https://huggingface.co/"
WANDB_TOKEN="token for https://wandb.ai/"