eases

Easing functions for image and video data.

Basic Usage: Eases

The easing operation functions (eases) are used to change the values within a set of image data. Using an easing operation (an “ease”) works like any other function.

Usage:

>>> import numpy as np
>>> a = np.array([[[0., .25, .5, .75, 1.], [0., .25, .5, .75, 1.]]])
>>> in_circ(a)
array([[[0.        , 0.03175416, 0.1339746 , 0.33856217, 1.        ],
        [0.        , 0.03175416, 0.1339746 , 0.33856217, 1.        ]]])

The functions themselves are simple. They all adhere to the Easing Operation protocol:

param a:

An array of image data.

return:

The eased data as a numpy.ndarray.

rtype:

numpy.ndarray

Value Scaling

Eases work best on image data. That is to say, they work best on arrays of floating point data with values from zero to one. This is because the math in many of the eases relies on the fact that multiplication results in a smaller number and division results in a larger one.

What happens if you pass an array with numbers outside of that range?

If you pass an array with values less than zero or greater than one, the :func:’pjimg.eases.will_scale’ decorator will scale the data before passing it to the ease and then unscale result before returning it.

What happens when the data is scaled?

When scaling the data, the function:

• Sets the lowest value to zero,

• Sets the highest value to one,

• Sets the rest of the values to their proportional location between the lowest and the highest value.

It will then undo that scaling before returning the eased data.

This can result in some undesirable results if the lowest or highest value in the data isn’t the lowest or highest value in the value range you are working in. For example, if you are working with the range 0–255 but the lowest and highest values in the data are 127 and 215, the ease will act like you are working in the range 127–215.

If this will cause problems for your code, you should scale the data yourself before using the easing function.

Easing Operations

The following are the easing functions available in pjimg.

Ease In

These functions start slow or extend the darkness in an image:

