dmtools package
dmtools.io module
- dmtools.io.read(path: str) numpy.ndarray
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) numpy.ndarray
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) 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_netpbm(image: numpy.ndarray, k: int, path: str, comment: List[str] = [])
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.
comment (str) – List of comment lines to include in the file.
- dmtools.io.write_png(image: numpy.ndarray, path: str)
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.
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 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: numpy.ndarray) numpy.ndarray
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.normalize(image: numpy.ndarray) numpy.ndarray
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: 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) numpy.ndarray
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: numpy.ndarray, f: Callable, c: int = - 1) numpy.ndarray
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: 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.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.image_to_ascii(image: numpy.ndarray) 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 (np.ndarray) – An image.
- Returns
ASCII representation of image.
- Return type
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
dmtools.arrange module
- dmtools.arrange.border(image: numpy.ndarray, b: int, color: int = 'white') 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).
- 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') 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).
- Returns
grid layout of the images.
- Return type
np.ndarray