Document 'accel_decel' FX properly; raise ValueError for invalid 'sooness' value

[mondeja]

This pull request improves accel_decel FX:

• Raises ValueError if sooness argument is invalid (when sooness < 0). Before this, a confusing ZeroDivisionError is raised.
• Adds proper documentation including the next image with grahps showing examples of different combination of arguments.

Matplotlib code

Before run this, you need to patch the function moviepy.video.fx.accel_decel._f_accel_decel adding two print statements:

def _f_accel_decel(t, old_duration, new_duration, abruptness=1.0, soonness=1.0):
    a = 1.0 + abruptness

    def _f(t):
        print("t", t)
        def f1(t):
            return (0.5) ** (1 - a) * (t ** a)

        def f2(t):
            return 1 - f1(1 - t)

        return (t < 0.5) * f1(t) + (t >= 0.5) * f2(t)

    response = old_duration * _f((t / new_duration) ** soonness)
    print(response)
    return response

After that, you can generate the graphs using Matplotlib:

import numpy as np
import matplotlib.pyplot as plt

from moviepy.video.io.VideoFileClip import VideoFileClip
from moviepy.video.fx.accel_decel import accel_decel

import io
from contextlib import redirect_stdout

kwargs_combinations = [
    [dict(abruptness=-0.8, soonness=1), "tab:orange"],
    [dict(abruptness=0, soonness=1), "tab:red"],
    [dict(abruptness=3, soonness=1), "tab:purple"],
    [dict(abruptness=3, soonness=5), "tab:olive"],
    [dict(abruptness=1, soonness=1), "tab:blue"],
    [dict(abruptness=1, soonness=5), "tab:green"],
    [dict(abruptness=1, soonness=10), "tab:brown"],
    [dict(abruptness=-0.5, soonness=10), "tab:cyan"],
]

rows = int(len(kwargs_combinations) / 2)
columns = int(len(kwargs_combinations) / rows)

clip = VideoFileClip("media/chaplin.mp4").cutout(0, 2).multiply_volume(0)

fig, axs = plt.subplots(rows, columns, figsize=(8, 9), tight_layout=True)

fig.supylabel("Frame transformation factor")
fig.supxlabel("Time")

column = 0
for i, (kwargs_combination, color) in enumerate(kwargs_combinations):
    stdout = io.StringIO()
    with redirect_stdout(stdout):
        fxclip = clip.fx(accel_decel, new_duration=1.5, **kwargs_combination)
        fxclip.preview()

    t, s = ([], [])
    for line in stdout.getvalue().splitlines():
        if line.startswith("t"):
            t.append(float(line.split(" ")[1]) * 1.5)
        else:
            s.append(float(line))

    t = np.array(t)
    facts = np.array(s)

    parameters_text = "\n".join(
        [f"{kwarg_name} = {value}" for kwarg_name, value in kwargs_combination.items()]
    )

    row = i % rows
    axs[row, column].grid()
    axs[row, column].scatter(
        t,
        facts,
        s=6,
        color=color,
        label=parameters_text,
    )
    axs[row, column].legend(loc='lower right', markerscale=0, handletextpad=-1.9)

    if ((i + 1) / rows) == 1:
        column += 1

plt.savefig("accel_decel-fx-params.png")
plt.show()

• I have provided code that clearly demonstrates the bug and that only works correctly when applying this fix
• I have added suitable tests demonstrating a fixed bug or new/changed feature to the test suite in tests/
• I have properly documented new or changed features in the documentation or in the docstrings
• I have properly explained unusual or unexpected code in the comments around it

[coveralls]

Coverage decreased (-0.02%) to 69.155% when pulling c0c8241 on mondeja:doc-accel_decel into 8523616 on Zulko:master.