Make it more useable out of the box

README.md

@@ -1,51 +1,83 @@
 # Video Gestalt
 
-[![gestalt-Vespa-Scooter-Commercial ia mp4][1]][3]
+[![gestalt-Vespa-Scooter-Commercial ia mp4][1]][2]
 
 Presents a video in a summary form that shows the entire video at once as an array of moving video thumbnails.
 
+## Description
+
+Video Gestalt presents a condensed video array, showing the entire video at once as moving video thumbnails.
+
+The above is an example of the Video Gestalt for a 50-second commercial for Vesta scooters. (Click the Video Gestalt to see the original video.)
+
+As you can see, it is a looping video with moving thumbnails of the original video. In one second, you can see every frame of the original video at a glance, without any discontinuities as it loops. This is done by arranging that each thumbnail slides over exactly its width in one loop so that the next thumbnail takes over seamlessly.
+
+Hence, the video gestalts can be read in two ways: 1- an overall quick glance shows all the scenes of the entire video, 2- by focusing on one animated thumbnail, we can watch the entire video, by starting in the upper left corner, and following to the right, then descending one block lower and moving from right to left, then descending one block and moving left to right again, etc.
+
+A longer explanation is available in [this blog post](https://eamonn.org/video-gestalt-one-glance-overview-of-a-video).
+
 ## Installation
 
-So far this has only been tested on Linux and Chrome OS, but it will likely work on MacOS too, and maybe even on Windows.
+So far this has been tested on Linux, Chrome OS and Windows, but it will likely work on MacOS too.
 
-The only file you need from this repo is `gestalt.py`. You can grab this however you want, and make it executable. For example, do the following from the command line:
+To install, simply use `pip`:
 
 ```bash
-wget https://raw.githubusercontent.com/eobrain/videogestalt/main/gestalt.py
-chmod +x gestalt.py
+pip install --upgrade videogestalt
 ```
 
-If they are not already installed, you will need to install `python3` and the corresponding Python package manager `pip`.
-
+If they are not already installed, you will need to install `python3` and the corresponding Python package manager `pip` beforehand.
 
 On Linux and friends you might be able to do this like so:
 ```bash
 sudo apt-get install python3 python3-pip
 ```
 
-You will need to install the `moviepy` Python library:
+## Usage
+
+An executable binary `videogestalt` is automatically installed in the local environment.
+
+The following examples assume you cloned the repository to get access to the `example` folder.
+
+To generate a video file:
+
+```bash
+videogestalt -i example/test.mp4 -o test-gestalt --video
+```
+
+To generate an animated GIF (warning, output can be large):
 
 ```bash
-pip install moviepy
+videogestalt -i example/test.mp4 -o test-gestalt --gif
 ```
 
+The application can also be used as a Python module:
 
-## Usage
+```python
+>>> from videogestalt import videogestalt as vg
+>>> vg.main('-i example/test.mp4 -o test-gestalt --gif')
+```
 
-Put the `gestalt.py` in the same directory as an input video file `test.mp4`.
+## Building
 
-Generate a video file:
+The module can be built with PEP517 standard tools, such as `pypa/build`:
 
 ```bash
-./gestalt.py -i test.mp4 -v
+python -sBm build .
 ```
 
-Generate an animated GIF (warning, can be large):
+It can also be installed in development/editable mode after cloning this git repository:
 
 ```bash
-./gestalt.py -i test.mp4 -g
+pip install --upgrade -e .
 ```
 
-[1]: https://user-images.githubusercontent.com/179320/226146985-d67db97e-bcd6-4377-a1da-cc6020135d84.gif
-[3]: https://ia904607.us.archive.org/11/items/vespa-scooter-commercial/Vespa%20Scooter%20Commercial.mp4
+## License
+
+Created by Eamonn O'Brien-Strain.
+
+Licensed under the Mozilla Public License 2.0
+
+[1]: https://github.com/eobrain/videogestalt/master/resources/vespa-commercial-gestalt.gif
+[2]: https://ia904607.us.archive.org/11/items/vespa-scooter-commercial/Vespa%20Scooter%20Commercial.mp4
 

pyproject.toml

@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: MPL-2.0
+
+[build-system]
+# never uppercap requirements unless we have evidence it won't work https://iscinumpy.dev/post/bound-version-constraints/ 
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]  # beware if using setuptools: setup.py still gets executed, and even if pyproject.toml fields take precedence, if there is any code error in setup.py, building will fail!
+name = "videogestalt"
+version = "0.2.0"  # see PEP 440 https://peps.python.org/pep-0440/#pre-releases and https://packaging.python.org/en/latest/guides/single-sourcing-package-version/
+description = "Regular Expression Path Matcher - Easily batch manipulate folders and files trees with regular expression!"
+authors = [
+    {name = "Eamonn O'Brien-Strain"},
+    ]
+maintainers = [
+    {name = "Eamonn O'Brien-Strain"},
+    ]
+requires-python = ">=3.7"
+license = {text = "Mozilla Public License 2.0"} # { file = "LICENSE" }
+keywords = ["video", "gestalt", "movie", "summary", "summarization", "thumbnails"]
+classifiers = [
+    'Development Status :: 3 - Alpha',
+    'License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)',
+    'Environment :: Console',
+    'Operating System :: POSIX :: Linux',
+    'Operating System :: MacOS :: MacOS X',
+    'Operating System :: Microsoft :: Windows',
+    'Environment :: Console',
+    'Intended Audience :: Developers',
+    'Intended Audience :: End Users/Desktop',
+    'Intended Audience :: Information Technology',
+    'Intended Audience :: System Administrators',
+    'Programming Language :: Python',
+    'Programming Language :: Python :: 3',
+    'Programming Language :: Python :: 3.7',
+    'Programming Language :: Python :: 3.8',
+    'Programming Language :: Python :: 3.9',
+    'Programming Language :: Python :: 3.10',
+    'Programming Language :: Python :: 3.11',
+    'Programming Language :: Python :: 3.12',
+    'Topic :: Multimedia :: Video',
+    'Topic :: Multimedia :: Video :: Display',
+    'Topic :: Software Development :: Libraries',
+    'Topic :: Software Development :: Libraries :: Python Modules',
+    'Topic :: Utilities',
+]
+dependencies = [
+    "moviepy",
+]
+
+[project.urls]
+Homepage = "https://github.com/eobrain/videogestalt"
+Documentation = "https://github.com/eobrain/videogestalt/blob/master/README.md"
+"Source" = "https://github.com/eobrain/videogestalt"
+Tracker = "https://github.com/eobrain/videogestalt/issues"
+Download = "https://github.com/eobrain/videogestalt/releases"
+#Changelog = "https://url/changelog"
+
+[project.optional-dependencies]
+testmeta = [  # dependencies to test meta-data
+    "build",
+    "twine",
+    "validate-pyproject",
+    "rstcheck",
+]
+
+[project.readme]
+file = "README.md"
+content-type = "text/markdown"
+
+[project.scripts]
+videogestalt = "videogestalt.videogestalt:main"
+
+#[tool.setuptools]
+#package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+# IMPORTANT: systematically delete `src/<project.name>.egg-info` folder before rebuilding, otherwise the list of included files will not get updated (it's in `SOURCES.txt` file in this folder)
+where = ["src"]
+include = ["videogestalt*"]
+#namespaces = true  # already the default
+
+[tool.setuptools.package-data]
+# Check the <mypkg>.egg-info/SOURCES.txt file generated after a `build` or `pip install` to check if the following files are correctly included in the sdist.
+# Check also the list of files included by default: https://packaging.python.org/en/latest/guides/using-manifest-in/
+"*" = [
+    "LICENSE*",
+    "README*",
+]

