Noisemaker API

Images are seamlessly tiled float32 tensors (0..1 range), with shape (height, width, channels).

This is a pre-1.0 API, and may receive backwards incompatible changes.

Interactive help is available.

(venv)$ python
>>> from noisemaker import effects, generators
>>>
>>> help(generators)
>>> help(effects)

noisemaker.generators

class noisemaker.generators.Distribution[source]

Bases: enum.Enum

Specify the random distribution function for basic noise.

See also: https://docs.scipy.org/doc/numpy/reference/routines.random.html

image = basic(freq, [height, width, channels], distrib=Distribution.uniform)
exponential = 2
laplace = 3
lognormal = 4
normal = 0
uniform = 1
noisemaker.generators.basic(freq, shape, ridges=False, wavelet=False, spline_order=3, seed=None, distrib=<Distribution.normal: 0>, lattice_drift=0.0, **post_process_args)[source]

Generate a single layer of scaled noise.

Noisemaker example output (CC0)
Parameters:
  • freq (int|list[int]) – Base noise frequency. Int, or list of ints for each spatial dimension.
  • list[int] – Shape of noise. For 2D noise, this is [height, width, channels].
  • ridges (bool) – “Crease” at midpoint values: (1 - abs(n * 2 - 1))
  • wavelet (bool) – Maybe not wavelets this time?
  • spline_order (int) – Spline point count. 0=Constant, 1=Linear, 2=Cosine, 3=Bicubic
  • distrib (int|Distribution) – Type of noise distribution. See Distribution enum.
  • lattice_drift (float) – Push away from underlying lattice.
  • seed (int) – Random seed for reproducible output. Ineffective with exponential.
Returns:

Tensor

Additional keyword args will be sent to noisemaker.effects.post_process()

noisemaker.generators.multires(freq, shape, octaves=4, ridges=True, wavelet=False, spline_order=3, seed=None, reflect_range=0.0, refract_range=0.0, reindex_range=0.0, distrib=<Distribution.normal: 0>, deriv=False, deriv_func=0, lattice_drift=0.0, post_reflect_range=0.0, post_refract_range=0.0, **post_process_args)[source]

Generate multi-resolution value noise. For each octave: freq increases, amplitude decreases.

Noisemaker example output (CC0)
Parameters:
  • freq (int|list[int]) – Bottom layer frequency. Int, or list of ints for each spatial dimension.
  • list[int] – Shape of noise. For 2D noise, this is [height, width, channels].
  • octaves (int) – Octave count. Number of multi-res layers. Typically 1-8.
  • ridges (bool) – “Crease” at midpoint values: (1 - abs(n * 2 - 1))
  • wavelet (bool) – Maybe not wavelets this time?
  • spline_order (int) – Spline point count. 0=Constant, 1=Linear, 2=Cosine, 3=Bicubic
  • seed (int) – Random seed for reproducible output. Ineffective with exponential.
  • reflect_range (float) – Per-octave derivative-based distort gradient.
  • refract_range (float) – Per-octave self-distort gradient.
  • reindex_range (float) – Per-octave self-reindexing gradient.
  • distrib (int|Distribution) – Type of noise distribution. See Distribution enum.
  • deriv (bool) – Derivative noise.
  • deriv_func (DistanceFunction|int) – Derivative distance function
  • lattice_drift (float) – Push away from underlying lattice.
  • post_reflect_range (float) – Derivative-based distort gradient.
  • post_refract_range (float) – Self-distort gradient.
Returns:

Tensor

Additional keyword args will be sent to noisemaker.effects.post_process()

noisemaker.effects

class noisemaker.effects.ConvKernel[source]

Bases: enum.Enum

A collection of convolution kernels for image post-processing, based on well-known recipes.

Pass the desired kernel as an argument to convolve().

