NAME

Math::Fractal::Noisemaker - Visual noise generator

VERSION

This document is for version 0.105 of Math::Fractal::Noisemaker.

SYNOPSIS

  use Math::Fractal::Noisemaker;

  Math::Fractal::Noisemaker::make();

See MAKE ARGS.

A command-line utility, make-noise, is included with this distribution. make-noise is a complete wrapper to this module.

  make-noise -h
  make-noise -h types

DESCRIPTION

Math::Fractal::Noisemaker provides a simple functional interface for generating several types of two-dimensional grayscale noise, which may be combined in interesting and novel ways.

This module isn't fast, but it can output production-quality noise for use in games or other media, and also serve as an educational toy.

FUNCTION

make(%ARGS)
Generate a new noise set, and save the resulting image to disk.

Returns an Imager instance containing final noise values, and filename which was used.

All args are optional. This function accepts many arguments; see MAKE ARGS, in this document.
```
  make();

  # my ($img, $filename) = make(
    #
    # Any MAKE ARGS or noise args here!
    #
  # );
```
Noisemaker's typical usage is via this function's command-line wrapper, make-noise.
```
  make-noise -h

  make-noise -type worley    # does make(type => "worley")
```

NOISE TYPES

To specify a noise type, use the type arg, for example:

  make-noise -type gradient

If generating multi-res noise, any single-res noise type may be specified as the slice type (stype), for example:

  make-noise -type ridged -stype gradient

SINGLE-RES NOISE

white

Each non-smoothed pixel contains a pseudo-random value.

See SINGLE-RES ARGS for allowed arguments.
```
  make(type => "white", ...);

  #
  # As a multi-res basis:
  #
  make(stype => "white", ...);
```

wavelet

wavelet noise example

Basis function for sharper multi-res slices

See SINGLE-RES ARGS for allowed arguments.

  make(type => "wavelet", ...);

  #
  # As a multi-res basis:
  #
  make(stype => "wavelet", ...);

gradient

Persistent gradient noise.

See SINGLE-RES ARGS for allowed arguments.

  make(type => "gradient", ...);

  #
  # As a multi-res basis:
  #
  make(stype => "gradient", ...);

simplex

Another gradient noise function described by Ken Perlin. Not much speed benefit in 2D, but it has a distinct flavor. I like it.

See tile arg to control forced tiling mode.
```
  make(type => "simplex", ...);

  #
  # As a multi-res basis:
  #
  make(stype => "simplex", ...);
```

simplex2

simplex2 noise example

Interpolated simplex noise which naturally tiles.

  make(type => "simplex2", ...);

  #
  # As a multi-res basis:
  #
  make(stype => "simplex2", ...);

square

Diamond-Square

See SINGLE-RES ARGS for allowed arguments.

persist arg is also permitted.
```
  make(type => "square", ...);
```

gel

gel noise example

Self-displaced white noise.

See SINGLE-RES ARGS and GEL TYPE ARGS for allowed arguments.

  make(type => "gel", ...);

  #
  # This can be fun
  #
  make(stype => "gel", octaves => 3, ...);

sgel

Self-displaced Diamond-Square noise.

See SINGLE-RES ARGS and GEL TYPE ARGS for allowed arguments.

persist arg is also permitted.
```
  make(type => "sgel", ...);
```
dla

Diffusion-limited aggregation, seeded from multiple random points.

See SINGLE-RES ARGS for allowed arguments.

freq arg determines number of seed points.

bias and amp currently have no effect.
```
  make(type => "dla", ...);
```
mandel
$mandelbrot fractal example$

Fractal type - Mandelbrot. Included as a demo.

See SINGLE-RES ARGS and FRACTAL ARGS for allowed arguments.

bias and amp currently have no effect.

Example maxiter value: 256
```
  make(type => "mandel", ...);
```
dmandel
$deep mandelbrot fractal example$

Fractal type - Deep Mandelbrot. Picks a random "interesting" location in the set (some point with a value which neither hovers near 0 nor flies off into infinity), and zooms in a random amount (unless an explicit zoom arg was provided).

See SINGLE-RES ARGS and FRACTAL ARGS for allowed arguments.

bias and amp currently have no effect.

Example maxiter value: 256
```
  make(type => "dmandel", ...);
```
buddha
$buddhabrot fractal example$

Fractal type - "Buddhabrot" Mandelbrot variant. Shows the paths of slowly escaping points, density-mapped to escape time.

See SINGLE-RES ARGS and FRACTAL ARGS for allowed arguments.

