# libnoise
[](https://coveralls.io/github/cookiephone/libnoise-rs?branch=master)
[](https://docs.rs/libnoise)
[](https://crates.io/crates/libnoise)
A simple, performant, and customizable procedural noise generation library
inspired by [libnoise for C++](https://libnoise.sourceforge.net/) 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](https://docs.rs/libnoise) can be found in
[`Source`](https://docs.rs/libnoise/latest/libnoise/struct.Source.html) and
[`Generator`](https://docs.rs/libnoise/latest/libnoise/trait.Generator.html) docs.
## Usage
First, add the dependency to your project by editing your `Cargo.toml`:
```toml
[dependencies]
libnoise = "1.1"
```
To get started easily, create a source generator using one of the many
sources found in [`Source`](https://docs.rs/libnoise/latest/libnoise/struct.Source.html),
and apply adapters documented in [`Generator`](https://docs.rs/libnoise/latest/libnoise/trait.Generator.html).
For a more detailed introduction, see the [quickstart guide](https://docs.rs/libnoise/latest/libnoise/).
```rs
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:
```rs
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`](https://docs.rs/libnoise/latest/libnoise/struct.NoiseBuffer.html) for efficiently filling n-dimensional arrays
with noise, and [`Visualizer`](https://docs.rs/libnoise/latest/libnoise/struct.Visualizer.html) 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](LICENSE.md) for details.