## create create — create images in various ways |

## Stability Level

Stable, unless otherwise indicated

## Functions

int | vips_black ()
int | vips_xyz ()
int | vips_grey ()
int | vips_gaussmat ()
int | vips_logmat ()
int | vips_text ()
int | vips_gaussnoise ()
int | vips_eye ()
int | vips_sines ()
int | vips_zone ()
int | vips_sdf ()
int | vips_identity ()
int | vips_buildlut ()
int | vips_invertlut ()
int | vips_tonelut ()
int | vips_mask_ideal ()
int | vips_mask_ideal_ring ()
int | vips_mask_ideal_band ()
int | vips_mask_butterworth ()
int | vips_mask_butterworth_ring ()
int | vips_mask_butterworth_band ()
int | vips_mask_gaussian ()
int | vips_mask_gaussian_ring ()
int | vips_mask_gaussian_band ()
int | vips_mask_fractal ()
int | vips_fractsurf ()
int | vips_worley ()
int | vips_perlin ()

## Types and Values

enum | VipsTextWrap
enum | VipsSdfShape

## Object Hierarchy

        GEnum
        ├── VipsSdfShape
        ╰── VipsTextWrap

## Includes

    #include <vips/vips.h>

## Description

These functions generate various images. You can combine them with the arithmetic and rotate functions to build more complicated images.

## Functions

### vips_black ()

    int
    vips_black (VipsImage **out,
                int width,
                int height,
                ...);

Optional arguments:

- `bands` : output bands

Make a black unsigned char image of a specified size.

See also: `vips_xyz()`, `vips_text()`, `vips_gaussnoise()`.

#### Parameters

out | output image. | [out]
width | output width |
height | output height |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_xyz ()

    int
    vips_xyz (VipsImage **out,
              int width,
              int height,
              ...);

Optional arguments:

- `csize` : `gint`, size for third dimension

- `dsize` : `gint`, size for fourth dimension

- `esize` : `gint`, size for fifth dimension

Create a two-band uint32 image where the elements in the first band have the value of their x coordinate and elements in the second band have their y coordinate.

You can make any image where the value of a pixel is a function of its (x, y) coordinate by combining this operator with the arithmetic operators.

Set `csize` , `dsize` , `esize` to generate higher dimensions and add more bands. The extra dimensions are placed down the vertical axis. Use `vips_grid()` to change the layout.

See also: `vips_grey()`, `vips_grid()`, `vips_identity()`.

#### Parameters

out | output image. | [out]
width | horizontal size |
height | vertical size |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_grey ()

    int
    vips_grey (VipsImage **out,
               int width,
               int height,
               ...);

Optional arguments:

- `uchar` : output a uchar image

Create a one-band float image with the left-most column zero and the right-most 1. Intermediate pixels are a linear ramp.

Set `uchar` to output a uchar image with the leftmost pixel 0 and the rightmost 255.

See also: `vips_xyz()`, `vips_identity()`.

#### Parameters

out | output image. | [out]
width | image size |
height | image size |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_gaussmat ()

    int
    vips_gaussmat (VipsImage **out,
                   double sigma,
                   double min_ampl,
                   ...);

Optional arguments:

- `separable` : generate a separable gaussian

- `precision` : VipsPrecision for `out`

Creates a circularly symmetric Gaussian image of radius `sigma` . The size of the mask is determined by the variable `min_ampl` ; if for instance the value .1 is entered this means that the produced mask is clipped at values less than 10 percent of the maximum amplitude.

The program uses the following equation:

H(r) = exp(-(r * r) / (2 * `sigma` * `sigma` ))

The generated image has odd size and its maximum value is normalised to 1.0, unless `precision` is VIPS_PRECISION_INTEGER.

If `separable` is set, only the centre horizontal is generated. This is useful for separable convolutions.

If `precision` is VIPS_PRECISION_INTEGER, an integer gaussian is generated. This is useful for integer convolutions.

