NAME
filters.im  implements filters that operate on images
SYNOPSIS
i_contrast(im, 0.8);
i_hardinvert(im);
i_hardinvertall(im);
i_unsharp_mask(im, 2.0, 1.0);
... and more
DESCRIPTION
filters.c implements basic filters for Imager. These filters should be accessible from the filter interface as defined in the pod for Imager.
FUNCTION REFERENCE
Some of these functions are internal.
 saturate(in)

Clamps the input value between 0 and 255. (internal)
in  input integer
 i_contrast(im, intensity)

Scales the pixel values by the amount specified.
im  image object intensity  scalefactor
 i_hardinvert(im)

Inverts the color channels of the input image.
im  image object
 i_hardinvertall(im)

Inverts all channels of the input image.
im  image object
 i_noise(im, amount, type)

Adjusts the sample values randomly by the amount specified.
If type is 0, adjust all channels in a pixel by the same (random) amount amount, if nonzero adjust each sample independently.
im  image object amount  deviation in pixel values type  noise individual for each channel if true
 i_bumpmap(im, bump, channel, light_x, light_y, st)

Makes a bumpmap on image im using the bump image as the elevation map.
im  target image bump  image that contains the elevation info channel  to take the elevation information from light_x  x coordinate of light source light_y  y coordinate of light source st  length of shadow
 i_bumpmap_complex(im, bump, channel, tx, ty, Lx, Ly, Lz, Ip, cd, cs, n, Ia, Il, Is)

Makes a bumpmap on image im using the bump image as the elevation map.
im  target image bump  image that contains the elevation info channel  to take the elevation information from tx  shift in x direction of where to start applying bumpmap ty  shift in y direction of where to start applying bumpmap Lx  x position/direction of light Ly  y position/direction of light Lz  z position/direction of light Ip  light intensity cd  diffuse coefficient cs  specular coefficient n  surface shinyness Ia  ambient colour Il  light colour Is  specular colour
if z<0 then the L is taken to be the direction the light is shining in. Otherwise the L is taken to be the position of the Light, Relative to the image.
 i_postlevels(im, levels)

Quantizes Images to fewer levels.
im  target image levels  number of levels
 i_mosaic(im, size)

Makes an image looks like a mosaic with tilesize of size
im  target image size  size of tiles
 i_watermark(im, wmark, tx, ty, pixdiff)

Applies a watermark to the target image
im  target image wmark  watermark image tx  x coordinate of where watermark should be applied ty  y coordinate of where watermark should be applied pixdiff  the magnitude of the watermark, controls how visible it is
 i_autolevels_mono(im, lsat, usat)

Do autolevels, but monochromatically.
 i_autolevels(im, lsat, usat, skew)

Scales and translates each color such that it fills the range completely. Skew is not implemented yet  purpose is to control the color skew that can occur when changing the contrast.
im  target image lsat  fraction of pixels that will be truncated at the lower end of the spectrum usat  fraction of pixels that will be truncated at the higher end of the spectrum skew  not used yet
Note: this code calculates levels and adjusts each channel separately, which will typically cause a color shift.
 Noise(x,y)

Pseudo noise utility function used to generate perlin noise. (internal)
x  x coordinate y  y coordinate
 SmoothedNoise1(x,y)

Pseudo noise utility function used to generate perlin noise. (internal)
x  x coordinate y  y coordinate
 G_Interpolate(a, b, x)

Utility function used to generate perlin noise. (internal)
 InterpolatedNoise(x, y)

Utility function used to generate perlin noise. (internal)
 PerlinNoise_2D(x, y)

Utility function used to generate perlin noise. (internal)
 i_radnoise(im, xo, yo, rscale, ascale)

Perlinlike radial noise.
im  target image xo  x coordinate of center yo  y coordinate of center rscale  radial scale ascale  angular scale
 i_turbnoise(im, xo, yo, scale)

Perlinlike 2d noise noise.
im  target image xo  x coordinate translation yo  y coordinate translation scale  scale of noise
 i_gradgen(im, num, xo, yo, ival, dmeasure)

Gradient generating function.
im  target image num  number of points given xo  array of x coordinates yo  array of y coordinates ival  array of i_color objects dmeasure  distance measure to be used. 0 = Euclidean 1 = Euclidean squared 2 = Manhattan distance
 i_nearest_color(im, num, xo, yo, oval, dmeasure)

This wasn't document  quoth Addi:
An arty type of filter
FIXME: check IRC logs for actual text.
Inputs:
i_img *im  image to render on.
int num  number of points/colors in xo, yo, oval
i_img_dim *xo  array of num x positions
i_img_dim *yo  array of num y positions
i_color *oval  array of num colors
xo, yo, oval correspond to each other, the point xo[i], yo[i] has a color something like oval[i], at least closer to that color than other points.
int dmeasure  how we measure the distance from some point P(x,y) to any (xo[i], yo[i]).
Valid values are:
 0

euclidean distance: sqrt((x2x1)**2 + (y2y1)**2)
 1

square of euclidean distance: ((x2x1)**2 + (y2y1)**2)
 2

manhattan distance: max((y2y1)**2, (x2x1)**2)
An invalid value causes an error exit (the program is aborted).
 i_unsharp_mask(im, stddev, scale)

Perform an usharp mask, which is defined as subtracting the blurred image from double the original.
 i_diff_image(im1, im2, mindist)

Creates a new image that is transparent, except where the pixel in im2 is different from im1, where it is the pixel from im2.
The samples must differ by at least mindiff to be considered different.
 i_fountain(im, xa, ya, xb, yb, type, repeat, combine, super_sample, ssample_param, count, segs)

