Isotope (isotope_118)

Isotope is a library for generating noise in Elixir, backed by a Rust NIF.

Noise maps are returned as compact binaries of packed f32 values (~4 bytes per value), making them suitable for generating large maps without excessive memory usage.

This is a fork.isotope_118 is a fork of isotope by Vinícius Müller / the Phiriq Project, published because upstream did not support Elixir 1.18+ and had seen no releases. Nearly all of the design and code is theirs. The fork adds Elixir 1.18+ support, a current rustler, and the changes listed in CHANGELOG.md. Issues with this package belong here, not upstream.

The noise implementation is a vendored copy of bracket-noise (a Rust port of Auburn's original FastNoise, not FastNoise Lite), with several cellular-noise bugs fixed. See native/noise/src/fastnoise.rs and native/noise/THIRD_PARTY_LICENSES.

Installation

Add isotope_118 to your list of dependencies in mix.exs:

def deps do
  [
    {:isotope_118, "~> 0.5"}
  ]
end

And running mix deps.get && mix deps.compile.

A Rust toolchain is required to build the NIF: rustc 1.91 or newer (rustler 0.38's minimum). Distro packages often lag — rustup is the safe route.

Usage

Generating a Noise Map

opts = %Isotope.Options{
  seed: 42,
  noise_type: :simplex_fractal,
  frequency: 0.01,
  fractal_options: %Isotope.Options.Fractal{octaves: 4}
}

{:ok, noise} = Isotope.Noise.new(opts)

# Returns an %Isotope.NoiseMap{} struct
nm = Isotope.Noise.noise_map(noise, {1000, 1000})

Accessing Values

# Single value at column x, row y
Isotope.NoiseMap.get(nm, 50, 50)

# Entire row as a list of floats
Isotope.NoiseMap.row(nm, 0)

# Dimensions
{width, height} = Isotope.NoiseMap.size(nm)

# Convert to nested list [[float()]]
Isotope.NoiseMap.to_list(nm)

Using with Enum

Isotope.NoiseMap implements Enumerable, iterating over rows:

# Average value per row
Enum.map(nm, fn row -> Enum.sum(row) / length(row) end)

# Visualize in the terminal
Isotope.Utils.show_noisemap(nm)

Chunks (Infinite Worlds / Tiling)

Generate a noise map starting at an arbitrary coordinate:

chunk = Isotope.Noise.chunk(noise, {512, 512}, 256, 256)

Sampling Individual Points

# 2D
value = Isotope.Noise.get_noise(noise, {1.5, 2.5})

# 3D
value = Isotope.Noise.get_noise(noise, {1.5, 2.5, 3.5})

Noise Types

Isotope supports the following noise types via the :noise_type option:

Options

See Isotope.Options, Isotope.Options.Fractal, and Isotope.Options.Cellular for all available configuration.

%Isotope.Options{
  seed: 1337,               # Random seed
  noise_type: :simplex,     # Noise algorithm
  frequency: 0.01,          # Controls noise scale
  interpolation: :quintic,  # :linear | :hermite | :quintic
  fractal_options: %Isotope.Options.Fractal{
    fractal_type: :fbm,     # :fbm | :billow | :rigid_multi
    octaves: 3,             # Number of fractal layers
    lacunarity: 2.0,        # Frequency multiplier per octave
    gain: 0.5               # Amplitude multiplier per octave
  },
  cellular_options: %Isotope.Options.Cellular{
    distance_function: :euclidean,  # :euclidean | :manhattan | :natural
    return_type: :cell_value,       # :cell_value | :distance | :distance2 | ...
    distance_indices: {0, 1},
    jitter: 0.45
  }
}

For more information, check the documentation here.

Examples

You can check and run the examples in the examples folder.

mix run examples/<example>.exs

Images