pjimg.eases.in_back(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that backs up a little before starting.

The action of in_back().

With image data, it extends the darker areas and compresses the lighter ones. The dip into negative values can be a little awkward. It’s left to the calling application to decide how to handle it. In the following example, values are just truncated at zero.

An example of how in_back() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_bounce(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a bounce.

The action of in_bounce().

With image data, it is a large extension of the lighter areas with multiple peaks and compression of the darker ones.

An example of how in_bounce() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_circ(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a circular curve.

The action of in_circ().

With image data, it is a moderate extension of the darker areas and compression of the lighter ones. This should not generate values outside of the original range.

An example of how in_circ() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_cubic(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a cubic curve.

The action of in_cubic().

With image data, it is a moderate extension of the darker areas and compression of the lighter ones. This should not generate values outside of the original range.

An example of how in_cubic() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_elastic(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that bounces.

The action of in_elastic().

With image data, it extends the darker areas and compresses the lighter ones. The dip into negative values can be a little awkward. It’s left to the calling application to decide how to handle it. In the following example, values are just truncated at zero.

An example of how in_elastic() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_expo(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has an exponential curve.

The action of in_expo().

With image data, it is a moderate extension of the darker areas and compression of the lighter ones. This should not generate values outside of the original range.

An example of how in_expo() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_quad(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a quadratic curve.

The action of in_quad().

With image data, it is a moderate extension of the darker areas and compression of the lighter ones. This should not generate values outside of the original range.

An example of how in_quad() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_quart(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a quadric curve.

The action of in_quart().

With image data, it is a moderate extension of the darker areas and compression of the lighter ones. This should not generate values outside of the original range.

An example of how in_quart() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_quint(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a quintic curve.

The action of in_quint().

With image data, it is a large extension of the darker areas and compression of the lighter ones. This should not generate values outside of the original range.

An example of how in_quint() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_sin(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a sine curve.

The action of in_sin().

With image data, it is a small extension of the darker areas and compression of the lighter ones. This should not generate values outside of the original range.

An example of how in_sin() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

Ease Out

These functions start fast or extend the lightness in an image:

pjimg.eases.out_back(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that backs up a little before ending.

The action of out_back().

With image data, it extends the lighter areas and compresses the darker ones. The dip into negative values can be a little awkward. It’s left to the calling application to decide how to handle it. In the following example, values are just truncated at zero.

An example of how out_back() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.out_bounce(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a bounce.

The action of out_bounce().

With image data, it is a large extension of the lighter areas with multiple peaks and compression of the darker ones.

An example of how out_bounce() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.out_circ(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a circular curve.

The action of out_circ().

With image data, it is a moderate extension of the lighter areas and compression of the darker ones.

An example of how out_circ() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.out_cubic(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a cubic curve.

The action of out_cubic().

With image data, it is a moderate extension of the lighter areas and compression of the darker ones.

An example of how out_cubic() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.out_elastic(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that bounces.

The action of out_elastic().

With image data, it extends the lighter areas and compresses the darker ones. The bounce into values over one can be a little awkward. It’s left to the calling application to decide how to handle it. In the following example, values are just truncated at one.

An example of how out_elastic() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.out_expo(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has an exponential curve.

The action of out_expo().

With image data, it extends the lighter areas and compresses the darker ones. The bounce into values over one can be a little awkward. It’s left to the calling application to decide how to handle it. In the following example, values are just truncated at one.

An example of how out_expo() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.out_quad(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a quadratic curve.

The action of out_quad().

With image data, it is a moderate extension of the lighter areas and compression of the darker ones.

An example of how out_quad() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.out_quart(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a quartic curve.

The action of out_quart().

With image data, it is a moderate extension of the lighter areas and compression of the darker ones.

An example of how out_quart() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.out_quint(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a quintic curve.

The action of out_quint().

With image data, it is a large extension of the lighter areas and compression of the darker ones.

An example of how out_quint() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.out_sin(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a sine curve.

The action of out_sin().

With image data, it is a small extension of the lighter areas and compression of the darker ones.

An example of how out_sin() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

Ease In Out

These functions go fast in the middle or compress the midtones of the image.

pjimg.eases.in_out_back(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that backs up then overshoots.

The action of in_out_back().

With image data, it extends the darker and lighter areas. The dip into negative values and bounce over one can be a little awkward. It’s left to the calling application to decide how to handle it. In the following example, values are just truncated at zero and one.

An example of how in_out_back() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_out_bounce(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that has a bounce

The action of in_out_bounce().

With image data, it extends the darker and lighter areas. The dip into negative values and bounce over one can be a little awkward. It’s left to the calling application to decide how to handle it. In the following example, values are just truncated at zero and one.

An example of how in_out_bounce() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_out_circ(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that uses a circular curve to compress the middle.

The action of in_out_circ().

With image data, it extends the darker and lighter areas. This should not generate values outside of the original range.

An example of how in_out_circ() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_out_cos(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that uses a cosine curve to turn the make the middle low and the edges high.

The action of in_out_cos().

With image data, it turns the midtones dark and the dark and light become midtones. This should not generate values outside of the original range.

An example of how in_out_cos() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_out_cubic(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that uses a cubic curve to compress the middle.

The action of in_out_cubic().

With image data, it extends the darker and lighter areas. This should not generate values outside of the original range.

An example of how in_out_cubic() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_out_elastic(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that uses a bouncy curve to compress the middle.

The action of in_out_elastic().

With image data, it extends the darker and lighter areas. The dip into values below zero or bounce into values over one can be a little awkward. It’s left to the calling application to decide how to handle it. In the following example, values are just truncated at one.

An example of how in_out_elastic() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_out_expo(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that uses a exponential curve to compress the middle.

The action of in_out_expo().

With image data, it extends the darker and lighter areas. This should not generate values outside of the original range.

An example of how in_out_expo() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_out_perlin(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that uses the easing equation from Ken Perlin’s “Improved Perlin Noise” papaer.

The action of in_out_perlin().

With image data, it slightly extends the darker and lighter areas. This should not generate values outside of the original range.

An example of how in_out_perlin() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_out_quad(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that uses a quadratic curve to compress the middle.

The action of in_out_quad().

With image data, it extends the darker and lighter areas. This should not generate values outside of the original range.

An example of how in_out_quad() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_out_quart(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that uses a quartic curve to compress the middle.

The action of in_out_quart().

With image data, it extends the darker and lighter areas. This should not generate values outside of the original range.

An example of how in_out_quart() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_out_quint(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that uses a quintic curve to compress the middle.

The action of in_out_quint().

With image data, it greatly extends the darker and lighter areas. This should not generate values outside of the original range.

An example of how in_out_quint() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.in_out_sin(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that uses a sine curve to compress the middle.

The action of in_out_sin().

With image data, it slightly extends the darker and lighter areas. This should not generate values outside of the original range.

An example of how in_out_sin() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

Ease Mid

These functions change the values in the data, making the midtones dark and the edges light.

pjimg.eases.mid_bump_linear(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that makes the middle of the range the peak of the values.

The action of mid_bump_linear().

With image data, it makes the midtones light and the edges dark.

An example of how mid_bump_linear() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

pjimg.eases.mid_bump_sin(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

An easing function that makes the middle of the range the peak of the values.

The action of mid_bump_sin().

With image data, it makes the midtones light and the edges dark.

An example of how mid_bump_sin() affects a simple gradient.

Parameters:

a – An array of image data.

Returns:

The eased data as a numpy.ndarray.

Return type:

numpy.ndarray

Registration

All easing functions are registered in dict pjimg.eases.eases for convenience, but they can also be called directly.

Decorators

Decorators for pjimg.eases.

pjimg.eases.register(registry: dict[str, Callable[[ndarray[tuple[int, ...], dtype[float64]]], ndarray[tuple[int, ...], dtype[float64]]]]) → Callable[[Callable[[ndarray[tuple[int, ...], dtype[float64]]], ndarray[tuple[int, ...], dtype[float64]]]], Callable[[ndarray[tuple[int, ...], dtype[float64]]], ndarray[tuple[int, ...], dtype[float64]]]]

Registers the decorated function under the function’s name in the given registry dictionary.

Parameters:

registry – The registry to register the given function in.

Returns:

The registration function pointed to the given registry.

Return type:

function

pjimg.eases.will_scale(fn: Callable[[ndarray[tuple[int, ...], dtype[float64]]], ndarray[tuple[int, ...], dtype[float64]]]) → Callable[[ndarray[tuple[int, ...], dtype[float64]]], ndarray[tuple[int, ...], dtype[float64]]]

These eases only work for values between zero and one. If given values outside of that range, it will scale the values down to that range, run the easing function, then scale the values back up to the original range.

Parameters:

fn – The decorated easing functions.

Returns:

The now wrapped function.

Return type:

function