"scale" is set to the sum of all the mask elements.

See also: `vips_logmat()`, `vips_conv()`.

#### Parameters

out | output image. | [out]
sigma | standard deviation of mask |
min_ampl | minimum amplitude |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_logmat ()

    int
    vips_logmat (VipsImage **out,
                 double sigma,
                 double min_ampl,
                 ...);

Optional arguments:

- `separable` : generate a separable mask

- `precision` : VipsPrecision for `out`

Creates a circularly symmetric Laplacian of Gaussian mask of radius `sigma` . The size of the mask is determined by the variable `min_ampl` ; if for instance the value .1 is entered this means that the produced mask is clipped at values within 10 percent of zero, and where the change between mask elements is less than 10%.

The program uses the following equation: (from Handbook of Pattern Recognition and image processing by Young and Fu, AP 1986 pages 220-221):

H(r) = (1 / (2 * M_PI * s4)) * (2 - (r2 / s2)) * exp(-r2 / (2 * s2))

where s2 = `sigma` * `sigma` , s4 = s2 * s2, r2 = r * r.

The generated mask has odd size and its maximum value is normalised to 1.0, unless `precision` is VIPS_PRECISION_INTEGER.

If `separable` is set, only the centre horizontal is generated. This is useful for separable convolutions.

If `precision` is VIPS_PRECISION_INTEGER, an integer mask is generated. This is useful for integer convolutions.

"scale" is set to the sum of all the mask elements.

See also: `vips_gaussmat()`, `vips_conv()`.

#### Parameters

out | output image. | [out]
sigma | standard deviation of mask |
min_ampl | minimum amplitude |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_text ()

    int
    vips_text (VipsImage **out,
               const char *text,
               ...);

Optional arguments:

- `font` : `gchararray`, font to render with

- `fontfile` : `gchararray`, load this font file

- `width` : `gint`, image should be no wider than this many pixels

- `height` : `gint`, image should be no higher than this many pixels

- `align` : VipsAlign, set justification alignment

- `justify` : `gboolean`, justify lines

- `dpi` : `gint`, render at this resolution

- `autofit_dpi` : `gint`, read out auto-fitted DPI

- `rgba` : `gboolean`, enable RGBA output

- `spacing` : `gint`, space lines by this in points

- `wrap` : VipsTextWrap, wrap lines on characters or words

Draw the string `text` to an image. `out` is normally a one-band 8-bit unsigned char image, with 0 for no text and 255 for text. Values between are used for anti-aliasing.

Set `rgba` to enable RGBA output. This is useful for colour emoji rendering, or support for pango markup features like `<span foreground="red">Red!</span>`.

`text` is the text to render as a UTF-8 string. It can contain Pango markup, for example `<i>The</i>Guardian`.

`font` is the font to render with, as a fontconfig name. Examples might be `sans 12` or perhaps `bitstream charter bold 10`.

You can specify a font to load with `fontfile` . You'll need to also set the name of the font with `font` .

`width` is the number of pixels to word-wrap at. By default, lines of text wider than this will be broken at word boundaries. Use `wrap` to set lines to wrap on word or character boundaries, or to disable line breaks.

Set `justify` to turn on line justification. `align` can be used to set the alignment style for multi-line text to the low (left) edge centre, or high (right) edge. Note that the output image can be wider than `width` if there are no word breaks, or narrower if the lines don't break exactly at `width` .

`height` is the maximum number of pixels high the generated text can be. This only takes effect when `dpi` is not set, and `width` is set, making a box. In this case, `vips_text()` will search for a `dpi` and set of line breaks which will just fit the text into `width` and `height` .

You can use `autofit_dpi` to read out the DPI selected by auto fit.

`dpi` sets the resolution to render at. "sans 12" at 72 dpi draws characters approximately 12 pixels high.

`spacing` sets the line spacing, in points. It would typically be something like font size times 1.2.

