NAME

Math::Fractal::Noisemaker - Visual noise generator

VERSION

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

SYNOPSIS

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

  #
  # use defaults
  #
  make();

  #
  # override defaults
  #
  make(type => 'gel',
    # ...
  );

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

  #
  # use defaults
  #
  make-noise

  #
  # override defaults
  #
  make-noise -type gel

  #
  # usage
  #
  make-noise --help

  make-noise --help types

Noise sets are just 2D arrays, which may be generated directly using named functions.

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

  my $grid = square(%args);

  #
  # Look up a value, given X and Y coords
  #
  my $value = $grid->[$x]->[$y];

Imager can take care of further post-processing.

  my $grid = perlin(%args);

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

  #
  # Insert image manip methods here!
  #

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

DESCRIPTION

Math::Fractal::Noisemaker provides a simple functional interface for generating 2D tiles from various flavors of fractal (and non-fractal) inputs.

As long as the specified side length is a power 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 would work fine for an image with a side length of 256 (256x256).

FUNCTION

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

  #
  # Just make some noise:
  #
  make();

  #
  # Care slightly more:
  #
  my ( $grid, $img, $filename ) = make(
    #
    # Any MAKE ARGS or noise args here!
    #
  );

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 you need. make-noise, included with this distribution, provides a CLI for this function.

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

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 pseudo-spheremap from the resulting noise.

When specifying sphere, the output image will be 50% of the len you asked for. This is done to avoid aliasing. Multiply the supplied len argument by 2 to work around this.

See spheremap.
```
  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 color lookup table

This feature is a work in progress.
```
  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.

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.

2: Fractal lookup, uses the same methodology as refract. Also good for seamless tiling.
```
  make(clut => $filename, clutdir => 1);
```
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);
```
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");
```
shadow => $float

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

Render lightmap only

NOISE TYPES

SIMPLE NOISE

Simple noise types may be specified as Perlin slice types (stype)

white(%args)

Each non-smoothed pixel contains a pseudo-random value
wavelet(%args)

Basis function for sharper Perlin slices
square(%args)

Diamond-Square
gel(%args)

Self-displaced white noise; see GEL TYPES
sgel(%args)

Self-displaced Diamond-Square noise; see GEL TYPES
dla(%args)

Diffusion-limited aggregation, seeded from multiple random points.
mandel(%args)

Fractal type - Mandelbrot. Included as a demo.
dmandel(%args)

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), zooms in a random amount, and embellishes the palette.
buddha(%args)

Fractal type - "Buddhabrot" Mandelbrot variant. Work in progress.
fflame(%args)

IFS type - "Fractal Flame". Work in progress. Neat.
fern(%args)

IFS type - Barnsley's fern. Included as a demo.
gasket(%args)

IFS type - Sierpinski's triangle/gasket. Included as a demo.
stars(%args)

White noise generated with extreme gappiness and smoothed
spirals(%args)

Tiny logarithmic spirals
voronoi(%args)

Ridged Voronoi cells.
moire(%args)

Interference pattern with blended image seams.

Appearance of output is heavily influenced by the freq arg.
textile(%args)

Moire noise with a randomized and large freq arg.
infile(%args)

Import the brightness values from the file specified by the "in" or "-in" arg.
```
  my $grid = infile(
    in => "dirt.bmp"
  );
```
intile(%args)

Calls infile, and makes a seamless repeating tile from the image.
```
  my $grid = intile(
    in => "dirt.bmp"
  );
```
sparkle

Stylized starfield

Simple noise types accept the following arguments in hash key form:

amp => $num

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 => $num

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 => $num

"Baseline" value for all pixels, .5 = 50%
```
  make(bias => .25);
```
smooth => $bool

Enable/disable noise smoothing. 1 is default/recommended
```
  make(smooth => 0);
```
zoom => $num