Draws a fountain fill using A(xa, ya) and B(xb, yb) as reference points.
type controls how the reference points are used:
 i_ft_linear

linear, where A is 0 and B is 1.
 i_ft_bilinear

linear in both directions from A.
 i_ft_radial

circular, where A is the centre of the fill, and B is a point on the radius.
 i_ft_radial_square

where A is the centre of the fill and B is the centre of one side of the square.
 i_ft_revolution

where A is the centre of the fill and B defines the 0/1.0 angle of the fill.
 i_ft_conical

similar to i_ft_revolution, except that the revolution goes in both directions
repeat can be one of:
 i_fr_none

values < 0 are treated as zero, values > 1 are treated as 1.
 i_fr_sawtooth

negative values are treated as 0, positive values are modulo 1.0
 i_fr_triangle

negative values are treated as zero, if (int)value is odd then the value is treated as 1(value mod 1.0), otherwise the same as for sawtooth.
 i_fr_saw_both

like i_fr_sawtooth, except that the sawtooth pattern repeats into negative values.
 i_fr_tri_both

Like i_fr_triangle, except that negative values are handled as their absolute values.
If combine is nonzero then nonopaque values are combined with the underlying color.
super_sample controls super sampling, if any. At some point I'll probably add a adaptive supersampler. Current possible values are:
 i_fts_none

No supersampling is done.
 i_fts_grid

A square grid of points withing the pixel are sampled.
 i_fts_random

Random points within the pixel are sampled.
 i_fts_circle

Points on the radius of a circle are sampled. This produces fairly good results, but is fairly slow since sin() and cos() are evaluated for each point.
ssample_param is intended to be roughly the number of points sampled within the pixel.
count and segs define the segments of the fill.
 i_new_fill_fount(
xa
,ya
,xb
,yb
,type
,repeat
,combine
,super_sample
,ssample_param
,count
,segs
) 
Creates a new general fill which fills with a fountain fill.
INTERNAL FUNCTIONS
 fount_init_state(...)

Used by both the fountain fill filter and the fountain fill.
 fount_getat(out, x, y, ffunc, rpfunc, state, segs, count)

Evaluates the fountain fill at the given point.
This is called by both the nonsupersampling and supersampling code.
You might think that it would make sense to sample the fill parameter instead, and combine those, but this breaks badly.
 linear_fount_f(x, y, state)

Calculate the fill parameter for a linear fountain fill.
Uses the point to line distance function, with some precalculation done in i_fountain().
 bilinear_fount_f(x, y, state)

Calculate the fill parameter for a bilinear fountain fill.
 radial_fount_f(x, y, state)

Calculate the fill parameter for a radial fountain fill.
Simply uses the distance function.
 square_fount_f(x, y, state)

Calculate the fill parameter for a square fountain fill.
Works by rotating the reference coordinate around the centre of the square.
 revolution_fount_f(x, y, state)

Calculates the fill parameter for the revolution fountain fill.
 conical_fount_f(x, y, state)

Calculates the fill parameter for the conical fountain fill.
 linear_interp(pos, seg)

Calculates linear interpolation on the fill parameter. Breaks the segment into 2 regions based in the middle value.
 sine_interp(pos, seg)

Calculates sine function interpolation on the fill parameter.
 sphereup_interp(pos, seg)

Calculates spherical interpolation on the fill parameter, with the cusp at the lowend.
 spheredown_interp(pos, seg)

Calculates spherical interpolation on the fill parameter, with the cusp at the highend.
 direct_cinterp(out, pos, seg)

Calculates the fountain color based on direct scaling of the channels of the color channels.
 hue_up_cinterp(put, pos, seg)

Calculates the fountain color based on scaling a HSV value. The hue increases as the fill parameter increases.
 hue_down_cinterp(put, pos, seg)

Calculates the fountain color based on scaling a HSV value. The hue decreases as the fill parameter increases.
 simple_ssample(out, parm, x, y, state, ffunc, rpfunc, segs, count)

Simple gridbased supersampling.
 random_ssample(out, parm, x, y, state, ffunc, rpfunc, segs, count)

Random supersampling.
 circle_ssample(out, parm, x, y, state, ffunc, rpfunc, segs, count)

Supersampling around the circumference of a circle.
I considered saving the sin()/cos() values and transforming stepsize around the circle, but that's inaccurate, though it may not matter much.
 fount_r_none(v)

Implements no repeats. Simply clamps the fill value.
 fount_r_sawtooth(v)

Implements sawtooth repeats. Clamps negative values and uses fmod() on others.
 fount_r_triangle(v)

Implements triangle repeats. Clamps negative values, uses fmod to get a range 0 through 2 and then adjusts values > 1.
 fount_r_saw_both(v)

Implements sawtooth repeats in the both postive and negative directions.
Adjusts the value to be postive and then just uses fmod().
 fount_r_tri_both(v)

Implements triangle repeats in the both postive and negative directions.
Uses fmod on the absolute value, and then adjusts values > 1.
 fill_fountf(fill, x, y, width, channels, data)

The fill function for fountain fills.
 fount_fill_destroy(fill)
AUTHOR
Arnar M. Hrafnkelsson <addi@umich.edu>
Tony Cook <tony@develophelp.com> (i_fountain())
SEE ALSO
Imager(3)
3 POD Errors
The following errors were encountered while parsing the POD:
 Around line 1205:
Expected text after =item, not a number
 Around line 1209:
Expected text after =item, not a number
 Around line 1829:
Unknown directive: =category