You can read the coordinate of the top edge of the character from `Xoffset` / `Yoffset`. This can be helpful if you need to line up the output of several `vips_text()`.

See also: `vips_bandjoin()`, `vips_composite()`.

#### Parameters

out | output image. | [out]
text | utf-8 text string to render |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_gaussnoise ()

    int
    vips_gaussnoise (VipsImage **out,
                     int width,
                     int height,
                     ...);

Optional arguments:

- `mean` : mean of generated pixels

- `sigma` : standard deviation of generated pixels

Make a one band float image of gaussian noise with the specified distribution. The noise distribution is created by averaging 12 random numbers with the appropriate weights.

See also: `vips_black()`, `vips_xyz()`, `vips_text()`.

#### Parameters

out | output image. | [out]
width | output width |
height | output height |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_eye ()

    int
    vips_eye (VipsImage **out,
              int width,
              int height,
              ...);

Optional arguments:

- `factor` : `gdouble`, maximum spatial frequency

- `uchar` : `gboolean`, output a uchar image

Create a test pattern with increasing spatial frequency in X and amplitude in Y. `factor` should be between 0 and 1 and determines the maximum spatial frequency.

Set `uchar` to output a uchar image.

See also: `vips_zone()`.

#### Parameters

out | output image. | [out]
width | image size |
height | image size |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_sines ()

    int
    vips_sines (VipsImage **out,
                int width,
                int height,
                ...);

Optional arguments:

- `hfreq` : horizontal frequency

- `vreq` : vertical frequency

- `uchar` : output a uchar image

Creates a float one band image of the a sine waveform in two dimensions.

The number of horizontal and vertical spatial frequencies are determined by the variables `hfreq` and `vfreq` respectively. The function is useful for creating displayable sine waves and square waves in two dimensions.

If horfreq and verfreq are integers the resultant image is periodical and therefore the Fourier transform does not present spikes

Pixels are normally in [-1, +1], set `uchar` to output [0, 255].

See also: `vips_grey()`, `vips_xyz()`.

#### Parameters

out | output image. | [out]
width | image size |
height | image size |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_zone ()

    int
    vips_zone (VipsImage **out,
               int width,
               int height,
               ...);

Optional arguments:

- `uchar` : output a uchar image

Create a one-band image of a zone plate.

Pixels are normally in [-1, +1], set `uchar` to output [0, 255].

See also: `vips_eye()`, `vips_xyz()`.

#### Parameters

out | output image. | [out]
width | image size |
height | image size |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_sdf ()

    int
    vips_sdf (VipsImage **out,
              int width,
              int height,
              VipsSdfShape shape,
              ...);

Optional arguments:

- `a` : VipsArrayDouble, first point

- `b` : VipsArrayDouble, second point

- `r` : `gfloat`, radius

- `corners` : VipsArrayDouble, corner radii

Create a signed distance field (SDF) image of the given shape. Different shapes use different combinations of the optional arguments, see below.

`shape` VIPS_SDF_SHAPE_CIRCLE: create a circle centred on `a` , radius `r` .

`shape` VIPS_SDF_SHAPE_BOX: create a box with top-left corner `a` and bottom-right corner `b` .

`shape` VIPS_SDF_SHAPE_ROUNDED_BOX: create a box with top-left corner `a` and bottom-right corner `b` , whose four corners are rounded by the four-element float array `corners` . `corners` will default to 0.0.

`shape` VIPS_SDF_SHAPE_LINE: draw a line from `a` to `b` .

See also: `vips_grey()`, `vips_grid()`, `vips_xyz()`.

#### Parameters

out | output image. | [out]
width | horizontal size |
height | vertical size |
shape | SDF to create |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_identity ()

    int
    vips_identity (VipsImage **out,
                   ...);

Optional arguments:

- `bands` : number of bands to create

- `ushort` : `TRUE` for an unsigned short identity

- `size` : number of LUT elements for a ushort image