image = convolve(ConvKernel.shadow, image)
blur = [[1, 4, 6, 4, 1], [4, 16, 24, 16, 4], [6, 24, 36, 24, 6], [4, 16, 24, 16, 4], [1, 4, 6, 4, 1]]
deriv_x = [[0, 0, 0], [0, -1, 1], [0, 0, 0]]
deriv_y = [[0, 0, 0], [0, -1, 0], [0, 1, 0]]
edges = [[1, 2, 1], [2, -12, 2], [1, 2, 1]]
emboss = [[0, 2, 4], [-2, 1, 2], [-4, -2, 0]]
invert = [[0, 0, 0], [0, -1, 0], [0, 0, 0]]
rand = <MagicMock name='mock.normal().tolist()' id='139723598599616'>
shadow = [[0, 1, 1, 1, 1, 1, 1], [-1, 0, 2, 2, 1, 1, 1], [-1, -2, 0, 2, 2, 1, 1], [-1, -2, -4, 12, 2, 2, 1], [-1, -1, -2, -4, 0, 2, 1], [-1, -1, -1, -2, -2, 0, 1], [-1, -1, -1, -1, -1, -1, 0]]
sharpen = [[0, -1, 0], [-1, 5, -1], [0, -1, 0]]
sobel_x = [[1, 0, -1], [2, 0, -2], [1, 0, -1]]
sobel_y = [[1, 2, 1], [0, 0, 0], [-1, -2, -1]]
unsharp_mask = [[1, 4, 6, 4, 1], [4, 16, 24, 16, 4], [6, 24, -476, 24, 6], [4, 16, 24, 16, 4], [1, 4, 6, 4, 1]]
class noisemaker.effects.DistanceFunction[source]

Bases: enum.Enum

Specify the distance function used for Voronoi cells.

chebyshev = 2
euclidean = 0
manhattan = 1
class noisemaker.effects.WormBehavior[source]

Bases: enum.Enum

Specify the type of heading bias for worms to follow.

image = worms(image, behavior=WormBehavior.unruly)
chaotic = 3
crosshatch = 1
obedient = 0
unruly = 2
noisemaker.effects.blend(a, b, g)[source]

Blend a and b values with linear interpolation.

Parameters:
  • a (Tensor) –
  • b (Tensor) –
  • g (Tensor) – Blending gradient a to b (0..1)
Return Tensor:
noisemaker.effects.blend_cosine(a, b, g)[source]

Blend a and b values with cosine interpolation.

Parameters:
  • a (Tensor) –
  • b (Tensor) –
  • g (Tensor) – Blending gradient a to b (0..1)
Return Tensor:
noisemaker.effects.blend_cubic(a, b, c, d, g)[source]

Blend b and c values with bi-cubic interpolation.

Parameters:
  • a (Tensor) –
  • b (Tensor) –
  • c (Tensor) –
  • d (Tensor) –
  • g (Tensor) – Blending gradient b to c (0..1)
Return Tensor:
noisemaker.effects.center_mask(center, edges, shape)[source]

Blend two image tensors from the center to the edges. Not perfect.

Parameters:
  • center (Tensor) –
  • edges (Tensor) –
  • shape (list[int]) –
Returns:

Tensor

noisemaker.effects.color_map(tensor, clut, shape, horizontal=False, displacement=0.5)[source]

Apply a color map to an image tensor.

The color map can be a photo or whatever else.

Noisemaker example output (CC0)
Parameters:
  • tensor (Tensor) –
  • clut (Tensor|str) – An image tensor or filename (png/jpg only) to use as a color palette
  • shape (list[int]) –
  • horizontal (bool) – Scan horizontally
  • displacement (float) – Gather distance for clut
noisemaker.effects.column_index(shape)[source]

Generate a Y index for the given tensor.

[
  [ 0, 0, 0, ... ],
  [ 1, 1, 1, ... ],
  [ n, n, n, ... ],
  ...
  [ height-1, height-1, height-1, ... ]
]
Parameters:shape (list[int]) –
Returns:Tensor
noisemaker.effects.convolve(kernel, tensor, shape, with_normalize=True)[source]

Apply a convolution kernel to an image tensor.