gestalt.py → src/videogestalt/videogestalt.py

@@ -1,14 +1,20 @@
 #!/usr/bin/env python3
 
-
 # Author: Eamonn O'Brien-Strain
+# Contributors: Stephen Karl Larroque
 # License: Mozilla Public License Version 2.0
 # Description: Generates overview of video
-# Usage: python generate.py -h
+# Usage: python videogestalt.py -h
+
+import os
+import shlex
+import sys
+import time
 
+from argparse import ArgumentParser, ArgumentTypeError
 from math import sqrt, ceil
-from argparse import ArgumentParser
 from moviepy.editor import CompositeVideoClip, ImageClip, VideoFileClip, ColorClip
+from pathlib import Path
 
 OUTPUT_WIDTH = 1000
 MIN_SPEED_PIXELS_PER_FRAME = 2
@@ -19,12 +25,13 @@
 HEIGHT = 1
 
 
-def main(originalPath, generateGif, generateVideo):
+def gen_gestalt(originalPath, outputPath, generateGif, generateVideo):
+    '''Generate an animated gestalt image or video from a video'''
     print("Generating gestalt for %s" % originalPath)
     if (generateVideo):
-        print("Will generating video")
+        print("Will generate a video")
     if (generateGif):
-        print("Will generating GIF")
+        print("Will generate a GIF")
 
     original = VideoFileClip(originalPath, audio=False)
     minSpeedPixelsPerSec = MIN_SPEED_PIXELS_PER_FRAME*original.fps