Creates an identity lookup table, ie. one which will leave an image unchanged when applied with `vips_maplut()`. Each entry in the table has a value equal to its position.

Use the arithmetic operations on these tables to make LUTs representing arbitrary functions.

Normally LUTs are 8-bit. Set `ushort` to create a 16-bit table.

Normally 16-bit tables have 65536 entries. You can set this smaller with `size` .

See also: `vips_xyz()`, `vips_maplut()`.

#### Parameters

out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_buildlut ()

    int
    vips_buildlut (VipsImage *in,
                   VipsImage **out,
                   ...);

This operation builds a lookup table from a set of points. Intermediate values are generated by piecewise linear interpolation. The lookup table is always of type VIPS_FORMAT_DOUBLE, use `vips_cast()` to change it to the type you need.

For example, consider this 2 x 2 matrix of (x, y) coordinates:

0 | 0
255 | 100

We then generate a 1 x 256 element LUT like this:

Index | Value
--- | ---
0 | 0
1 | 0.4
etc. | 0.4
255 | 100

This is then written as the output image, with the left column giving the index in the image to place the value.

The (x, y) points don't need to be sorted: we do that. You can have several Ys, each becomes a band in the output LUT. You don't need to start at zero, any integer will do, including negatives.

See also: `vips_identity()`, `vips_invertlut()`, `vips_cast()`, `vips_maplut()`.

[method]

#### Parameters

in | input matrix |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_invertlut ()

    int
    vips_invertlut (VipsImage *in,
                    VipsImage **out,
                    ...);

Optional arguments:

- `size` : generate this much

Given a mask of target values and real values, generate a LUT which will map reals to targets. Handy for linearising images from measurements of a colour chart. All values in [0,1]. Piecewise linear interpolation, extrapolate head and tail to 0 and 1.

Eg. input like this:

4 | 3 |  |
0.1 | 0.2 | 0.3 | 0.1
0.2 | 0.4 | 0.4 | 0.2
0.7 | 0.5 | 0.6 | 0.3

Means a patch with 10% reflectance produces an image with 20% in channel 1, 30% in channel 2, and 10% in channel 3, and so on.

Inputs don't need to be sorted (we do that). Generate any precision LUT, default to 256 elements.

It won't work too well for non-monotonic camera responses (we should fix this). Interpolation is simple piecewise linear; we ought to do something better really.

See also: `vips_buildlut()`.

[method]

#### Parameters

in | input mask |
out | output LUT. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_tonelut ()

    int
    vips_tonelut (VipsImage **out,
                  ...);

Optional arguments:

- `in_max` : input range

- `out_max` : output range

- `Lb` : black-point [0-100]

- `Lw` : white-point [0-100]

- `Ps` : shadow point (eg. 0.2)

- `Pm` : mid-tone point (eg. 0.5)

- `Ph` : highlight point (eg. 0.8)

- `S` : shadow adjustment (+/- 30)

- `M` : mid-tone adjustment (+/- 30)

- `H` : highlight adjustment (+/- 30)

vips_tonelut() generates a tone curve for the adjustment of image levels. It is mostly designed for adjusting the L* part of a LAB image in a way suitable for print work, but you can use it for other things too.

The curve is an unsigned 16-bit image with (`in_max` + 1) entries, each in the range [0, `out_max` ].

`Lb` , `Lw` are expressed as 0-100, as in LAB colour space. You specify the scaling for the input and output images with the `in_max` and `out_max` parameters.

#### Parameters

out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_mask_ideal ()

    int
    vips_mask_ideal (VipsImage **out,
                     int width,
                     int height,
                     double frequency_cutoff,
                     ...);

Optional arguments:

- `nodc` : don't set the DC pixel

- `reject` : invert the filter sense

- `optical` : coordinates in optical space

- `uchar` : output a uchar image

Make an ideal high- or low-pass filter, that is, one with a sharp cutoff positioned at `frequency_cutoff` , where `frequency_cutoff` is in the range 0 - 1.