Parameters:
  • kernel (ConvKernel) – See ConvKernel enum
  • tensor (Tensor) – An image tensor.
  • shape (list[int]) –
  • with_normalize (bool) – Normalize output (True)
Returns:

Tensor

noisemaker.effects.crease(tensor)[source]

Create a “crease” (ridge) at midpoint values. 1 - abs(n * 2 - 1)

Noisemaker example output (CC0)
Parameters:tensor (Tensor) – An image tensor.
Returns:Tensor
noisemaker.effects.derivative(tensor, shape, dist_func=0)[source]

Extract a derivative from the given noise.

Noisemaker example output (CC0)
Parameters:
  • tensor (Tensor) –
  • shape (list[int]) –
  • dist_func (DistanceFunction|int) – Derivative distance function
Returns:

Tensor

noisemaker.effects.distance(a, b, func)[source]

Compute the distance from a to b using the specified function.

Parameters:
  • a (Tensor) –
  • b (Tensor) –
  • dist_func (DistanceFunction|int) – Distance function (0=Euclidean, 1=Manhattan, 2=Chebyshev)
Returns:

Tensor

noisemaker.effects.erode(tensor, shape)[source]

WIP hydraulic erosion effect.

noisemaker.effects.freq_for_shape(freq, shape)[source]

Given a base frequency as int, generate noise frequencies for each spatial dimension.

Parameters:
  • freq (int) – Base frequency
  • shape (list[int]) – List of spatial dimensions, e.g. [height, width]
noisemaker.effects.jpeg_decimate(tensor)[source]

Needs more JPEG? Never again.

Parameters:tensor (Tensor) –
Returns:Tensor
noisemaker.effects.normal_map(tensor, shape)[source]

Generate a tangent-space normal map.

Parameters:
  • tensor (Tensor) –
  • shape (list[int]) –
Returns:

Tensor

noisemaker.effects.normalize(tensor)[source]

Squeeze the given Tensor into a range between 0 and 1.

Parameters:tensor (Tensor) – An image tensor.
Returns:Tensor
noisemaker.effects.offset_index(y_index, height, x_index, width)[source]

Offset X and Y displacement channels from each other, to help with diagonal banding.

Returns a combined Tensor with shape [height, width, 2]

Parameters:
  • y_index (Tensor) – Tensor with shape [height, width, 1], containing Y indices
  • height (int) –
  • x_index (Tensor) – Tensor with shape [height, width, 1], containing X indices
  • width (int) –
Returns:

Tensor

noisemaker.effects.post_process(tensor, shape, freq, spline_order=1, reflect_range=0.0, refract_range=0.0, reindex_range=0.0, clut=None, clut_horizontal=False, clut_range=0.5, with_worms=False, worms_behavior=None, worms_density=4.0, worms_duration=4.0, worms_stride=1.0, worms_stride_deviation=0.05, worms_bg=0.5, worms_kink=1.0, with_sobel=False, sobel_func=0, with_normal_map=False, deriv=False, deriv_func=0, with_wormhole=False, wormhole_kink=2.5, wormhole_stride=0.1, with_voronoi=False, voronoi_density=0.1, voronoi_nth=0, voronoi_func=0, posterize_levels=0, with_erosion_worms=False, warp_range=0.0, warp_octaves=3, **convolve_kwargs)[source]

Apply post-processing effects.

