Alex Ayars >
Math-Fractal-Noisemaker-0.105 >
Math::Fractal::Noisemaker

Module Version: 0.105
Math::Fractal::Noisemaker - Visual noise generator

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

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

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.

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

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

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

- 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
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
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
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: 256make(type => "mandel", ...);

- dmandel
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: 256make(type => "dmandel", ...);

- buddha
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: 4096make(type => "buddha", ...);

- julia
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: 200make(type => "julia", ...);

- djulia
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: 200make(type => "djulia", ...);

- newton
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: 10make(type => "newton", ...);

- fflame
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: 6553600make(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 smoothedSee 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 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.

- terra
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 );

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
"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 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);

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');

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

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

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');

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

Imager, Math::Trig, Tie::CArray

Check out the examples set on Flickr:

http://www.flickr.com/photos/aayars/sets/72157622726199318/

Math::Fractal::Noisemaker is on GitHub: http://github.com/aayars/noisemaker

Inspiration and/or pseudocode borrowed from these notable sources:

- http://freespace.virgin.net/hugo.elias/models/m_perlin.htm
Hugo Elias's Perlin noise page provided pseudocode for smoothing and interpolation functions.

Apparently, the above URL really explains something called "value noise", which is not real Perlin noise. Noisemaker follows its examples closely, regardless.

- http://gameprogrammer.com/fractal.html
Generating Random Fractal Terrain by Paul Martz (Diamond-Square)

- http://graphics.pixar.com/library/WaveletNoise/paper.pdf
Pixar - Wavelet noise

- http://www.complang.tuwien.ac.at/schani/mathmap/stills.html
Moire recipe inspired by MathMap

- http://libnoise.sourceforge.net/
Libnoise, by Jason Bevins, inspired the terrain recipe

- http://flam3.com/flame.pdf
The Fractal Flame Algorithm by Scott Draves and Erik Reckase

- http://en.wikipedia.org/wiki/File:Demj.jpg
Julia fractal functions ported from "Julia set using DEM/J" by Adam Majewski

- http://vlab.infotech.monash.edu.au/simulations/fractals/
Newton functions ported from "Fractals on the Complex Plane", Monash University

- http://staffwww.itn.liu.se/~stegu/aqsis/aqsis-newnoise/
Simplex functions ported from simplexnoise1234.cpp by Stefan Gustavson

... and a host of others.

To learn more about the art of making noise, one might start here:

Alex Ayars <pause@nodekit.org>

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/

syntax highlighting: