first commit

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 David Madison
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,13 +1,63 @@
----
-title: FrameVis
-emoji: 👀
-colorFrom: red
-colorTo: red
-sdk: gradio
-sdk_version: 5.6.0
-app_file: app.py
-pinned: false
-short_description: Movie Barcode Poster Maker
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+![FrameVis Banner](images/FrameVis_Banner.jpg)
+
+FrameVis is a Python script for generating video frame visualizations, also known as "movie barcodes". These visualizations are composed of frames taken from a video file at a regular interval, resized, and then stacked together to show the compressed color palette of the video and how it changes over time.
+
+For more information, see [the blog post on PartsNotIncluded.com](http://www.partsnotincluded.com/programming/framevis/).
+
+## Basic Usage
+
+```bash
+python framevis.py source_video.mkv result.png -n 1600
+```
+
+To use the script, invoke it from the command line and pass positional arguments for the source and destination file paths (respectively). You will also need to provide either the number of frames to use (`-n`), or a capture interval in seconds (`-i`). The script will then process the video and save the result to the file specified.
+
+## Installation
+
+To use FrameVis, you will need a copy of [Python 3](https://www.python.org/downloads/) installed and added to your computer's path. You will also need a copy of the OpenCV library for Python 3, which can either be built from source ([Windows](https://docs.opencv.org/master/d5/de5/tutorial_py_setup_in_windows.html), [Ubuntu](https://docs.opencv.org/master/d2/de6/tutorial_py_setup_in_ubuntu.html), [Fedora](https://docs.opencv.org/master/dd/dd5/tutorial_py_setup_in_fedora.html)) or installed using [the **unofficial** binaries](https://pypi.org/project/opencv-python/) available via pip:
+
+```python
+pip install opencv-python
+```
+
+Test that both OpenCV (`cv2`) and NumPy (`numpy`) successfully import into Python before trying the script for the first time. Note that this script was developed using Python 3.6.4 and OpenCV version 3.4.1. More recent versions may not work properly.
+
+## Command Line Arguments
+
+### source (positional)
+
+The first positional argument is the file path for the video file to be visualized. Works with all OpenCV compatible video codecs and wrappers.
+
+### destination (positional)
+
+The second positional argument is the file path to save the final, visualized image. [Compatible file formats](https://docs.opencv.org/2.4/modules/highgui/doc/reading_and_writing_images_and_video.html?highlight=imread#imread) include jpeg, png, bmp, and tiff. A proper file extension *must* be included in the path or saving will fail.
+
+### (n)frames and (i)nterval
+
+One of these two arguments is required to set the number of frames to use in the visualization. You can either set the number of frames directly with `--(n)frames`, or indirectly by setting a capture `--(i)nterval` in seconds. Captured frames with either method are spaced throughout the entire video.
+
+## Optional Arguments
+
+### (h)eight and (w)idth
+
+The number of pixels to use for height and width *per frame*. If unset, these default to 1 px in the concatenated direction and the full size of the video in the other.
+
+### (d)irection
+
+The direction in which to concatenate the video frames, either "horizontal" or "vertical". Defaults to "horizontal".
+
+### (t)rim
+
+Setting this flag attempts to automatically remove hard matting present in the video file ([letterboxing / pillarboxing](https://en.wikipedia.org/wiki/Letterboxing_(filming))) before resizing. Off by default.
+
+### (a)verage
+
+Postprocess effect that averages all of the colors in each frame. Off by default, mutually exclusive with [(b)lur](#blur). It's recommended to enable trimming when using this option, otherwise colors will be excessively darkened.
+
+### (b)lur
+
+Postprocess effect that blurs each frame to smooth the final image. The value is the kernel size used for [convolution](https://en.wikipedia.org/wiki/Kernel_(image_processing)). If the flag is set and no value is passed, defaults to 100. Off by default, mutually exclusive with [(a)verage](#average). It's recommended to enable trimming when using this option, otherwise frame colors will bleed into any present matting.
+
+## License
+
+This script is licensed under the terms of the [MIT license](https://opensource.org/licenses/MIT). See the [LICENSE](LICENSE) file for more information.

app.py

@@ -0,0 +1,201 @@
+import gradio as gr
+import cv2
+import numpy as np
+import tempfile
+import os
+from framevis import FrameVis
+import json
+
+class InteractiveFrameVis(FrameVis):
+    """Extended FrameVis class that tracks frame positions"""
+    
+    def visualize(self, source, nframes, height=None, width=None, direction="horizontal", trim=False, quiet=True):
+        """Extended visualize method that returns both the visualization and frame data"""
+        video = cv2.VideoCapture(source)
+        if not video.isOpened():
+            raise FileNotFoundError("Source Video Not Found")
+        
+        # Calculate frame positions and timestamps
+        total_frames = video.get(cv2.CAP_PROP_FRAME_COUNT)
+        fps = video.get(cv2.CAP_PROP_FPS)
+        keyframe_interval = total_frames / nframes
+        
+        # Get the visualization
+        output_image = super().visualize(source, nframes, height, width, direction, trim, quiet)
+        
+        # Calculate frame positions and timestamps
+        frame_data = []
+        img_height, img_width = output_image.shape[:2]
+        
+        for i in range(nframes):
+            frame_pos = int(keyframe_interval * (i + 0.5))  # Same calculation as in visualize
+            timestamp = frame_pos / fps
+            
+            if direction == "horizontal":
+                x_start = (i * img_width) // nframes
+                x_end = ((i + 1) * img_width) // nframes
+                frame_info = {
+                    "frame": frame_pos,
+                    "time": timestamp,
+                    "x_start": int(x_start),
+                    "x_end": int(x_end),
+                    "y_start": 0,
+                    "y_end": img_height
+                }
+            else:  # vertical
+                y_start = (i * img_height) // nframes
+                y_end = ((i + 1) * img_height) // nframes
+                frame_info = {
+                    "frame": frame_pos,
+                    "time": timestamp,
+                    "x_start": 0,
+                    "x_end": img_width,
+                    "y_start": int(y_start),
+                    "y_end": int(y_end)
+                }
+            frame_data.append(frame_info)
+        
+        video.release()
+        return output_image, frame_data
+
+def extract_frame(video_path, frame_number):
+    """Extract a specific frame from the video"""
+    if not video_path:
+        return None
+        
+    cap = cv2.VideoCapture(video_path)
+    cap.set(cv2.CAP_PROP_POS_FRAMES, frame_number)
+    ret, frame = cap.read()
+    cap.release()
+    
+    if ret:
+        return cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+    return None
+
+def process_video(video_path, nframes, height, width, direction, trim, average, blur_amount):
+    """Process video using FrameVis and return the visualization with frame data"""
+    try:
+        fv = InteractiveFrameVis()
+        
+        # Process the video
+        output_image, frame_data = fv.visualize(
+            video_path, 
+            nframes=nframes,
+            height=height if height > 0 else None,
+            width=width if width > 0 else None,
+            direction=direction,
+            trim=trim,
+            quiet=False
+        )
+        
+        # Apply post-processing if requested
+        if average:
+            output_image = fv.average_image(output_image, direction)
+        elif blur_amount > 0:
+            output_image = fv.motion_blur(output_image, direction, blur_amount)
+        
+        # Convert from BGR to RGB for Gradio
+        output_image = cv2.cvtColor(output_image, cv2.COLOR_BGR2RGB)
+        
+        # Store frame data in a temporary file
+        temp_dir = tempfile.gettempdir()
+        data_path = os.path.join(temp_dir, "frame_data.json")
+        with open(data_path, "w") as f:
+            json.dump({"video_path": video_path, "frames": frame_data}, f)
+            
+        return output_image, data_path
+        
+    except Exception as e:
+        raise gr.Error(str(e))
+
+def on_mouse_move(evt: gr.EventData, frame_data_path):
+    """Handle mouseover on the visualization image"""
+    if not frame_data_path:
+        return None
+        
+    try:
+        # Load frame data
+        with open(frame_data_path) as f:
+            data = json.load(f)
+            
+        video_path = data["video_path"]
+        frames = data["frames"]
+        
+        # Get mouse coordinates
+        x, y = evt.index[0], evt.index[1]  # Extract x, y from index
+        
+        # Find which frame was hovered
+        for frame in frames:
+            if (frame["x_start"] <= x <= frame["x_end"] and 
+                frame["y_start"] <= y <= frame["y_end"]):
+                # Extract and return the frame
+                preview = extract_frame(video_path, frame["frame"])
+                if preview is not None:
+                    return preview, f"Frame {frame['frame']} (Time: {frame['time']:.2f}s)"
+                
+    except Exception as e:
+        print(f"Error handling mouseover: {e}")
+    return None, ""
+
+# Create the Gradio interface
+with gr.Blocks(title="FrameVis - Video Frame Visualizer") as demo:
+    gr.Markdown("""
+    # 🎬 FrameVis - Video Frame Visualizer
+    Upload a video to create a beautiful visualization of its frames. The tool will extract frames at regular intervals 
+    and combine them into a single image. **Move your mouse over the visualization to see the original frames!**
+    """)
+    
+    with gr.Row():
+        with gr.Column(scale=1):
+            # Input components
+            video_input = gr.Video(label="Upload Video")
+            with gr.Row():
+                nframes = gr.Slider(minimum=1, maximum=500, value=100, step=1, 
+                                 label="Number of Frames")
+                direction = gr.Radio(["horizontal", "vertical"], value="horizontal",
+                                   label="Direction")
+            
+            with gr.Row():
+                height = gr.Number(value=0, label="Frame Height (0 for auto)")
+                width = gr.Number(value=0, label="Frame Width (0 for auto)")
+            
+            with gr.Row():
+                trim = gr.Checkbox(label="Auto-trim black bars")
+                average = gr.Checkbox(label="Average colors")
+                blur_amount = gr.Slider(minimum=0, maximum=200, value=0, step=1,
+                                     label="Motion Blur Amount")
+            
+            process_btn = gr.Button("Generate Visualization", variant="primary")
+        
+        with gr.Column(scale=2):
+            # Output components
+            frame_data = gr.State()  # Hidden component to store frame data
+            output_image = gr.Image(label="Visualization Result", interactive=True, height=300)
+            frame_info = gr.Markdown("Hover over the visualization to see frame details")
+            preview_frame = gr.Image(label="Frame Preview", interactive=False, height=300)
+            
+    # Handle processing
+    result = process_btn.click(
+        fn=process_video,
+        inputs=[
+            video_input,
+            nframes,
+            height,
+            width,
+            direction,
+            trim,
+            average,
+            blur_amount
+        ],
+        outputs=[output_image, frame_data]
+    )
+    
+    # Handle mouseover events
+    output_image.mouseover(
+        fn=on_mouse_move,
+        inputs=[frame_data],
+        outputs=[preview_frame, frame_info]
+    )
+
+if __name__ == "__main__":
+    demo.launch() 

eval.txt

@@ -0,0 +1,93 @@
+I'll analyze the FrameVis script and break down its key functionality.
+
+### Core Purpose
+FrameVis is a Python script that creates a visual representation of a video by extracting frames at regular intervals and combining them into a single image. It's essentially creating what's sometimes called a "movie barcode."
+
+### Key Components
+
+1. **Main Class: FrameVis**
+   - Primary class that handles the video frame extraction and visualization
+   - Default settings for frame dimensions and concatenation direction
+   - Main method: `visualize()` which does the heavy lifting
+
+2. **Supporting Classes:**
+   - `MatteTrimmer`: Handles detection and removal of black bars (letterboxing/pillarboxing)
+   - `ProgressBar`: Provides console feedback during processing
+
+### Core Workflow
+
+1. **Input Processing**
+```python
+# Takes key parameters:
+- source: video file path
+- nframes: number of frames to extract
+- height/width: dimensions for output frames
+- direction: horizontal/vertical concatenation
+- trim: whether to remove black bars
+```
+
+2. **Frame Extraction Logic**
+```python
+# Calculates frame interval
+video_total_frames = video.get(cv2.CAP_PROP_FRAME_COUNT)
+keyframe_interval = video_total_frames / nframes
+
+# Frames are extracted at regular intervals:
+next_keyframe = keyframe_interval / 2  # Starts from middle of first interval
+```
+
+3. **Frame Processing**
+   - Reads frames using OpenCV
+   - Optionally trims black bars
+   - Resizes frames to specified dimensions
+   - Concatenates frames either horizontally or vertically
+
+4. **Post-Processing Options**
+   - `average_image()`: Creates a color average across frames
+   - `motion_blur()`: Applies directional blur effect
+
+### Special Features
+
+1. **Matte Detection**
+   - Automatically detects and removes letterboxing/pillarboxing
+   - Samples multiple frames to ensure consistent detection
+   - Uses threshold-based detection for black bars
+
+2. **Flexible Output**
+   - Can output horizontally (traditional movie barcode)
+   - Can output vertically (stacked frames)
+   - Supports automatic dimension calculation
+
+3. **Time-Based Frame Selection**
+```python
+# Can specify frames either by:
+- Total number of frames (-n/--nframes)
+- Time interval between frames (-i/--interval)
+```
+
+### Command Line Interface
+```python
+# Supports various arguments:
+-n/--nframes: Number of frames
+-i/--interval: Time between frames
+-h/--height: Frame height
+-w/--width: Frame width
+-d/--direction: Concatenation direction
+-t/--trim: Auto-trim black bars
+-a/--average: Average colors
+-b/--blur: Apply motion blur
+-q/--quiet: Suppress output
+```
+
+### Error Handling
+- Validates input parameters
+- Checks for file existence
+- Ensures frame counts are valid
+- Handles video reading errors
+
+### Performance Considerations
+- Uses OpenCV for efficient video processing
+- Maintains float precision for frame intervals
+- Only loads required frames rather than entire video
+
+This is a well-structured script that provides a robust set of features for video frame visualization while maintaining good error handling and user feedback through progress bars and console output.

framevis.py

@@ -0,0 +1,571 @@
+#
+#  Project     FrameVis - Video Frame Visualizer Script
+#  @author     David Madison
+#  @link       github.com/dmadison/FrameVis
+#  @version    v1.0.1
+#  @license    MIT - Copyright (c) 2019 David Madison
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
+import cv2
+import numpy as np
+import argparse
+from enum import Enum, auto
+import time
+
+
+class FrameVis:
+	"""
+	Reads a video file and outputs an image comprised of n resized frames, spread evenly throughout the file.
+	"""
+
+	default_frame_height = None  # auto, or in pixels
+	default_frame_width = None  # auto, or in pixels
+	default_concat_size = 1  # size of concatenated frame if automatically calculated, in pixels
+	default_direction = "horizontal"  # left to right
+
+	def visualize(self, source, nframes, height=default_frame_height, width=default_frame_width, \
+		direction=default_direction, trim=False, quiet=True):
+		"""
+		Reads a video file and outputs an image comprised of n resized frames, spread evenly throughout the file.
+
+		Parameters:
+			source (str): filepath to source video file
+			nframes (int): number of frames to process from the video
+			height (int): height of each frame, in pixels
+			width (int): width of each frame, in pixels
+			direction (str): direction to concatenate frames ("horizontal" or "vertical")
+			quiet (bool): suppress console messages
+
+		Returns:
+			visualization image as numpy array
+		"""
+
+		video = cv2.VideoCapture(source)  # open video file
+		if not video.isOpened():
+			raise FileNotFoundError("Source Video Not Found")
+
+		if not quiet:
+			print("")  # create space from script call line
+		
+		# calculate keyframe interval
+		video_total_frames = video.get(cv2.CAP_PROP_FRAME_COUNT)  # retrieve total frame count from metadata
+		if not isinstance(nframes, int) or nframes < 1:
+			raise ValueError("Number of frames must be a positive integer")
+		elif nframes > video_total_frames:
+			raise ValueError("Requested frame count larger than total available ({})".format(video_total_frames))
+		keyframe_interval = video_total_frames / nframes  # calculate number of frames between captures
+
+		# grab frame for dimension calculations
+		success,image = video.read()  # get first frame
+		if not success:
+			raise IOError("Cannot read from video file")
+
+		# calculate letterbox / pillarbox trimming, if specified
+		matte_type = 0
+		if trim == True:
+			if not quiet:
+				print("Trimming enabled, checking matting... ", end="", flush=True)
+
+			# 10 frame samples, seen as matted if an axis has all color channels at 3 / 255 or lower (avg)
+			success, cropping_bounds = MatteTrimmer.determine_video_bounds(source, 10, 3)
+
+			matte_type = 0
+			if success:  # only calculate cropping if bounds are valid
+				crop_width = cropping_bounds[1][0] - cropping_bounds[0][0] + 1
+				crop_height = cropping_bounds[1][1] - cropping_bounds[0][1] + 1
+
+				if crop_height != image.shape[0]:  # letterboxing
+					matte_type += 1
+				if crop_width != image.shape[1]:  # pillarboxing
+					matte_type +=2
+			
+			if not quiet:
+				if matte_type == 0:
+					print("no matting detected")
+				elif matte_type == 1:
+					print("letterboxing detected, cropping {} px from the top and bottom".format(int((image.shape[0] - crop_height) / 2)))
+				elif matte_type == 2:
+					print("pillarboxing detected, trimming {} px from the sides".format(int((image.shape[1] - crop_width) / 2)))
+				elif matte_type == 3:
+					print("multiple matting detected - cropping ({}, {}) to ({}, {})".format(image.shape[1], image.shape[0], crop_width, crop_height))
+
+		# calculate height
+		if height is None:  # auto-calculate
+			if direction == "horizontal":  # non-concat, use video size
+				if matte_type & 1 == 1:  # letterboxing present
+					height = crop_height
+				else:
+					height = image.shape[0]  # save frame height
+			else:  # concat, use default value
+				height = FrameVis.default_concat_size
+		elif not isinstance(height, int) or height < 1:
+			raise ValueError("Frame height must be a positive integer")
+		
+		# calculate width
+		if width is None:  # auto-calculate
+			if direction == "vertical":  # non-concat, use video size
+				if matte_type & 2 == 2:  # pillarboxing present
+					width = crop_width
+				else:
+					width = image.shape[1]  # save frame width
+			else:  # concat, use default value
+				width = FrameVis.default_concat_size
+		elif not isinstance(width, int) or width < 1:
+			raise ValueError("Frame width must be a positive integer")
+
+		# assign direction function and calculate output size
+		if direction == "horizontal":
+			concatenate = cv2.hconcat
+			output_width = width * nframes
+			output_height = height
+		elif direction == "vertical":
+			concatenate = cv2.vconcat
+			output_width = width
+			output_height = height * nframes
+		else:
+			raise ValueError("Invalid direction specified")
+
+		if not quiet:
+			aspect_ratio = output_width / output_height
+			print("Visualizing \"{}\" - {} by {} ({:.2f}), from {} frames (every {:.2f} seconds)"\
+				.format(source, output_width, output_height, aspect_ratio, nframes, FrameVis.interval_from_nframes(source, nframes)))
+
+		# set up for the frame processing loop
+		next_keyframe = keyframe_interval / 2  # frame number for the next frame grab, starting evenly offset from start/end
+		finished_frames = 0  # counter for number of processed frames
+		output_image = None
+		progress = ProgressBar("Processing:")
+
+		while True:
+			if finished_frames == nframes:
+				break  # done!
+
+			video.set(cv2.CAP_PROP_POS_FRAMES, int(next_keyframe))  # move cursor to next sampled frame
+			success,image = video.read()  # read the next frame
+
+			if not success:
+				raise IOError("Cannot read from video file (frame {} out of {})".format(int(next_keyframe), video_total_frames))
+
+			if matte_type != 0:  # crop out matting, if specified and matting is present
+				image = MatteTrimmer.crop_image(image, cropping_bounds)
+
+			image = cv2.resize(image, (width, height))  # resize to output size
+
+			# save to output image
+			if output_image is None:
+				output_image = image
+			else:
+				output_image = concatenate([output_image, image])  # concatenate horizontally from left -> right
+
+			finished_frames += 1
+			next_keyframe += keyframe_interval  # set next frame capture time, maintaining floats
+
+			if not quiet:
+				progress.write(finished_frames / nframes)  # print progress bar to the console
+
+		video.release()  # close video capture
+
+		return output_image
+
+	@staticmethod
+	def average_image(image, direction):
+		"""
+		Averages the colors in an axis across an entire image
+
+		Parameters:
+			image (arr x.y.c): image as 3-dimensional numpy array
+			direction (str): direction to average frames ("horizontal" or "vertical")
+
+		Returns:
+			image, with pixel data averaged along provided axis
+		"""
+
+		height, width, depth = image.shape
+
+		if direction == "horizontal":
+			scale_height = 1
+			scale_width = width
+		elif direction == "vertical":
+			scale_height = height
+			scale_width = 1
+		else:
+			raise ValueError("Invalid direction specified")
+
+		image = cv2.resize(image, (scale_width, scale_height))  # scale down to '1', averaging values
+		image = cv2.resize(image, (width, height))  # scale back up to size
+
+		return image
+
+	@staticmethod
+	def motion_blur(image, direction, blur_amount):
+		"""
+		Blurs the pixels in a given axis across an entire image.
+
+		Parameters:
+			image (arr x.y.c): image as 3-dimensional numpy array
+			direction (str): direction of stacked images for blurring ("horizontal" or "vertical")
+			blur_amount (int): how much to blur the image, as the convolution kernel size
+
+		Returns:
+			image, with pixel data blurred along provided axis
+		"""
+		
+		kernel = np.zeros((blur_amount, blur_amount))  # create convolution kernel
+
+		# fill group with '1's
+		if direction == "horizontal":
+			kernel[:, int((blur_amount - 1)/2)] = np.ones(blur_amount)  # fill center column (blurring vertically for horizontal concat)
+		elif direction == "vertical":
+			kernel[int((blur_amount - 1)/2), :] = np.ones(blur_amount)  # fill center row (blurring horizontally for vertical concat)
+		else:
+			raise ValueError("Invalid direction specified")
+
+		kernel /= blur_amount  # normalize kernel matrix
+
+		return cv2.filter2D(image, -1, kernel)  # filter using kernel with same depth as source
+
+	@staticmethod
+	def nframes_from_interval(source, interval):
+		"""
+		Calculates the number of frames available in a video file for a given capture interval
+
+		Parameters:
+			source (str): filepath to source video file
+			interval (float): capture frame every i seconds
+
+		Returns:
+			number of frames per time interval (int)
+		"""
+		video = cv2.VideoCapture(source)  # open video file
+		if not video.isOpened():
+			raise FileNotFoundError("Source Video Not Found")
+
+		frame_count = video.get(cv2.CAP_PROP_FRAME_COUNT)  # total number of frames
+		fps = video.get(cv2.CAP_PROP_FPS)  # framerate of the video
+		duration = frame_count / fps  # duration of the video, in seconds
+
+		video.release()  # close video capture
+
+		return int(round(duration / interval))  # number of frames per interval
+
+	@staticmethod
+	def interval_from_nframes(source, nframes):
+		"""
+		Calculates the capture interval, in seconds, for a video file given the
+		number of frames to capture
+
+		Parameters:
+			source (str): filepath to source video file
+			nframes (int): number of frames to capture from the video file
+
+		Returns:
+			time interval (seconds) between frame captures (float)
+		"""
+		video = cv2.VideoCapture(source)  # open video file
+		if not video.isOpened():
+			raise FileNotFoundError("Source Video Not Found")
+
+		frame_count = video.get(cv2.CAP_PROP_FRAME_COUNT)  # total number of frames
+		fps = video.get(cv2.CAP_PROP_FPS)  # framerate of the video
+		keyframe_interval = frame_count / nframes  # calculate number of frames between captures
+
+		video.release()  # close video capture
+
+		return keyframe_interval / fps  # seconds between captures
+
+
+class MatteTrimmer:
+	"""
+	Functions for finding and removing black mattes around video frames
+	"""
+
+	@staticmethod
+	def find_matrix_edges(matrix, threshold):
+		"""
+		Finds the start and end points of a 1D array above a given threshold
+
+		Parameters:
+			matrix (arr, 1.x): 1D array of data to check
+			threshold (value): valid data is above this trigger level
+
+		Returns:
+			tuple with the array indices of data bounds, start and end
+		"""
+
+		if not isinstance(matrix, (list, tuple, np.ndarray)) or len(matrix.shape) != 1:
+			raise ValueError("Provided matrix is not the right size (must be 1D)")
+
+		data_start = None
+		data_end = None
+
+		for value_id, value in enumerate(matrix):
+			if value > threshold:
+				if data_start is None:
+					data_start = value_id
+				data_end = value_id
+
+		return (data_start, data_end)
+
+	@staticmethod
+	def find_larger_bound(first, second):
+		"""
+		Takes two sets of diagonal rectangular boundary coordinates and determines
+		the set of rectangular boundary coordinates that contains both
+
+		Parameters:
+			first  (arr, 1.2.2): pair of rectangular coordinates, in the form [(X,Y), (X,Y)]
+			second (arr, 1.2.2): pair of rectangular coordinates, in the form [(X,Y), (X,Y)]
+
+			Where for both arrays the first coordinate is in the top left-hand corner, 
+			and the second coordinate is in the bottom right-hand corner.
+
+		Returns:
+			numpy coordinate matrix containing both of the provided boundaries
+		"""
+		left_edge  = first[0][0] if first[0][0] <= second[0][0] else second[0][0]
+		right_edge = first[1][0] if first[1][0] >= second[1][0] else second[1][0]
+
+		top_edge = first[0][1] if first[0][1] <= second[0][1] else second[0][1]
+		bottom_edge = first[1][1] if first[1][1] >= second[1][1] else second[1][1]
+
+		return np.array([[left_edge, top_edge], [right_edge, bottom_edge]])
+
+	@staticmethod
+	def valid_bounds(bounds):
+		"""
+		Checks if the frame bounds are a valid format
+
+		Parameters:
+			bounds (arr, 1.2.2): pair of rectangular coordinates, in the form [(X,Y), (X,Y)]
+
+		Returns:
+			True or False
+		"""
+
+		for x, x_coordinate in enumerate(bounds):
+			for y, y_coordinate in enumerate(bounds):
+				if bounds[x][y] is None:
+					return False  # not a number
+
+		if bounds[0][0] > bounds[1][0]  or \
+			bounds[0][1] > bounds[1][1]:
+			return False  # left > right or top > bottom
+
+		return True
+
+	@staticmethod
+	def determine_image_bounds(image, threshold):
+		"""
+		Determines if there are any hard mattes (black bars) surrounding
+		an image on either the top (letterboxing) or the sides (pillarboxing)
+
+		Parameters:
+			image (arr, x.y.c): image as 3-dimensional numpy array
+			threshold (8-bit int): min color channel value to judge as 'image present'
+
+		Returns:
+			success (bool): True or False if the bounds are valid
+			image_bounds: numpy coordinate matrix with the two opposite corners of the 
+				image bounds, in the form [(X,Y), (X,Y)]
+		"""
+
+		height, width, depth = image.shape
+
+		# check for letterboxing
+		horizontal_sums = np.sum(image, axis=(1,2))  # sum all color channels across all rows
+		hthreshold = (threshold * width * depth)  # must be below every pixel having a value of "threshold" in every channel
+		vertical_edges = MatteTrimmer.find_matrix_edges(horizontal_sums, hthreshold)
+
+		# check for pillarboxing
+		vertical_sums = np.sum(image, axis=(0,2))  # sum all color channels across all columns
+		vthreshold = (threshold * height * depth)  # must be below every pixel having a value of "threshold" in every channel
+		horizontal_edges = MatteTrimmer.find_matrix_edges(vertical_sums, vthreshold)
+
+		image_bounds = np.array([[horizontal_edges[0], vertical_edges[0]], [horizontal_edges[1], vertical_edges[1]]])
+
+		return MatteTrimmer.valid_bounds(image_bounds), image_bounds
+
+	@staticmethod
+	def determine_video_bounds(source, nsamples, threshold):
+		"""
+		Determines if any matting exists in a video source
+
+		Parameters:
+			source (str): filepath to source video file
+			nsamples (int): number of frames from the video to determine bounds,
+				evenly spaced throughout the video
+			threshold (8-bit int): min color channel value to judge as 'image present'
+
+		Returns:
+			success (bool): True or False if the bounds are valid
+			video_bounds: numpy coordinate matrix with the two opposite corners of the 
+				video bounds, in the form [(X,Y), (X,Y)]
+		"""
+		video = cv2.VideoCapture(source)  # open video file
+		if not video.isOpened():
+			raise FileNotFoundError("Source Video Not Found")
+
+		video_total_frames = video.get(cv2.CAP_PROP_FRAME_COUNT)  # retrieve total frame count from metadata
+		if not isinstance(nsamples, int) or nsamples < 1:
+			raise ValueError("Number of samples must be a positive integer")
+		keyframe_interval = video_total_frames / nsamples  # calculate number of frames between captures
+
+		# open video to make results consistent with visualizer
+		# (this also GREATLY increases the read speed? no idea why)
+		success,image = video.read()  # get first frame
+		if not success:
+			raise IOError("Cannot read from video file")
+
+		next_keyframe = keyframe_interval / 2  # frame number for the next frame grab, starting evenly offset from start/end
+		video_bounds = None
+
+		for frame_number in range(nsamples):
+			video.set(cv2.CAP_PROP_POS_FRAMES, int(next_keyframe))  # move cursor to next sampled frame
+			success,image = video.read()  # read the next frame
+
+			if not success:
+				raise IOError("Cannot read from video file")
+			
+			success, frame_bounds = MatteTrimmer.determine_image_bounds(image, threshold)
+
+			if not success:
+				continue  # don't compare bounds, frame bounds are invalid
+
+			video_bounds = frame_bounds if video_bounds is None else MatteTrimmer.find_larger_bound(video_bounds, frame_bounds)
+			next_keyframe += keyframe_interval  # set next frame capture time, maintaining floats
+
+		video.release()  # close video capture
+
+		return MatteTrimmer.valid_bounds(video_bounds), video_bounds
+
+	@staticmethod
+	def crop_image(image, bounds):
+		"""
+		Crops a provided image by the coordinate bounds pair provided.
+
+		Parameters:
+			image (arr, x.y.c): image as 3-dimensional numpy array
+			second (arr, 1.2.2): pair of rectangular coordinates, in the form [(X,Y), (X,Y)]
+
+		Returns:
+			image as 3-dimensional numpy array, cropped to the coordinate bounds
+		"""
+		return image[bounds[0][1]:bounds[1][1], bounds[0][0]:bounds[1][0]]
+
+class ProgressBar:
+	"""
+	Generates a progress bar for the console output
+
+	Args:
+		pre (str): string to prepend before the progress bar
+		bar_length (int): length of the progress bar itself, in characters
+		print_elapsed (bool): option to print time elapsed or not
+
+	Attributes:
+		pre (str): string to prepend before the progress bar
+		bar_length (int): length of the progress bar itself, in characters
+		print_time (bool): option to print time elapsed or not
+		print_elapsed (int): starting time for the progress bar, in unix seconds
+
+	"""
+
+	def __init__(self, pre="", bar_length=25, print_elapsed=True):
+		pre = (pre + '\t') if pre != "" else pre  # append separator if string present
+		self.pre = pre
+		self.bar_length = bar_length
+		self.print_elapsed = print_elapsed
+		if self.print_elapsed:
+			self.__start_time = time.time()  # store start time as unix
+
+	def write(self, percent):
+		"""Prints a progress bar to the console based on the input percentage (float)."""
+		term_char = '\r' if percent < 1.0 else '\n'  # rewrite the line unless finished
+
+		filled_size = int(round(self.bar_length * percent))  # number of 'filled' characters in the bar
+		progress_bar = "#" * filled_size + " " * (self.bar_length - filled_size)  # progress bar characters, as a string
+
+		time_string = ""
+		if self.print_elapsed:
+			time_elapsed = time.time() - self.__start_time
+			time_string = "\tTime Elapsed: {}".format(time.strftime("%H:%M:%S", time.gmtime(time_elapsed)))
+
+		print("{}[{}]\t{:.2%}{}".format(self.pre, progress_bar, percent, time_string), end=term_char, flush=True)
+		
+
+
+def main():
+	parser = argparse.ArgumentParser(description="video frame visualizer and movie barcode generator", add_help=False)  # removing help so I can use '-h' for height
+
+	parser.add_argument("source", help="file path for the video file to be visualized", type=str)
+	parser.add_argument("destination", help="file path output for the final image", type=str)
+	parser.add_argument("-n", "--nframes", help="the number of frames in the visualization", type=int)
+	parser.add_argument("-i", "--interval", help="interval between frames for the visualization", type=float)
+	parser.add_argument("-h", "--height", help="the height of each frame, in pixels", type=int, default=FrameVis.default_frame_height)
+	parser.add_argument("-w", "--width", help="the output width of each frame, in pixels", type=int, default=FrameVis.default_frame_width)
+	parser.add_argument("-d", "--direction", help="direction to concatenate frames, horizontal or vertical", type=str, \
+		choices=["horizontal", "vertical"],	default=FrameVis.default_direction)
+	parser.add_argument("-t", "--trim", help="detect and trim any hard matting (letterboxing or pillarboxing)", action='store_true', default=False)
+	parser.add_argument("-a", "--average", help="average colors for each frame", action='store_true', default=False)
+	parser.add_argument("-b", "--blur", help="apply motion blur to the frames (kernel size)", type=int, nargs='?', const=100, default=0)
+	parser.add_argument("-q", "--quiet", help="mute console outputs", action='store_true', default=False)
+	parser.add_argument("--help", action="help", help="show this help message and exit")
+
+	args = parser.parse_args()
+
+	# check number of frames arguments
+	if args.nframes is None:
+		if args.interval is not None:  # calculate nframes from interval
+			args.nframes = FrameVis.nframes_from_interval(args.source, args.interval)
+		else:
+			parser.error("You must provide either an --(n)frames or --(i)nterval argument")
+
+	# check postprocessing arguments
+	if args.average is True and args.blur != 0:
+		parser.error("Cannot (a)verage and (b)lur, you must choose one or the other")
+
+	fv = FrameVis()
+
+	output_image = fv.visualize(args.source, args.nframes, height=args.height, width=args.width, \
+		direction=args.direction, trim=args.trim, quiet=args.quiet)
+
+	# postprocess
+	if args.average or args.blur != 0:
+		if args.average:
+			if not args.quiet:
+				print("Averaging frame colors... ", end="", flush=True)
+			output_image = fv.average_image(output_image, args.direction)
+		
+		if args.blur != 0:
+			if not args.quiet:
+				print("Adding motion blur to final frame... ", end="", flush=True)
+			output_image = fv.motion_blur(output_image, args.direction, args.blur)
+
+		if not args.quiet:
+			print("done")
+	
+	cv2.imwrite(args.destination, output_image)  # save visualization to file
+
+	if not args.quiet:
+		print("Visualization saved to {}".format(args.destination))
+
+
+if __name__ == "__main__":
+	main()

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=3.50.2
+opencv-python>=4.8.0
+numpy>=1.24.0
+fastapi>=0.115.0
+python-multipart>=0.0.6