Alternate backend (#14)

* Major changes in API - `Scikit-video` is no longer being used as the backend. The new backend is now [ffmpeg-python](https://github.com/kkroening/ffmpeg-python) - Related dependencies have been removed (Pillow) - Removed `required_fps` parameter, and in order to simplify the API, merged the functionality of `mode` and `extract_position` - Added type annotations - Initial support for custom frame selection - Refactored code - Version bump to 2.0.0b * Subsequent changes in docs and related functions - Added `plot()` - Updated documentation - Bumped version to 2.0.0 * Minor API change and docs update - `TargetSize` moved from utils.py to mydia.py, which makes much more sense as cannot be categorized as a utility. - Docs update - Updated README.rst to reflect the updates in the API * Minor type fix in README.rst
MrinalJain17 · Sep 19, 2018 · 7530078 · 7530078
1 parent 2a5d91d
commit 7530078
Show file tree

Hide file tree

Showing 10 changed files with 333 additions and 311 deletions.
diff --git a/README.rst b/README.rst
@@ -1,10 +1,9 @@
-
 Mydia
 =====
 
-Reading videos into NumPy arrays was never more simple. In addition,
-this library also provides an entire range of additional functionalities
-for reading the videos.
+Reading videos into NumPy arrays was never more simple. This library provides 
+an entire range of additional functionalities such as custom frame selection, 
+frame resizing, pixel normalization, grayscale conversion and much more.
 
 `Read the Documentation <https://mrinaljain17.github.io/mydia/>`__
 
@@ -64,8 +63,11 @@ Requirements
 ``Python 3.x`` (preferably from the `Anaconda
 Distribution <https://www.anaconda.com/download/>`__)
 
-The program uses `Scikit-video <http://www.scikit-video.org/stable/>`__, which requires 
-``FFmpeg`` to be installed on the system. To install ``FFmpeg`` on your machine - 
+The program uses `ffmpeg-python <https://github.com/kkroening/ffmpeg-python>`__, which provides
+python bindings for `FFmpeg <https://www.ffmpeg.org/>`__ (used as the backend for reading and 
+processing videos)
+
+To install ``FFmpeg`` on your machine - 
 
 For **Linux** users:
 
@@ -83,24 +85,30 @@ For **Windows or MAC/OSX** users:
 Additional Libraries to install:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Several libraries like `Numpy <http://www.numpy.org/>`__,
-`Pillow <https://python-imaging.github.io/>`__ and
-`Matplotlib <https://matplotlib.org/>`__, required for the package come
-pre-installed with the Anaconda distribution for Python. If you are not
-using the default anaconda distribution, then first install the packages
-mentioned above and along with their dependencies.
+Install the following packages along with their dependencies:
+
+-  `ffmpeg-python <https://github.com/kkroening/ffmpeg-python>`__
+
+.. code:: bash
 
-Also, install the following additional packages:
+       pip install ffmpeg-python
 
--  `Scikit-video <http://www.scikit-video.org/stable/>`__
+-  `Numpy <http://www.numpy.org/>`__
 
 .. code:: bash
 
-       pip install sk-video
+       pip install numpy
 
 -  `tqdm <https://pypi.python.org/pypi/tqdm#installation>`__ - Required
    for displaying the progress bar.
 
 .. code:: bash
 
        pip install tqdm
+
+-  `Matplotlib <https://matplotlib.org/>`__ - (Optional) For plotting the frames
+   of a video
+
+.. code:: bash
+
+       pip install matplotlib
diff --git a/docs/examples/plot_1_getting_started.py b/docs/examples/plot_1_getting_started.py
@@ -2,9 +2,10 @@
 Get started with some basics
 ============================
 
-Reading videos into NumPy arrays was never more simple. In addition,
-this library also provides an entire range of additional functionalities
-for reading the videos.
+Reading videos into NumPy arrays was never more simple. This library provides 
+an entire range of additional functionalities such as custom frame selection, 
+frame resizing, pixel normalization, grayscale conversion and much more.
+
 """
 
 ##############################################################################

diff --git a/docs/examples/plot_2_frame_selection.py b/docs/examples/plot_2_frame_selection.py
@@ -1,6 +1,6 @@
 """
-Frame selection and resizing
-============================
+Frame selection, resizing, and grayscale conversion
+===================================================
 
 -  We want to resize each frame to be 720 pixels in width and 480 pixels
    in height.
@@ -11,7 +11,7 @@
 
 # Imports
 import matplotlib.pyplot as plt
-from mydia import Videos
+from mydia import Videos, plot
 
 # Initialize video path
 video_path = r"./sample_video/bigbuckbunny.mp4"
@@ -26,9 +26,35 @@
 video = reader.read(video_path)  # a tensor of shape (1, 12, 480, 720, 3)
 
 # Plot the video frames in a grid
-reader.plot(video[0])
+plot(video[0])
 plt.show()
 
 ##############################################################################
 # .. note:: The number of channels for a RGB video is 3
 #  (indicated by the last value in the tuple).
+# 
+# 
+# - Now let's read the video with the same parameters, but in grayscale
+
+# Imports
+import matplotlib.pyplot as plt
+from mydia import Videos, plot
+
+# Initialize video path
+video_path = r"./sample_video/bigbuckbunny.mp4"
+
+# Configuring the parameters
+# Other parameters are the same as described above.
+# The only additional parameter to modify is 'to_gray'
+reader = Videos(target_size=(720, 480), to_gray=True, num_frames=12)
+
+# Call the 'read()' function to get the required video tensor
+video = reader.read(video_path)  # a tensor of shape (1, 12, 480, 720, 1)
+
+# Plot the video frames in a grid
+plot(video[0])
+plt.show()
+
+##############################################################################
+# .. note:: The number of channels for a video in gray scale is 1
+#  (indicated by the last value in the tuple).
diff --git a/docs/examples/plot_3_frame_selection_with_gray.py b/docs/examples/plot_3_frame_selection_with_gray.py
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -19,16 +19,18 @@
 import sphinx_rtd_theme
 from sphinx_gallery.sorting import FileNameSortKey
 
+from mydia import mydia
+
 # -- Project information -----------------------------------------------------
 
 project = "Mydia"
 copyright = "2018, Mrinal Jain"
 author = "Mrinal Jain"
 
 # The short X.Y version
-version = "1.0"
+version = "2.0"
 # The full version, including alpha/beta/rc tags
-release = "1.0.5"
+release = mydia.__version__
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -28,8 +28,11 @@ Requirements
 ``Python 3.x`` (preferably from the `Anaconda
 Distribution <https://www.anaconda.com/download/>`__)
 
-The program uses `Scikit-video <http://www.scikit-video.org/stable/>`__, which requires 
-``FFmpeg`` to be installed on the system. To install ``FFmpeg`` on your machine - 
+The program uses `ffmpeg-python <https://github.com/kkroening/ffmpeg-python>`__, which provides
+python bindings for `FFmpeg <https://www.ffmpeg.org/>`__ (used as the backend for reading and 
+processing videos)
+
+To install ``FFmpeg`` on your machine - 
 
 For **Linux** users:
 
@@ -47,24 +50,30 @@ For **Windows or MAC/OSX** users:
 Additional Libraries to install:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Several libraries like `Numpy <http://www.numpy.org/>`__,
-`Pillow <https://python-imaging.github.io/>`__ and
-`Matplotlib <https://matplotlib.org/>`__, required for the package come
-pre-installed with the Anaconda distribution for Python. If you are not
-using the default anaconda distribution, then first install the packages
-mentioned above and along with their dependencies.
+Install the following packages along with their dependencies:
+
+-  `ffmpeg-python <https://github.com/kkroening/ffmpeg-python>`__
+
+.. code:: bash
 
-Also, install the following additional packages:
+       pip install ffmpeg-python
 
--  `Scikit-video <http://www.scikit-video.org/stable/>`__
+-  `Numpy <http://www.numpy.org/>`__
 
 .. code:: bash
 
-       pip install sk-video
+       pip install numpy
 
 -  `tqdm <https://pypi.python.org/pypi/tqdm#installation>`__ - Required
    for displaying the progress bar.
 
 .. code:: bash
 
        pip install tqdm
+
+-  `Matplotlib <https://matplotlib.org/>`__ - (Optional) For plotting the frames
+   of a video
+
+.. code:: bash
+
+       pip install matplotlib
diff --git a/mydia/__init__.py b/mydia/__init__.py
@@ -1 +1,2 @@
-from .mydia import Videos
+from .mydia import *
+from .utils import _mode_auto, _mode_first, _mode_last, _mode_middle, _mode_random