Skip to content
This repository has been archived by the owner on Aug 16, 2023. It is now read-only.

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@dthpham
dthpham committed Feb 2, 2016
1 parent 1dd8a35 commit 1c3290a
Show file tree
Hide file tree
Showing 4 changed files with 70 additions and 61 deletions.
34 changes: 16 additions & 18 deletions README.md
View file
Expand Up @@ -4,30 +4,27 @@ motion and motion interpolated videos.

## How does it work?
It works by rendering intermediate frames between existing frames. For example,
given two existing frames `A` and `B`, this program can generate frames `C.1`,
given two existing frames, `A` and `B`, this program can generate frames `C.1`,
`C.2`...`C.n` that are positioned between the two. This process, called
[motion interpolation](http://en.wikipedia.org/wiki/Motion_interpolation),
increases frame rates and can give the perception of smoother motion and more
fluid animation, an effect most people know as the "soap opera effect".
Butterflow takes advantage of this increase in frame rates to make high speed
and slow motion videos with minimal judder.
Butterflow takes advantage of newly-available frames to make high speed, slow
motion videos with minimal judder.

![](http://srv.dthpham.me/static/ink.gif)

In this example, Butterflow has slowed down a `1s` video down by `10x`. An
additional `270` frames were interpolated from `30` original source frames
additional `270` frames were interpolated from `30` original source frames,
giving the video a smooth feel during playback. The same video was slowed down
with FFmpeg alone, but because it dupes frames and can't interpolate new ones
the video has a noticeable stutter.
with FFmpeg alone (shown on the right-hand side), but because it dupes frames
and can't interpolate new ones, the video has a noticeable stutter.

![](http://srv.dthpham.me/static/blow.gif)

Here is another example of the same concept. Interpolated frames between
source frames are marked `Int: Y`. Opening the Butterflow'd video and
frame-stepping through it would make the interpolated frames more obvious.

See the [In Action](https://github.com/dthpham/butterflow/blob/master/docs/In-Action.md)
page for more demonstrations.
Here is another example of the same concept. Interpolated frames between source
frames are marked `Int: Y`. Opening the Butterflow'd video and frame-stepping
through it would make the interpolated frames more obvious.

## Installing
### Mac OS X:
Expand All @@ -42,17 +39,15 @@ A package is available in the AUR under
[`butterflow`](https://aur.archlinux.org/packages/butterflow/).

### From Source:
This is the only way to install Butterflow on Ubuntu, Debian, and Windows.

Refer to the
[Install From Source Guide](https://github.com/dthpham/butterflow/blob/master/docs/Install-From-Source-Guide.md)
for instructions.

## Setup
Butterflow requires no additional setup to use but it's too slow out of the box
to do any serious work so you're expected to set up a functional OpenCL
environment on your machine to take advantage of hardware accelerated methods
that will make rendering significantly faster.
Butterflow requires no additional setup to use, but it's too slow out of the box
to do any serious work, so you need to set up a functional OpenCL environment on
your machine to take advantage of hardware accelerated methods that will make
rendering significantly faster.

See [Setting up OpenCL](https://github.com/dthpham/butterflow/blob/master/docs/Setting-Up-OpenCL.md)
for details on how to do this.
Expand All @@ -62,3 +57,6 @@ Run `butterflow -h` for a full list of options and their default values.

See [Example Usage](https://github.com/dthpham/butterflow/blob/master/docs/Example-Usage.md)
for typical commands.

## More documentation
Check the [docs folder](https://github.com/dthpham/butterflow/tree/master/docs#readme).
51 changes: 31 additions & 20 deletions docs/Example-Usage.md
View file
@@ -1,64 +1,75 @@
# Example Usage
Run `butterflow -h` for a full list of options and their default values.

## Interpolation
## Typical commands that you will use
### Frame interpolation
Double the frame rate:

```
butterflow -sm -r 2x [video]
butterflow -r 2x [video]
```

Increase a video's frame rate to 96fps:
Set a video's frame rate to 96fps:

```
butterflow -sm -r 96 [video]
butterflow -r 96 [video]
```

## Slow motion
Use the `-sm`, `--smooth-motion` flag if having artifact-less frames is a
priority. This will tune settings to emphasize blending frames over warping
pixels, which is the default behavior.

### Altering speed and duration
Slow-mo a video to 0.25x speed:

```
butterflow -s full,spd=0.25 [video]
```

Slow-mo a video to be 30s long:
Set a video's duration to be 30s long:

```
butterflow -s full,dur=30 [video]
```

## Working on a single region
Slow-mo a 1s region by 0.5x speed:
This will speed up or slow down the video depending on it's original duration.

### Working on one region
Slow-mo a 1s region to 0.5x speed:

```
butterflow -s a=5,b=6,spd=0.5 [video]
butterflow -t -s a=5,b=6,spd=0.5 [video]
```

Slowmo a 0.5s region to be 3s long:
The `-t`, `--trim-regions` option will discard all regions that are not
explicitly specified. Keep in mind, rendering will be faster if you're working
on smaller regions, so this flag will be useful if you need to do quick tests.

```
butterflow -s a=1.5,b=2,dur=3 [video]
```
### Multiple regions
Separate regions with a colon `:`.

## Multiple regions
With two regions:

```
butterflow -s a=1,b=2,spd=0.5:a=9,b=end,spd=0.5 [video]
butterflow -t -s a=1,b=2,spd=0.5:a=9,b=end,spd=0.5 [video]
```

With four regions:

```
butterflow -s \
a=4.2,b=6,spd=0.125:\
butterflow -t -s \
a=0,b=6,spd=0.125:\
a=6,b=6.8,dur=3:\
a=6.8,b=7,dur=0.4:\
a=20,b=end,fps=200 [video]
```

## Quality
## Using fractions
You can use fractions for rates, e.g., `30/1.001` is equivalent to 29.97fps.

## 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.
quality (robustness of image) of the resulting videos.

Run `butterflow -h` for a list of advanced options and their default values.
38 changes: 19 additions & 19 deletions docs/Install-From-Source-Guide.md
View file
@@ -1,10 +1,12 @@
# Install From Source Guide

## Supported platforms
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 support to be limited.
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 support to be limited.

## Instructions
### OS X (El Capitan)
Expand All @@ -26,7 +28,7 @@ sudo easy_install pip
pip install virtualenv
```

Finally build and install a development version of Butterflow.
Finally, build and install a development version of Butterflow.

```
git clone https://github.com/dthpham/butterflow.git
Expand All @@ -36,7 +38,7 @@ source bin/activate
# Pick up the cv2.so module
echo "$(brew --prefix)/lib/python2.7/site-packages" > lib/python2.7/site-packages/butterflow.pth
# Alternatively, you can add Homebrew's Python site-packages to your
# PYTHONPATH. Adding an expoert to your ~/.profile will save you the trouble of
# PYTHONPATH. Adding an exxport to your ~/.profile will save you the trouble of
# having to set this every time you activate the virtual environment:
# export PYTHONPATH=$PYTHONPATH:$(brew --prefix)/lib/python2.7/site-packages
python setup.py develop
Expand All @@ -51,9 +53,9 @@ Line tools with `xcode-select --install` to get a version that searches

### Ubuntu (Vivid Vervet)
These instructions will show you how to get Butterflow working in Ubuntu 15.04
(Vivid Vervet). This version of Ubuntu brings back support for FFmpeg.
Installing Butterflow is more difficult on older versions of Ubuntu because
FFmpeg is not readily available.
(Vivid Vervet). This version of Ubuntu brings back support for FFmpeg,
installing Butterflow is more difficult on older versions of Ubuntu because
it's not readily available.

Begin by installing tools, development files, and a generic OpenCL library and
headers.
Expand All @@ -69,15 +71,13 @@ git clone https://github.com/dthpham/butterflow.git
virtualenv -p /usr/bin/python2 butterflow
cd butterflow
source bin/activate
# dist-packages is a Debian-specific convention that is present in
# derivative distros
# dist-packages is a Debian-specific convention that is present in derivative distros
echo "/usr/lib/python2.7/dist-packages" > lib/python2.7/site-packages/butterflow.pth
python setup.py develop
```

### Debian (Jessie)
Begin by installing FFmpeg. These instructions are adapted from this [guide](https://www.assetbank.co.uk/support/documentation/install/ffmpeg-debian-squeeze/ffmpeg-debian-jessie/).
This [gist](https://gist.github.com/holms/7009218) is a tad more comprehensive
Begin by installing FFmpeg. Note: these instructions are adapted from this [guide](https://www.assetbank.co.uk/support/documentation/install/ffmpeg-debian-squeeze/ffmpeg-debian-jessie/). This [gist](https://gist.github.com/holms/7009218) is a tad more comprehensive
and will show you how to make a package that you can manage with `apt-get`.

First add the multimedia source to the bottom of `/etc/apt/sources.list`.
Expand Down Expand Up @@ -105,7 +105,7 @@ Download the latest package of FFmpeg from their [releases](http://ffmpeg.org/re
page. Extract it to a folder, `cd` into it and run:

```
# This is going to install it into /usr/local
# This is going to install into /usr/local
./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
make
sudo make install
Expand Down Expand Up @@ -149,16 +149,16 @@ python setup.py develop
## What to do afterwards
### Enabling OpenCL acceleration
Refer to [Setting up OpenCL](Setting-up-OpenCL.md) for details on how to take
advantage of hardware acceleration through OpenCL. This step isn't mandatory but
it's one you are expected to take.
advantage of hardware acceleration through OpenCL. This step isn't mandatory,
but it's one you are expected to take.

### Testing
You can run a suite of tests against Butterflow to ensure everything is set up
properly with `python setup.py test` or just `nosetests` or `nosetests2` if you
properly with `python setup.py test`, or just `nosetests` or `nosetests2`, if you
have [nose](https://nose.readthedocs.org/en/latest/) installed. Tests will fail
if you don't have OpenCL set up.

### Installing outside of a virtualenv
To install Butterflow outside of a virtual environment, first exit your
virtualenv if you are in one with `deactivate` and then run
`python setup.py install`. To uninstall run `pip uninstall butterflow`.
virtualenv if you are in one with `deactivate`, then run
`python setup.py install`. To uninstall, run `pip uninstall butterflow`.
8 changes: 4 additions & 4 deletions docs/Setting-Up-OpenCL.md
View file
Expand Up @@ -23,7 +23,7 @@ If you encounter an error that you suspect is related to OpenCL, it may be
because you don't have a compatible graphics device. Double check to see if your
Mac is listed on Apple's [Mac computers that use OpenCL and OpenGL graphics](https://support.apple.com/en-us/HT202823)
support page and verify that it meets the minimum requirements outlined in the
[Requirements](#Requirements) section.
[Requirements](#general-requirements) section.

### Ubuntu (Vivid Vervet)
#### Nvidia
Expand All @@ -46,7 +46,7 @@ To do this, download the driver from the [AMD website](http://support.amd.com/en
We're going to use version 15.9 as an example
(`amd-catalyst-15.9-linux-installer-15.201.1151-x86.x86_64.zip`).

Extract the driver package to a folder. Launch a terminal and `cd` into it and
Extract the driver package to a folder. Launch a terminal, `cd` into it, and
run:

```
Expand Down Expand Up @@ -112,9 +112,9 @@ Just install a client driver:
```

## When you're done
When you're done setting up OpenCL you can run `butterflow -d` to print a list
When you're done setting up OpenCL, you can run `butterflow -d` to print a list
of detected devices.

Butterflow will always pick the fastest rendering method possible (it will
automatically switch to OpenCL if it detects you have a compatible device) but
automatically switch to OpenCL if it detects you have a compatible device), but
you can still force it to use software rendering with the `-sw` flag.

0 comments on commit 1c3290a

Please sign in to comment.