anl 0.3.0

Accidental Noise Library port for Rust.

Crate anl [] [src]





The AutoCorrect module is a tool to help tame the wild beasts that are fractals. When a function is set as a source to AutoCorrect, the calculate() method is called. This method will sample the input function a number of times across a region of the domain, and attempt to calculate a set of "correction parameters" to remap the function's output to a different range. Multi-fractals especially are notorious for outputting values in odd ranges, and this function provides a drop-in method for correcting them. Due to the necessity of sampling the function a number of times, there is some processing overhead when calculate() is called.


The BasisFunction function encapsulates basic noise generators. The function is customizable; you can choose what type of noise to generate and what interpolation style to use. The types of basis and interpolation functions are enumerated as enum.BasisType.html and enum.InterpType.html respectively.


Bias has the effect of applying the following function to the output of its source: f(x)=pow(x, log(b)/log(0.5)) When applied to a function in the range of (0,1), this has the effect of "pushing" the values of the function toward 1 if b is greater than 0.5, or pushing them toward 0 if b is less than 0.5. In effect, it "biases" the function toward one end of the range or the other. source and b are scalar parameters. They default to 0 and 0.5, respectively, and may be overridden with either another constant or with a function source.


Blend has the effect of blending the value from lowSource with the value of highSource by linearly interpolating from one to the other using the value of controlSource. For best results, controlSource should output in the range of (0,1). All three inputs are scalar parameters that may accept either a constant value or a functional input as a source.