Parameters:
  • tensor (Tensor) –
  • shape (list[int]) –
  • freq (list[int]) –
  • spline_order (int) – Ortho spline point count. 0=Constant, 1=Linear, 2=Cosine, 3=Bicubic
  • reflect_range (float) – Derivative distortion gradient.
  • refract_range (float) – Self-distortion gradient.
  • reindex_range (float) – Self-reindexing gradient.
  • clut (str) – PNG or JPG color lookup table filename.
  • clut_horizontal (float) – Preserve clut Y axis.
  • clut_range (float) – Gather range for clut.
  • with_worms (bool) – Do worms.
  • worms_behavior (WormBehavior) –
  • worms_density (float) – Worm density multiplier (larger == slower)
  • worms_duration (float) – Iteration multiplier (larger == slower)
  • worms_stride (float) – Mean travel distance per iteration
  • worms_stride_deviation (float) – Per-worm travel distance deviation
  • worms_bg (float) – Background color brightness for worms
  • worms_kink (float) – Worm twistiness
  • with_sobel (bool) – Sobel operator
  • sobel_func (DistanceFunction|int) – Sobel distance function
  • with_normal_map (bool) – Create a tangent-space normal map
  • with_wormhole (bool) – Wormhole effect. What is this?
  • wormhole_kink (float) – Wormhole kinkiness, if you’re into that.
  • wormhole_stride (float) – Wormhole thickness range
  • with_voronoi (bool) – Voronoi cells
  • voronoi_density (float) – Voronoi cell count multiplier
  • voronoi_nth (int) – Voronoi Nth nearest
  • voronoi_func (DistanceFunction|int) – Voronoi distance function
  • deriv (bool) – Derivative operator
  • deriv_func (DistanceFunction|int) – Derivative distance function
  • posterize_levels (float) – Posterize levels
  • with_erosion_worms (bool) – Erosion worms
  • warp_range (float) – Orthogonal distortion gradient.
  • warp_octaves (int) – Multi-res iteration count for warp
Returns:

Tensor

noisemaker.effects.posterize(tensor, levels)[source]

Reduce the number of color levels per channel.

Parameters:
  • tensor (Tensor) –
  • levels (int) –
Returns:

Tensor

noisemaker.effects.refract(tensor, shape, displacement=0.5, reference_x=None, reference_y=None, warp_freq=None, spline_order=1, from_derivative=False)[source]

Apply self-displacement along X and Y axes, based on each pixel value.

Noisemaker example output (CC0)
Parameters:
  • tensor (Tensor) – An image tensor.
  • shape (list[int]) –
  • displacement (float) –
  • reference_x (Tensor) – An optional horizontal displacement map.
  • reference_y (Tensor) – An optional vertical displacement map.
  • warp_freq (list[int]) – If given, generate new reference_x and reference_y noise with this base frequency.
  • spline_order (int) – Ortho offset spline point count. 0=Constant, 1=Linear, 2=Cosine, 3=Bicubic
  • from_derivative (bool) – If True, generate X and Y offsets from noise derivatives.
Returns:

Tensor

noisemaker.effects.reindex(tensor, shape, displacement=0.5)[source]

Re-color the given tensor, by sampling along one axis at a specified frequency.

Noisemaker example output (CC0)
Parameters:
  • tensor (Tensor) – An image tensor.
  • shape (list[int]) –
  • displacement (float) –
Returns:

Tensor

noisemaker.effects.resample(tensor, shape, spline_order=3)[source]

Resize an image tensor to the specified shape.

Parameters:
  • tensor (Tensor) –
  • shape (list[int]) –
  • spline_order (int) – Spline point count. 0=Constant, 1=Linear, 2=Cosine, 3=Bicubic
Returns:

Tensor

noisemaker.effects.row_index(shape)[source]

Generate an X index for the given tensor.

[
  [ 0, 1, 2, ... width-1 ],
  [ 0, 1, 2, ... width-1 ],
  ... (x height)
]
Parameters:shape (list[int]) –
Returns:Tensor
noisemaker.effects.sobel(tensor, shape, dist_func=0)[source]

Apply a sobel operator.

Parameters:
  • tensor (Tensor) –
  • shape (list[int]) –
  • dist_func (DistanceFunction|int) – Sobel distance function
Returns:

Tensor

noisemaker.effects.value_map(tensor, shape, keep_dims=False)[source]

Create a grayscale value map from the given image Tensor by reducing the sum across channels.

Parameters:
  • tensor (Tensor) –
  • shape (list[int]) –
  • keep_dims (bool) – If True, don’t collapse the channel dimension.
