Utils

face_crop_plus.utils.as_batch(images, size=512, padding_mode='constant')[source]

Creates image batch from a list of image paths.

For every image in the given list, the image is resized to not exceed either of the dimensions specified in size while keeping the same aspect ratio and the shorter dimension is padded to fully match the specified size. All the images are stacked and returned as a batch. Variables required to transform the images back to the original ones (padding and scale) are also returned as a batch.

Example

If some loaded image dimension is (1280×720) and the desired output size is specified as (512, 256), then the image is first be resized to (455, 256) and then the width is padded from both sides. The final image size is (512, 256).

Parameters:

images (list[ndarray]) – The list of paths to images.
padding_mode (str) – The type of padding to apply to pad the shorter dimension. For the available options, see OpenCV BorderTypes. It can be all lowercase. Defaults to “constant”.
size (int | tuple[int, int]) – The width and the height each image should be resized + padded to. I.e., the spacial dimensions of the batch. If a single number is specified then it is the same for width height. Defaults to 512.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

A tuple of stacked numpy arrays representing 3 batches - resized + padded images of shape (N, H, W, 3) of type numpy.uint8 with values from 0 to 255, un-scale factors of shape (N,) of type numpy.float32, and applied paddings of shape (N, 4) of type numpy.int64 with values >= 0.

face_crop_plus.utils.as_numpy(img)[source]

Converts batch of images to numpy type.

Converts a batch of images to numpy type. UINT8 type and channel dimension is last. If the batch of images is already of numpy type, it is simply returned.

Parameters:: img (Tensor | ndarray | list[Tensor] | list[ndarray]) – The image batch represented as a torch tensor of shape (N, 3, H, W) or a list of torch tensors of different spatial sizes.
Return type:: ndarray | list[ndarray]
Returns:: A batch of images represented as a numpy array of shape (N, H, W, 3) of type numpy.uint8 or a list of numpy arrays of different spatial sizes.

face_crop_plus.utils.as_tensor(img, device='cpu')[source]

Converts batch of images to torch tensor type.

Converts a batch of images to torch tensor type. Float 32 type and channel dimension is before spatial dimension. If the batch of images is already of torch tensor type, it is simply returned.

Parameters:

img (ndarray | Tensor | list[ndarray] | list[Tensor]) – The image batch represented as a numpy array of shape (N, H, W, 3) or a list of numpy arrays of different spatial sizes.
device (str | device) – The device on which to return the torch tensor.

Return type:

Tensor | list[Tensor]

Returns:

A batch of images represented as a torch tensor of shape (N, 3, H, W) of type torch.float32 or a list of torch tensors of different spatial sizes.

face_crop_plus.utils.clean_names(input_dir, output_dir=None, max_chars=250, exclude={'\\x00', '!', '"', '#', '$', '%', '&', "'", '*', ',', '.', '/', ':', ';', '<', '=', '>', '?', '@', '\\\\', '^', '{', '|', '}'}, desc='Cleaning file names')[source]

Cleans the names of the files in the given directory.

Converts all names of the files to os-compatible. In other words, each file is copied to a new directory with a clean name or is renamed in-place.

Here is a list of fixes applied to the names of the files:

Converts non-ascii symbols to ascii, e.g., “北亰” to “Bei Jing”, “České” to “Ceske” etc.

Removes os-reserved characters, e.g., in Windows, that would be ‘?’, ‘:’, ‘/’ etc.

Truncates the file name such that the overall path length would not exceed max_chars. For instance, in Windows, there is a limit of _256_ characters per path.

Appends suffixes to file names, such that, after the above mentioned changes, no file has the same name (counters are appended to duplicate names). This also deals with cases issue - for instance, in windows, same file names, even with different cases, cannot exist.

Parameters:

