NAME

Math::Fractal::Noisemaker - Visual noise generator

VERSION

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

SYNOPSIS

use Math::Fractal::Noisemaker qw| :all |;

make();

A wrapper script, make-noise, is included with this distribution.

make-noise -help
make-noise -help types

DESCRIPTION

Math::Fractal::Noisemaker provides a simple functional interface for generating 2D fractal (or non-fractal) noise.

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).

FUNCTION

make(type => $type, out => $filename, %ARGS)

Creates the specified noise type (see NOISE TYPES), writing the resulting image to the received filename. Unless seriously tinkering, make may be the only function needed.

Returns the resulting dataset, as well as the Imager object which was created from it and filename used.

This function accepts a plethora of optional arguments, see MAKE ARGS.
```
#
# Just make some noise:
#
make();

#
# Care slightly more:
#
my ( $grid, $img, $filename ) = make(
  #
  # Any MAKE ARGS or noise args here!
  #
);
```
Noise sets are 2D array refs.
```
#
# Look up a value, given X and Y coords
#
my $value = $grid->[$x]->[$y];
```
Imager can take care of further post-processing.
```
#
# Insert image manip methods here!
#
$img->write(file => "oot.png");
```
make-noise, included with this distribution, provides a CLI wrapper to this function.

NOISE TYPES

SINGLE-RES NOISE

Single-res noise types may be specified as a multi-res slice types (stype)

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

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", ...);
```
simplex

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

Does not seamlessly tile.
```
make(type => "simplex", ...);

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

simplex2

simplex2 noise example

Interpolated simplex noise which seamlessly tiles.

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

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

square

Diamond-Square

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

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.
```
make(type => "sgel", ...);
```
dla

Diffusion-limited aggregation, seeded from multiple random points.

See SINGLE-RES ARGS for allowed arguments.

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", ...);
```
voronoi

Ridged Voronoi cells.

bias and amp currently have no effect.
```
make(type => "voronoi", ...);
```
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", ...);
```

MULTI-RES TYPES

Perlin (multi-res) noise combines the values from multiple 2D slices (octaves), which are generated using successively 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.

perlin

Multi-resolution noise.

See MULTI-RES ARGS for allowed args.
```
make(type => 'perlin', 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

Fur-lin noise; traced paths of worms with 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

Persistent noise with heavy banding.

Looks vaguely wood-like with the right clut.

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.

make(
  type   => "terra",
  lbase  => "perlin",   # 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 perlin. Specify any type.
```
make(type => 'gel');
```
sphere => $bool

Generate a false spheremap from the resulting noise.
```
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>

0: Hypotenuse lookup (corner to corner, so it doesn't matter if the input table is oriented horizontally or vertically).

This is the default. Best for seamless tiling.
```
make(clut => $filename, clutdir => 0);
```
1: Vertical lookup, good for generating maps which have ice caps at the poles and tropical looking colors at the equator.

Output will have color seams at the poles unless viewed on a spheroid. This lookup method produces output which resembles a reflection map, if a photograph is used for the clut.
```
make(clut => $filename, clutdir => 1);
```
2: Fractal lookup, uses the same methodology as refract. Also good for seamless tiling.
```
make(clut => $filename, clutdir => 2);
```
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. Default is (1) cosine.
```
make(type => "gel", interp => 0); # budget noise
```
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);
```
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.
```
make(freq => 8);
```
len => $int

Side length of the output images, which are always square.
```
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>

Larger values increase the chance for black pixels in white noise (which many noise types are derived from).
```
make(type => "white", 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. Higher generally looks nicer.
```
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) 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 "perlin". Any type except for terra may be used.
```
make(type => 'terra', lbase => 'gel');
```
ltype => $noiseType

Complex layer type - defaults to "perlin". Any type except for terra may be used.
```
make(type => 'terra', ltype => 'gel');
```

MORE FUNCTIONS

These functions are not useful unless going outside of what make can do.

img($grid,%args)

my $grid = perlin();

my $img = img($grid,%args);

#
# Insert Imager image manip stuff here!
#

$img->write(file => "oot.png");

Returns an Imager object from the received two-dimensional grid.

clamp($value)

Limits the received value to between 0 and 255. If the received value is less than 0, returns 0; more than 255, returns 255; otherwise returns the same value which was received.
```
my $clamped = clamp($num);
```
noise($grid, $x, $y)

Smoothed noise lookup function
lerp($a, $b, $x)

Linear interpolate from $a to $b, by $x percent. $x is between 0 and 1.
coslerp($a, $b, $x)

Cosine interpolate from $a to $b, by $x percent. $x is between 0 and 1.
smooth($grid, %args)
```
#
# Unsmoothed noise source
#
my $grid = white(smooth => 0);

my $smooth = smooth($grid,%args);
```
Perform smoothing of the values contained in the received two-dimensional grid. Returns a new grid.

Smoothing is on by default.
spheremap($grid, %args)

Generates a fake (but convincing) spheremap from the received 2D noise grid, by embellishing the polar regions.

Re-maps the pixel values along the north and south edges of the source image using polar coordinates, slowly blending back into original pixel values towards the middle.

Returns a new 2D grid of pixel values.
```
my $grid = perlin(%args);

my $spheremap = spheremap($grid,%args);
```
See MAKE ARGS
refract($grid,%args)

Return a new grid, replacing the color values in the received grid with one-dimensional indexed noise values from itself. This can enhance the "fractal" appearance of noise.
```
my $grid = perlin(%args);

my $refracted = refract($grid);
```
See MAKE ARGS
displace($grid,%args)

Use the received grid as its own displacement map; returns a new grid.

The amount of displacement is controlled by the displace arg.

See GEL TYPE ARGS

BUGS AND LIMITATIONS

Noisemaker was written in Perl as an exploration of the included algorithms, and is many orders of magnitude slower than comparable C-based solutions.

This module only produces single-channel two-dimensional noise.

AUTHOR

Alex Ayars <pause@nodekit.org>

COPYRIGHT

 File: Math/Fractal/Noisemaker.pm

 Copyright (C) 2009, 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/

To install Math::Fractal::Noisemaker, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Math::Fractal::Noisemaker

CPAN shell

perl -MCPAN -e shell
install Math::Fractal::Noisemaker

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)