dmtools package

dmtools.io module

dmtools.io.read_png(path: str) → numpy.ndarray

Read a png file into a NumPy array.

Parameters: path (str) – String file path.
Returns: NumPy array representing the image.
Return type: np.ndarray

dmtools.io.write_png(image: numpy.ndarray, path: str)

Write NumPy array to a png file.

The NumPy array should have integer values in the range [0, 255]. Otherwise, this function has undefined behavior.

Parameters

image (np.ndarray) – NumPy array representing image.
path (str) – String file path.

dmtools.netpbm module

class dmtools.netpbm.Netpbm(P: int, k: int, M: numpy.ndarray)

Bases: object

An object representing a Netpbm image.

Netpbm is a package of graphics programs and a programming library. These programs work with a set of graphics formats called the “netpbm” formats. Each format is identified by a “magic number” which is denoted as P followed by the number identifier. This class works with the following formats.

pbm: Pixels are black or white (P1 and P4).
pgm: Pixels are shades of gray (P2 and P5).
ppm: Pixels are in full color (P3 and P6).

Each of the formats has two “magic numbers” associated with it. The lower number corresponds to the ASCII (plain) format while the higher number corresponds to the binary (raw) format. This class can handle reading both the plain and raw formats though it can only export Netpbm images in the plain formats (P1, P2, and P3).

The plain formats for all three of pbm, pgm, and ppm are quite similar. Here is an example pgm format.

The first row of the file contains the “magic number”. In this example, the file is a grayscale pgm image. The second row gives the file dimensions (width by height) separated by whitespace. The third row gives the maximum gray/color value. In this case, it is the maximum gray value since this is a grayscale pgm image. Essentially, this number encodes how many different gradients there are in the image. Lastly, the remaining lines of the file encode the actual pixels of the image. In a pbm image, the third line is not needed since pixels have binary (black or white) values. In a ppm full-color image, each pixels has three values represeting it–the values of the red, green, and blue channels.

This descriptions serves as a brief overview of the Netpbm formats with the relevant knowledge for using this class. For more information about Netpbm, see the Netpbm Home Page.

extension_to_magic_number = {'pbm': 1, 'pgm': 2, 'ppm': 3}

magic_number_to_extension = {1: 'pbm', 2: 'pgm', 3: 'ppm'}

rescale(k: int)

Rescale the image by the desired scaling factor.

Uses Nearest-neighbor interpolation as the image scaling algorithm. Read more about image scaling algorithms at Image scaling.

Parameters: k (int) – Scale factor

set_max_color_value(k: int)

Set the maximum gray/color value of this Netpbm image.

Parameters: k (int) – Maximum gray/color value.

to_netpbm(path: str, comment: List[str] = [])

Write object to a Netpbm file (pbm, pgm, ppm).

Uses the ASCII (plain) magic numbers.

Parameters

path (str) – String file path.
comment (str) – List of comment lines to include in the file.

to_png(path: str)

Write object to a png file.

Parameters: path (str) – String file path.

dmtools.netpbm.read_netpbm(path: str) → dmtools.netpbm.Netpbm

Read Netpbm file (pbm, pgm, ppm) into Netpbm.

Parameters: path (str) – String file path.
Returns: A Netpbm image
Return type: Netpbm

dmtools.transform module

dmtools.transform.blur(image: numpy.ndarray, sigma: float, radius: float = 0) → numpy.ndarray

Blur the image.

This image blur implentation is largley based off of the ImageMagick impmenetation. It uses a Gaussian Filter with parameter sigma and a support of radius to blur the image.

Parameters

image (np.ndarray) – Image to be blurred.
sigma (float) – “Neighborhood” of the blur. A larger value is blurrier.
radius (float) – Limit of the blur. Defaults to 4 x sigma.

Returns

Blurred image.

Return type

np.ndarray

dmtools.transform.clip(image: numpy.ndarray, k: int = 255) → numpy.ndarray

Clip the image so the maximum gray/color value is k.

Every value less than 0 is mapped to 0 and every value more than k is mapped to k. Values in [0,k] are untouched.

Parameters

image (np.ndarray) – Image to clip.
k (int) – Maximum gray/color value. Defaults to 255.

Returns

Clipped image.

Return type

np.ndarray

dmtools.transform.normalize(image: numpy.ndarray, k: int = 255) → numpy.ndarray

Normalize the image so the maximum gray/color value is k.

Normalize the range of values in the image to [0,k]. If applied to a three channel image, normalizes each channel by the same amount.

Parameters

image (np.ndarray) – Image to normalize.
k (int) – Maximum gray/color value. Defaults to 255.

Returns

Normalized image.

Return type

np.ndarray

dmtools.transform.rescale(image: numpy.ndarray, k: int, filter: str = 'point', weighting_function: Optional[Callable] = None, support: Optional[Callable] = None, **kwargs) → numpy.ndarray

Rescale the image by the given scaling factor.

This image rescale implentation is largley based off of the ImageMagick impmenetation. The following filters are built-in:

Point Filter (“point”): Nearest-neighbor heuristic.
Box Filter (“box”): Average of neighboring pixels.
Triangle Filter (“triangle”): Linear decrease in pixel weight.
Catmull-Rom Filter (“catrom”): Produces a sharper edge.
Gaussian Filter (“gaussian”): Blurs image. Useful as low pass filter.

Additionally, advanced users can specify a custom filter by providing a weighting function and a support.

Parameters

image (np.ndarray) – Image to rescale.
k (int) – Scaling factor.
filter (str) – {point, box, triangle, catrom, gaussian}.
weighting_function (Callable) – Weighting function to use.
support (float) – Support of the provided weighting function.

Returns

Rescaled image.

Return type

np.ndarray

dmtools.transform.wraparound(image: numpy.ndarray, k: int = 255) → numpy.ndarray

Wraparound the image so the maximum gray/color value is k.

Each value x is mapped to x mod k+1 such that values outside of [0,k] wraparound until they fall in the desired range.

Parameters

image (np.ndarray) – Image to wraparound
k (int) – Maximum gray/color value. Defaults to 255.

Returns

Wraparound image.

Return type

np.ndarray

dmtools.colorspace module

dmtools.colorspace.Lab_to_RGB(image: numpy.ndarray, illuminant: str = 'D65') → numpy.ndarray

Convert an image in Lab space to CIE RGB space.

For details about the implemented conversion, see CIE 1931 color space and CIELAB color space.

Parameters

image (np.ndarray) – Image in Lab space.
illuminant (str) – Standard illuminant {D65, D50}

Returns

Image in CIE RGB space.

Return type

np.ndarray

dmtools.colorspace.Lab_to_XYZ(image: numpy.ndarray, illuminant: str = 'D65') → numpy.ndarray

Convert an image in Lab space to CIE XYZ space.

For details about the implemented conversion, see CIELAB color space.

Parameters

image (np.ndarray) – Image in Lab space.
illuminant (str) – Standard illuminant {D65, D50}

Returns

Image in CIE XYZ space.

Return type

np.ndarray

dmtools.colorspace.RGB_to_Lab(image: numpy.ndarray, illuminant: str = 'D65') → numpy.ndarray

Convert an image in CIE RGB space to Lab space.

For details about the implemented conversion, see CIE 1931 color space and CIELAB color space.

Parameters

image (np.ndarray) – Image in CIE RGB space.
illuminant (str) – Standard illuminant {D65, D50}

Returns

Image in Lab space.

Return type

np.ndarray

dmtools.colorspace.RGB_to_XYZ(image: numpy.ndarray) → numpy.ndarray

Convert an image in CIE RGB space to XYZ space.

For details about the implemented conversion, see CIE 1931 color space.

Parameters: image (np.ndarray) – Image in CIE RGB space.
Returns: Image in CIE XYZ space.
Return type: np.ndarray

dmtools.colorspace.RGB_to_YUV(image: numpy.ndarray) → numpy.ndarray

Convert an image in CIE RGB space to YUV space.

For details about the implemented conversion, see YUV.

Parameters: image (np.ndarray) – Image in CIE RGB space.
Returns: Image in YUV space.
Return type: np.ndarray

dmtools.colorspace.RGB_to_gray(image: numpy.ndarray) → numpy.ndarray

Convert an image in CIE RGB space to grayscale.

For details about the implemented conversion, see FAQs about Color.

Parameters: image (np.ndarray) – Image in CIE RGB space.
Returns: Image in grayscale.
Return type: np.ndarray

dmtools.colorspace.XYZ_to_Lab(image: numpy.ndarray, illuminant: str = 'D65') → numpy.ndarray

Convert an image in CIE XYZ space to Lab space.

For details about the implemented conversion, see CIELAB color space.

Parameters

image (np.ndarray) – Image in CIE XYZ space.
illuminant (str) – Standard illuminant {D65, D50}

Returns

Image in Lab space.

Return type

np.ndarray

dmtools.colorspace.XYZ_to_RGB(image: numpy.ndarray) → numpy.ndarray

Convert an image in CIE XYZ space to RGB space.

For details about the implemented conversion, see CIE 1931 color space.

Parameters: image (np.ndarray) – Image in CIE XYZ space.
Returns: Image in CIE RGB space.
Return type: np.ndarray

dmtools.colorspace.YUV_to_RGB(image: numpy.ndarray) → numpy.ndarray

Convert an image in YUV space to CIE RGB space.

For details about the implemented conversion, see YUV.

Parameters: image (np.ndarray) – Image in YUV space.
Returns: Image in CIE RGB space.
Return type: np.ndarray

dmtools.colorspace.apply_to_channels(image: numpy.ndarray, f_1: Callable, f_2: Callable, f_3: Callable) → numpy.ndarray

Return the image with the functions applied to each channel.

Parameters

