Python Script for Adding Face Masks to CelebA Images Using the face_recognition Library

The article introduces a project that adds synthetic face masks to images from the open‑source FaceMask_CelebA dataset. It first shows example results and provides the GitHub repository link.

It explains that the face_recognition library (a Python wrapper for dlib) simplifies facial landmark detection, reducing the complexity of implementing face‑mask overlay functionality.

FaceMasker class implementation :

#!/usr/bin/env python
# -*- coding: utf-8 -*-
# @Author  : 2014Vee
import os
import numpy as np
from PIL import Image, ImageFile

__version__ = '0.3.0'

IMAGE_DIR = os.path.dirname('E:/play/FaceMask_CelebA-master/facemask_image/')
WHITE_IMAGE_PATH = os.path.join(IMAGE_DIR, 'front_14.png')
BLUE_IMAGE_PATH = os.path.join(IMAGE_DIR, 'front_14.png')
SAVE_PATH = os.path.dirname('E:/play/FaceMask_CelebA-master/save/synthesis/')
SAVE_PATH2 = os.path.dirname('E:/play/FaceMask_CelebA-master/save/masks/')

class FaceMasker:
    KEY_FACIAL_FEATURES = ('nose_bridge', 'chin')

    def __init__(self, face_path, mask_path, white_mask_path, save_path, save_path2, model='hog'):
        self.face_path = face_path
        self.mask_path = mask_path
        self.save_path = save_path
        self.save_path2 = save_path2
        self.white_mask_path = white_mask_path
        self.model = model
        self._face_img: ImageFile = None
        self._black_face_img = None
        self._mask_img: ImageFile = None
        self._white_mask_img = None

    def mask(self):
        import face_recognition
        face_image_np = face_recognition.load_image_file(self.face_path)
        face_locations = face_recognition.face_locations(face_image_np, model=self.model)
        face_landmarks = face_recognition.face_landmarks(face_image_np, face_locations)
        self._face_img = Image.fromarray(face_image_np)
        self._mask_img = Image.open(self.mask_path)
        self._white_mask_img = Image.open(self.white_mask_path)
        self._black_face_img = Image.new('RGB', self._face_img.size, 0)
        found_face = False
        for face_landmark in face_landmarks:
            skip = False
            for facial_feature in self.KEY_FACIAL_FEATURES:
                if facial_feature not in face_landmark:
                    skip = True
                    break
            if skip:
                continue
            found_face = True
            self._mask_face(face_landmark)
        if found_face:
            self._save()
        else:
            print('Found no face.')

    def _mask_face(self, face_landmark: dict):
        nose_bridge = face_landmark['nose_bridge']
        nose_point = nose_bridge[len(nose_bridge) * 1 // 4]
        nose_v = np.array(nose_point)
        chin = face_landmark['chin']
        chin_len = len(chin)
        chin_bottom_point = chin[chin_len // 2]
        chin_bottom_v = np.array(chin_bottom_point)
        chin_left_point = chin[chin_len // 8]
        chin_right_point = chin[chin_len * 7 // 8]
        width = self._mask_img.width
        height = self._mask_img.height
        width_ratio = 1.2
        new_height = int(np.linalg.norm(nose_v - chin_bottom_v))
        # left mask part
        mask_left_img = self._mask_img.crop((0, 0, width // 2, height))
        mask_left_width = int(self.get_distance_from_point_to_line(chin_left_point, nose_point, chin_bottom_point) * width_ratio)
        mask_left_img = mask_left_img.resize((mask_left_width, new_height))
        # right mask part
        mask_right_img = self._mask_img.crop((width // 2, 0, width, height))
        mask_right_width = int(self.get_distance_from_point_to_line(chin_right_point, nose_point, chin_bottom_point) * width_ratio)
        mask_right_img = mask_right_img.resize((mask_right_width, new_height))
        # merge mask
        size = (mask_left_img.width + mask_right_img.width, new_height)
        mask_img = Image.new('RGBA', size)
        mask_img.paste(mask_left_img, (0, 0), mask_left_img)
        mask_img.paste(mask_right_img, (mask_left_img.width, 0), mask_right_img)
        # rotate mask
        angle = np.arctan2(chin_bottom_point[1] - nose_point[1], chin_bottom_point[0] - nose_point[0])
        rotated_mask_img = mask_img.rotate(angle, expand=True)
        # calculate position
        center_x = (nose_point[0] + chin_bottom_point[0]) // 2
        center_y = (nose_point[1] + chin_bottom_point[1]) // 2
        offset = mask_img.width // 2 - mask_left_img.width
        radian = angle * np.pi / 180
        box_x = center_x + int(offset * np.cos(radian)) - rotated_mask_img.width // 2
        box_y = center_y + int(offset * np.sin(radian)) - rotated_mask_img.height // 2
        self._face_img.paste(mask_img, (box_x, box_y), mask_img)
        self._black_face_img.paste(mask_img, (box_x, box_y), mask_img)

    def _save(self):
        path_splits = os.path.splitext(self.face_path)
        new_face_path = self.save_path + '/' + os.path.basename(self.face_path) + '-with-mask' + path_splits[1]
        new_face_path2 = self.save_path2 + '/' + os.path.basename(self.face_path) + '-binary' + path_splits[1]
        self._face_img.save(new_face_path)
        self._black_face_img.save(new_face_path2)

    @staticmethod
    def get_distance_from_point_to_line(point, line_point1, line_point2):
        distance = np.abs((line_point2[1] - line_point1[1]) * point[0] +
                          (line_point1[0] - line_point2[0]) * point[1] +
                          (line_point2[0] - line_point1[0]) * line_point1[1] +
                          (line_point1[1] - line_point2[1]) * line_point1[0]) / \
                   np.sqrt((line_point2[1] - line_point1[1]) ** 2 + (line_point1[0] - line_point2[0]) ** 2)
        return int(distance)

After defining the class, the script iterates over all images in the CelebA alignment folder, creates a FaceMasker instance for each image, and applies the mask, printing progress information.

from pathlib import Path
images = Path("E:/play/FaceMask_CelebA-master/bbox_align_celeba").glob("*")
cnt = 0
for image in images:
    if cnt < 1:
        cnt += 1
        continue
    FaceMasker(image, BLUE_IMAGE_PATH, WHITE_IMAGE_PATH, SAVE_PATH, SAVE_PATH2, 'hog').mask()
    cnt += 1
    print(f"正在处理第{cnt}张图片，还有{99 - cnt}张图片")

The second part of the article provides a separate script for binarizing mask images, converting them to black‑and‑white PNG/BMP files suitable for downstream model training.

import os
from PIL import Image
MyPath = 'E:/play/FaceMask_CelebA-master/save/masks/'
OutPath = 'E:/play/FaceMask_CelebA-master/save/Binarization/'

def processImage(filesoure, destsoure, name, imgtype):
    imgtype = 'bmp' if imgtype == '.bmp' else 'png'
    im = Image.open(filesoure + name)
    img = im.convert("RGBA")
    pixdata = img.load()
    for y in range(img.size[1]):
        for x in range(img.size[0]):
            if pixdata[x, y][0] < 90:
                pixdata[x, y] = (0, 0, 0, 255)
    for y in range(img.size[1]):
        for x in range(img.size[0]):
            if pixdata[x, y][1] < 136:
                pixdata[x, y] = (0, 0, 0, 255)
    for y in range(img.size[1]):
        for x in range(img.size[0]):
            if pixdata[x, y][2] > 0:
                pixdata[x, y] = (255, 255, 255, 255)
    img.save(destsoure + name, imgtype)

def run():
    os.chdir(MyPath)
    for i in os.listdir(os.getcwd()):
        postfix = os.path.splitext(i)[1]
        name = os.path.splitext(i)[0]
        name2 = name.split('.')
        if name2[1] == 'jpg-binary' or name2[1] == 'png-binary':
            processImage(MyPath, OutPath, i, postfix)

if __name__ == '__main__':
    run()

The article ends with a disclaimer that the content is collected from the internet and the original author holds the copyright.