This operation creates a one-band float image of the specified size. The image has values in the range [0, 1] and is typically used for multiplying against frequency domain images to filter them. Masks are created with the DC component at (0, 0). The DC pixel always has the value 1.0.

Set `nodc` to not set the DC pixel.

Set `optical` to position the DC component in the centre of the image. This makes the mask suitable for multiplying against optical Fourier transforms. See `vips_wrap()`.

Set `reject` to invert the sense of the filter. For example, low-pass becomes low-reject.

Set `uchar` to output an 8-bit unsigned char image rather than a float image. In this case, pixels are in the range [0 - 255].

See also: `vips_mask_ideal()`, `vips_mask_ideal_ring()`, `vips_mask_ideal_band()`, `vips_mask_butterworth()`, `vips_mask_butterworth_ring()`, `vips_mask_butterworth_band()`, `vips_mask_gaussian()`, `vips_mask_gaussian_ring()`, `vips_mask_gaussian_band()`.

#### Parameters

out | output image. | [out]
width | image size |
height | image size |
frequency_cutoff | threshold at which filter ends |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_mask_ideal_ring ()

    int
    vips_mask_ideal_ring (VipsImage **out,
                          int width,
                          int height,
                          double frequency_cutoff,
                          double ringwidth,
                          ...);

Optional arguments:

- `nodc` : don't set the DC pixel

- `reject` : invert the filter sense

- `optical` : coordinates in optical space

- `uchar` : output a uchar image

Make an ideal ring-pass or ring-reject filter, that is, one with a sharp ring positioned at `frequency_cutoff` of width `width` , where `frequency_cutoff` and `width` are expressed as the range 0 - 1.

See also: `vips_mask_ideal()`.

#### Parameters

out | output image. | [out]
width | image size |
height | image size |
frequency_cutoff | threshold at which filter ends |
ringwidth | ring width |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_mask_ideal_band ()

    int
    vips_mask_ideal_band (VipsImage **out,
                          int width,
                          int height,
                          double frequency_cutoff_x,
                          double frequency_cutoff_y,
                          double radius,
                          ...);

Optional arguments:

- `nodc` : don't set the DC pixel

- `reject` : invert the filter sense

- `optical` : coordinates in optical space

- `uchar` : output a uchar image

Make an ideal band-pass or band-reject filter, that is, one with a sharp cutoff around the point `frequency_cutoff_x` , `frequency_cutoff_y` , of size `radius` .

See also: `vips_mask_ideal()`.

#### Parameters

out | output image. | [out]
width | image size |
height | image size |
frequency_cutoff_x | position of band |
frequency_cutoff_y | position of band |
radius | size of band |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_mask_butterworth ()

    int
    vips_mask_butterworth (VipsImage **out,
                           int width,
                           int height,
                           double order,
                           double frequency_cutoff,
                           double amplitude_cutoff,
                           ...);

Optional arguments:

- `nodc` : don't set the DC pixel

- `reject` : invert the filter sense

- `optical` : coordinates in optical space

- `uchar` : output a uchar image

Make an butterworth high- or low-pass filter, that is, one with a variable, smooth transition positioned at `frequency_cutoff` , where `frequency_cutoff` is in range 0 - 1. The shape of the curve is controlled by `order` --- higher values give a sharper transition. See Gonzalez and Wintz, Digital Image Processing, 1987.

See also: `vips_mask_ideal()`.

#### Parameters

out | output image. | [out]
width | image size |
height | image size |
order | filter order |
frequency_cutoff | frequency threshold |
amplitude_cutoff | amplitude threshold |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_mask_butterworth_ring ()

    int
    vips_mask_butterworth_ring (VipsImage **out,
                                int width,
                                int height,
                                double order,
                                double frequency_cutoff,
                                double amplitude_cutoff,
                                double ringwidth,
                                ...);

Optional arguments:

