Create Cropped Video v1.0

Date completed	August 7, 2024
Release where first appeared	OpenWillis v2.2
Researcher / Developer	Kieran McVeigh

---

1 – Syntax

import openwillis as ow

create_cropped_video(video_path = '', detections = [{}, {}], output_path = '', crop = False, trim = True, debug = False, default_size_for_cropped = (512, 512))

---

2 – Methods

This function takes video_path, a string indicating where the original video is saved, and detections, the list of dictionaries with bounding box information for a given face returned from the pre_preprocess_video_for_faces function. It crops the video based on the bounding box info and saves it to output_path as an mp4 file.

Several additional parameters allow researchers to control what is saved in the cropped video.

First, there are then two options for how spatial cropping is handled that are set by the crop parameter:

• The default option is crop = False. This will darken the frame outside of the face, turning all pixels outside the bounding box to black but retaining the original frame size
• If crop = True, frames are cropped to the height and width defined in the default_size_for_cropped parameter and the face is placed in the center of the cropped frame.

Second, there are two options for how temporal trimming is handled, this is set by the trim parameter:

• If trim = True (the default option), each video only contains frames for which the individual face was detected. This results in the cropped video differing in length from the original video file.
• If trim = False, the cropped videos have the same number of frames as the original video and frames without a face of a given identity are returned as black frames, leaving the temporal information in the video the same as the original.

Finally we include a debug parameter.

• If debug = True, this parameter darkens frames using bounding box information in the detections parameter (i.e. turns all pixels outside the bounding box to black but does not resize the frame or reposition the face), but writes all other frames to saved video without altering them. This allows researchers to examine the cropped outputs for quality (i.e. missed faces).

There is nothing returned from this function - upon completion a video with specified cropping options will be saved at output path.

3 – Inputs

3.1 – video_path

Type	String
Description	Path to the video file

3.2 – detections

Type	List of dictionaries
Description	List of dictionaries containing bounding box information

3.3 – output_path

Type	String
Description	Path where video should be saved

3.4 – darken

Type	Boolean; optional, default value is True
Description	This parameter defines how to crop video frames. When True, the method keeps the video in original size and turns all pixels black except pixels in the face bounding box. When False, the method resizes frames to the standardized size and with a cropped face in the center.

3.5 – keep_original_timing

Type

Boolean; optional, default value is False

Description

This parameter defines whether to crop videos temporally or not. If True, for frames in which the face is not present all pixels are turned black but the frame is retained. This causes the output videos to have the same number of frames and timing information as the input video. If False, only frames which contain the face are present in the output video, causing the video to be shorter, and but contain only frames in which the face is present.

3.6 – debug

Type

Boolean; optional, default value is False

Description

This parameter defines whether to crop videos temporally or not. If True, for frames in which the face is not present all pixels are turned black but the frame is retained. This causes the output videos to have the same number of frames and timing information as the input video. If false, only frames which contain the face are present in the output video, causing the video to be shorter, and but contain only frames in which the face is present.

3.7 – default_size_for_cropped

Type	Tuple of integers; optional, default value is (512, 512)
Description	This parameter defines the size of a cropped video if darken = False. As if darken = False all frames will be resized and the cropped faces will be centered in the resized frame.

4 – Outputs

None

---

5 – Example use

This function is designed to be used in combination with preprocess_face_video as shown in the example below.

video_path = 'example.mp4'
import openwillis as ow
bb_dict, facedata_df = ow.preprocess_video_for_faces(video_path)

Bounding_box_list_1 = bb_dict[0] # gets bounding box info for first face
Bounding_box_list_2 = bb_dict[1] # gets bounding box info for second face

# crop video based on the bounding box info and save
save_path_face_1 = 'example_face_video_1.mp4'
ow.create_cropped_video(
    video_path,
    bounding_box_list_1,
    save_path_face_1
)

save_path_face_2 = 'example_face_video_2.mp4'
ow.create_cropped_video(
    video_path,
    bounding_box_list_2,
    save_path_face_2
)

---

6 – Dependencies

Below are dependencies specific to calculation of this measure.

Dependency	License	Justification
opencv	Apache 2.0	Open-source computer vision library for basic CV operations.