From 31791beef757f2652f9752f005b0c20fc58fa57f Mon Sep 17 00:00:00 2001
From: Yazhou Cao <yazhou.cao@landing.ai>
Date: Mon, 25 Mar 2024 15:07:32 -0700
Subject: [PATCH] Add frame extraction tool for video processing

---
 poetry.lock                 | 124 ++++++++++++++++++++++-
 pyproject.toml              |   5 +
 tests/data/video/test.mp4   | Bin 0 -> 17317 bytes
 tests/tools/test_video.py   |   7 ++
 vision_agent/tools/tools.py |  28 ++++++
 vision_agent/tools/video.py | 190 ++++++++++++++++++++++++++++++++++++
 6 files changed, 353 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/video/test.mp4
 create mode 100644 tests/tools/test_video.py
 create mode 100644 vision_agent/tools/video.py

diff --git a/poetry.lock b/poetry.lock
index 3f479663..d7c66b5d 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -257,6 +257,17 @@ files = [
 [package.extras]
 dev = ["black", "flake8", "flake8-pyi", "matplotlib", "mypy (==0.770)", "numpy", "pandas", "pytest"]
 
+[[package]]
+name = "decorator"
+version = "4.4.2"
+description = "Decorators for Humans"
+optional = false
+python-versions = ">=2.6, !=3.0.*, !=3.1.*"
+files = [
+    {file = "decorator-4.4.2-py2.py3-none-any.whl", hash = "sha256:41fa54c2a0cc4ba648be4fd43cff00aedf5b9465c9bf18d64325bc225f08f760"},
+    {file = "decorator-4.4.2.tar.gz", hash = "sha256:e3a62f0520172440ca0dcc823749319382e377f37f140a0b99ef45fecb84bfe7"},
+]
+
 [[package]]
 name = "distro"
 version = "1.9.0"
@@ -518,6 +529,56 @@ files = [
     {file = "idna-3.6.tar.gz", hash = "sha256:9ecdbbd083b06798ae1e86adcbfe8ab1479cf864e4ee30fe4e46a003d12491ca"},
 ]
 
+[[package]]
+name = "imageio"
+version = "2.34.0"
+description = "Library for reading and writing a wide range of image, video, scientific, and volumetric data formats."
+optional = false
+python-versions = ">=3.8"
+files = [
+    {file = "imageio-2.34.0-py3-none-any.whl", hash = "sha256:08082bf47ccb54843d9c73fe9fc8f3a88c72452ab676b58aca74f36167e8ccba"},
+    {file = "imageio-2.34.0.tar.gz", hash = "sha256:ae9732e10acf807a22c389aef193f42215718e16bd06eed0c5bb57e1034a4d53"},
+]
+
+[package.dependencies]
+numpy = "*"
+pillow = ">=8.3.2"
+
+[package.extras]
+all-plugins = ["astropy", "av", "imageio-ffmpeg", "pillow-heif", "psutil", "tifffile"]
+all-plugins-pypy = ["av", "imageio-ffmpeg", "pillow-heif", "psutil", "tifffile"]
+build = ["wheel"]
+dev = ["black", "flake8", "fsspec[github]", "pytest", "pytest-cov"]
+docs = ["numpydoc", "pydata-sphinx-theme", "sphinx (<6)"]
+ffmpeg = ["imageio-ffmpeg", "psutil"]
+fits = ["astropy"]
+full = ["astropy", "av", "black", "flake8", "fsspec[github]", "gdal", "imageio-ffmpeg", "itk", "numpydoc", "pillow-heif", "psutil", "pydata-sphinx-theme", "pytest", "pytest-cov", "sphinx (<6)", "tifffile", "wheel"]
+gdal = ["gdal"]
+itk = ["itk"]
+linting = ["black", "flake8"]
+pillow-heif = ["pillow-heif"]
+pyav = ["av"]
+test = ["fsspec[github]", "pytest", "pytest-cov"]
+tifffile = ["tifffile"]
+
+[[package]]
+name = "imageio-ffmpeg"
+version = "0.4.9"
+description = "FFMPEG wrapper for Python"
+optional = false
+python-versions = ">=3.5"
+files = [
+    {file = "imageio-ffmpeg-0.4.9.tar.gz", hash = "sha256:39bcd1660118ef360fa4047456501071364661aa9d9021d3d26c58f1ee2081f5"},
+    {file = "imageio_ffmpeg-0.4.9-py3-none-macosx_10_9_intel.macosx_10_9_x86_64.macosx_10_10_intel.macosx_10_10_x86_64.whl", hash = "sha256:24095e882a126a0d217197b86265f821b4bb3cf9004104f67c1384a2b4b49168"},
+    {file = "imageio_ffmpeg-0.4.9-py3-none-manylinux2010_x86_64.whl", hash = "sha256:2996c64af3e5489227096580269317719ea1a8121d207f2e28d6c24ebc4a253e"},
+    {file = "imageio_ffmpeg-0.4.9-py3-none-manylinux2014_aarch64.whl", hash = "sha256:7eead662d2f46d748c0ab446b68f423eb63d2b54d0a8ef96f80607245540866d"},
+    {file = "imageio_ffmpeg-0.4.9-py3-none-win32.whl", hash = "sha256:b6de1e18911687c538d5585d8287ab1a23624ca9dc2044fcc4607de667bcf11e"},
+    {file = "imageio_ffmpeg-0.4.9-py3-none-win_amd64.whl", hash = "sha256:7e900c695c6541b1cb17feb1baacd4009b30a53a45b81c23d53a67ab13ffb766"},
+]
+
+[package.dependencies]
+setuptools = "*"
+
 [[package]]
 name = "iniconfig"
 version = "2.0.0"
@@ -803,6 +864,30 @@ files = [
 griffe = ">=0.37"
 mkdocstrings = ">=0.20"
 
+[[package]]
+name = "moviepy"
+version = "1.0.3"
+description = "Video editing with Python"
+optional = false
+python-versions = "*"
+files = [
+    {file = "moviepy-1.0.3.tar.gz", hash = "sha256:2884e35d1788077db3ff89e763c5ba7bfddbd7ae9108c9bc809e7ba58fa433f5"},
+]
+
+[package.dependencies]
+decorator = ">=4.0.2,<5.0"
+imageio = {version = ">=2.5,<3.0", markers = "python_version >= \"3.4\""}
+imageio_ffmpeg = {version = ">=0.2.0", markers = "python_version >= \"3.4\""}
+numpy = {version = ">=1.17.3", markers = "python_version > \"2.7\""}
+proglog = "<=1.0.0"
+requests = ">=2.8.1,<3.0"
+tqdm = ">=4.11.2,<5.0"
+
+[package.extras]
+doc = ["Sphinx (>=1.5.2,<2.0)", "numpydoc (>=0.6.0,<1.0)", "pygame (>=1.9.3,<2.0)", "sphinx_rtd_theme (>=0.1.10b0,<1.0)"]
+optional = ["matplotlib (>=2.0.0,<3.0)", "opencv-python (>=3.0,<4.0)", "scikit-image (>=0.13.0,<1.0)", "scikit-learn", "scipy (>=0.19.0,<1.5)", "youtube_dl"]
+test = ["coverage (<5.0)", "coveralls (>=1.1,<2.0)", "pytest (>=3.0.0,<4.0)", "pytest-cov (>=2.5.1,<3.0)", "requests (>=2.8.1,<3.0)"]
+
 [[package]]
 name = "mpmath"
 version = "1.3.0"
@@ -1106,6 +1191,29 @@ typing-extensions = ">=4.7,<5"
 [package.extras]
 datalib = ["numpy (>=1)", "pandas (>=1.2.3)", "pandas-stubs (>=1.1.0.11)"]
 
+[[package]]
+name = "opencv-python-headless"
+version = "4.9.0.80"
+description = "Wrapper package for OpenCV python bindings."
+optional = false
+python-versions = ">=3.6"
+files = [
+    {file = "opencv-python-headless-4.9.0.80.tar.gz", hash = "sha256:71a4cd8cf7c37122901d8e81295db7fb188730e33a0e40039a4e59c1030b0958"},
+    {file = "opencv_python_headless-4.9.0.80-cp37-abi3-macosx_10_16_x86_64.whl", hash = "sha256:2ea8a2edc4db87841991b2fbab55fc07b97ecb602e0f47d5d485bd75cee17c1a"},
+    {file = "opencv_python_headless-4.9.0.80-cp37-abi3-macosx_11_0_arm64.whl", hash = "sha256:e0ee54e27be493e8f7850847edae3128e18b540dac1d7b2e4001b8944e11e1c6"},
+    {file = "opencv_python_headless-4.9.0.80-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:57ce2865e8fec431c6f97a81e9faaf23fa5be61011d0a75ccf47a3c0d65fa73d"},
+    {file = "opencv_python_headless-4.9.0.80-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:976656362d68d9f40a5c66f83901430538002465f7db59142784f3893918f3df"},
+    {file = "opencv_python_headless-4.9.0.80-cp37-abi3-win32.whl", hash = "sha256:11e3849d83e6651d4e7699aadda9ec7ed7c38957cbbcb99db074f2a2d2de9670"},
+    {file = "opencv_python_headless-4.9.0.80-cp37-abi3-win_amd64.whl", hash = "sha256:a8056c2cb37cd65dfcdf4153ca16f7362afcf3a50d600d6bb69c660fc61ee29c"},
+]
+
+[package.dependencies]
+numpy = [
+    {version = ">=1.21.4", markers = "python_version >= \"3.10\" and platform_system == \"Darwin\" and python_version < \"3.11\""},
+    {version = ">=1.21.2", markers = "platform_system != \"Darwin\" and python_version >= \"3.10\" and python_version < \"3.11\""},
+    {version = ">=1.23.5", markers = "python_version >= \"3.11\""},
+]
+
 [[package]]
 name = "packaging"
 version = "24.0"
@@ -1325,6 +1433,20 @@ files = [
 dev = ["pre-commit", "tox"]
 testing = ["pytest", "pytest-benchmark"]
 
+[[package]]
+name = "proglog"
+version = "0.1.10"
+description = "Log and progress bar manager for console, notebooks, web..."
+optional = false
+python-versions = "*"
+files = [
+    {file = "proglog-0.1.10-py3-none-any.whl", hash = "sha256:19d5da037e8c813da480b741e3fa71fb1ac0a5b02bf21c41577c7f327485ec50"},
+    {file = "proglog-0.1.10.tar.gz", hash = "sha256:658c28c9c82e4caeb2f25f488fff9ceace22f8d69b15d0c1c86d64275e4ddab4"},
+]
+
+[package.dependencies]
+tqdm = "*"
+
 [[package]]
 name = "pycodestyle"
 version = "2.9.1"
@@ -2488,4 +2610,4 @@ watchmedo = ["PyYAML (>=3.10)"]
 [metadata]
 lock-version = "2.0"
 python-versions = ">=3.10,<3.12"
-content-hash = "dbb1f3241c006408ab8056349c63d7f947450c01fd518a758af66e2e5c000916"
+content-hash = "c22b1c0eb7fbae1f326837eacfe7af3dd0ee754d7a074c9ae1b465e05d65e98e"
diff --git a/pyproject.toml b/pyproject.toml
index 5af13d3a..2ea59ef3 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -29,6 +29,10 @@ sentence-transformers = "2.*"
 openai = "1.*"
 typing_extensions = "4.*"
 
+[tool.poetry.group.video.dependencies]
+moviepy = "1.*"
+opencv-python-headless = "4.*"
+
 [tool.poetry.group.dev.dependencies]
 autoflake = "1.*"
 pytest = "7.*"
@@ -84,4 +88,5 @@ module = [
     "faiss.*",
     "openai.*",
     "sentence_transformers.*",
+    "moviepy.*",
 ]
diff --git a/tests/data/video/test.mp4 b/tests/data/video/test.mp4
new file mode 100644
index 0000000000000000000000000000000000000000..596eea389407ac08915148bbd2212567a1382b4a
GIT binary patch
literal 17317
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

literal 0
HcmV?d00001

diff --git a/tests/tools/test_video.py b/tests/tools/test_video.py
new file mode 100644
index 00000000..8952c238
--- /dev/null
+++ b/tests/tools/test_video.py
@@ -0,0 +1,7 @@
+from vision_agent.tools.video import extract_frames_from_video
+
+
+def test_extract_frames_from_video():
+    video_path = "tests/data/video/test.mp4"
+    res = extract_frames_from_video(video_path)
+    assert len(res) == 1
diff --git a/vision_agent/tools/tools.py b/vision_agent/tools/tools.py
index a2b75851..42b3a810 100644
--- a/vision_agent/tools/tools.py
+++ b/vision_agent/tools/tools.py
@@ -457,6 +457,33 @@ def __call__(self, input: List[int]) -> float:
         return round(input[0] / input[1], 2)
 
 
+class ExtractFrames(Tool):
+    name = "extract_frames_"
+    description = "'extract_frames_' extract image frames from the input video, return a list of tuple (frame, timestamp), where the timestamp is the relative time in seconds of the frame occurred in the video."
+    usage = {
+        "required_parameters": [{"name": "video_uri", "type": "str"}],
+        "examples": [
+            {
+                "scenario": "Can you extract the frames from this video? Video: www.foobar.com/video?name=test.mp4",
+                "parameters": {"video_uri": "www.foobar.com/video?name=test.mp4"},
+            },
+            {
+                "scenario": "Can you extract the images from this video file? Video path: tests/data/test.mp4",
+                "parameters": {"video_uri": "tests/data/test.mp4"},
+            },
+        ],
+    }
+
+    def __call__(self, video_uri: str) -> list[tuple[np.ndarray, float]]:
+        try:
+            from vision_agent.tools.video import extract_frames_from_video
+        except Exception as e:
+            raise ImportError(
+                "vision_agent is not installed correctly (cause: missing dependencies), please run 'pip install vision-agent[video]' instead."
+            ) from e
+        return extract_frames_from_video(video_uri)
+
+
 TOOLS = {
     i: {"name": c.name, "description": c.description, "usage": c.usage, "class": c}
     for i, c in enumerate(
@@ -472,6 +499,7 @@ def __call__(self, input: List[int]) -> float:
             Subtract,
             Multiply,
             Divide,
+            ExtractFrames,
         ]
     )
     if (hasattr(c, "name") and hasattr(c, "description") and hasattr(c, "usage"))
diff --git a/vision_agent/tools/video.py b/vision_agent/tools/video.py
new file mode 100644
index 00000000..1957915d
--- /dev/null
+++ b/vision_agent/tools/video.py
@@ -0,0 +1,190 @@
+import logging
+import math
+import os
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from typing import cast
+
+import cv2
+import numpy as np
+from moviepy.video.io.VideoFileClip import VideoFileClip
+from tqdm import tqdm
+
+_LOGGER = logging.getLogger(__name__)
+# The maximum length of the clip to extract frames from, in seconds
+_CLIP_LENGTH = 30.0
+
+
+def extract_frames_from_video(
+    video_uri: str, fps: int = 2, motion_detection_threshold: float = 0.06
+) -> list[tuple[np.ndarray, float]]:
+    """Extract frames from a video
+
+    Parameters
+    ----------
+    video_uri: str, the path to the video file or a video file url
+    fps: int, the frame rate per second to extract the frames
+    motion_detection_threshold: float, the threshold to detect the motion between frames.
+        A value between 0-1, the percentage change that is considered a different frame.
+        A lower value means more frames will be extracted.
+
+    Returns
+    -------
+    list[tuple[np.ndarray, int]], a list of tuples containing the extracted frame and the timestamp in seconds. E.g. [(frame1, 0.0), (frame2, 0.5), ...]
+        The timestamp is the time in seconds from the start of the video. E.g. 12.125 means 12.125 seconds from the start of the video.
+        The frames are sorted by the timestamp in ascending order.
+    """
+    with VideoFileClip(video_uri) as video:
+        video_duration: float = video.duration
+        num_workers = os.cpu_count()
+        clip_length: float = min(video_duration, _CLIP_LENGTH)
+        start_times = list(range(0, math.ceil(video_duration), math.ceil(clip_length)))
+        assert start_times, f"No frames to extract from the input video: {video_uri}"
+        segment_args = [
+            {
+                "video_uri": video_uri,
+                "start": start,
+                "end": (
+                    start + clip_length if i < len(start_times) - 1 else video_duration
+                ),
+                "fps": fps,
+                "motion_detection_threshold": motion_detection_threshold,
+            }
+            for i, start in enumerate(start_times)
+        ]
+        if (
+            cast(float, segment_args[-1]["end"])
+            - cast(float, segment_args[-1]["start"])
+            < 1
+        ):
+            # If the last segment is less than 1s, merge it with the previous segment
+            # This is to avoid the failure of the last segment extraction
+            assert (
+                len(segment_args) > 1
+            ), "Development bug - Expect at least 2 segments."
+            segment_args[-2]["end"] = video_duration
+            segment_args.pop(-1)
+        _LOGGER.info(
+            f"""Created {len(segment_args)} segments from the input video  {video_uri} of length {video.duration}s, with clip size: {clip_length}s and {num_workers} workers.
+            Segments: {segment_args}
+            """
+        )
+        frames = []
+        with tqdm(total=len(segment_args)) as pbar:
+            with ProcessPoolExecutor(max_workers=num_workers) as executor:
+                futures = [
+                    executor.submit(_extract_frames_by_clip, **kwargs)  # type: ignore
+                    for kwargs in segment_args
+                ]
+                for future in as_completed(futures):
+                    result = future.result()
+                    frames.extend(result)
+                    pbar.update(1)
+        frames.sort(key=lambda x: x[1])
+        _LOGGER.info(f"Extracted {len(frames)} frames from video {video_uri}")
+        return frames
+
+
+def _extract_frames_by_clip(
+    video_uri: str,
+    start: int = 0,
+    end: float = -1,
+    fps: int = 2,
+    motion_detection_threshold: float = 0.06,
+) -> list[tuple[np.ndarray, float]]:
+    """Extract frames from a video clip with start and end time in seconds.
+
+    Parameters
+    ----------
+    video_uri: str, the path to the video file or a video file url
+    start: int, the start time (in seconds) of the clip to extract
+    end: float, the end time (in seconds, up to millisecond level precision) of the clip to extract, if -1, extract the whole video
+    fps: int, the frame rate to extract the frames
+    motion_detection_threshold: float, the threshold to detect the motion between frames
+    """
+    with VideoFileClip(video_uri) as video:
+        source_fps = video.fps
+        if end <= 0:
+            end = video.duration
+        _LOGGER.info(
+            f"Extracting frames from video {video_uri} ({video.duration}s) with start={start}s and end={end}s"
+        )
+        clip = video.subclip(start, end)
+        processable_frames = int(clip.duration * fps)
+        _LOGGER.info(
+            f"Extracting frames from video clip of length {clip.duration}s with FPS={fps} and start_time={start}s. Total number of frames in clip: {processable_frames}"
+        )
+        frames = []
+        total_count, skipped_count = 0, 0
+        prev_processed_frame = None
+        pbar = tqdm(
+            total=processable_frames, desc=f"Extracting frames from clip {start}-{end}"
+        )
+        for i, frame in enumerate(clip.iter_frames(fps=fps, dtype="uint8")):
+            curr_processed_frame = _preprocess_frame(frame)
+            total_count += 1
+            pbar.update(1)
+            # Skip the frame if it is similar to the previous one
+            if prev_processed_frame is not None and _similar_frame(
+                prev_processed_frame,
+                curr_processed_frame,
+                threshold=motion_detection_threshold,
+            ):
+                skipped_count += 1
+                continue
+            prev_processed_frame = curr_processed_frame
+            ts = round(clip.reader.pos / source_fps, 3)
+            frames.append((frame, ts))
+
+        _LOGGER.info(
+            f"""Finished!
+                Frames extracted: {len(frames)}
+                Extracted frame timestamp: {[f[1] for f in frames]}
+                Total processed frames: {total_count}
+                Skipped frames:  {skipped_count}
+                Scan FPS: {fps}
+                Clip start time: {start}s, {clip.pos}
+                Clip end time: {end}s
+                Clip duration: {clip.duration}s
+                Clip total frames: {clip.duration * source_fps}
+                Video duration: {video.duration}s
+                Video FPS: {video.fps}
+                Video total frames: {video.reader.nframes}"""
+        )
+        return frames
+
+
+def _preprocess_frame(frame: np.ndarray) -> np.ndarray:
+    # Convert to grayscale
+    frame = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+    frame = cv2.GaussianBlur(src=frame, ksize=(5, 5), sigmaX=0)
+    return frame
+
+
+def _similar_frame(
+    prev_frame: np.ndarray, curr_frame: np.ndarray, threshold: float
+) -> bool:
+    """Detect two frames are similar or not
+
+    Parameters
+    ----------
+    threshold : float, optional
+        Similarity threshold, a value between 0-1, the percentage change that is considered a different frame.
+    """
+    # calculate difference and update previous frame TODO: don't assume the processed image is cached
+    diff_frame = cv2.absdiff(src1=prev_frame, src2=curr_frame)
+    # Only take different areas that are different enough (>20 / 255)
+    thresh_frame = cv2.threshold(
+        src=diff_frame, thresh=20, maxval=255, type=cv2.THRESH_BINARY
+    )[1]
+    change_percentage = cv2.countNonZero(thresh_frame) / (
+        curr_frame.shape[0] * curr_frame.shape[1]
+    )
+    _LOGGER.debug(f"Image diff: {change_percentage}")
+    return change_percentage < threshold
+
+
+# res = extract_frames(video)
+if __name__ == "__main__":
+    video_path = "/Users/asia/Downloads/frames/baby_cam1.MP4"
+    res = extract_frames_from_video(video_path)
+    print("done, extracted num frames: ", len(res))