bias and amp currently have no effect. This type does not zoom well, due to the diminished sample of escaping points.

Example maxiter value: 4096
```
  make(type => "buddha", ...);
```
julia
$julia fractal example$

Fractal type - Julia. Included as demo.

See SINGLE-RES ARGS and FRACTAL ARGS for allowed arguments.

bias and amp currently have no effect.

zoom is not yet implemented for this type.

Example maxiter value: 200
```
  make(type => "julia", ...);
```
djulia
$deep julia fractal example$

Fractal type - Deep Julia. Zoomed in to a random location, which might not even be in the Julia set at all. Not currently very smart, but pretty, and pretty slow. maxiter is very low by default.

See SINGLE-RES ARGS and FRACTAL ARGS for allowed arguments.

bias and amp currently have no effect.

zoom is not yet implemented for this type.

Example maxiter value: 200
```
  make(type => "djulia", ...);
```
newton
$newton fractal example$

Fractal type - Newton. Included as demo.

Currently, this function is ridiculously slow.

See SINGLE-RES ARGS and FRACTAL ARGS for allowed arguments.

bias and amp currently have no effect.

zoom is not yet implemented for this type.

Example maxiter value: 10
```
  make(type => "newton", ...);
```
fflame
$ifs fractal flame example$

IFS type - "Fractal Flame". Slow but neat.

See SINGLE-RES ARGS and FRACTAL ARGS for allowed arguments.

bias and amp currently have no effect.

Example maxiter value: 6553600
```
  make(type => "fflame", ...);
```
fern

IFS type - Barnsley's fern. Included as a demo.
```
  make(type => "fern", ...);
```
gasket

IFS type - Sierpinski's triangle/gasket. Included as a demo.
```
  make(type => "gasket", ...);
```
stars

White noise generated with extreme gap, and smoothed

See SINGLE-RES ARGS for allowed arguments.

bias and amp currently have no effect.
```
  make(type => "stars", ...);
```
spirals

Tiny logarithmic spirals

See SINGLE-RES ARGS for allowed arguments.

bias and amp currently have no effect.
```
  make(type => "spirals", ...);
```
moire

Interference pattern with blended image seams.

Appearance of output is heavily influenced by the freq arg.

bias and amp currently have no effect.
```
  make(type => "moire", ...);
```
textile

Moire noise with a randomized and large freq arg.

bias and amp currently have no effect.
```
  make(type => "textile", ...);
```

infile

Import the brightness values from the file specified by the "in" or "-in" arg.

  make(type => "infile", in => "dirt.bmp", ...);

  #
  # also
  #
  my $grid = infile(in => "dirt.bmp", ...);

sparkle

Stylized starfield

bias and amp currently have no effect.
```
  make(type => "sparkle", ...);
```
canvas

Unsmoothed square noise with perpenticular linear blur
```
  make(type => "canvas", ...);
```
worley
Voronoi cell noise.

Specify Nth closest neighbor with nth arg, or will default to an nth of the freq's square root, which tends to produce a neat 3D-looking effect.

Specify an nth of 0 for "traditional" voronoi cells.

Specify a cell argument of "1" to use gray-mapped cells, rather than distance gradient.

Specify dist function as 0 (Euclidean), 1 (Manhattan), 2 (Chebyshev), or 3 (Bendy?)

Specify tile to override seam blending (see docs).

freq arg determines number of seed points.
```
  make(type => "worley", nth => 1, dist => 3, ...);

  #
  # As a multi-res basis:
  #
  make(stype => "worley", nth => 0, octaves => 3);
```
wgel
Self-displaced worley noise. Quite bendy.

See SINGLE-RES ARGS and GEL TYPE ARGS for allowed arguments.

Also accepts "nth" and "dist" worley args.
```
  make(type => "wgel", ...);

  #
  # As a multi-res basis:
  #
  make(stype => "wgel", octaves => 3, ...);
```

MULTI-RES TYPES

Multi-res noise combines the values from multiple 2D slices (octaves), which are generated using progressively higher frequencies and lower amplitudes.

The slice type used for generating multi-res noise may be controlled with the stype argument. Any single-res type may be specified.

The default slice type is smoothed white noise.

multires

Multi-resolution noise.

See MULTI-RES ARGS for allowed args.
```
  make(type => 'multires', stype => '...');
```
ridged

Ridged multifractal.

See MULTI-RES ARGS for allowed args.

Provide zshift arg to specify a post-processing bias.
```
  make(type => 'ridged', stype => '...', zshift => .5 );
```
block

Unsmoothed multi-resolution.