Used for fractal types only. Magnifaction factor.
```
  make(type => 'mandel', zoom => 2);
```
maxiter => $int

Used for fractal types only. Iteration limit for determining infinite boundaries, larger values take longer but are more accurate/look nicer.
```
  make(type => 'mandel', maxiter => 2000);
```

PERLIN TYPES

Perlin 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 Perlin noise may be controlled with the stype argument. Any simple type may be specified.

The default slice type is smoothed wavelet noise.

perlin(%args)

Perlin

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

ridged(%args)

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

Unsmoothed Perlin
```
  make(type => 'block', stype => ...);
```
pgel(%args)

Self-displaced Perlin noise; see GEL TYPES
```
  make(type => 'pgel', stype => ...);
```
fur(%args)

Fur-lin noise; traced paths of worms with Perlin input.
tesla(%args)

Long, fiberous worm paths with random skew.
delta(%args)

Difference noise; output contains absolute values of subtracting two noise sets.
```
  make( type => "delta" );
```
Use ltype to specify any simple or perlin layer type.
```
  make(
    type => "delta",
    ltype => "gel"
  );
```
chiral(%args)

Twin noise; output contains the lightest values of two noise sets.
```
  make( type => "chiral" );
```
Use ltype to specify any simple or perlin layer type.
```
  make(
    type => "chiral",
    ltype => "tesla"
  );
```
stereo(%args)

Stereoscopic depth map.

Use ltype to specify any simple or perlin layer type.

In addition to any of the args which may be used for simple noise types, Perlin noise types accept the following arguments in hash key form:

octaves => $int

e.g. 1..8

Octave (slice) count, increases the complexity of Perlin noise. Higher generally looks nicer.
```
  my $blurry = make(octaves => 3);

  my $sharp = make(octaves => 8);
```
stype => $simpleType

Perlin slice type, defaults to wavelet. Any simple type may be specified.
```
  my $grid = make(stype => 'gel');
```

COMPLEX NOISE

complex

Complex layered noise
```
  make(type => "complex");
```
Complex noise is a homebrew noise recipe inspired by (but not using) libnoise.

This function generates a noise base and multiple noise layers. Each pixel in the resulting noise is blended towards the value in the noise layer which corresponds to the reference value in the noise base. Finally, the noise base itself is very slightly superimposed over the combined layers.
```
  my $grid = complex();
```
Presets for hundreds of noise variants (many of them quite interesting visually) may be generated through this function, by combining different base types, layer types, and slice types.
```
  my $grid = complex(
    lbase => <any noise type but complex>,
    ltype => <any noise type but complex>,
    stype => <any simple type>,
    # ...
  );
```

In addition to all simple and Perlin args, complex noise accepts the following args in hash key form:

feather => $num

e.g. 0..255

Amount of blending between different regions of the noise.
```
  make(type => 'complex', feather => 50);
```
layers => $int

Number of complex layers to generate
```
  make(type => 'complex', layers => 4);
```
lbase => $noiseType

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

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

GEL TYPES

The simple and Perlin "gel" types (gel, sgel, pgel) accept the following additional arguments:

offset => $float

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

MORE FUNCTIONS

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)

The so-called "noise function" required to generate coherent noise. Returns the same "random" value each time it is called with the same arguments (makes it more like a key hashing function a la memcached doesn't it? Not very random, if you ask me).

Math::Fractal::Noisemaker diverges from most Perlin implementations in that its noise function simply utilizes a lookup table. The lookup table contains pre-populated random values. Turns out, this works fine.
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 TYPES

AUTHOR

  Alex Ayars <pause@nodekit.org>

COPYRIGHT

  File: Fractal/Noisemaker.pm
 
  Copyright (c) 2009 Alex Ayars
 
  All rights reserved. This program and the accompanying materials
  are made available under the terms of the Common Public License v1.0
  which accompanies this distribution, and is available at
  http://opensource.org/licenses/cpl1.0.txt

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)