dmtools package

dmtools.io module

class dmtools.io.Metadata(title: Optional[str] = None, author: Optional[str] = None, description: Optional[str] = None, copyright: Optional[str] = None, creation_time: Optional[str] = None, software: Optional[str] = None, disclaimer: Optional[str] = None, warning: Optional[str] = None, source: Optional[str] = None, comment: Optional[str] = None)[source]

Bases: object

Maintain metadata for an image. Based on the PNG format.

Initialize metadata.

Parameters
  • title (str) – Short (one line) title or caption for image. Defaults to None

  • author (str) – Name of image’s creator. Defaults to None

  • description (str) – Description of image (possibly long). Defaults to None

  • copyright (str) – Copyright notice. Defaults to None

  • creation_time (str) – Time of original image creation. Defaults to the time of initialization.

  • software (str) – Software used to create the image. Defaults to “dmtools”.

  • disclaimer (str) – Legal disclaimer. Defaults to None.

  • warning (str) – Warning of nature of content. Defaults to None.

  • source (str) – Device used to create the image. Defaults to the source code of the invoked script.

  • comment (str) – Miscellaneous comment. Defaults to None.

dmtools.io.read(path: str) ndarray[source]

Read an image file into a NumPy array.

Parameters

path (str) – String file path with extention in {png, pbm, pgm, ppm}.

Returns

NumPy array representing the image.

Return type

np.ndarray

dmtools.io.read_netpbm(path: str) ndarray[source]

Read a Netpbm file (pbm, pgm, ppm) into a NumPy array.

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.

P2
5 3
4
1 1 0 1 0
2 0 3 0 1
2 2 3 1 0

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.

Parameters

path (str) – String file path.

Returns

NumPy array representing image.

Return type

image (np.ndarray)

dmtools.io.read_png(path: str) ndarray[source]

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.recreate_script_from_png(image_path: str, script_path: str)[source]

Recreate a script from the metadata of a PNG file.

Parameters
  • image_path (str) – String file path of PNG image.

  • script_path (str) – String file path of generated script.

dmtools.io.write_ascii(image: ndarray, path: str, txt: str = False)[source]

Write object to an ASCII art representation.

Parameters
  • image (np.ndarray) – NumPy array representing image.

  • path (str) – String file path.

  • txt (str) – True iff write to a txt file. Defaults to False.

dmtools.io.write_netpbm(image: ndarray, k: int, path: str, versioning=False, metadata=None)[source]

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

Uses the ASCII (plain) magic numbers.

Parameters
  • image (np.ndarray) – NumPy array representing image.

  • k (int) – Maximum color/gray value.

  • path (str) – String file path.

  • versioning (bool) – Version files (rather than overwrite).

  • metadata (Metadata) – Metadata for image. Defaults to Metadata().

dmtools.io.write_png(image: ndarray, path: str, versioning=False, metadata=None)[source]

Write NumPy array to a png file.

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

Parameters
  • image (np.ndarray) – NumPy array representing image.

  • path (str) – String file path.

  • versioning (bool) – Version files (rather than overwrite).

  • metadata (Metadata) – Metadata for image. Defaults to Metadata().

dmtools.transform module

class dmtools.transform.CompositeOp(alpha, color)

Bases: tuple

Image alpha compositing operators.

To learn more about image alpha compositing, see Alpha Compositing.

Parameters
  • alpha (Callable) – The function producing the alpha of the resulting image.

  • color (Callable) – The function producing the color of the resulting image.

Create new instance of CompositeOp(alpha, color)

property alpha

Alias for field number 0

property color

Alias for field number 1

class dmtools.transform.CompositeOpName(value)[source]

Bases: Enum

An enumeration of supported image alpha compositing operator names.

The supported operators are a subset of Cairo operators.

  • (OVER): two semi-transparent slides; source over dest.

  • (DEST_OVER): two semi-transparent slides; dest over source.

  • (ADD): Add source and dest.