image (np.ndarray) – Image (recommended to be normalized).
f_1 (Callable) – Function to apply to the first channel.
f_2 (Callable) – Function to apply to the second channel.
f_3 (Callable) – Function to apply to the third channel.

Returns

Pixel matrix with functions applied to each channel.

Return type

np.ndarray

dmtools.colorspace.denormalize(image: numpy.ndarray, color_space: str) → numpy.ndarray

Denormalize the image in the given color space.

Parameters

image (np.ndarray) – Normalized image in the given color space.
color_space (str) – Color space {RGB, Lab, YUV}.

Returns

Denormalized image in the given color space.

Return type

np.ndarray

dmtools.colorspace.gray_to_RGB(image: numpy.ndarray) → numpy.ndarray

Convert an image in grayscale to CIE RGB space.

Parameters: image (np.ndarray) – Image in grayscale.
Returns: Image in CIE RGB space.
Return type: np.ndarray

dmtools.colorspace.normalize(image: numpy.ndarray, color_space: str) → numpy.ndarray

Normalize the image in the given color space.

Parameters

image (np.ndarray) – Image in the given color space.
color_space (str) – Color space {RGB, Lab, YUV}.

Returns

Normalized image with values in [0,1].

Return type

np.ndarray

dmtools.animation module

dmtools.animation.clip(path: str, start: int = 0, end: int = - 1) → List[numpy.ndarray]

Return a list of images in the given directory.

Images are ordered according to their name. Hence, the following naming convention is recommend.

name0000.png, name0001.png, …

Parameters

path (str) – String directory path.
start (int, optional) – Starting frame. Defaults to 0.
end (int, optional) – Ending frame. Defaults to -1.

Returns

List of NumPy arrays representing images.

Return type

List[np.ndarray]

dmtools.animation.to_mp4(frames: List[numpy.ndarray], path: str, fps: int, s: int = 1, audio: Optional[dmtools.sound.WAV] = None)

Write an animation as a .mp4 file using ffmpeg through imageio.mp4

Parameters

frames (List[np.ndarray]) – List of frames in the animation.
audio (sound.WAV) – Audio for the animation (None if no audio).
path (str) – String file path.
fps (int) – Frames per second.
s (int, optional) – Multiplier for scaling. Defaults to 1.

dmtools.ascii module

class dmtools.ascii.Ascii(M: numpy.ndarray)

Bases: object

An object representing an ASCII image.

For more information about ASCII, see ASCII

to_png(path: str)

Write object to a png file.

Parameters: path (str) – String file path.

to_txt(path: str)

Write object to a txt file.

Parameters: path (str) – String file path.

dmtools.ascii.netpbm_to_ascii(image: dmtools.netpbm.Netpbm) → dmtools.ascii.Ascii

Return an ASCII representation of the given image.

This function uses a particular style of ASCII art in which “symbols with various intensities [are used for] creating gradients or contrasts.”

Parameters: image (netpbm.Netpbm) – Netpbm image.
Returns: ASCII representation of image.
Return type: Ascii

dmtools.sound module

class dmtools.sound.WAV(r: numpy.ndarray, l: numpy.ndarray, sample_rate: int = 44100)

Bases: object

An object representing a WAV audio file.

For more information about the audio file format, see WAV

to_wav(path)

Write object to a WAV audio file (wav)

Parameters: path (str) – String file path.

dmtools.sound.wave(f: float, a: float, t: float) → numpy.ndarray

Generate the samples of a sound wave.

Parameters

f (float) – Frequency of the sound wave.
a (float) – Amplitude of the sound wave.
t (float) – Duration (seconds) of the sound wave.

Returns

NumPy array with sample points of wave.

Return type

np.ndarray

dmtools.sound.wave_sequence(frequencies: numpy.ndarray, t) → dmtools.sound.WAV

Return a Wav sound which iterates through the given frequencies.

Parameters

frequencies (np.ndarray) – frequencies to iterate through.
t ([type]) – duration of iteration.

Returns

Wav file.

Return type

WAV

dmtools.arrange module

dmtools.arrange.border(image: numpy.ndarray, b: int, color: int = 'white', k: int = 255) → numpy.ndarray

Add a border of width b to the image.

Parameters

image (Netpbm) – Netpbm image to add a border to
b (int) – width of the border/margin.
color (int) – color of border {‘white’, ‘black’} (defaults to white).
k (int) – white point (defaults to 255).

Returns

Image with border added.

Return type

np.ndarray

dmtools.arrange.image_grid(images: List[numpy.ndarray], w: int, h: int, b: int, color: int = 'white', k: int = 255) → numpy.ndarray

Create a w * h grid of images with a border of width b.

Parameters

images (List[np.ndarray]) – images (of same dimension) for grid.
w (int) – number of images in each row of the grid.
h (int) – number of images in each column of the grid.
b (int) – width of the border/margin.
color (int) – color of border {‘white’, ‘black’} (defaults to white).
k (int) – white point (defaults to 255).

Returns

grid layout of the images.

Return type

np.ndarray