The BrightContrast function provides a method for adjusting the brightness and contrast of the image. Contrast is adjusted relative to a specified threshold. Values greater than the threshold are adjust upward (brighter), while values below the threshold are adjusted downward (darker). (Note: The brightness and contrast correction provided by this function are additive, meaning that all values are brightened or darkened across the applicable range, unlike the Bias function, which lightens or darkens, but preserves the total range of the function.


The Cellular function provides an interface to a CellularGenerator to generate cellular noise based on the function originally written by Steve Worley. The function calculates F1,F2,F3 and F4 as distances to the first, second, third and fourth nearest seed points, applies the specified coefficients to the distances and sums them together, returning the result.


Clamp is useful for ensuring that the output of a function does not go beyond a specified range. And values beyond the given range will be clipped.


Combiner is useful for mathematically combining several functions together using arithmetic operators. The function will accept up to 20 sources, and generates a combination of the sources depending on the type parameter, which can be one of Add, Mul, Max, Min or Avg.


Constant is simply that: a constant value. Note: This may be going away, as the increasing use of ScalarParameters (parameters that can either be a constant or a noise source) is making it irrelevant. Even in the case of something like a combiner, which still takes pointers to modules rather than a scalar parameter, it is just as easy to use a Cache with a constant source.


Takes the cos() of the input function.


ExtractRGBAChannel accepts an 'RgbaParameter' and extracts one of the channels. The accepted values for channel are listed in the ExtractChannel.


Fractals are a special type of combiner that combine up to 20 noise sources using fractal methods pioneered by Perlin, Musgrave, and friends. They come in various types (specifiable through set_type() or in the constructor). Each fractal has up to 20 built-in BasisFunctions whose basistype and interptype can be set via the provided methods. Additionally, you can obtain a pointer to any source of the fractal via get_basis(). Any source module in the fractal may also be overridden by an external noise function via overrideSource(). The complexity of this system serves a purpose: "generic" fractals of a given type, with basis functions of all the same type, can easily be instance just by construction, yet more complex behavior can be produced by overriding layers with external sources, to build up very complex fractals, if so desired. Fractals are highly parameterized. The two most useful parameters are numoctaves which determines how many layers contribute to the fractal, and frequency which specifies the density of the function. Frequency mimics combining a ScaleDomain function to the source, multiplying the input coordinates by frequency before calculating the function. Other parameters that control the fractal are offset, lacunarity, gain and H. These parameters can have subtle, drastic, or no effect on the fractal, depending on the type, and they are typically best left alone.


Gain is similar in effect to Bias, and in fact uses Bias in its working. It applies the following function to the source input: if(t<0.5) { return bias(1.0-g, 2.0*t)/2.0; } else { return 1.0 - bias(1.0-g, 2.0 - 2.0*t)/2.0; } This function has the effect of pushing the values of the input either toward the ends and away from the middle (if bias is >0.5) or pushing values toward the middle and away from the ends (if bias is < 0.5).


Gradient has the effect of allowing you to specify a line segment in N-dimensional space by setting endpoints. The endpoints are set via set_gradient() and the segment extends from P1=(x1,y1,z1,w1,u1,v1) to P2=(x2,y2,z2,w2,u2,v2). Only the coordinates pertinent to the dimensionality of the function being called are used, however. A gradient field is aligned with this segment such that any input coordinate is projected onto the line formed by the segment, and a value is assigned based on where on the line the projected point lies. If it lies on or beyond P1, the value is assigned as 0. If it lies on or beyond P2 the value is assigned as 1. Anything in between is assigned as a linear interpolation between 0 and 1. (This behavior may be changing; I may remove the clamping aspect, and allow values to go infinitely depending on distance from the "origin" point. Some useful things could be done in this fashion.) The result is a smooth gradient field oriented along an axis.


RotateDomain applies a domain rotation to the input function. That is, it actually modifies the coordinates that the input function will be called by. If the RotateDomain is called by the input coordinate (x,y), it will call its source with the input coordinate (nx,ny) where (nx,ny) is a transformation of the original input; specifically, a rotation around an axis. This function has slightly different behavior depending on if the 2D version is called or if some higher version is called. 2D version rotates the input around the Z axis by the given angular amount, and the axis sources set by set_axis() are ignored. 3D and above, however, rotate the domain around the axis specified.


ScaleDomain applies a domain scaling to the coordinates input to the function.


ScaleOffset applies a scaling and translation factor to the output of its source function, as v*scale+offset.


Select is used to choose between one function or another based on the output value of a third control function. Two parameters control how the select is performed, threshold and falloff. Threshold determines where the dividing line is; values on one side of threshold are taken from one source module, while values on the other side are taken from the second source. Falloff defines the width of a soft "blend" zone that straddles threshold, helping to smooth the transition between the two functions.


Takes the sin() of the input source.


Generates a hyper sphere as a distance field. Values between the center and the radius are interpolated between 0 and 1, while values beyond radius are 0. The individual axis components of the center point, as well as the radius, are specifiable as either constants or as noise functions, making this an extremely flexible sphere indeed. Following are images taken as cross-sections of the sphere in the 2D plane, the one on the left with all constants for the components, the one in the center with constants for center and a fractal function for radius, and the one on the right with a fractal for the x component, and a constant radius.


TranslateDomain is used to translate the input coordinates of a function. Each axis is specifiable as a constant or noise source. This application of domain transformation is commonly called turbulence and is useful in generating many types of effects.




Basis function types.


Aside from being able to assignt he type of noise generated, the user can also assign the type of interpolation used. This parameter only applies to the variants of Value, Gradval and Gradient.


Many functions have "parameters" that affect their functionality, aside from any "source" function they might have. An example is the ImplicitSelect function. This function has a control source, a low source, a high source, a threshold parameter, and a falloff parameter. The threshold parameter is used to select between the output of lowSource and highSource, depending on if the value of controlSource is above or below threshold. All five of these inputs are instances of what ANL calls a "scalar parameter". A scalar parameter can be set to either a constant (double-precision) value, or to another function. Most will default to some sane double-precision value (ie, 0), but if desired they can be overridden with any constant or any implicit functional output. In this way, complex behaviors can be obtained through a relatively simple interface.



Implicit modules output double-precision float values. Implicit functions are derived from ImplicitModule trait. Noise values are obtained by calling one of the get() methods provided, with the appropriate number of coordinates. Note that the performance of the system as a hold is affected by the dimensionality of the function called, so a 6D function will take significantly longer than a 2D function. Typical applications will probably stick with 2D or 3D versions; the higher orders are provided for the purpose of seamless mapping.


Type Definitions