noisemaker.effects.voronoi(tensor, shape, density=0.1, nth=0, dist_func=0)[source]

Create a voronoi diagram, blending with input image Tensor color values.

Parameters:
  • tensor (Tensor) –
  • shape (list[int]) –
  • density (float) – Cell count multiplier (1.0 = min(height, width); larger is more costly) `
  • nth (float) – Plot Nth nearest neighbor, or -Nth farthest
  • dist_func (DistanceFunction|int) – Voronoi distance function (0=Euclidean, 1=Manhattan, 2=Chebyshev)
Returns:

Tensor

noisemaker.effects.warp(tensor, shape, freq, octaves=5, displacement=1, spline_order=3)[source]
noisemaker.effects.wavelet(tensor, shape)[source]

Convert regular noise into 2-D wavelet noise.

Completely useless. Maybe useful if Noisemaker supports higher dimensions later.

Noisemaker example output (CC0)
Parameters:
  • tensor (Tensor) – An image tensor.
  • shape (list[int]) –
Returns:

Tensor

noisemaker.effects.wormhole(tensor, shape, kink, input_stride)[source]

Apply per-pixel field flow. Non-iterative.

Parameters:
  • tensor (Tensor) –
  • shape (list[int]) –
  • kink (float) – Path twistiness
  • input_stride (float) – Maximum pixel offset
Returns:

Tensor

noisemaker.effects.worms(tensor, shape, behavior=0, density=4.0, duration=4.0, stride=1.0, stride_deviation=0.05, bg=0.5, kink=1.0, colors=None)[source]

Make a furry patch of worms which follow field flow rules.

Noisemaker example output (CC0)
Parameters:
  • tensor (Tensor) –
  • shape (list[int]) –
  • behavior (int|WormBehavior) –
  • density (float) – Worm density multiplier (larger == slower)
  • duration (float) – Iteration multiplier (larger == slower)
  • stride (float) – Mean travel distance per iteration
  • stride_deviation (float) – Per-worm travel distance deviation
  • bg (float) – Background color intensity.
  • kink (float) – Make your worms twist.
  • colors (Tensor) – Optional starting colors, if not from tensor.
Returns:

Tensor

noisemaker.recipes

noisemaker.recipes.crt(tensor, shape)[source]

Apply vintage CRT snow and scanlines.

Parameters:
  • tensor (Tensor) –
  • shape (list[int]) –
noisemaker.recipes.dither(tensor, shape, amount)[source]
noisemaker.recipes.glitch(tensor, shape)[source]

Apply a glitch effect.

Parameters:
  • tensor (Tensor) –
  • shape (list[int]) –
Returns:

Tensor

noisemaker.recipes.pop(tensor, shape)[source]
noisemaker.recipes.post_process(tensor, shape, freq, with_glitch, with_vhs, with_crt, with_scan_error, with_snow, with_dither)[source]

Apply complex post-processing recipes.

Parameters:
  • tensor (Tensor) –
  • shape (list[int]) –
  • freq (int) –
  • with_glitch (bool) – Glitch effect (Bit shit)
  • with_vhs (bool) – VHS effect (Shitty tracking)
  • with_crt (bool) – Vintage TV effect
  • with_scan_error (bool) – Horizontal scan error
  • with_snow (float) – Analog broadcast snow
  • with_dither (float) – Per-pixel brightness jitter
Returns:

Tensor

noisemaker.recipes.scanline_error(tensor, shape)[source]
noisemaker.recipes.snow(tensor, shape, amount)[source]
noisemaker.recipes.vhs(tensor, shape)[source]

Apply a bad VHS tracking effect.

Parameters:
  • tensor (Tensor) –
  • shape (list[int]) –
Returns:

Tensor

noisemaker.util

noisemaker.util.save(tensor, name='noise.png')[source]

Save an image Tensor to a file.

Parameters:
  • tensor (Tensor) – Image tensor
  • name (str) – Filename, ending with .png or .jpg
Returns:

None