filters

A Python package for distorting or otherwise affecting image data.

Filters

The filter operation functions (filters) are used to make changes to values in image data where the resulting value of each pixel can be influenced by the values of other pixels in the data.

Usage:

>>> import numpy as np
>>> a = np.array([[[0., .25, .5, .75, 1.], [0., .25, .5, .75, 1.]]])
>>> box_blur(a, size=2)
array([[[0.125, 0.125, 0.375, 0.625, 0.875],
        [0.125, 0.125, 0.375, 0.625, 0.875]]])

The parameters of a filter depends on what the filter is doing. However, the following is true for all of them:

• They take a numpy.ndarray of image data as the first parameter.

• They return a numpy.ndarray of image data.

The following filters are available in pjimg.filters.

Affine Transformation Filters

Affine transformation filters are geometrical transformations that preserve straight lines and parallels within the image.

pjimg.filters.flip(a: ndarray[tuple[int, ...], dtype[float64]], axis: int) → ndarray[tuple[int, ...], dtype[float64]]

Flip the image around an axis.

An example of flip() affecting an image.

Parameters:

• a – The image data to alter.

• axis – The axis to flip the image data around.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

pjimg.filters.grow(a: ndarray[tuple[int, ...], dtype[float64]], factor: float, yx_only: bool = False) → ndarray[tuple[int, ...], dtype[float64]]

Increase the size of an image.

An example of grow() affecting an image.

Parameters:

• a – The image data to alter.

• factor – The scaling factor to use when increasing the size of the image.

• xy_only – (Optional.) Only grow the length and the width of a three-dimensional array.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

pjimg.filters.rotate_2d(a: ndarray[tuple[int, ...], dtype[float64]], angle: float, origin: Sequence[int] | None = None, safe: bool = True) → ndarray[tuple[int, ...], dtype[float64]]

Rotate the image by an arbitrary angle around the Z axis.

An example of rotate_2d() affecting an image.

Parameters:

• a – The image data to alter.

• angle – The angle to rotate the image in degrees.

• origin – (Optional.) The point of rotation. Defaults to the center of the image.

• safe – (Optional.) Make a defensive copy of the image data before operating on the data to prevent unexpected changes to the original image data. This can be turned off in cases where it is more important to preserve the memory. Defaults to True.

Returns:

An array of image data.

Return type:

A :class:numpy.ndarray object.

Warning

This filter uses a third-party library that cannot handle color or three-dimensional arrays. The filter itself will be able to handle three-dimensional arrays, but the filter will affect each two-dimensional slice individually.

pjimg.filters.rotate_90(a: ndarray[tuple[int, ...], dtype[float64]], direction: str = 'cw') → ndarray[tuple[int, ...], dtype[float64]]

Rotate the data 90° around the Z axis.

An example of rotate_90() affecting an image.

Parameters:

• a – The image data to alter.

• direction – (Optional.) Whether to rotate the data clockwise or counter clockwise.

Returns:

An array of image data.

Return type:

A :class:numpy.ndarray object.

pjimg.filters.skew(a: ndarray[tuple[int, ...], dtype[float64]], slope: float) → ndarray[tuple[int, ...], dtype[float64]]

Perform a skew distort on the data.

An example of skew() affecting an image.

Parameters:

• a – The image data to alter.

• slope – The slope of the Y axis of the image after the skew.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

Warning

This filter uses a third-party library that cannot handle color or three-dimensional arrays. The filter itself will be able to handle three-dimensional arrays, but the filter will affect each two-dimensional slice individually.

Blur Filters

Blur filters alter the image by blending the values of different pixels within the image.

pjimg.filters.box_blur(a: ndarray[tuple[int, ...], dtype[float64]], size: int) → ndarray[tuple[int, ...], dtype[float64]]

Perform a box blur.

An example of box_blur() affecting an image.

Parameters:

• a – The image data to alter.

• size – The size of the blox used in the blur.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

Warning

This filter uses a third-party library that cannot handle color or three-dimensional arrays. The filter itself will be able to handle three-dimensional arrays, but the filter will affect each two-dimensional slice individually.

pjimg.filters.gaussian_blur(a: ndarray[tuple[int, ...], dtype[float64]], sigma: float) → ndarray[tuple[int, ...], dtype[float64]]

Perform a gaussian blur.

An example of gaussian_blur() affecting an image.

Parameters:

• a – The image data to alter.

• sigma – The sigma value of the blur. A gaussian blur uses a gaussian function to determine how much the other pixels in the image should affect the value of a pixel. Gaussian functions produce a normal distribution. This value is the size of a standard deviation in that normal distribution.

Returns:

A numpy.ndarray object.

Return type:

numpy.ndarray

Warning

This filter uses a third-party library that cannot handle color or three-dimensional arrays. The filter itself will be able to handle three-dimensional arrays, but the filter will affect each two-dimensional slice individually.

pjimg.filters.glow(a: ndarray[tuple[int, ...], dtype[float64]], sigma: int) → ndarray[tuple[int, ...], dtype[float64]]

Use gaussian blurs to create a halo around brighter objects in the image.

An example of glow() affecting an image.

Parameters:

• a – The image data to alter.

• sigma – The sigma value of the blur. A gaussian blur uses a gaussian function to determine how much the other pixels in the image should affect the value of a pixel. Gaussian functions produce a normal distribution. This value is the size of a standard deviation in that normal distribution.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

pjimg.filters.motion_blur(a: ndarray[tuple[int, ...], dtype[float64]], amount: int, axis: int) → ndarray[tuple[int, ...], dtype[float64]]

Perform a motion blur.

An example of motion_blur() affecting an image.

Parameters:

• a – The image data to alter.

• size – The size of the blur to apply.

• direction – The axis that the blur should be performed along. The index should be indicated using the filters.X or filters.Y objects.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

Warning

This filter uses a third-party library that cannot handle color or three-dimensional arrays. The filter itself will be able to handle three-dimensional arrays, but the filter will affect each two-dimensional slice individually.

Distortion Filters

Distortion filters are geometrical transformations that do not preserve straight lines and parallels within in the image.

pjimg.filters.linear_to_polar(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

Convert the linear coordinates of the image data to polar coordinates.

An example of linear_to_polar() affecting an image.

Parameters:

a – The image data to alter.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

Warning

This function works best if you provide it a square image. If you provide image data that doesn’t have equal sized X and Y axes, it will square them itself for processing then trim them back to the original shape after. This may introduce unwanted artifacts into the image.

Warning

This filter uses a third-party library that cannot handle color or three-dimensional arrays. The filter itself will be able to handle three-dimensional arrays, but the filter will affect each two-dimensional slice individually.

pjimg.filters.pinch(a: ndarray[tuple[int, ...], dtype[float64]], amount: float, radius: float, scale: Sequence[float], offset: Sequence[int] = (0, 0, 0)) → ndarray[tuple[int, ...], dtype[float64]]

Distort an image to make it appear as though it is being pinched or swelling.

An example of pinch() affecting an image.

Parameters:

• a – The image data to alter.

• amount – How much the image should be distorted. Best results seem to be with numbers in the range of -1 <= x <= 1.

• radius – Sets the outside edge of the distortion, measured from the center of the distortion.

• scale – Adjusts the scale of the distortion. I’m not exactly clear on the math, but values less than one seem to increase the distortion. Values greater than one seem to decrease the distortion.

• offset – (Optional.) Sets how far the center of the distortion should be offset from the center of the image.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

Warning

If done too close to the edge of the image data, you will get artifacts due to the lack of data. To calculate the minimum safe distance from the edge:

radius * (1 + amount)

Warning

This filter uses a third-party library that cannot handle color or three-dimensional arrays. The filter itself will be able to handle three-dimensional arrays, but the filter will affect each two-dimensional slice individually.

pjimg.filters.polar_to_linear(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

Convert the polar coordinates of the image data to linear coordinates.

An example of polar_to_linear() affecting an image.

Parameters:

a – The image data to alter.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

Warning

This function works best if you provide it a square image. If you provide image data that doesn’t have equal sized X and Y axes, it will square them itself for processing then trim them back to the original shape after. This may introduce unwanted artifacts into the image.

Warning

This filter uses a third-party library that cannot handle color or three-dimensional arrays. The filter itself will be able to handle three-dimensional arrays, but the filter will affect each two-dimensional slice individually.

pjimg.filters.ripple(a: ndarray[tuple[int, ...], dtype[float64]], wave: Sequence[float], amp: Sequence[float], distaxis: Sequence[int], offset: Sequence[int] = (0, 0, 0)) → ndarray[tuple[int, ...], dtype[float64]]

Perform a ripple distortion.

An example of ripple() affecting an image.

Parameters:

• a – The image data to alter.

• wave – The distance between peaks in the distortion. There needs to be one value in the sequence per dimension in the image.

• amp – The amount of change caused by each ripple. There needs to be one value in the sequence per dimension in the image.

• distaxis – Whether the distortion should be along the same axis being distorted, causing the pattern to bunch up like it is rippling, or along a different axis, causing the pattern to wave like it’s the cross-section of a wave. The values are the indexes of the axis to distort along.

• offset – (Optional.) The amount to offset the location of the ripples in the image. There needs to be one value in the sequence per dimension in the image. The default value for all dimensions is zero.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

Warning

This filter uses a third-party library that cannot handle color or three-dimensional arrays. The filter itself will be able to handle three-dimensional arrays, but the filter will affect each two-dimensional slice individually.

pjimg.filters.twirl(a: ndarray[tuple[int, ...], dtype[float64]], radius: float, strength: float, offset: tuple[int, int] = (0, 0)) → ndarray[tuple[int, ...], dtype[float64]]

Swirl the image data.

An example of twirl() affecting an image.

Parameters:

• a – The image data to alter.

• radius – The location of the edge of the distortion. This is measured from the center of the distortion.

• strength – The amount of the distortion. Its roughly equivalent to the number of rotations the distortion makes around the center of the distortion.

• offset – (Optional.) How far to offset the center of the distortion from the center of the image.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

Warning

This filter uses a third-party library that cannot handle color or three-dimensional arrays. The filter itself will be able to handle three-dimensional arrays, but the filter will affect each two-dimensional slice individually.

Value Filters

Value filters operate on the values of the image data without any geometrical transformations or blurs. They are somewhat similar to the easing functions found in pjimg.eases

pjimg.filters.autocontrast(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

Adjust the image to fill the full dynamic range frame by frame.

An example of autocontrast() affecting an image.

Parameters:

a – The image data to alter.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

Warning

This filter uses a third-party library that cannot handle color or three-dimensional arrays. The filter itself will be able to handle three-dimensional arrays, but the filter will affect each two-dimensional slice individually.

pjimg.filters.colorize(a: ndarray[tuple[int, ...], dtype[float64]], colorkey: str = '', white: str = '#FFFFFF', black: str = '#000000') → ndarray[tuple[int, ...], dtype[float64]]

Colorize a grayscale image.

An example of colorize() affecting an image.

Parameters:

• a – The image data to alter.

• colorkey – (Optional.) The key for the pre-defined colors to use in the colorization. These are defined in pjimg.filters.constants.COLORS.

• white – (Optional.) The color name for the color to use to replace white in the image. Color names are defined by PIL.ImageColor.

• black – (Optional.) The color name for the color to use to replace black in the image. Color names are defined by PIL.ImageColor.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

Warning

The output of this filter is in RGB color rather than grayscale. This will impact the ability to use the output with other features of pjimg.

Warning

This filter uses a third-party library that cannot handle color or three-dimensional arrays. The filter itself will be able to handle three-dimensional arrays, but the filter will affect each two-dimensional slice individually.

pjimg.filters.contrast(a: ndarray[tuple[int, ...], dtype[float64]], black: float = 0.0, white: float = 1.0) → ndarray[tuple[int, ...], dtype[float64]]

Adjust the image to fill the full dynamic range.

An example of contrast() affecting an image.

Parameters:

• a – The image data to alter.

• black – (Optional.) The minimum value in the output.

• white – (Optional.) The maximum value in the output.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

pjimg.filters.cut_highlight(a: ndarray[tuple[int, ...], dtype[float64]], threshold: float) → ndarray[tuple[int, ...], dtype[float64]]

Set the white point of the image to the given threshold, removing detail from and increasing the size of the highlights.

An example of cut_highlight() affecting an image.

Parameters:

• a – The image data to alter.

• threshold – The threshold value for the new white point.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

pjimg.filters.cut_shadow(a: ndarray[tuple[int, ...], dtype[float64]], threshold: float) → ndarray[tuple[int, ...], dtype[float64]]

Set the black point of the image to the given threshold, removing detail from and increasing the size of the shadows.

An example of cut_shadow() affecting an image.

Parameters:

• a – The image data to alter.

• threshold – The threshold value for the new black point.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

pjimg.filters.distance(a: ndarray[tuple[int, ...], dtype[float64]], mask_size: int = 5) → ndarray[tuple[int, ...], dtype[float64]]

Make each pixel the distance to the nearest black pixel in the original image.

An example of distance() affecting an image.

Parameters:

• a – The image data to alter.

• mask_size – (Optional.) The size of the mask used to determine the distance to a black pixel.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

Warning

This filter uses a third-party library that cannot handle color or three-dimensional arrays. The filter itself will be able to handle three-dimensional arrays, but the filter will affect each two-dimensional slice individually.

pjimg.filters.inverse(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

Inverse the colors of an image.

An example of inverse() affecting an image.

Parameters:

a – The image data to alter.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

pjimg.filters.posterize(a: ndarray[tuple[int, ...], dtype[float64]], levels: int = 2)

Reduce the number of colors in the image data.

An example of posterize() affecting an image.

Parameters:

• a – The image data to alter.

• levels – (Optional.) The number of colors in the resulting data. Default is 2.

Returns:

A np.ndarray object.

Return type:

numpy.ndarray

Registration

All filter functions are registered in the dict pjimg.filters.filters for convenience, but they can also be called directly.

Decorators

These decorators provide useful functions for building new filters:

pjimg.filters.register(registry: dict[str, Callable[[...], ndarray[tuple[int, ...], dtype[float64]]]]) → Callable[[Callable[[...], ndarray[tuple[int, ...], dtype[float64]]]], Callable[[...], 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.filters.processes_by_grayscale_frame(fn: Callable[[...], ndarray[tuple[int, ...], dtype[float64]]]) → Callable[[...], ndarray[tuple[int, ...], dtype[float64]]]

If the given array is more than two dimensions, iterate through each two dimensional slice. This is used when the filter can’t handle more than two dimensions in an array.

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

Converts the image data from floats to ints.

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

The array needs to have equal sized X and Y axes. The result will be sliced to the size of the original array.