Libnoise

This is a haxe port of libnoise, the coherent noise library. The port is almost complete, only the gradient and noise2D utilities are missing.

Every now and then, I try out a new library and find something cool. libnoise is one such library, so it’s time for a Haxelib review!

In this post, I’ll explain what libnoise offers, how good it is at its job, and where it has room for improvement. Plus whatever else I think of along the way.

As its description states, libnoise is a tool for generating coherent noise. To keep things simple, I’m going to pretend “coherent noise” means “grayscale images.” But if you want to dig deeper, Rick Sidwell has an excellent rundown.

Let’s begin with some coherent noise.

This cloud-like image is what’s called Perlin noise, and it’s just one of many patterns libnoise can make.

Generators

Each of libnoise’s generators creates a distinct pattern. Four of these generators are dead simple.

ConstCylinderSphereChecker

• Const a solid color. It can be any shade, though this demo keeps it simple.
• Cylinder and Sphere create repeating gradients centered on the top-left corner. Because the demo is 2D, they barely resemble their namesakes, so you just have to imagine a bunch of 3D spheres nested inside one another, or a bunch of nested cylinders centered on the left edge.
• Checker creates a checkerboard pattern on the pixel level. One pixel is white, the next is black, the next is white, and so on.

The other four involve randomness.

PerlinBillowRidgedMultifractalVoronoi

• Perlin generates (what else?) Perlin noise. Not going to go into depth on how it works; see Rick Sidwell’s post for that. This example uses 8 octaves (fractal layers), meaning there’s extra detail but it takes longer to draw.
• Billow creates what I’d describe as wandering lines, but under the hood it’s very similar to Perlin. If you compare the source code side-by-side, you’ll notice the algorithm is identical except for a single Math.abs() call on line 35.
• RidgedMultifractal also creates wandering lines. I guess you could also call them “ridges”? That’s probably how it got that name. If you look at the source code, you’ll see that it’s also pretty similar to Perlin, though with a few more differences. In the end, it comes out looking like the inverse of Billow.
• Voronoi creates a Voronoi diagram. This is a way of partitioning space based on a set of “seed” points, where every pixel is assigned to the closest seed… You know what? I can’t fit a full explanation here, so go read the article for the details.

3D patterns

I hinted at this already, but libnoise is built to generate 3D patterns. You can set the Z coordinate to 0 – as I did – and just make 2D images, but each of these 2D images is a cross-section of the full pattern. That’s why libnoise calls the classes Cylinder and Sphere rather than Line and Circle: the full 3D pattern really is cylindrical/spherical.

CylinderSphere

Voronoi, Perlin, Billow, and RidgedMultifractal all subtly change because of this. Each pixel in these patterns is influenced by points outside the 2D plane, meaning they appear different than if we were using a 2D algorithm to generate them. (Because the 2D algorithm would only calculate points in the 2D plane.) But it’s very hard to tell just by looking at a single image of them.

Here’s a way to see the difference. If we took different cross-sections of a cylinder, we could see its lines start to curve.

CylinderCylinder rotated 20°Cylinder rotated 40°

If we kept going until 90°, it would look fully circular, just like Sphere.

Operators

libnoise’s generators make the basic images, but its operators are where things get interesting. They modify those base images in all kinds of ways. Inverting, combining, you name it.

To get a good sense of how an operator works, it helps to see the input and output side-by-side. The downside is, it requires splitting up the canvas and cropping each input and output. To view more of a pattern, hover over it and click the “expand” button in the bottom corner.

Unary operators

The simplest operators are those that only take a single image as input, like the Rotate operator shown above. Most unary operators either perform simple arithmetic or move the pattern somehow.

AbsClampInvert

The above three perform arithmetic on the brightness of each pixel. libnoise represents brightness using a value between -1 (black) and 1 (white).

• Abs takes the absolute value of the brightness, so anything below 0 (gray) becomes positive. After this, no part of the pattern will be darker than gray.
• Clamp sets a minimum and maximum value. This demo uses -0.5 (dark gray) as the minimum and 0.5 (light gray) as the maximum, but other programs could adjust further. This cuts out the shadows and highlights but leaves the midtones untouched.
• Invert does exactly what it says on the tin.

RotateScale downTranslate
Rotate (3D)Scale upTranslate (3D)

Rotate, Scale, and Translate do exactly what their names imply. Though they can rotate, scale, and translate in any direction, this demo only includes two options each.

Turbulence (low)Turbulence (high)

Turbulence moves pixels in random directions. “Low” and “high” refer to the maximum distance pixels are allowed to move. However, there’s a bit more to it than that, if we look closely. Fortunately, libnoise allows applying an operator to an operator, so we can Scale the Turbulence.

Close-up turbulence