input_dir (str) – The input directory of files to process. Note that the directory should only contain files.
output_dir (Optional[str]) – The output directory to save the copies of the renamed files to. If not specified, the files are renamed in-place, i.e., inside input_dir. Defaults to None.
max_chars (int) – The maximum number of characters per file path (not file name). File paths longer than that will be truncated to max_chars. However, note that if duplicates are detected, then suffixes will be added and file paths for them could be longer by 2 or more characters. This should not be an issue if there are only a few duplicates and if max_chars is not directly set to the limit, e.g., in Windows the ultimate path length limit is 256. Defaults to 250.
exclude (set) – The set of characters to exclude from the file name, but not the extension. Note that this includes a dot ‘.’ to only keep a single dot for the file extension. Defaults to {”00!@#$%^&*?={}:;’<>,.?/\|” + ‘”’}.
desc (Optional[str]) – The description to use for the progress bar. If specified as None, no progress bar is shown. Defaults to “Cleaning file names”.

Raises:

RuntimeError – If the length of the path to the directory is too long and near max_chars limit.

face_crop_plus.utils.get_landmark_slices_5(num_landmarks)[source]

Gets the landmarks slices that show where the 5 landmarks are.

Generates slices of which coordinates to select in a larger set of landmarks (e.g., 12, 68, 106) to represent the coordinates of 5-points landmarks set. The slice of indices can be used to select multiple coordinates and average them to a single point.

Parameters:: num_landmarks (int) – The number of landmarks in the larger set.
Raises:: ValueError – If the number of landmarks in the larger set is not supported.
Return type:: list[slice]
Returns:: A list of slices where each slice indicates the indices of coordinates to select from the larger set of landmarks to represent a 5-point landmarks set.

face_crop_plus.utils.get_ldm_slices(num_tgt_landmarks, num_src_landmarks)[source]

Generates a list of slices that form a reduced landmarks set.

Takes the number of target landmarks and the number of source landmarks and generates slices that show which coordinates to select from a larger landmarks set (that should be averaged) to form a reduced landmarks set that has the same number of landmarks as the target landmarks set.

Parameters:

num_tgt_landmarks (int) – The number of reduced landmarks to generate slices for.
num_src_landmarks (int) – The number of actual landmarks that is larger or equal to the number of target landmarks. Based on this number, generated slices will contain different indices.

Raises:

ValueError – If the number of target landmarks is not supported.

Return type:

list[slice]

Returns:

A list of slices where each slice indicates the indices of coordinates to select from the larger set of landmarks to represent a reduced (like target) landmarks set.

face_crop_plus.utils.parse_landmarks_file(file_path, **kwargs)[source]

Parses landmarks file.

Reads the file containing landmark coordinates and corresponding image file names and generates a numpy array of those names and a corresponding numpy array of those sets of landmarks.

The files are expected to be formatted as follows:

.json:

{
    "image_1.jpg": [23, 45, 64, 47, ...],
    "image_2.jpg": [17, 32, 30, 29, ...],
    ...
}

.csv:

images,x1,y1,x2,y2,...
image_1.jpg,23,45,64,47,...
image_2.jpg,17,32,30,29,...
...

.txt and other:

image_1.jpg 23 45 64 47 ...
image_2.jpg 17 32 30 29 ...
...

Note

The number of landmarks does not matter, all will be transformed to shape (-1, 2), where -1 stands for the number of facial points (landmark coordinates), e.g., 5, 68 etc.

Parameters:

file_path (str) – The path to the landmarks file.
**kwargs – Additional keyword arguments that go into numpy.genfromtxt(). Please do not specify dtype and usecols arguments as they are already specified.

Return type:

tuple[ndarray, ndarray]

Returns:

A tuple where the first element is the parsed landmarks batch as a numpy array of shape (N, num_landm, 2) of type numpy.float32 and the second element is a corresponding batch of image file names of shape (N,) of type numpy.str_.

face_crop_plus.utils.read_images(file_names, input_dir)[source]

Reads images from the specified paths.

Takes a list of file names and an input directory and loads the specified images from it. If an image could not be loaded, a warning is raised.

Parameters:

file_names (list[str]) – The list of image file names.
input_dir (str) – The input directory with the images.

Return type:

tuple[list[ndarray], ndarray]

Returns:

A tuple where the first element is a list of length N (number of loaded images) where each element is an RGB image represented as a numpy array of type numpy.uint8 of shape (H, W, 3) (note that H and W for each image can be different) and the second element is a numpy array of type numpy.str_ of shape (N,) representing the list of file names that correspond to each image. The second element is just a numpy form of file_names but it can have a lower length, in case some images were not read successfully.