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
andP4
).pgm: Pixels are shades of gray (
P2
andP5
).ppm: Pixels are in full color (
P3
andP6
).
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
, andP3
).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.
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.
- 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 ofradius
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.
- 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.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