CS 381  >  Pnoise 1.2 Package Documentation

CS 381, Fall 2002
Pnoise 1.2 Package Documentation

December 7, 2003

1. Contents

This file gives documentation for the Pnoise package, version 1.2. Sections are as follows.
  1. Contents
  2. Legal Notice
  3. Introduction
  4. Files
  5. Pseudorandom Number Generation
  6. Interface
    1. Overview
    2. 3-D and 2-D Arrays
    3. Function pnoise3d
    4. Function fnoise3d
    5. Function filterfnoise3d
    6. Function normalize3d
    7. Function pnoise_abs
  7. Revision History

2. Legal Notice

The Pnoise package, version 1.2, consisting of this file and pnoise.h, is Copyright © 2002, 2003 Glenn G. Chappell. The package is intended for use in the CS 381 (Computer Graphics) class at the U. of Alaska Fairbanks. Anyone desiring to use this package in some other context should contact the author.

3. Introduction

The Pnoise package provides pseudorandom “noise” generation in C++, intended for use in generating procedural texture. The package is based on the work of °Ken Perlin. Functions are provided to generate basic noise (“Perlin noise”), simulated 1/f noise produced by summing scaled copies of the basic noise function, and the variant of this (noise with cusps) produced by summing absolute values (see Perlin’s °Making Noise slides).

The package generates noise in a 3-D array. The provided functions can be used to generate noise in a 2-D (or 1-D) array as well.

4. Files

The Pnoise package consists of this documentation and one C++ file, pnoise.h, containing the source code for the various noise functions. It may be either #include’d in a C++ source file, or functions may be declared in the source file and pnoise.h maybe compiled separately.

5. Pseudorandom Number Generation

Perlin’s noise function is entirely deterministic, with the “randomness” generated using a hard-coded permutation and a hash function. In contrast, the Pnoise package generates similar noise functions to Perlin’s, but the pseudorandom values are generated using the standard C++ function rand().

The rand() function is not seeded by the Pnoise package. Users may wish to seed with either a constant, in order to generate the same noise functions each time, or with a time-dependent value (e.g., “srand(time(0));”), in order to generate different noise functions each time.

6. Interface

6a. Overview

While it is written in C++, the Pnoise package defines no new classes. Rather, it provides three noise-generation functions, a utility normalization function, and an absolute-value function.

The noise-generation functions are the following.

pnoise3d
Basic noise generation.
fnoise3d
Simulated 1/f noise generation.
filterfnoise3d
Simulated 1/f noise with a “filter function”. Generates noise with cusps if pnoise_abs (see below) if passed as the filter function.
The utility functions are the following.
normalize3d
Noise array normalization.
pnoise_abs
Absolute value.

6b. 3-D and 2-D Arrays

The three noise-generation functions, along with normalize3d are passed a (double *) as their first parameter; this should be a pointer to a 3-D array of doubles. The next three parameters are the x-, y-, and z-dimensions of this array.

Example (3-D Array)

const int xdim = 20,
          ydim = 30,
          zdim = 10;
double noise_array[xdim][ydim][zdim];

normalize3d(&noise_array[0][0][0], xdim, ydim, zdim);

When passing a 2-D array to these functions, pass a z-dimension of 1. (Also pass a z-frequency of 1 to the noise-generation functions; see below.)

Example (2-D Array)

const int xdim = 20,
          ydim = 30;
double noise_array_2D[xdim][ydim];

normalize3d(&noise_array_2D[0][0], xdim, ydim, 1);
Similarly, when passing a 1-D array, pass both a y- and a z-dimension of 1.

6c. Function pnoise3d

Prototype

void pnoise3d(
   double * data,                    // the 3-D array
   int dimx, int dimy, int dimz,     // array dim's
   int freqx, int freqy, int freqz,  // "frequencies"
   double scale=1.0,                 // "amplitude"
   double shiftx=0.0, double shifty=0.0, double shiftz=0.0)
                                     // phase shifts

Action

Function pnoise3d generates basic noise, or “Perlin noise” — see Perlin’s °Making Noise slides for a description.

Noise values are returned in a caller-provided array; this must be allocated by the caller. Frequencies for the noise, in the x-, y-, and z-directions, are specified by the caller. Values for the noise function are in the range [–1,1], with a mean of 0.

Parameters

data
Pointer to an array to return the noise in.
dimx, dimy, dimz
The x-, y-, and z-dimensions of the array; see the 3-D and 2-D Arrays section.
freqx, freqy, freqz
The “frequencies” of the noise, in the x-, y-, and z-directions, respectively. Setting one of these parameters to 1 results in one cycle in that direction, to 2 gives two cycles, etc.
scale
Optional multipler. When the noise is generated, all values are multiplied by scale.
shiftx, shifty, shiftz
Optional shift parameters. The noise function is shifted the given amount in the x-, y-, and z-directions. (These parameters are primarily for internal use.)

Example (3-D Array)

const int dimx = 100,
          dimy = 100,
          dimz = 100;
double noise_array[dimx][dimy][dimz];
int freqx = 10,
    freqy = 10,
    freqz = 10;
pnoise3d(&noise_array[0][0][0], dimx,dimy,dimz, freqx,freqy,freqz);

Example (2-D Array)

const int dimx = 100,
          dimy = 100;
double noise_array_2D[dimx][dimy];
int freqx = 10,
    freqy = 10;
pnoise3d(&noise_array_2D[0][0], dimx,dimy,1, freqx,freqy,1);

6d. Function fnoise3d

Prototype

void fnoise3d(
   double * data,                    // the 3-D array
   int dimx, int dimy, int dimz,     // array dim's
   int freqx, int freqy, int freqz,  // "frequencies"
   double scaleratio=0.5,            // scale is multiplied by this,
                                     //  when frequency is doubled
   double scale=1.0,                 // "amplitude"
   double shiftx=0.0, double shifty=0.0, double shiftz=0.0)
                                     // phase shifts

Action

Function fnoise3d generates simulated 1/f noise, generated by adding scaled copies of basic noise (generated by function pnoise3d). Beginning with the basic noise function, each successive noise function to be added has twice the frequency of the previous and some fraction of the amplitude. (This fraction is specified by the caller; it defaults to 0.5.) Copies of basic noise are added until the frequencies exceed the dimensions of the array.

Noise values are returned in a caller-provided array; this must be allocated by the caller. Frequencies for the noise, in the x-, y-, and z-directions, are specified by the caller. Values for the noise function have a mean of 0. The range of the values may vary; thus it is recommended that function normalize3d be called after fnoise3d.

Parameters

data
Pointer to an array to return the noise in.
dimx, dimy, dimz
The x-, y-, and z-dimensions of the array; see the 3-D and 2-D Arrays section.
freqx, freqy, freqz
The “frequencies” of the noise, in the x-, y-, and z-directions, respectively. Setting one of these parameters to 1 results in one cycle in that direction, to 2 gives two cycles, etc.
scaleratio
Optional multipler for the scale. Function fnoise3d operates by summing a number of basic noise functions. Each has frequency twice the previous and amplitude some fraction of the previous. scaleratio specifies this amplitude fraction. Default is 0.5. Useful values are in the range [0.5, 1.0). Higher values of scaleratio give greater weight to higher frequencies of noise.
scale
Optional multipler. When the noise is generated, all values are multiplied by scale.
shiftx, shifty, shiftz
Optional shift parameters. The noise function is shifted the given amount in the x-, y-, and z-directions. (These parameters are primarily for internal use.)

Example (3-D Array)

const int dimx = 100,
          dimy = 100,
          dimz = 100;
double noise_array[dimx][dimy][dimz];
int freqx = 10,
    freqy = 10,
    freqz = 10;
fnoise3d(&noise_array[0][0][0], dimx,dimy,dimz, freqx,freqy,freqz);
normalize3d(&noise_array[0][0][0], dimx,dimy,dimz);

Example (2-D Array)

const int dimx = 100,
          dimy = 100;
double noise_array_2D[dimx][dimy];
int freqx = 10,
    freqy = 10;
fnoise3d(&noise_array_2D[0][0], dimx,dimy,1, freqx,freqy,1);
normalize3d(&noise_array_2D[0][0], dimx,dimy,1);

6e. Function filterfnoise3d

Prototype

void filterfnoise3d(
   double * data,                    // the 3-D array
   int dimx, int dimy, int dimz,     // array dim's
   int freqx, int freqy, int freqz,  // "frequencies"
   double (* filter)(double),        // filter function for pnoise values
   double scaleratio=0.5,            // scale is multiplied by this,
                                     //  when frequency is doubled
   double scale=1.0,                 // "amplitude"
   double shiftx=0.0, double shifty=0.0, double shiftz=0.0)
                                     // phase shifts

Action

Function filterfnoise3d generates simulated 1/f noise using filtered basic noise. This is generated by adding scaled copies of basic noise (generated by function pnoise3d), each of which is passed through a filter function before being summed with the rest. Beginning with the basic noise function, each successive noise function to be added has twice the frequency of the previous and some fraction of the amplitude. (This fraction is specified by the caller; it defaults to 0.5.) Copies of basic noise are added until the frequencies exceed the dimensions of the array.

A useful filter function is pnoise_abs.

Noise values are returned in a caller-provided array; this must be allocated by the caller. Frequencies for the noise, in the x-, y-, and z-directions, are specified by the caller. The mean and range of the values may vary; thus it is recommended that function normalize3d be called after filterfnoise3d.

Parameters

data
Pointer to an array to return the noise in.
dimx, dimy, dimz
The x-, y-, and z-dimensions of the array; see the 3-D and 2-D Arrays section.
freqx, freqy, freqz
The “frequencies” of the noise, in the x-, y-, and z-directions, respectively. Setting one of these parameters to 1 results in one cycle in that direction, to 2 gives two cycles, etc.
filter
A pointer to the filter function. Function filter must take a single double parameter and return a double. Values generated by pnoise3d are passed through the filter function before being summed. A useful function to pass as a filter is pnoise_abs, which will produce Perlin’s noise with cusps.
scaleratio
Optional multipler for the scale. Function fnoise3d operates by summing filtered versions of a number of basic noise functions. Each has frequency twice the previous and amplitude some fraction of the previous. scaleratio specifies this amplitude fraction. Default is 0.5. Useful values are in the range [0.5, 1.0). Higher values of scaleratio give greater weight to higher frequencies of noise.
scale
Optional multipler. When the noise is generated, all values are multiplied by scale.
shiftx, shifty, shiftz
Optional shift parameters. The noise function is shifted the given amount in the x-, y-, and z-directions. (These parameters are primarily for internal use.)

Example (3-D Array)

const int dimx = 100,
          dimy = 100,
          dimz = 100;
double noise_array[dimx][dimy][dimz];
int freqx = 10,
    freqy = 10,
    freqz = 10;
filterfnoise3d(&noise_array[0][0][0], dimx,dimy,dimz, freqx,freqy,freqz, pnoise_abs);
normalize3d(&noise_array[0][0][0], dimx,dimy,dimz);

Example (2-D Array)

const int dimx = 100,
          dimy = 100;
double noise_array_2D[dimx][dimy];
int freqx = 10,
    freqy = 10;
filterfnoise3d(&noise_array_2D[0][0], dimx,dimy,1, freqx,freqy,1, pnoise_abs);
normalize3d(&noise_array_2D[0][0], dimx,dimy,1);

6f. Function normalize3d

Prototype

void normalize3d(
   double * data,                // the 3-D array
   int dimx, int dimy, int dimz) // array dim's

Action

Function normalize3d takes an array of doubles and transforms the values in this array using a function of the form
k → ak + b,
with a and b chosen so that
  1. the resulting values have mean 0, and
  2. the values are scaled to be as large as possible while staying within the interval [–1,1].
It is recommended that normalize3d be called after calling functions fnoise3d or filterfnoise3d.

Parameters

data
Pointer to an array to return the noise in.
dimx, dimy, dimz
The x-, y-, and z-dimensions of the array; see the 3-D and 2-D Arrays section.

Example

For an example, see the sections on fnoise3d and filterfnoise3d.

6g. Function pnoise_abs

Function pnoise_abs is an absolute-value function, defined as follows: 
double pnoise_abs(double t)
{
   return (t >= 0) ? t : -t;
}

This function is intended to be used as a filter function for filterfnoise3d. It is provided because of inconsistencies in the absolute-value functions provided with some C++ compilers.

Example

For an example, see the section on filterfnoise3d.

7. Revision History

Version 1.0 (4 Dec 2002)
Initial version, for CS 381 (Computer Graphics), fall 2002.
Version 1.1 (4 Dec 2003)
Minor revision for fall 2003 class.
Version 1.2 (7 Dec 2003)
Improved efficiency when generating high frequency noise. Thus fnoise3d, filterfnoise3d run faster.

CS 381, Fall 2002: Pnoise 1.2 Package Documentation / Last update: 7 Dec 2003 / Glenn G. Chappell / chappellg@member.ams.org