The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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 non-zero 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)

Perlin-like 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)

Perlin-like 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((x2-x1)**2 + (y2-y1)**2)

    1

    square of euclidean distance: ((x2-x1)**2 + (y2-y1)**2)

    2

    manhattan distance: max((y2-y1)**2, (x2-x1)**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_rgbdiff_image(im1, im2)

Creates a new image that is black, except where the pixel in im2 is different from im1, where it is the arithmetical difference to im2 per color.

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 non-zero then non-opaque values are combined with the underlying color.

super_sample controls super sampling, if any. At some point I'll probably add a adaptive super-sampler. Current possible values are:

i_fts_none

No super-sampling 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 non-super-sampling and super-sampling 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 bi-linear 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 co-ordinate 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 low-end.

spheredown_interp(pos, seg)

Calculates spherical interpolation on the fill parameter, with the cusp at the high-end.

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 grid-based super-sampling.

random_ssample(out, parm, x, y, state, ffunc, rpfunc, segs, count)

Random super-sampling.

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

Super-sampling around the circumference of a circle.

I considered saving the sin()/cos() values and transforming step-size 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@develop-help.com> (i_fountain())

SEE ALSO

Imager(3)

3 POD Errors

The following errors were encountered while parsing the POD:

Around line 1206:

Expected text after =item, not a number

Around line 1210:

Expected text after =item, not a number

Around line 1886:

Unknown directive: =category