See MULTI-RES ARGS for allowed args.
```
  make(type => 'block', stype => ...);
```
pgel

Self-displaced multi-res noise.

See MULTI-RES ARGS and GEL TYPE ARGS for allowed args.
```
  make(type => 'pgel', stype => ...);
```
fur

Traced "worm paths" from multi-res input.

See MULTI-RES ARGS for allowed args.
tesla

Long, fiberous worm paths with random skew.

See MULTI-RES ARGS for allowed args.
lumber

Noise with heavy forced banding.

See MULTI-RES ARGS for allowed args.
wormhole

Noise values displaced according to field flow rules, and plotted.

amp controls displacement amount (eg 8).

See MULTI-RES ARGS for allowed args.
flux

Noise values extruded in three dimensions, and plotted.

amp controls extrusion amount (eg 8).

See MULTI-RES ARGS for allowed args.

BONUS NOISE

terra

terra example

Multi-layered complex noise. Very slow.

See TERRA ARGS for additional arguments.

Example:

  make(
    type   => "terra",
    lbase  => "multires",   # Layer base = continent shapes
    ltype  => "ridged",   # Layer type = elevation layers
    stype  => "simplex2", # Basis function is any simple type

    clut     => "color.bmp", # color lookup table
    clutdir  => 1,  # vertical "polar" lookup
    shadow   => .5, # false shadow
    grow     => 1,  # gaussian spread
    sphere   => 1,  # false spheremap

  );

NOISE ARGS

MAKE ARGS

In addition to any argument appropriate to the type of noise being generated, make accepts the following args in hash key form:

type => $noiseType
The type of noise to generate, defaults to multires. Specify any type.
```
  make(type => 'gel');
```
quality => 0|1|2|3
Sets levels for smooth, interp, and grow in one swoop. These may also be overridden individually, see docs.
```
  0: no smoothing, no interpolation, no growth (fastest)
  1: smoothing, linear interpolation, no growth
  2: smoothing, cosine interpolation, no growth
  3: smoothing, cosine interpolation, gaussian growth (slowest)
```
Add a "+" to the quality argument to disable upsampling. This will render noise at the image's natural resolution, which is slower but looks nicer, eg:
```
  make(quality => "2+");
```
sphere => $bool

Generate a false spheremap from the resulting noise. This will output as a 2:1 rectangular image.
```
  make(sphere => 1);
```
refract => $bool
$refract example$

"Refracted" pixel values. Can be used to enhance the fractal appearance of the resulting noise. Often makes it look dirty.
```
  make(refract => 1);
```
clut => $filename
Use an input image as a false color lookup table.
```
  make(clut => $filename);
```
clutdir => <0|1|2>
Specify the "direction" of the color lookup table.

0: Corner-to-corner lookup. This is the default clut direction.

CLUT arrangement guidance:

- Bottom left corner: Used for dark input values

- Top right corner: Used for bright input values

- Bottom right, top left corners are disregarded.
```
  make(clut => $filename, clutdir => 0); # mycolors.bmp
```
1: Vertical lookup. This lookup direction complements noise made with the sphere arg, and is intended for mapping to a spheroid.

CLUT arrangement guidance:

- Left side: Used for dark input values

- Right side: Used for bright input values

- Up/Down: Corresponds to Y position of input values

Blurring the input image in your editing app of choice can reduce visible banding in the output.
```
  make(clut => $filename, clutdir => 1, sphere => 1); # mycolors.bmp
```
2: "Fractal" lookup, uses the same methodology as refract.
```
  make(clut => $filename, clutdir => 2); # mycolors.bmp
```
limit => <0|1>
0: Scale the pixel values of the noise set to image-friendly levels

1: Clamp pixel values outside of a representable range
```
  make(limit => 1);
```
shadow => $float

Amount of false self-shadowing to apply, between 0 and 1.
emboss => <0|1>

Render false lightmap only
interp => <0|1>
Use linear (0) or cosine (1) interpolation.

Linear is faster, cosine looks nicer. Default is cosine (1)
```
  make(type => "gel", interp => 1);
```
grow => <0|1>
This option may dramatically improve noise quality!

Use interpolation (0) or gaussian neighborhoods (1) when upsampling pixel grids. Gaussian (1) is best for avoiding directional artifacts, but is substantially slower. Default is interpolation (0), which will use the specified interp function.
```
  make(type => "gel", grow => 1); # spendy goo
```
delta => 1

Output difference noise
```
  make(delta => 1);
```
chiral => 1

Output additive noise
```
  make(chiral => 1);
```
stereo => 1

