/ 
Math-Fractal-Noisemaker-0.105
River stage zero No dependents
/ Math::Fractal::Noisemaker

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

    white noise example

    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

    simplex noise example

    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

    square noise example

    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

    square gel noise example

    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 noise example

    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

    fern example

    IFS type - Barnsley's fern. Included as a demo.

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

  • gasket

    gasket example

    IFS type - Sierpinski's triangle/gasket. Included as a demo.

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

  • stars

    stars example

    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

    spirals example

    Tiny logarithmic spirals

    See SINGLE-RES ARGS for allowed arguments.

    bias and amp currently have no effect.

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

  • moire

    moire example

    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

    textile example

    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

    sparkle example

    Stylized starfield

    bias and amp currently have no effect.

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

  • canvas

    canvas example

    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

    multires example

    Multi-resolution noise.

    See MULTI-RES ARGS for allowed args.

    make(type => 'multires', stype => '...');

  • ridged

    ridged example

    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

    block example

    Unsmoothed multi-resolution.

    See MULTI-RES ARGS for allowed args.

    make(type => 'block', stype => ...);

  • pgel

    multires gel example

    Self-displaced multi-res noise.

    See MULTI-RES ARGS and GEL TYPE ARGS for allowed args.

    make(type => 'pgel', stype => ...);

  • fur

    fur example

    Traced "worm paths" from multi-res input.

    See MULTI-RES ARGS for allowed args.

  • tesla

    tesla example

    Long, fiberous worm paths with random skew.

    See MULTI-RES ARGS for allowed args.

  • lumber

    lumber example

    Noise with heavy forced banding.

    See MULTI-RES ARGS for allowed args.

  • wormhole

    wormhole example

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

    amp controls displacement amount (eg 8).

    See MULTI-RES ARGS for allowed args.

  • flux

    flux example

    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

    sphere example

    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.

    clutdir 0 example

    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.

    clutdir 1 example

    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.

    clutdir 2 example

    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

    shadow example

    Amount of false self-shadowing to apply, between 0 and 1.

  • emboss => <0|1>

    emboss example

    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

    delta example

    Output difference noise

    make(delta => 1);

  • chiral => 1

    chiral example

    Output additive noise

    make(chiral => 1);

  • stereo => 1

    stereo example

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

SEE ALSO

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:

... and a host of others.

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

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/