ADD = CompositeOp(alpha=<function _add_alpha_composite>, color=<function _add_color_composite>)
DEST_OVER = CompositeOp(alpha=<function _dest_over_alpha_composite>, color=<function _dest_over_color_composite>)
OVER = CompositeOp(alpha=<function _over_alpha_composite>, color=<function _over_color_composite>)
class dmtools.transform.Loc(value)[source]

Bases: Enum

An enumeration.

CENTER = 'center'
LOWER_LEFT = 'lower_left'
UPPER_LEFT = 'upper_left'
class dmtools.transform.ResizeFilter(weighting_function, support)

Bases: tuple

Image resize filter.

To learn more about image resize filters, see the ImageMagick reference on Resampling Filters.

Parameters
  • weighting_function (Callable) – Weighting function defined on [0, support].

  • support (float) – The ideal neighborhood size of the filter.

Create new instance of ResizeFilter(weighting_function, support)

property support

Alias for field number 1

property weighting_function

Alias for field number 0

class dmtools.transform.ResizeFilterName(value)[source]

Bases: Enum

An enumeration of supported resize filter names.

The supported filters are a subset of ImageMagick filters.

BOX = ResizeFilter(weighting_function=<function _box_weighting_function>, support=0.5)
CATROM = ResizeFilter(weighting_function=<function _catmull_rom_weighting_function>, support=2.0)
GAUSSIAN = ResizeFilter(weighting_function=<function _gaussian_weighting_function>, support=2.0)
POINT = ResizeFilter(weighting_function=<function _box_weighting_function>, support=0.0)
TRIANGLE = ResizeFilter(weighting_function=<function _triangle_weighting_function>, support=1.0)
dmtools.transform.blur(image: ndarray, sigma: float, radius: float = 0) ndarray[source]

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: ndarray) ndarray[source]

Clip gray/color values that are out of bounds.

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

Parameters

image (np.ndarray) – Image to clip.

Returns

Clipped image.

Return type

np.ndarray

dmtools.transform.composite(source: ndarray, dest: ndarray, operator: Union[CompositeOpName, CompositeOp] = CompositeOpName.OVER) ndarray[source]

Return the image formed by compositing one image with another.

For more information about alpha compositing, see Alpha Compositing. The implementation is largely based on the Cairo implementation.

Parameters
  • source (np.ndarray) – Image on top.

  • dest (np.ndarray) – Image on bottom.

  • operator (Union[CompositeOpName, CompositeOp]) – The compositing operator to use.

Returns

The two images overlaid.

Return type

np.ndarray

dmtools.transform.crop(image: ndarray, x: float, y: float, w: float, h: float, relative: bool = False, loc: Loc = Loc.UPPER_LEFT) ndarray[source]

Crop an image using an (x,y) point, width, and height.

Parameters
  • image (np.ndarray) – Image to be cropped.

  • x (float) – x coordinate of the point (relative to left of image).

  • y (float) – y coordinate of the point (relative to top of image).

  • w (float) – Width of the cropped portion.

  • h (float) – Height of the cropped portion.

  • relative (bool) – If True, x, y, w, and h are given relative to the dimensions of the image. Defaults to False.

  • loc (Loc) – Location of (x,y) relative to substituted portion.

Returns

The cropped portion of the image.

Return type

np.ndarray

dmtools.transform.normalize(image: ndarray) ndarray[source]

Normalize the image to bring all gray/color values into bounds.

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

Parameters

image (np.ndarray) – Image to normalize.

Returns

Normalized image.

Return type

np.ndarray

dmtools.transform.rescale(image: ndarray, k: int = - 1, w: int = - 1, h: int = - 1, filter: Union[ResizeFilterName, ResizeFilter] = ResizeFilterName.POINT, **kwargs) ndarray[source]

Rescale the image.

Provide either a global scale factor k or the desired dimensions (w,h) of the rescaled image. This image rescale implentation is largley based off of the ImageMagick impmenetation.

Parameters
  • image (np.ndarray) – Image to rescale.

  • k (int) – Scaling factor.

  • w (int) – Desired width (in pixels).

  • h (int) – Desired height (in pixels).

  • filter (Union[ResizeFilterName, ResizeFilter]) – Resize filter to use.

Returns

Rescaled image.

Return type

np.ndarray

dmtools.transform.substitute(image: ndarray, substitution: ndarray, x: float, y: float, relative: bool = False, loc: Loc = Loc.UPPER_LEFT) ndarray[source]

Substitute a portion of image with substitution.

Parameters
  • image (np.ndarray) – Base image.

  • substitution (np.ndarray) – Image to substitute into the base image.

  • x (float) – x coordinate of the point (relative to left of image).

  • y (float) – y coordinate of the point (relative to top of image).

  • relative (bool) – If True, x, y, w, and h are given relative to the dimensions of the image. Defaults to False.

  • loc (Loc) – Location of (x,y) relative to substituted portion.

Returns

The image with substitution substituted in.

Return type

np.ndarray

dmtools.transform.wraparound(image: ndarray) ndarray[source]

Wraparound gray/color values that are out of bounds.

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

Parameters

image (np.ndarray) – Image to wraparound

Returns

Wraparound image.

Return type

np.ndarray

dmtools.adjustments module

dmtools.adjustments.apply_curve(image: ndarray, f: Callable, c: int = - 1) ndarray[source]

Apply a curve f to an image or channel of an image.

Parameters
  • image (np.ndarray) – Image on which to apply curve.

  • f (Callable) – Curve to apply. f: [0,1] -> [0,1].

  • c (int) – Channel to apply curve to. Apply to all channels if -1.

Returns

Image with curve applied.

Return type

np.ndarray

dmtools.colorspace module

dmtools.colorspace.Lab_to_RGB(image: ndarray, illuminant: str = 'D65') ndarray[source]

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: ndarray, illuminant: str = 'D65') ndarray[source]

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: ndarray, illuminant: str = 'D65') ndarray[source]

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: ndarray) ndarray[source]

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: ndarray) ndarray[source]

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: ndarray) ndarray[source]

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: ndarray, illuminant: str = 'D65') ndarray[source]

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: ndarray) ndarray[source]

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: ndarray) ndarray[source]

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.add_alpha(image: ndarray, a: float = 1) ndarray[source]

Add an alpha channel to a three color channel image.

Parameters
  • image (np.ndarray) – Image with three color channels.

  • a (float) – Alpha value to use in the image.

Returns

Four channel image with alpha channel.

Return type

np.ndarray

dmtools.colorspace.denormalize(image: ndarray, color_space: str) ndarray[source]

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: ndarray) ndarray[source]

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: ndarray, color_space: str) ndarray[source]

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[ndarray][source]

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[ndarray], path: str, fps: int, s: int = 1, audio: Optional[WAV] = None)[source]

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.sound module

class dmtools.sound.WAV(r: ndarray, l: ndarray, sample_rate: int = 44100)[source]

Bases: object

An object representing a WAV audio file.

For more information about the audio file format, see WAV

Initialize a WAV sound.

Parameters
  • r (np.ndarray) – NumPy array of samples of the right channel.

  • l (np.ndarray) – NumPy array of samples of the left channel.

  • sample_rate (int) – Sample rate. Defaults to SAMPLE_RATE.

to_wav(path)[source]

Write object to a WAV audio file (wav)

Parameters

path (str) – String file path.

dmtools.sound.wave(f: float, a: float, t: float) ndarray[source]

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: ndarray, t) WAV[source]

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: ndarray, b: int, color: Optional[ndarray] = None) ndarray[source]

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 (np.ndarray) – Pixel to use for bordering. Defaults to white.

Returns

Image with border added.

Return type

np.ndarray

dmtools.arrange.image_grid(images: List[ndarray], w: int, h: int, b: int, color: Optional[ndarray] = None) ndarray[source]

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 (np.ndarray) – Pixel to use for bordering. Defaults to white.

Returns

grid layout of the images.

Return type

np.ndarray