perfectcrop 1.1.1

A video cropping tool for artists that detects an object, finds the average center pixel of the bounding box, and crops out from center without a decrease in video quality.

Perfect Crop

Perfect Crop will locate a detected object within a video clip, find its average location, and create a cropped clip from the center. Object detection models splice videos into individual frames & then run detection on static images - Perfect Crop transmutes this into workable video.

This tool is most useful when used on large clip sets (200+). It was built for the quick processing of over 50 hours of live-stream footage!

As a test example, searching the video for "cell phone":

Source Clip	Detected Object

Perfect Crop's algorithm was built around Hugging Face's hustvl/yolo sets, a series of vision transformer models trained on the COCO dataset. It's computationally light on any system. At the moment, the algorithm is set only for models using YOLO bounding box annotations - so if you want to swap out the model, keep that in mind.

Calculating the center pixel of a bounding box requires backward engineering of detection algorithms - I'm excited to release support for other annotations in v2.

---

Perfect Crop can also label scenes with content and object locations, as well as index a video & splice it into individual scenes without quality loss.

perfectcrop accepts the following inputs:

  -p   [video or directory]    | crop a video or directory of clips to select label (runs perfect_crop.py)

  -s   [video]                 | create .json file identifying shots (scene changes) in a long form video. shots.py will then splice the video into individual clips (or scenes).
  
  -vs  [video or directory]    | standardizes video length, codecs, etc. with ffmpeg bash. needed for concatenation!
  
  -g   [video or directory]    | creates a dynamic, randomized moving video grid with ffmpeg bash commands. this is a legacy file from Court Laureate, not necessary for the project itself :)

Due to the sensitive nature of working with video, Perfect Crop does not currently support multiple command line options. Please note that perfectcrop -s needs to be run in the same directory as the source video for shot splicing to occur.

potential errors:

  * global loadsave ->   thankfully, this is harmless and most often caused by minute differences in codecs or issues with local reading. I'll hide it.
  * video not found ->   please check permissions, you can do this by running ls -al on the directory & open with chmod commands.
  * file limit hit  ->   grid specific error. please run 'ulimit -n' in terminal to see your current limit, then ulimit -n [whatever] to increase the size to whatever you see fit. please note that this is isolated to your terminal window.

---

Made for Court Laureate, a short film screened at LARPA, December 2023, NY NY. Although one cannot patent an algorithm, please respect the open-source nature of this project & all derivatives.