Merge pull request #17 from LukasBommes/dev

Dev

Author: LukasBommes

.gitignore

@@ -5,6 +5,7 @@
 .eggs
 __pycache__/
 /venv3.*/
+out-*/
 
 *.tar
 a.out

Dockerfile

@@ -1,23 +1,42 @@
-FROM ubuntu:18.04 AS builder
+FROM ubuntu:22.04 AS builder
 
 WORKDIR /home/video_cap
 
-COPY install.sh /home/video_cap
-COPY ffmpeg_patch /home/video_cap/ffmpeg_patch/
+# Install build tools
+RUN apt-get update -qq --fix-missing && \
+  apt-get upgrade -y && \
+  apt-get install -y \
+    wget \
+    unzip \
+    build-essential \
+    cmake \
+    git \
+    pkg-config \
+    autoconf \
+    automake \
+    git-core \
+    python3-dev \
+    python3-pip \
+    python3-numpy \
+    python3-pkgconfig && \
+    rm -rf /var/lib/apt/lists/*
 
-# Install dependencies
+# Install OpenCV
+COPY install_opencv.sh /home/video_cap
 RUN mkdir -p /home/video_cap && \
   cd /home/video_cap && \
-  chmod +x install.sh && \
-  ./install.sh
+  chmod +x install_opencv.sh && \
+  ./install_opencv.sh
 
-# Install debugging tools
-RUN apt-get update && \
-  apt-get -y install \
-  gdb \
-  python3-dbg
+# Install FFMPEG
+COPY install_ffmpeg.sh /home/video_cap
+COPY ffmpeg_patch /home/video_cap/ffmpeg_patch/
+RUN mkdir -p /home/video_cap && \
+  cd /home/video_cap && \
+  chmod +x install_ffmpeg.sh && \
+  ./install_ffmpeg.sh
 
-FROM ubuntu:18.04
+FROM ubuntu:22.04
 
 # install Python
 RUN apt-get update && \
@@ -44,7 +63,7 @@ RUN apt-get update && \
     libvdpau-dev \
     libvorbis-dev \
     libopus-dev \
-    libdc1394-22-dev \
+    libdc1394-dev \
     liblzma-dev && \
     rm -rf /var/lib/apt/lists/*
 
@@ -72,7 +91,6 @@ COPY src /home/video_cap/src/
 
 # Install Python package
 COPY vid.mp4 /home/video_cap
-RUN cd /home/video_cap && \
-  python3 setup.py install
+RUN python3 setup.py install
 
 CMD ["sh", "-c", "tail -f /dev/null"]

LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2010-2019 Google, Inc. http://angularjs.org
+Copyright (c) 2010-2022 Lukas Bommes
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -14,10 +14,26 @@ The image below shows a video frame with extracted motion vectors overlaid,
 
 ![motion_vector_demo_image](mvs.png)
 
-A usage example can be found in `test.py`.
+A usage example can be found in `extract_mvs.py`.
 
 
-## Installation
+## News
+
+### Recent Changes
+
+- Added unittests in `tests/tests.py`
+- Updated to Ubuntu 22.04, Python 3.10, and OpenCV 4.5.5
+- Provided a script to wrap Docker run command
+- Updated demo script with command line arguments for extraction and storing of motion vectors
+
+### Looking for Contributors
+
+The mv-extractor seems to be quite popular and I want to improve it. However, I do not have the time and resources to do this alone. Hence, I gladly welcome any community contributions.
+
+One improvement that is on my mind, is the packaging and distribution of mv-extractor via PyPI. This requires creating a source distribution and building binary wheels for different target architectures and Python versions. Ideally, the build would be automated with a CI pipeline, e.g., GitHub Actions. It would be awesome, if someone is interested in helping me and getting this to work. In this case, please just open an issue and we can discuss the details.
+
+
+## Quickstart
 
 ### Step 1: Install Prerequisites
 
@@ -30,58 +46,63 @@ Change into the desired installation directory on your machine and clone the sou
 git clone https://github.com/LukasBommes/mv-extractor.git mv_extractor
 ```
 
-### Step 3: Pull and Run Docker Image
+### Step 3: Extract Motion Vectors
 
-Change into the `mv_extractor` directory and run the prebuilt Docker image
+Change into the `mv_extractor` directory and run the extraction script
 ```
-sudo docker run -it --ipc=host --env="DISPLAY" -v $(pwd):/home/video_cap -v /tmp/.X11-unix:/tmp/.X11-unix:rw lubo1994/mv-extractor:latest /bin/bash
+sudo ./run.sh python3 extract_mvs.py
 ```
+This pulls a prebuild Docker image and runs the mv-extractor within this image. 
 
-<details>
-  <summary>Alternative: Build Docker image locally</summary>
-  
-This step is not required and for faster installation, we recommend using the prebuilt image. 
-If you still want to build the Docker image locally, you can do so by running the following command in the `mv_extractor` directory
+The extraction script provides several command line options, e.g., to store extracted motion vectors to disk, and to enable/disable graphical output. To see all command line options type
 ```
-sudo docker build . --tag=mv_extractor
+sudo ./run.sh python3 extract_mvs.py -h
+``` 
+For example, if you want to store extracted frames and motion vectors to disk, you can do so by running
 ```
-Note that building can take more than one hour.
-
-Now, run the docker container with
+sudo ./run.sh python3 extract_mvs.py --dump
 ```
-sudo docker run -it --ipc=host --env="DISPLAY" -v $(pwd):/home/video_cap -v /tmp/.X11-unix:/tmp/.X11-unix:rw mv_extractor /bin/bash
-```
-
-Building the image leaves some intermediate images behind which can be deleted via
+You can also open another video stream by specifying its file path or url, e.g.,
 ```
-sudo docker rmi -f $(sudo docker images -f "dangling=true" -q)
+sudo ./run.sh python3 extract_mvs.py "another_video.mp4"
 ```
-</details>
+Note, that the last command will fail because there is no file called `another_video.mp4`.
 
 
-### Step 4: Test Installation
+## Advanced Usage
 
-Test if everything is installed succesfully by running the demo script
-```
-python3 test.py
-```
-If you encounter the error message "cannot open display: :1" or similar, you have to disable the X server access control by running
+### Run Tests
+
+To test if everything is installed succesfully you can run the tests with
 ```
-xhost +
+sudo ./run.sh python3 tests/tests.py
 ```
-in a new terminal on the host machine (not inside the Docker container).
-
+Confirm that all tests pass.
 
-## Usage
+### Importing mv-extractor into Your Own Scripts
 
 If you want to use the motion vector extractor in your own Python script import it via
 ```
 from mv_extractor import VideoCap
 ```
-You can then use it according to the example in `test.py`.
+You can then use it according to the example in `extract_mvs.py`.
 
 Generally, a video file is opened by `VideoCap.open()` and frames, motion vectors, frame types and timestamps are read by calling `VideoCap.read()` repeatedly. Before exiting the program, the video file has to be closed by `VideoCap.release()`. For a more detailed explanation see the API documentation below.
 
+### Building the Docker Image Locally
+ 
+This step is not required and for faster installation, we recommend using the prebuilt image.
+If you still want to build the Docker image locally, you can do so by running the following command in the `mv_extractor` directory
+```
+sudo docker build . --tag=mv_extractor
+```
+Note that building can take more than one hour.
+
+Now, run the docker container with
+```
+sudo docker run -it --ipc=host --env="DISPLAY" -v $(pwd):/home/video_cap -v /tmp/.X11-unix:/tmp/.X11-unix:rw mv_extractor /bin/bash
+```
+
 
 ## Python API
 

extract_mvs.py

@@ -0,0 +1,106 @@
+import os
+import time
+from datetime import datetime
+import argparse
+
+import numpy as np
+import cv2
+
+from mv_extractor import VideoCap
+
+def draw_motion_vectors(frame, motion_vectors):
+    if len(motion_vectors) > 0:
+        num_mvs = np.shape(motion_vectors)[0]
+        for mv in np.split(motion_vectors, num_mvs):
+            start_pt = (mv[0, 3], mv[0, 4])
+            end_pt = (mv[0, 5], mv[0, 6])
+            cv2.arrowedLine(frame, start_pt, end_pt, (0, 0, 255), 1, cv2.LINE_AA, 0, 0.1)
+    return frame
+
+
+if __name__ == "__main__":
+
+    parser = argparse.ArgumentParser(description='Extract motion vectors from video.')
+    parser.add_argument('video_url', type=str, nargs='?', default="vid.mp4", help='File path or url of the video stream')
+    parser.add_argument('--preview', action=argparse.BooleanOptionalAction, default=True, help='Show a preview video with overlaid motion vectors')
+    parser.add_argument('--verbose', action=argparse.BooleanOptionalAction, default=True, help='Show detailled text output')
+    parser.add_argument('--dump', action=argparse.BooleanOptionalAction, default=False, help='Dump frames, motion vectors, frame types, and timestamps to output directory')
+    args = parser.parse_args()
+
+    if args.dump:
+        now = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
+        for child in ["frames", "motion_vectors"]:
+            os.makedirs(os.path.join(f"out-{now}", child), exist_ok=True)
+
+    cap = VideoCap()
+
+    # open the video file
+    ret = cap.open(args.video_url)
+
+    if not ret:
+        raise RuntimeError(f"Could not open {args.video_url}")
+    
+    if args.verbose:
+        print("Sucessfully opened video file")
+
+    step = 0
+    times = []
+
+    # continuously read and display video frames and motion vectors
+    while True:
+        if args.verbose:
+            print("Frame: ", step, end=" ")
+
+        tstart = time.perf_counter()
+
+        # read next video frame and corresponding motion vectors
+        ret, frame, motion_vectors, frame_type, timestamp = cap.read()
+
+        tend = time.perf_counter()
+        telapsed = tend - tstart
+        times.append(telapsed)
+
+        # if there is an error reading the frame
+        if not ret:
+            if args.verbose:
+                print("No frame read. Stopping.")
+            break
+
+        # print results
+        if args.verbose:
+            print("timestamp: {} | ".format(timestamp), end=" ")
+            print("frame type: {} | ".format(frame_type), end=" ")
+
+            print("frame size: {} | ".format(np.shape(frame)), end=" ")
+            print("motion vectors: {} | ".format(np.shape(motion_vectors)), end=" ")
+            print("elapsed time: {} s".format(telapsed))
+
+        frame = draw_motion_vectors(frame, motion_vectors)
+
+        # store motion vectors, frames, etc. in output directory
+        if args.dump:
+            cv2.imwrite(os.path.join(f"out-{now}", "frames", f"frame-{step}.jpg"), frame)
+            np.save(os.path.join(f"out-{now}", "motion_vectors", f"mvs-{step}.npy"), motion_vectors)
+            with open(os.path.join(f"out-{now}", "timestamps.txt"), "a") as f:
+                f.write(str(timestamp)+"\n")
+            with open(os.path.join(f"out-{now}", "frame_types.txt"), "a") as f:
+                f.write(frame_type+"\n")
+
+
+        step += 1
+
+        if args.preview:
+            cv2.imshow("Frame", frame)
+
+            # if user presses "q" key stop program
+            if cv2.waitKey(1) & 0xFF == ord('q'):
+                break
+    
+    if args.verbose:
+        print("average dt: ", np.mean(times))
+
+    cap.release()
+
+    # close the GUI window
+    if args.preview:
+        cv2.destroyAllWindows()