Output stereo map
```
  make(stereo => 1);
```
tile => <0|1|2|3>
Image seam linear blending mode. Naturally tiling noise types don't need this argument. For false spheremap blending, see sphere.
```
  0: no blending
  1: horizontal and vertical
  2: horizontal
  3: vertical
```
xscale|yscale => $num
Stretch or shrink the final noise values, along either axis. This does not alter the dimensions of the resulting image.
```
  make(xscale => .5, yscale => 2);
```
"Scale" in this context means input scaling. Numbers larger than 1 will shrink noise, repeating values along the specified axis. Fractional numbers will stretch the noise, using the interpolation function.

For naturally tiling noise types, providing a non-integer value here will break tiling. Stick to multiples of 1 for best results. Artifically tiled noise types do not require this workaround.
quiet => <0|1>
Don't spam console
```
  make(quiet => 1);
```
out => $filename
Output image filename. Defaults to the name of the noise type being generated.
```
  make(out => "oot.bmp");
```

SINGLE-RES ARGS

Single-res noise consumes the following arguments in hash key form:

amp => <0..1>
Amplitude, or max variance from the bias value.

For the purposes of this module, amplitude actually means semi- amplitude (peak-to-peak amp/2).
```
  make(amp => 1);
```
freq => $int
Frequency, or "density" of the noise produced.

For the purposes of this module, frequency represents the edge length of the starting noise grid.

If the specified side length is a product of the noise's frequency, this module will produce seamless tiles (with the exception of a few noise types). For example, a base frequency of 4 works for an image with a side length of 256 (256x256).
```
  make(freq => 8);
```
len => $int
Specifies edge length of the output image, in pixels
```
  make(len => 512);
```
bias => <0..1>
"Baseline" value for all pixels, .5 = 50%
```
  make(bias => .25);
```
smooth => <0..1>
Enable/disable noise smoothing. 1 is default/recommended
```
  make(smooth => 0);
```
gap => <0..1>
Increases the probability of black pixels in white noise.
```
  make(type => "stars", gap => .995);
```

MULTI-RES ARGS

In addition to any of the args which may be used for single-res noise types, Multi-res types consume the following arguments in hash key form:

octaves => $int
e.g. 1..8

Octave (slice) count, increases the complexity of multi-res noise.
```
  my $blurry = make(octaves => 3);

  my $sharp = make(octaves => 8);
```
persist => $num
Per-octave amplitude multiplicand (persistence). Traditional and default value is .5
```
  my $grid => make(persist => .25);
```
stype => $simpleType
Multi-res slice type, defaults to wavelet. Any single-res type may be specified.
```
  my $grid = make(stype => 'gel');
```

GEL TYPE ARGS

The "gel" types (gel, sgel, pgel, wgel) accept the following additional arguments:

displace => $float
Amount of self-displacement to apply to gel noise
```
  make(type => 'gel', displace => .125);
```

FRACTAL ARGS

zoom => $num
Magnifaction factor.
```
  make(type => 'mandel', zoom => 2);
```
maxiter => $int
Iteration limit for determining infinite boundaries, larger values take longer but are more accurate/look nicer.
```
  make(type => 'mandel', maxiter => 2000);
```

TERRA ARGS

In addition to all single-res and multi-res args, terra noise consumes the following args in hash key form:

feather => $num
e.g. 0..255

Amount of blending between elevation layers
```
  make(type => 'terra', feather => 50);
```
layers => $int
Number of elevation layers to generate
```
  make(type => 'terra', layers => 4);
```
lbase => $noiseType
Complex layer base - defaults to "multires". Any type except for terra may be used.
```
  make(type => 'terra', lbase => 'gel');
```
ltype => $noiseType
Complex layer type - defaults to "multires". Any type except for terra may be used.
```
  make(type => 'terra', ltype => 'gel');
```

BUGS AND LIMITATIONS

Noisemaker was written in Perl as an exploration of the included algorithms, and is much slower than, say, something written in C and optimized for speed.

This module only produces single-channel two-dimensional noise-- false colormaps don't count!

Image file types are limited to the types supported by Imager on your host.

Some noise algorithms might not be implemented "by the book".

AUTHOR

  Alex Ayars <pause@nodekit.org>

COPYRIGHT

  File: Math/Fractal/Noisemaker.pm
 
  Copyright (C) 2009, 2010 Alex Ayars <pause@nodekit.org>

  This program is free software; you can redistribute it and/or modify
  it under the same terms as Perl 5.10.0 or later. See:
  http://dev.perl.org/licenses/