Merge pull request #762 from danforthcenter/visualize_time_lapse_video

Create time lapse video (visualize sub package)

Author: HaleySchuhl

docs/updating.md

@@ -1066,6 +1066,11 @@ pages for more details on the input and output variable types.
 * pre v4.0: NA
 * post v4.0: fig, ax = **pcv.visualize.pixel_scatter_plot**(*paths_to_imgs, x_channel, y_channel*)
 
+#### plantcv.visualize.time_lapse_video
+
+* pre v4.0: NA
+* post v4.0: frame_size = **pcv.visualize.time_lapse_video**(*img_list, out_filename='./time_lapse_video.mp4', fps=29.97, display=True*)
+
 #### plantcv.watershed_segmentation
 
 * pre v3.0dev2: device, watershed_header, watershed_data, analysis_images = **plantcv.watershed_segmentation**(*device, img, mask, distance=10, filename=False, debug=None*)

docs/visualize_time_lapse_video.md

@@ -0,0 +1,44 @@
+## Automatically Generate a Time-Lapse Video given A Directory of Images
+
+This function generates and saves the time-lapse video based on a list of paths to the images.
+
+**plantcv.visualize.time_lapse_video**(*img_list, out_filename='./time_lapse_video.mp4', fps=29.97, display=True*)
+
+**returns** frame_size
+
+- **Parameters:**
+    - list_img       - List of paths to the images to create the video.    
+    - out_filename   - Name of file to save the generated video to.
+    - fps            - Frame rate (frames per second) By default fps=29.97. Commonly used values: 23.98, 24, 25, 29.97, 30, 50, 59.94, 60   
+    - display        - if True (default), displays the path to the generated video.
+
+- **Context:**
+    - Used to generate time-lapse video given a list of images.
+    - List of image paths can be generated with [`plantcv.io.read_dataset`](io_read_dataset.md). 
+
+- **Example Use:**
+    - Below
+
+
+```python
+from plantcv import plantcv as pcv
+# Note you will have to change this part on your own path
+img_directory = './path_to_images_directory/'
+img_paths_list = pcv.io.read_dataset(source_path=img_directory, sort=True)
+
+fps = 29.97
+name_video = './eg_time_lapse'
+display    = True
+
+frame_size = pcv.visualize.time_lapse_video(img_list=img_paths_list,
+                                                    out_filename=name_video,
+                                                    fps=fps, display=display)
+```
+
+**Video generated**
+
+The generated video is saved automatically in the user-specified directory name_video. The user defined directory must already exist. The generated video should look similar to the one below:
+<iframe src="https://player.vimeo.com/video/436453444" width="640" height="640" frameborder="0" allow="autoplay; fullscreen" allowfullscreen></iframe>
+
+
+**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/master/plantcv/plantcv/visualize/time_lapse_video.py)

mkdocs.yml

@@ -183,6 +183,7 @@ nav:
           - 'Object Sizes': visualize_obj_sizes.md
           - 'Pixel Scatter Plot': 'visualize_pixel_scatter_vis.md'
           - 'Pseudocolor': visualize_pseudocolor.md
+          - 'Time Lapse Video': visualize_time_lapse_video.md
       - 'Watershed Segmentation': watershed.md
       - 'White balance': white_balance.md
       - 'Within Frame': within_frame.md

plantcv/plantcv/__init__.py

@@ -12,6 +12,7 @@
 outputs = Outputs()
 
 from plantcv.plantcv.deprecation_warning import deprecation_warning
+from plantcv.plantcv.warn import warn
 from plantcv.plantcv.print_image import print_image
 from plantcv.plantcv.plot_image import plot_image
 from plantcv.plantcv.color_palette import color_palette

plantcv/plantcv/deprecation_warning.py

@@ -4,6 +4,7 @@
 from plantcv.plantcv import _version
 from plantcv.plantcv import params
 