- `nodc` : don't set the DC pixel

- `reject` : invert the filter sense

- `optical` : coordinates in optical space

- `uchar` : output a uchar image

Make a butterworth ring-pass or ring-reject filter, that is, one with a variable, smooth transition positioned at `frequency_cutoff` of width `width` , where `frequency_cutoff` is in the range 0 - 1. The shape of the curve is controlled by `order` --- higher values give a sharper transition. See Gonzalez and Wintz, Digital Image Processing, 1987.

See also: `vips_mask_ideal()`.

#### Parameters

out | output image. | [out]
width | image size |
height | image size |
order | filter order |
frequency_cutoff | frequency threshold |
amplitude_cutoff | amplitude threshold |
ringwidth | ringwidth |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_mask_butterworth_band ()

    int
    vips_mask_butterworth_band (VipsImage **out,
                                int width,
                                int height,
                                double order,
                                double frequency_cutoff_x,
                                double frequency_cutoff_y,
                                double radius,
                                double amplitude_cutoff,
                                ...);

Optional arguments:

- `nodc` : don't set the DC pixel

- `reject` : invert the filter sense

- `optical` : coordinates in optical space

- `uchar` : output a uchar image

Make an butterworth band-pass or band-reject filter, that is, one with a variable, smooth transition positioned at `frequency_cutoff_x` , `frequency_cutoff_y` , of radius `radius` . The shape of the curve is controlled by `order` --- higher values give a sharper transition. See Gonzalez and Wintz, Digital Image Processing, 1987.

See also: `vips_mask_ideal()`.

#### Parameters

out | output image. | [out]
width | image size |
height | image size |
order | filter order |
frequency_cutoff_x | band position |
frequency_cutoff_y | band position |
radius | band radius |
amplitude_cutoff | amplitude threshold |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_mask_gaussian ()

    int
    vips_mask_gaussian (VipsImage **out,
                        int width,
                        int height,
                        double frequency_cutoff,
                        double amplitude_cutoff,
                        ...);

Optional arguments:

- `nodc` : don't set the DC pixel

- `reject` : invert the filter sense

- `optical` : coordinates in optical space

- `uchar` : output a uchar image

Make a gaussian high- or low-pass filter, that is, one with a variable, smooth transition positioned at `frequency_cutoff` .

See also: `vips_mask_ideal()`.

#### Parameters

out | output image. | [out]
width | image size |
height | image size |
frequency_cutoff | frequency threshold |
amplitude_cutoff | amplitude threshold |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_mask_gaussian_ring ()

    int
    vips_mask_gaussian_ring (VipsImage **out,
                             int width,
                             int height,
                             double frequency_cutoff,
                             double amplitude_cutoff,
                             double ringwidth,
                             ...);

Optional arguments:

- `nodc` : don't set the DC pixel

- `reject` : invert the filter sense

- `optical` : coordinates in optical space

- `uchar` : output a uchar image

Make a gaussian ring-pass or ring-reject filter, that is, one with a variable, smooth transition positioned at `frequency_cutoff` of width `ringwidth` .

See also: `vips_mask_ideal()`.

#### Parameters

out | output image. | [out]
width | image size |
height | image size |
frequency_cutoff | frequency threshold |
amplitude_cutoff | amplitude threshold |
ringwidth | ringwidth |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_mask_gaussian_band ()

    int
    vips_mask_gaussian_band (VipsImage **out,
                             int width,
                             int height,
                             double frequency_cutoff_x,
                             double frequency_cutoff_y,
                             double radius,
                             double amplitude_cutoff,
                             ...);

Optional arguments:

- `nodc` : don't set the DC pixel

- `reject` : invert the filter sense

- `optical` : coordinates in optical space

- `uchar` : output a uchar image

Make a gaussian band-pass or band-reject filter, that is, one with a variable, smooth transition positioned at `frequency_cutoff_x` , `frequency_cutoff_y` , of radius `radius` .

