version 0.2.2.dev0-alpha.1

.gitignore

@@ -43,3 +43,8 @@ tags
 *.pth
 dev_settings.py
 out.mp4
+
+# win10
+win10_include_files
+butterflow.lnk
+init.bat

README.md

@@ -19,15 +19,15 @@ In this example, BF has slowed down a `1s` video down by `10x`. An additional `2
 
 Here is another example of the same concept. Opening the Butterflow'd video and frame-stepping through it would make the interpolated frames (marked "`Int: Y`") more obvious.
 
-## How to install
+## How to install:
 **Important:** Only works on 64-bit systems.
 
 * **Mac OS X:** With [Homebrew](http://brew.sh/), `brew install homebrew/science/butterflow`.
+* **Windows (Portable)**: Download [butterflow-0.2.2.dev0-alpha.1.7z](http://srv.dthpham.me/butterflow/releases/win/butterflow-0.2.2.dev0-alpha.1.7z). See: [How to use it](https://github.com/dthpham/butterflow/blob/master/docs/Install-On-Windows-Guide.md#how-to-use-it).
 * **Arch Linux:** A package is available in the AUR under [`butterflow`](https://aur.archlinux.org/packages/butterflow/).
-* **From Source (Ubuntu and Debian):** Refer to the [Install From Source Guide](https://github.com/dthpham/butterflow/blob/master/docs/Install-From-Source-Guide.md) for instructions.
-* **Windows:** See the [Install on Windows Guide](https://github.com/dthpham/butterflow/blob/master/docs/Install-On-Windows-Guide.md).
+* **From Source (Ubuntu, Debian):** Refer to the [Install From Source Guide](https://github.com/dthpham/butterflow/blob/master/docs/Install-From-Source-Guide.md) for instructions.
 
-## Setup (Recommended)
+## Setup (recommended)
 **Tip:** No setup is necessary on OS X. Read [this](https://github.com/dthpham/butterflow/blob/master/docs/Setting-Up-OpenCL.md#os-x-mavericks-and-newer) if you run into a problem w/ OpenCL.
 
 Butterflow requires no additional setup to use, however it's too slow out of the box to do any serious work. It's recommended that you set up a functional OpenCL environment on your machine to take advantage of hardware accelerated methods that will make rendering significantly faster.

butterflow/__init__.py

@@ -1 +1 @@
-__version__ = '0.2.1'
+__version__ = '0.2.2.dev0'

butterflow/__main__.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python2
+
+if __name__ == '__main__':
+    import sys
+    from butterflow.cli import main
+    sys.exit(main())

butterflow/cli.py

@@ -58,7 +58,7 @@ def main():
 
     vid.add_argument('-o', '--output-path', type=str,
                      default=settings['out_path'],
-                     help='Specify path to the .mp4 output video')
+                     help='Specify path to the output video')
     vid.add_argument('-r', '--playback-rate', type=str,
                      help='Specify the playback rate as an integer or a float '
                      'Fractional forms are acceptable, e.g., 24/1.001 is the '
@@ -188,7 +188,7 @@ def main():
 
     extension = os.path.splitext(os.path.basename(args.output_path))[1].lower()
     if extension[1:] != 'mp4':
-        print('out file needs .mp4 extension')
+        print('bad out file extension')
         return 0
 
     av_info = avinfo.get_av_info(args.video)
@@ -232,7 +232,7 @@ def optflow_fn(x, y,
         rate = rate_from_input_str(args.playback_rate, av_info['rate'])
     except (ValueError, AttributeError) as error:
         print('error: '+str(error))
-        exit(1)
+        return 1
 
     def nearest_even_int(x):
         return x & ~1

docs/Example-Usage.md

@@ -1,15 +1,15 @@
 # Example Usage
 **Tip:** Run `butterflow -h` for a full list of options and their default values.
 
-## Typical commands that most will use
+## Typical commands that will be used
 
 ### Altering the frame rate:
 #### Examples:
 * Double a video's frame rate with `butterflow -r 2x <VIDEO>`.
- * `-r` sets the playback rate and will still apply across all subregions if you use `-s`.
+ * `-r` sets the playback rate and will still apply across all subregions even if you use `-s`.
  * `3x` would triple the frame rate, etc.
 * Set a video's frame rate to 60fps with `butterflow -r 60 <VIDEO>`.
-* Set a frame rate with fractions `butterflow -r 24/1.001 <VIDEO>`.
+* Set a frame rate with fractions: `butterflow -r 24/1.001 <VIDEO>`.
  * This is equivalent to using 23.976.
 
 In general, frames will be interpolated if the rate is increased, otherwise they will be dropped.
@@ -22,6 +22,8 @@ In general, frames will be interpolated if the rate is increased, otherwise they
  * `spd` is what we're targeting in the region.
  * Since the frame rate is unchanged, this would produce a video with 4x more frames, all interpolated.
 * Set a video's duration to be 8s long with `butterflow -s full,dur=8 <VIDEO>`.
+* Create 200 frames for every 1s of video with `butterflow -s full,fps=200 <VIDEO>`.
+ * `fps` is different from `-r`, which sets the overall playback rate.
 
 In most cases, slowing a video down/extending it's duration will cause frames to be interpolated, otherwise they will be dropped.
 
@@ -36,9 +38,9 @@ In most cases, slowing a video down/extending it's duration will cause frames to
  * The `end` keyword signifies "to the end of the video".
  * This command is the same as `butterflow -s full,spd=0.9`.
 
-**Tip:** Rendering will be faster if you're working on smaller regions so use `-s` on small segments of a video if you need to do quick tests.
+**Tip:** Rendering will be faster if you're working on smaller regions so use `-s` on small segments of a video if you need to do quick tests. Scaling the video down with `-vs` is another way to speed up rendering.
 
-**Tip:** The `-k` option will render regions that are not explicitly specified into the output video at 1x speed (unaltered, the playback rate still applies to these regions).
+**Tip:** The `-k` option will render regions that are not explicitly specified into the output video at 1x speed (the playback rate still applies across these regions).
 
 ### Multiple regions:
 Separate regions with a colon `:`.
@@ -50,6 +52,4 @@ Separate regions with a colon `:`.
 ## Robustness of image
 Butterflow uses the Farneback algorithm to compute dense optical flows for frame interpolation. You can pass in different values to the function to fine-tune the quality (robustness of image) of the resulting videos.
 
-Run `butterflow -h` for a list of advanced options and their default values.
-
 **Tip:** Use the `-sm` flag if having artifact-less frames is a priority. This will tune settings to emphasize blending frames over the default behavior of warping pixels.

docs/Install-FFmpeg-On-Debian-Guide.md

@@ -1,5 +1,6 @@
 # Install FFmpeg on Debian Guide
 
+## Instructions:
 1. Add `deb http://www.deb-multimedia.org jessie main non-free` and `deb-src http://www.deb-multimedia.org jessie main non-free` to the bottom of `/etc/apt/sources.list`.
 2. Update your package list with `sudo apt-get update`.
 3. Update your keyring with `sudo apt-get install deb-multimedia-keyring`.