+
 def deprecation_warning(warning):
     """Print out deprecation warning
 

plantcv/plantcv/visualize/__init__.py

@@ -6,11 +6,12 @@
 from plantcv.plantcv.visualize.auto_threshold_methods import auto_threshold_methods
 from plantcv.plantcv.visualize.overlay_two_imgs import overlay_two_imgs
 from plantcv.plantcv.visualize.colorize_label_img import colorize_label_img
+from plantcv.plantcv.visualize.time_lapse_video import time_lapse_video
 from plantcv.plantcv.visualize.obj_sizes import obj_sizes
 from plantcv.plantcv.visualize.obj_size_ecdf import obj_size_ecdf
 from plantcv.plantcv.visualize.hyper_histogram import hyper_histogram
 from plantcv.plantcv.visualize.pixel_scatter_vis import pixel_scatter_plot
 
 __all__ = ["pseudocolor", "colorize_masks", "histogram", "clustered_contours", "colorspaces", "auto_threshold_methods",
            "overlay_two_imgs", "colorize_label_img", "obj_size_ecdf", "obj_sizes", "hyper_histogram",
-           "pixel_scatter_plot"]
+           "pixel_scatter_plot", "time_lapse_video"]

plantcv/plantcv/visualize/overlay_two_imgs.py

@@ -1,11 +1,5 @@
 # Overlay two input images
 
-"""
-Created on Tue. September 01 21:00:01 2020
-A function
-@author: hudanyunsheng
-"""
-
 import os
 import cv2
 import numpy as np

plantcv/plantcv/visualize/time_lapse_video.py

@@ -0,0 +1,70 @@
+# Create time-lapse videos with input directory of images
+
+import os
+import cv2
+import numpy as np
+from plantcv.plantcv import params
+from plantcv.plantcv import fatal_error
+from plantcv.plantcv.transform import resize
+# import warnings
+from plantcv.plantcv import warn
+
+
+def time_lapse_video(img_list, out_filename='./time_lapse_video.mp4', fps=29.97, display=True):
+    """Generate time-lapse video given a list of paths to the images
+
+    Inputs:
+    img_list       = the desired list of paths to the images to create the video
+    out_filename   = name of file to save the generated video to
+    fps            = frame rate (frames per second)
+    display        = if True (default), displays the path to the generated video
+
+    Outputs:
+    frame_size     = the frame size of the generated video
+
+    :param img_list: list
+    :param fps: float
+    :param out_filename: string
+    :param display: boolean
+    :return frame_size: tuple
+    """
+    # debug = params.debug
+    params.debug = None
+
+    if len(img_list) <= 0:
+        fatal_error("Image list is empty")
+
+    imgs = []
+    list_r = []
+    list_c = []
+    for file in img_list:
+        img = cv2.imread(file)
+        if img is None:
+            fatal_error(f"Unable to read {file}")
+        list_r.append(img.shape[0])
+        list_c.append(img.shape[1])
+        imgs.append(img)
+    max_c, max_r = np.max(list_c), np.max(list_r)
+
+    # use the largest size of the images as the frame size
+    # frame_size = frame_size or (max_c, max_r)
+    frame_size = (max_c, max_r)
+
+    if not (len(np.unique(list_r)) == 1 and len(np.unique(list_c)) == 1):
+        warn("The sizes of images are not the same, an image resizing (cropping or zero-padding) will be done "
+             f"to make all images the same size ({frame_size[0]}x{frame_size[1]}) before creating the video! ")
+
+    out_path, _ = os.path.splitext(out_filename)
+    out_filename = out_path + '.mp4'
+
+    fourcc = cv2.VideoWriter_fourcc(*'mp4v')  # Be sure to use lower case
+    out = cv2.VideoWriter(out_filename, fourcc, fps, frame_size)
+
+    for img in imgs:
+        out.write(resize(img, frame_size, interpolation=None))
+    out.release()
+    cv2.destroyAllWindows()
+    if display is True:
+        print(f'Path to generated video: \n{out_filename}')
+
+    return frame_size

plantcv/plantcv/warn.py

@@ -0,0 +1,14 @@
+# Warnings handling
+
+import sys
+
+
+def warn(warning):
+    """Print out warning message
+
+    Inputs:
+    warning = warning message text
+
+    :param warning: str
+    """
+    print(f"Warning: {warning}", file=sys.stderr)

tests/plantcv/visualize/test_time_lapse_video.py

@@ -0,0 +1,53 @@
+import pytest
+import os
+import cv2
+import numpy as np
+
+from plantcv.plantcv.visualize.time_lapse_video import time_lapse_video
+
+@pytest.mark.parametrize("display",[False,True])
+def test_plantcv_visualize_time_lapse_video_passes(display, tmpdir):
+    """Test for PlantCV."""
+    # Generate 3 test images and saved in tmpdir
+    list_im = []
+    for i in range(3):
+        temp_img = np.random.rand(3,3)
+        min_, max_ = np.nanmin(temp_img), np.nanmax(temp_img)
+        temp_img = np.interp(temp_img, (min_, max_), (0, 255)).astype('uint8')
+        img_i_path = os.path.join(tmpdir, f"img{i}.png")
+        cv2.imwrite(img_i_path, temp_img)
+        list_im.append(img_i_path)
+
+    # list_im = [os.path.join(tmpdir, img) for img in os.listdir(tmpdir) if img.endswith('.png')]
+
+    vid_name = os.path.join(tmpdir, 'test_time_lapse_video.mp4')
+    _ = time_lapse_video(img_list=list_im, out_filename=vid_name, fps=29.97, display=display)
+    assert os.path.exists(vid_name)
+
+@pytest.mark.parametrize("list_im_f",
+                         [([]),    # empty list
+                         (['./this_img_does_not_exist.png'])])  # non existent image
+def test_plantcv_visualize_time_lapse_video_errors(list_im_f, tmpdir):
+    """Test for PlantCV."""
+    with pytest.raises(RuntimeError):
+        _ = time_lapse_video(img_list=list_im_f, fps=29.97)
+
+
+# not all images have the same size (essential to generate a video)
+def test_plantcv_visualize_time_lapse_video_different_img_sizes_warns(tmpdir, capsys):
+    """Test for PlantCV."""
+    # Generate 3 test images of different size and save in tmpdir
+    list_im = []
+    for i in range(2):
+        temp_img = np.random.rand(i+2, 3)
+        min_, max_ = np.nanmin(temp_img), np.nanmax(temp_img)
+        temp_img = np.interp(temp_img, (min_, max_), (0, 255)).astype('uint8')
+        img_i_path = os.path.join(tmpdir, f"img{i}.png")
+        cv2.imwrite(img_i_path, temp_img)
+        list_im.append(img_i_path)
+
+    vid_name = os.path.join(tmpdir, 'test_time_lapse_video.mp4')
+    _ = time_lapse_video(img_list=list_im, out_filename=vid_name, fps=29.97, display=True)
+    _, err = capsys.readouterr()
+
+    assert "Warning" in err and os.path.exists(vid_name)