See also: `vips_mask_ideal()`.

#### Parameters

out | output image. | [out]
width | image size |
height | image size |
frequency_cutoff_x | band position |
frequency_cutoff_y | band position |
radius | band radius |
amplitude_cutoff | amplitude threshold |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_mask_fractal ()

    int
    vips_mask_fractal (VipsImage **out,
                       int width,
                       int height,
                       double fractal_dimension,
                       ...);

Optional arguments:

- `nodc` : don't set the DC pixel

- `reject` : invert the filter sense

- `optical` : coordinates in optical space

- `uchar` : output a uchar image

This operation should be used to create fractal images by filtering the power spectrum of Gaussian white noise. See `vips_gaussnoise()`.

See also: `vips_mask_ideal()`.

#### Parameters

out | output image. | [out]
width | image size |
height | image size |
fractal_dimension | fractal dimension |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_fractsurf ()

    int
    vips_fractsurf (VipsImage **out,
                    int width,
                    int height,
                    double fractal_dimension,
                    ...);

Generate an image of size `width` by `height` and fractal dimension `fractal_dimension` . The dimension should be between 2 and 3.

See also: `vips_gaussnoise()`, `vips_mask_fractal()`.

#### Parameters

out | output image. | [out]
width | output width |
height | output height |
fractal_dimension | fractal dimension |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_worley ()

    int
    vips_worley (VipsImage **out,
                 int width,
                 int height,
                 ...);

Optional arguments:

- `cell_size` : `gint`, size of Worley cells

Create a one-band float image of Worley noise. See:

https://en.wikipedia.org/wiki/Worley_noise

Use `cell_size` to set the size of the cells from which the image is constructed. The default is 256 x 256.

If `width` and `height` are multiples of `cell_size` , the image will tessellate.

See also: `vips_perlin()`, `vips_fractsurf()`, `vips_gaussnoise()`.

#### Parameters

out | output image. | [out]
width | horizontal size |
height | vertical size |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_perlin ()

    int
    vips_perlin (VipsImage **out,
                 int width,
                 int height,
                 ...);

Optional arguments:

- `cell_size` : `gint`, size of Perlin cells

- `uchar` : output a uchar image

Create a one-band float image of Perlin noise. See:

https://en.wikipedia.org/wiki/Perlin_noise

Use `cell_size` to set the size of the cells from which the image is constructed. The default is 256 x 256.

If `width` and `height` are multiples of `cell_size` , the image will tessellate.

Normally, output pixels are VIPS_FORMAT_FLOAT in the range [-1, +1]. Set `uchar` to output a uchar image with pixels in [0, 255].

See also: `vips_worley()`, `vips_fractsurf()`, `vips_gaussnoise()`.

#### Parameters

out | output image. | [out]
width | horizontal size |
height | vertical size |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

## Types and Values

### enum VipsTextWrap

Sets the word wrapping style for `vips_text()` when used with a maximum width.

See also: `vips_text()`.

#### Members

VIPS_TEXT_WRAP_WORD | wrap at word boundaries |
VIPS_TEXT_WRAP_CHAR | wrap at character boundaries |
VIPS_TEXT_WRAP_WORD_CHAR | wrap at word boundaries, but fall back to character boundaries if there is not enough space for a full word |
VIPS_TEXT_WRAP_NONE | no wrapping |
VIPS_TEXT_WRAP_LAST |  |

### enum VipsSdfShape

The SDF to generate,

See also: `vips_sdf()`.

#### Members

VIPS_SDF_SHAPE_CIRCLE | a circle at `a` , radius `r` |
VIPS_SDF_SHAPE_BOX | a box from `a` to `b` |
VIPS_SDF_SHAPE_ROUNDED_BOX | a box with rounded `corners` from `a` to `b` |
VIPS_SDF_SHAPE_LINE | a line from `a` to `b` |
VIPS_SDF_SHAPE_LAST |  |