@@ -10,4 +11,4 @@
 8. Configure it with `./configure --enable-gpl --enable-postproc --enable-swscale --enable-avfilter --enable-libmp3lame --enable-libvorbis --enable-libtheora --enable-libx264 --enable-libspeex --enable-shared --enable-pthreads --enable-libopenjpeg --enable-libfaac --enable-nonfree`.
 9. Build it with `make`.
 10. Install it with `sudo make install`.
- * This is going to install FFmpeg into `/usr/local`, which is the optimal location for packages built by the user.
+ * This will install FFmpeg into /usr/local.

docs/Install-From-Source-Guide.md

@@ -1,72 +1,52 @@
 # Install From Source Guide
-**Important:** Read [What to do when you're done](#what-to-do-when-youre-done-installing) after installing.
 
 ## Supported platforms
-**Important:** Butterflow only works on 64-bit systems.
+**Important:** BF only works on 64-bit systems.
 
-Butterflow has been successfully built and tested on several platforms, including OS X 10.11 (El Capitan), Windows 10, Ubuntu 15.04 (Vivid Vervet), Debian 8.2 (Jessie), and Arch Linux. Getting Butterflow to work on other Linux distributions *may* be possible, but expect any kind of support to be limited.
+Butterflow has been successfully built and tested on OS X 10.11 (El Capitan), Windows 10, Ubuntu 15.04 (Vivid Vervet), Debian 8.2 (Jessie), and Arch Linux. Getting BF to work on other Linux distributions *may* be possible, but expect any kind of support to be limited.
 
 ## Instructions
-### Windows 10:
-See the [Install on Windows Guide](Install-On-Windows-Guide.md).
 
-### OS X (El Capitan):
-These instructions will show you how to compile Butterflow using OS X's pre-installed Python. At minimum, you will need to have OS X Mavericks installed.
-
-1. Install dependencies with [Homebrew](http://brew.sh/) with `brew install ffmpeg` and `brew install homebrew/science/opencv --with-ffmpeg`.
- * **Optional:** You can build opencv `--with-opengl` to use OpenGL windows.
-2. Install packages that will be used to set up a virtual environment with `sudo easy_install pip`, then `pip install virtualenv`.
-3. Clone the butterflow repo with `git clone https://github.com/dthpham/butterflow.git`.
-4. Create a virtual environment using the system's python with `virtualenv -p /usr/bin/python butterflow`.
-5. Change into the project directory and activate the virtualenv with `source bin/activate`.
-6. Pick up the cv2.so module with `echo "$(brew --prefix)/lib/python2.7/site-packages" > lib/python2.7/site-packages/butterflow.pth`.
- * **Alternative:** You can add Homebrew's Python site-packages to your PYTHONPATH with `export PYTHONPATH=$PYTHONPATH:$(brew --prefix)/lib/python2.7/site-packages`. Adding an export to your ~/.profile will save you the trouble of having to set this every time you activate the virtual environment.
-7. [Install it](#installing-it).
-
-#### Search paths
-You may have to manually add `/usr/local/lib` and `/usr/local/include` to your search paths to pick up some headers and libraries. If you're using Xcode's clang, it will only search OS X SDK paths. You should install the Xcode Command Line tools with `xcode-select --install` to get a version that searches `/usr/local` by default.
-
-### Ubuntu (Vivid Vervet):
-1. Install dependencies with `sudo apt-get install git virtualenv python-dev ocl-icd-opencl-dev libopencv-dev python-opencv ffmpeg`.
-2. [Set up the project folder](#setting-up-the-project-folder).
-3. [Install it](#installing-it).
-
-**Side note:** The Vivid Vervet version of Ubuntu brings back support for FFmpeg, installing Butterflow will be more difficult on older versions of Ubuntu because that package is not readily available.
-
-### Debian (Jessie):
-1. Install FFmpeg using the [Install FFmpeg on Debian Guide](Install-FFmpeg-On-Debian-Guide.md).
-2. Install other dependencies with `sudo apt-get install build-essential git python-virtualenv python-dev python-setuptools libopencv-dev python-opencv ocl-icd-opencl-dev libgl1-mesa-dev x264`
-3. [Set up the project folder](#setting-up-the-project-folder).
-4. [Install it](#installing-it).
-
-### Arch Linux:
-1. Install dependencies with `sudo pacman -S git python2-setuptools python2-virtualenv python2-numpy ocl-icd opencl-headers ffmpeg`
-2. Install the [opencv2](https://aur.archlinux.org/packages/opencv2/) package from the AUR.
- * **Tip:** Remove all packages that depend on opencv, like opencv-samples, before installing opencv2. This will save you the trouble of re-compiling the package, which takes a long time, if the install fails.
-3. [Set up the project folder](#setting-up-the-project-folder).
-4. [Install it](#installing-it).
-
-## Setting up the project folder
-1. Clone the project repo with `git clone https://github.com/dthpham/butterflow.git`.
-2. Create a virtual environment with `virtualenv -p /usr/bin/python2 butterflow`.
-3. Change into the project directory and activate the virtualenv with `source bin/activate`.
-4. Add a path configuration file
- * Ubuntu or Debian: `echo "/usr/lib/python2.7/dist-packages" > lib/python2.7/site-packages/butterflow.pth`. **Side note:** dist-packages is a Debian-specific convention that is present in all derivative distros (Ubuntu, Mint, etc.).
- * Arch Linux: `echo "/usr/lib/python2.7/site-packages/" > lib/python2.7/site-packages/butterflow.pth`.
-
-## Installing it
-4. If you intend to edit the source code:
-  * Create a development version with `python setup.py develop`.
-  * The development version will let you edit the source code and see the changes directly *without* having to reinstall everytime.
-  * You will have to be inside a virtualenv to use butterflow if you used one. On Windows 10, you should be able to use butterflow system-wide without having to activate one everytime.
-  * **Tip:** Uninstall with `python setup.py develop -u`.
-5. If you're going to use the package without making changes:
-  * Exit any virtualenv virtual environment you are in first with `deactivate`.
-  * Install with `python setup.py install`.
-  * **Tip:** Uninstall with `pip2 uninstall butterflow`.
-
-## What to do when you're done installing
-1. **Recommended:** Check if your OpenCL device is detected with `buutterflow -d`.
+**Important:** Windows users, refer to the [Install on Windows Guide](Install-On-Windows-Guide.md#install-from-source).
+
+### Compile and install Butterflow:
+1. Install dependencies:
+  * **OS X:**
+    1. Install with [Homebrew](http://brew.sh/), `brew install ffmpeg` and `brew install homebrew/science/opencv --with-ffmpeg --with-opengl`.
+    2. Install packages that will be used to set up a virtual environment with `sudo easy_install pip`, then `pip install virtualenv`.
+  * **Arch Linux:**
+    1. Install with `sudo pacman -S git python2-setuptools python2-virtualenv python2-numpy ocl-icd opencl-headers ffmpeg`.
+    2. Install the [opencv2](https://aur.archlinux.org/packages/opencv2/) package from the AUR.
+      * **Tip:** Remove all packages that depend on opencv, like opencv-samples, before installing opencv2. This will save you the trouble of re-compiling the package, which takes a long time, if the install fails.
+  * **Ubuntu:** Install with `sudo apt-get install git virtualenv python-dev ocl-icd-opencl-dev libopencv-dev python-opencv ffmpeg`.
+  * **Debian:**
+      1. Install FFmpeg (See: [Install FFmpeg on Debian Guide](Install-FFmpeg-On-Debian-Guide.md)).
+      2. Install other dependencies with `sudo apt-get install build-essential git python-virtualenv python-dev python-setuptools libopencv-dev python-opencv ocl-icd-opencl-dev libgl1-mesa-dev x264`.
+2. Clone the project repo with `git clone https://github.com/dthpham/butterflow.git`.
+3. Create a virtual environment:
+  * **OS X (using the system's python):** `virtualenv -p /usr/bin/python butterflow`.
+  * **Linux:** `virtualenv -p /usr/bin/python2 butterflow`.
+4. Change into the project directory and activate the virtualenv with `source bin/activate`.
+5. Add a path configuration file:
+  * **OS X:** Pick up the cv2.so module with `echo "$(brew --prefix)/lib/python2.7/site-packages" > lib/python2.7/site-packages/butterflow.pth`.
+    * **Alternative:** You can add Homebrew's Python site-packages to your PYTHONPATH with `export PYTHONPATH=$PYTHONPATH:$(brew --prefix)/lib/python2.7/site-packages`. Adding an export to your ~/.profile will save you the trouble of having to set this every time you activate the virtual environment.
+    * **Important:** You may have to manually add /usr/local/lib and /usr/local/include to your search paths to pick up some headers and libraries. If you're using Xcode's clang, it will only search OS X SDK paths. You should install the Xcode Command Line tools with `xcode-select --install` to get a version that searches /usr/local by default.
+  * **Arch Linux:** `echo "/usr/lib/python2.7/site-packages/" > lib/python2.7/site-packages/butterflow.pth`.
+  * **Ubuntu or Debian:** `echo "/usr/lib/python2.7/dist-packages" > lib/python2.7/site-packages/butterflow.pth`.
+    * **Side note:** dist-packages is a Debian-specific convention that is present in all derivative distros (Ubuntu, Mint, etc.).
+6. Install it:
+  * If you intend to edit the source code:
+    * Create a development version with `python setup.py develop`.
+    * **Tip:** Uninstall with `python setup.py develop -u`.
+    * The development version will let you edit the source code and see the changes directly *without* having to reinstall everytime.
+    * You must be inside a virtualenv to use butterflow if you used one (activate with `source bin/activate`).
+  * If you're using the package without making changes:
+    * Exit any virtualenv virtual environment you are in with `deactivate`.
+    * Install with `python setup.py install`.
+    * **Tip:** Uninstall with `pip2 uninstall butterflow`.
+
+## What to do when you're done
+* **Recommended:** Check if your OpenCL device is detected with `buutterflow -d`.
  * If it isn't, refer to [Setting up OpenCL](Setting-Up-OpenCL.md) for instructions on how to get it working. This step isn't required but when working on large segments of a video or with high resolution frames, rendering will be extremely slow without it.
-2. **Optional:** While in the project directory, you can run a suite of tests against butterflow with `python setup.py test`.
+* **Optional:** While in the project directory, you can run a suite of tests against butterflow with `python setup.py test`.
  * Tests will fail if OpenCL isn't set up.