@@ -104,29 +111,72 @@ def right(j):
     output = CompositeVideoClip(
         thumbs+lefts+rights+[leading, trailing], (extendeWidth, fullHeight))
 
+    # Write output
     if generateGif:
-        output.write_gif("gestalt-"+originalPath+".gif", program="ffmpeg")
-    if generateVideo:
-        output.write_videofile("gestalt-"+originalPath)
-
-
-if __name__ == "__main__":
-    import time
-
+        # to a gif file
+        output.write_gif("%s%s" % (outputPath, ".gif"), program="ffmpeg")
+    elif generateVideo:
+        # to a video file
+
+        # MoviePy requires a file extension to determine how to encode the output
+        # Hence, by default, if none is provided, reuse the input file extension
+        if (outputPath.find('.') < 0):  # no extension found
+            outputPath = "%s%s" % (outputPath, Path(originalPath).suffix)  # we append the input path file extension
+        output.write_videofile(outputPath)
+
+def is_dir_or_file(dirname):
+    '''Checks if a path is an actual directory that exists or a file'''
+    if not os.path.isdir(dirname) and not os.path.isfile(dirname):
+        msg = "{0} is not a directory nor a file".format(dirname)
+        raise ArgumentTypeError(msg)
+    else:
+        return dirname
+
+def fullpath(relpath):
+    '''Relative path to absolute'''
+    if (type(relpath) is object or hasattr(relpath, 'read')): # relpath is either an object or file-like, try to get its name
+        relpath = relpath.name
+    return os.path.abspath(os.path.expanduser(relpath))
+
+def main(argv=None):
+    '''Script entry point, can be used in commandline or as a Python module'''
+    # Allow to be used as a module or in commandline, by storing the commandline arguments in function argument argv if empty
+    if argv is None: # if argv is empty, fetch from the commandline
+        argv = sys.argv[1:]
+    elif isinstance(argv, str): # else if argv is supplied but it's a simple string, we need to parse it to a list of arguments before handing to argparse or any other argument parser
+        argv = shlex.split(argv) # Parse string just like argv using shlex
+
+    # Setup arguments parser
     parser = ArgumentParser(
         prog='gestalt.py',
         description='Generates overview of video',
         epilog='(c) Eamonn O\'Brien-Strain')
+
     parser.add_argument('-i', '--input', metavar='something.mp4',
+                        type=is_dir_or_file,
                         required=True,
                         help='input video file')
-    parser.add_argument('-g', '--gif', action='store_true',
+    parser.add_argument('-o', '--output', metavar='/some/folder/output.(gif|mp4)',
+                        type=str,
+                        required=True,
+                        help='output filepath')
+
+    mgroup = parser.add_mutually_exclusive_group(required=True)
+    mgroup.add_argument('-g', '--gif', action='store_true',
                         default=False,
                         help='generate GIF')
-    parser.add_argument('-v', '--video', action='store_true',
+    mgroup.add_argument('-v', '--video', action='store_true',
                         default=False,
                         help='generate video file')
-    args = parser.parse_args()
-    start_time = time.time()
-    main(args.input, args.gif, args.video)
-    print("--- %d seconds ---" % (time.time() - start_time))
+
+    # Parse arguments (either from commandline or function argument when used as a module)
+    args = parser.parse_args(argv)
+
+    # Generate the gestalt image
+    start_time = time.time()  # note this is not a reliable performance indicator, use time.process_time() instead
+    gen_gestalt(fullpath(args.input), fullpath(args.output), args.gif, args.video)
+    print("--- Total time spent: %d seconds ---" % (time.time() - start_time))
+
+# Commandline call
+if __name__ == "__main__":
+    main_entry()