cookiephone / libnoise-rs

Simple and customizable procedural noise generation library written in Rust.

libnoise

A simple, performant, and customizable procedural noise generation library inspired by libnoise for C++ featuring:

• Easy coherent noise generation through sources provided via Source
• Modular generator creation by chaining adapters to modify and combine generator inputs and outputs, and the ability to flexibly create custom generators and adapters, all through the Generator trait
• Efficient and cache friendly sampling of generators through NoiseBuffer and much of the generator complexity resolving at compile time
• Easy visualization of generator outputs for debugging through Visualizer

Libnoise provides utilities to generate coherent noise and customize them by applying a variety of operations which modify and combine generators. With a focus on customizability, the library allows users to create custom generators and modifiers.

Most immediately relevant documentation can be found in Source and Generator docs.

Usage

First, add the dependency to your project by editing your Cargo.toml:

[dependencies]
libnoise = "1.1"

To get started easily, create a source generator using one of the many sources found in Source, and apply adapters documented in Generator. For a more detailed introduction, see the quickstart guide.

use libnoise::prelude::*;

// build a simplex noise generator seeded with 42
let generator = Source::simplex(42);

// sample the generator for input point [0.2, 0.5]
let value = generator.sample([0.2, 0.5]);

Note how the dimensionality, which is internally represented as a constant generic argument, is automatically inferred by sampling the generator with a 2-dimensional input point.

Naturally, we can create more interesting complex generators:

use libnoise::prelude::*;

// build a generator
let generator = Source::simplex(42)                 // start with simplex noise
    .fbm(5, 0.013, 2.0, 0.5)                        // apply fractal brownian motion
    .blend(                                         // apply blending...
        Source::worley(43).scale([0.05, 0.05]),     // ...with scaled worley noise
        Source::worley(44).scale([0.02, 0.02]))     // ...controlled by other worley noise
    .lambda(|f| (f * 2.0).sin() * 0.3 + f * 0.7);   // apply a closure to the noise

// sample the generator for input point [0.2, 0.5]
let value = generator.sample([0.2, 0.5]);

We can also use NoiseBuffer for efficiently filling n-dimensional arrays with noise, and Visualizer to get a visual representation of a given generator. The above generator produces the following image, when sampled for every pixel position:

It is common to interpret the 3rd or 4th dimension as time, allowing us to produce space-time noise such as:

Contributing

Contributors and feature suggestions are welcome!

Should you want to contact me directly, it is best via discord (username: oogie).

License

Libnoise is distributed under the terms of the MIT license.

See LICENSE-MIT for details.

libnoise-rs's Issues

Feature Discussion: Generic Seeds

Before coming across this great library, I was about to spin my own noise crate! Thanks for saving me the hassle - this seems fantastic!

However, I do have a weird feature request that only might make sense. I would love to be able to provide theoretically infinite seeds, such as vectors/arrays of values - or even a string slice, to the generator.

Do you know if this is viable from an implementation standpoint? You don't need to worry about implementing it - I don't think it's widely interesting. However, I'm definitely interested!

From what I can tell, rand_chacha happily implements Seed for any byte slice, so you can give it any kind of data to get random data back. That should allow it to work for sources that use core::utils::ptable::PermutationTable, at least if seed also allowed anything serializable to [u8].

Once again, thanks for the great library! 🦀✨