While it normally looks grainy, if we zoom in enough times, the turbulence starts to look surprisingly smooth. It turns out that it doesn’t move pixels completely at random. There’s an underlying pattern, and that pattern is called… Perlin noise.

Yes indeed, the Turbulence class generates Perlin noise to figure out where it should move each pixel. Perlin noise is a type of gradient noise, and gradient noise always looks smooth when you zoom in. The trick is that the Turbulence class does not zoom in by default, creating the illusion that it isn’t smooth.

Binary operators

libnoise’s two-input operators all perform arithmetic. As a reminder, libnoise represents brightness using a value between -1 (black) and 1 (white).

AddSubtractMultiplyAverageMinMax

• Add takes the sum of two patterns. If both inputs are bright, the output will be even brighter. If both are dark, the output will be even darker.
• Subtract takes the difference. It’s the same as if you inverted the second pattern before adding.
• Multiply takes the product of the numbers. Since we’re multiplying numbers less than 1, they always tend towards 0, and we end up with a lot of gray.
• Average looks like Add but grayer, because that’s exactly what it is: (a + b) / 2. Strangely libnoise doesn’t include this operator, so I implemented it myself for demo purposes.
• Min takes the darker value at each point.
• Max takes the lighter value at each point.

Ternary operators

Finally, libnoise has two three-input operators, and they’re both very similar. Their output is always a combination of pattern 1 and pattern 2, and they use pattern 3 to decide what combination.

SelectBlendSelect (fuzzy)

• Select is all-or-nothing. If pattern 3 is darker than a certain value, it selects pattern 1 and shows that. If pattern 3 is above that threshold, it selects pattern 2.
• Blend interpolates between the first two patterns, using pattern 3 to decide how much of each to blend. If pattern 3 is dark, it’ll use more of pattern 1. If pattern 3 is light, it’ll use more of pattern 2.
• Select also has a fallOff value that makes it do a little of both. If a number is close to the threshold value, it blends just like Blend. If the number is farther away, it selects like normal.

More patterns

Hopefully now you have a good idea of what each generator and operator does, so it’s time for some more interesting combinations. But first, it’s time to take the training wheels off:

Enable editing

The UI is simple to explain, if unwieldy. Hover over a section of canvas to see a dropdown. Pick an option from the dropdown to fill that part of the canvas. Scroll all the way to the bottom of the dropdown if you want to split the canvas up (or put it back together).

With that out of the way, here are some interesting patterns I’ve come across. Try them out, and be sure to try switching up the generators. You can always revert your changes by clicking the button again.

Minimum of two gradientsClose-up turbulenceBlending based on CylinderSelection based on Voronoi regionsTurbulent selectionSphere and Cylinder interference patternDifference between octavesDifference between equal valuesDifference between near-equal valuesMultiplying Voronoi regionsBillow squaredRidgedMultifractal cubed

What patterns can you come up with? If you make something you want to share, you can copy it with ctrl+C, and others can paste it in with ctrl+V. Feel free to post it in the comments, but make sure to insert four spaces in front of your code. If you don’t, WordPress could mess up your formatting.

//Step 1: define the pattern.
var billow:Billow = new Billow(0.01, 2, 0.5, seed, HIGH);
var cylinder:Cylinder = new Cylinder(0.01);
var min:Min = new Min(billow, cylinder);

//Step 2: create something to draw onto.
var bitmapData:BitmapData = new BitmapData(512, 512, false);

//Step 3: iterate through every pixel.
for(x in 0...bitmapData.width) {
    for(y in 0...bitmapData.height) {
        //Step 3a: Get the pixel value, a number between -1 and 1. Use a z coordinate of 0.
        var value:Float = min.getValue(x, y, 0);
        
        //Step 3b: Convert to the range [0, 255].
        var brightness:Int = Std.int(128 + value * 128);
        if(brightness < 0) {
            brightness = 0;
        } else if(brightness >= 256) {
            brightness = 255;
        }
        
        // Step 3c: Convert to a color.
        var color:Int = brightness << 16 | brightness << 8 | brightness;
        
        //Step 3d: Save the pixel color.
        bitmapData.setPixel32(x, y, color);
    }
}

//Step 4: display and/or save the bitmap.
addChild(new Bitmap(bitmapData));

//Step 1: define the pattern.
var billow:Billow = new Billow(0.01, 2, 0.5, seed, HIGH);
var cylinder:Cylinder = new Cylinder(0.01);
var min:Min = new Min(billow, cylinder);

//Step 2: make the drawing.
var noise2D:Noise2D = new Noise2D(512, 512, min);
var bitmapData:BitmapData = noise2D.getBitmapData(GradientPresets.grayscale);

//Step 3: display and/or save the bitmap.
addChild(new Bitmap(bitmapData));