util

Common utilities for the pjimg packages.

convert

Data conversion utilities.

pjimg.util.float_to_uint8(a: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → ndarray[tuple[int, ...], dtype[uint8]][source]

Convert an array of floating point values to an array of unsigned 8-bit integers.

Parameters:

a – The array of image data to convert to unsigned 8-bit integers.

Returns:

A numpy.ndarray object.

Return type:

numpy.ndarray

pjimg.util.grayscale_to_rgb(a: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]][source]

Convert single channel image data to three channel.

Parameters:

a – The array of grayscale image data to convert.

Returns:

A numpy.ndarray object.

Return type:

numpy.ndarray

lerps

Interpolation functions.

pjimg.util.cubic_interpolation(a: ndarray[tuple[int, ...], dtype[T]], b: ndarray[tuple[int, ...], dtype[T]], x: ndarray[tuple[int, ...], dtype[float64]], a_: ndarray[tuple[int, ...], dtype[T]] | None = None, b_: ndarray[tuple[int, ...], dtype[T]] | None = None) → ndarray[tuple[int, ...], dtype[T]][source]

Perform a cubic interpolation on the values of four arrays. This is adapted from code found at: Cubic Interpolation

Parameters:

  • a – The closest value on the “left” side.

  • b – The closest value on the “right” side.

  • x – How close the final value is to the closest “left” value.

  • a – (Optional.) The farther value on the “left” side.

  • b – (Optional.) The farther value on the “right” side.

Returns:

A numpy.ndarray object.

Return type:

numpy.ndarray

Usage:

>>> import numpy as np
>>>
>>> base = np.array([0, 1, 2, 3, 4, 5], dtype=float)
>>> a = base[1:4]
>>> b = base[2:5]
>>> a_ = base[:3]
>>> b_ = base[3:]
>>> x = np.array([0.5, 0.5, 0.5])
>>> cubic_interpolation(a, b, x, a_, b_)
array([1.5, 2.5, 3.5])

You can do the interpolation if you don’t have the furthest data points. It will just be inaccurate at the edges because of the missing data:

>>> base = np.array([1, 2, 3, 4], dtype=float)
>>> a = base[:3]
>>> b = base[1:]
>>> x = np.array([0.5, 0.5, 0.5])
>>> cubic_interpolation(a, b, x)
array([1.4375, 2.5   , 3.5625])
pjimg.util.linear_interpolation(a: ndarray[tuple[int, ...], dtype[T]], b: ndarray[tuple[int, ...], dtype[T]], x: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[T]][source]

Perform a linear interpolation on the values of two arrays

Parameters:

  • a – The “left” values. The datatype of a also determines the datatype of the returned array.

  • b – The “right” values.

  • x – An array of how close the location of the final value should be to the “left” value.

Returns:

A numpy.ndarray object.

Return type:

numpy.ndarray

Usage:

>>> import numpy as np
>>>
>>> a = np.array([1, 2, 3])
>>> b = np.array([3, 4, 5])
>>> x = np.array([.5, .5, .5])
>>> linear_interpolation(a, b, x)
array([2, 3, 4])
pjimg.util.n_dimensional_interpolation(a: ndarray[tuple[int, ...], dtype[T]], b: ndarray[tuple[int, ...], dtype[T]], x: ndarray[tuple[int, ...], dtype[float64]], interpolator: Callable[[ndarray[tuple[int, ...], dtype[T]], ndarray[tuple[int, ...], dtype[T]], ndarray[tuple[int, ...], dtype[float64]]], ndarray[tuple[int, ...], dtype[T]]]) → ndarray[tuple[int, ...], dtype[T]][source]

Perform an interpolation over multiple dimensions.

Parameters:

  • a – The “left” values.

  • b – The “right” values.

  • x – An array of how close the location of the final value should be to the “left” value.

Returns:

A numpy.ndarray object.

Return type:

numpy.ndarray

Usage:

>>> import numpy as np
>>>
>>> a = np.zeros((2, 3, 3), dtype=int)
>>> b = np.full((2, 3, 3), 255, dtype=int)
>>> x = np.linspace(0.0, 1.0, 18, True, False, float)
>>> x = x.reshape((2, 3, 3))
>>> n_dimensional_interpolation(a, b, x, lerp)
array([[135, 150, 165],
       [179, 194, 210],
       [225, 240, 255]])
pjimg.util.n_dimensional_cubic_interpolation(a: ndarray[tuple[int, ...], dtype[T]], b: ndarray[tuple[int, ...], dtype[T]], x: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[T]][source]

Perform a cubic interpolation over multiple dimensions. This is a shortcut for lerpy.n_dimensional_interpolation() using cubic_interpolation() as an interpolator.

Parameters:

  • a – The “left” values. The datatype of a also determines the datatype of the returned array.

  • b – The “right” values.

  • x – An array of how close the location of the final value should be to the “left” value.

Returns:

A numpy.ndarray object.

Return type:

numpy.ndarray

pjimg.util.n_dimensional_linear_interpolation(a: ndarray[tuple[int, ...], dtype[T]], b: ndarray[tuple[int, ...], dtype[T]], x: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[T]][source]

Perform a linear interpolation over multiple dimensions. This is a shortcut for lerpy.n_dimensional_interpolation() using linear_interpolation() as an interpolator.

Parameters:

  • a – The “left” values. The datatype of a also determines the datatype of the returned array.

  • b – The “right” values.

  • x – An array of how close the location of the final value should be to the “left” value.

Returns:

A numpy.ndarray object.

Return type:

numpy.ndarray

resize

Functions for resizing numpy arrays.

pjimg.util.build_resizing_matrices(src_shape: Sequence[int], dst_shape: Sequence[int]) → tuple[ndarray[tuple[int, ...], dtype[uint8]], ndarray[tuple[int, ...], dtype[uint8]], ndarray[tuple[int, ...], dtype[float64]]][source]

Create the indexing and distance arrays needed to interpolate values when resizing an array.

Parameters:

  • src_shape – The original shape of the array.

  • dst_shape – The resized shape of the array.

Returns:

A tuple object.

Return type:

tuple

pjimg.util.crop_array(a: ndarray[tuple[int, ...], dtype[T]], new_size: Sequence[int], loc: Sequence[int] = (0, 0, 0)) → ndarray[tuple[int, ...], dtype[T]][source]

Crop an array to a smaller size.

Parameters:

  • a – The array to crop.

  • new_size – The size of the cropped array.

  • loc – (Optional.) How far to offset the crop from the center of the image. Defaults to no offset.

Returns:

The cropped numpy.ndarray.

Return type:

numpy.ndarray

pjimg.util.magnify_size(shape: Sequence[int], factor: int) → Sequence[int][source]

Magnify the shape of an array.

Parameters:

  • shape – The original shape of the array.

  • factor – The magnification factor.

Returns:

A tuple containing the shape of the magnified array.

pjimg.util.pad_array(a: ndarray[tuple[int, ...], dtype[T]], size: Sequence[int], fill: float = 0.0) → ndarray[tuple[int, ...], dtype[T]][source]

Pad an array to a larger size.

Parameters:

  • a – The array to pad.

  • size – The shape of the size.

  • fill – The color of the padded area.

Returns:

The padded numpy.ndarray.

Return type:

numpy.ndarray

pjimg.util.resize_array(src: ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~pjimg.util.model.T]], shape: ~typing.Sequence[int], interpolator: ~typing.Callable[[~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~pjimg.util.model.T]], ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~pjimg.util.model.T]], ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy.float64]]], ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~pjimg.util.model.T]]] = <function n_dimensional_linear_interpolation>) → ndarray[tuple[int, ...], dtype[T]][source]

Resize a two dimensional array using an interpolation.

Parameters:

  • src – The array to resize. The array is expected to have at least two dimensions.

  • shape – The shape for the resized array.

  • interpolator – The interpolation algorithm for the resizing.

Returns:

A numpy.ndarray object.

Return type:

numpy.ndarray

util

General utility functions for pjimg.

pjimg.util.find_center(size: Sequence[int], loc: Sequence[int] = (0, 0, 0)) → Sequence[int][source]

Find the center pixel of an image of the given size.

Parameters:

  • size – The shape of the image data.

  • loc – (Optional.) How much to offset the center in each dimension. Defaults to no offset.

Returns:

A tuple with the center location of the image.

Return type:

tuple

pjimg.util.get_free_rotation_size_2d(size: Sequence[int], pivot_offset: Sequence[int] = (0, 0, 0)) → Sequence[int][source]

Given the size of a final image, return the size of the image data you need to create in order to rotate the final image within the image data freely around the Z axis without the corners of the final image going outside of the bounds of the image data.

Basically, it says how big the image data needs to be so the corners of the final image won’t be black if you rotate the image.

Parameters:

size – The size of the final image.

Returns:

A tuple containing the shape of the needed image data.

Return type:

tuple

pjimg.util.translate_by_polar_coords(start: tuple[float, float], p: float, o: float) → tuple[float, float][source]

Given a two-dimensional location in linear coordinates and a distance in polar coordinates, return the linear coordinates of the location that distance away from the original location.

Parameters:

  • start – The starting location.

  • p – The rho (distance) of the polar coordinates.

  • o – The theta (angle) of the polar coordinates in radians.

Returns:

A tuple with the final coordinates.

Return type:

tuple

debug

Utilities useful for debugging code that uses pjimg.

pjimg.util.debug.print_array(a: ndarray[tuple[int, ...], dtype[T]], depth: int = 0) → None[source]

Write the values of the given array to stdout.

Parameters:

  • a – The array to print.

  • depth – (Optional.) How far to indent the printed lines.

Returns:

None.

Return type:

NoneType