12. Image Module

The main object of the Image module, this object is used as drawing area, mask or result of operations.

basic:
clear, clone, create, xsize, ysize

plain drawing:
box, circle, getpixel, line, setcolor, setpixel, threshold, polyfill

operators:
`&, `*, `+, `-, `==, `>, `<, `|

pasting images:
paste, paste_alpha, paste_alpha_color, paste_mask

getting subimages, scaling, rotating:
autocrop, clone, copy, dct, mirrorx, rotate, rotate_ccw, rotate_cw, rotate_expand, scale, skewx, skewx_expand, skewy, skewy_expand

calculation by pixels:
apply_matrix, change_color, color, distancesq, grey, invert, modify_by_intensity, outline select_from, rgb_to_hsv, hsv_to_rgb, rgb_to_yuv, yuv_to_rgb,

average, max, min, sum, sumf, find_min, find_max

special pattern drawing:
noise, turbulence, test, tuned_box, gradients, random

Image, Image.Font, Image.Colortable, Image.X

Divides pixel values and creates a new image from the result or the rest.

the other image to divide with; the images must have the same size.

if specified as color or value, it will act as a whole image of that color (or value).

the new image object

It isn't possible to do a modulo 256 either. (why?)

`-, `+, `|, `&, `*, Image.Layer

makes a new image out of the minimum pixels values

the other image to compare with; the images must have the same size.

an array in format ({r,g,b}), this is equal to using an uniform-colored image.

equal to ({value,value,value}).

the new image object

`-, `+, `|, `*, Image.Layer

Multiplies pixel values and creates a new image. This can be useful to lower the values of an image, making it greyer, for instance:

image=image*128+64;

the other image to multiply with; the images must have the same size.

an array in format ({r,g,b}), this is equal to using an uniform-colored image.

equal to ({value,value,value}).

the new image object

`-, `+, `|, `&, Image.Layer

adds two images; values are truncated at 255.

the image which to add.

an array in format ({r,g,b}), this is equal to using an uniform-colored image.

equal to ({value,value,value}).

the new image object

`-, `|, `&, `*, Image.Layer

makes a new image out of the difference

the other image to compare with; the images must have the same size.

an array in format ({r,g,b}), this is equal to using an uniform-colored image.

equal to ({value,value,value}).

the new image object

`+, `|, `&, `*, Image.Layer, min, max, `==

Compares an image with another image or a color.

Comparision is strict and on pixel-by-pixel basis. (Means if not all pixel r,g,b values are correct compared with the corresponding pixel values, 0 is returned.)

the other image to compare with; the images must have the same size.

an array in format ({r,g,b}), this is equal to using an uniform-colored image.

equal to ({value,value,value}).

true (1) or false (0).

`< or `> on empty ("no image") image objects or images with different size will result in an error. `== is always true on two empty image objects and always false if one and only one of the image objects is empty or the images differs in size.

a>=b and a<=b between objects is equal to !(a<b) and !(a>b), which may not be what you want (since both < and > can return false, comparing the same images).

`-, `+, `|, `*, `&

makes a new image out of the maximum pixels values

the other image to compare with; the images must have the same size.

an array in format ({r,g,b}), this is equal to using an uniform-colored image.

equal to ({value,value,value}).

the new image object

`-, `+, `&, `*, Image.Layer

Apply a lookup-table on all pixels in an image. If only one curve is passed, use the same curve for red, green and blue. If 'channel' is specified, the curve is only applied to the specified channel.

An array with 256 elements, each between 0 and 255. It is used as a look-up table, if the pixel value is 2 and curve[2] is 10, the new pixel value will be 10.

one of "red", "green", "blue", "value", "saturation" and "hue".

a new image object

gamma, `*, modify_by_intensity

Applies a pixel-transform matrix, or filter, to the image.

                       2   2
pixel(x,y)= base+ k ( sum sum pixel(x+k-1,y+l-1)*matrix(k,l) )
                      k=0 l=0

1/k is sum of matrix, or sum of matrix multiplied with div. base is given by r,g,b and is normally black.

blur (ie a 2d gauss function): ({({1,2,1}), ({2,5,2}), ({1,2,1})})
		original
sharpen (k>8, preferably 12 or 16): ({({-1,-1,-1}), ({-1, k,-1}), ({-1,-1,-1})})
edge detect: ({({1, 1,1}), ({1,-8,1}), ({1, 1,1})})
horisontal edge detect (get the idea): ({({0, 0,0}), ({1,-2,1}), ({0, 0,0})})
emboss (might prefer to begin with a grey image): ({({2, 1, 0}), ({1, 0,-1}), ({0,-1,-2})}), 128,128,128, 3
		greyed

This function is not very fast.

the matrix; innermost is a value or an array with red, green, blue values for red, green, blue separation.

base level of result, default is zero

division factor, default is 1.0.

the new image object

This is the same as apply_matrix, but it uses the maximum instead.

This function is not very fast.

the matrix; innermost is a value or an array with red, green, blue values for red, green, blue separation.

base level of result, default is zero

division factor, default is 1.0.

the new image object

experimental status; may not be exact the same output in later versions

Removes "unnecessary" borders around the image, adds one of its own if wanted to, in selected directions.

"Unnecessary" is all pixels that are equal -- ie if all the same pixels to the left are the same color, that column of pixels are removed.

The find_autocrop() function simply returns x1,y1,x2,y2 for the kept area. (This can be used with copy later.)

which borders to scan and cut the image; a typical example is removing the top and bottom unnecessary pixels:

img=img->autocrop(0, 0,0,1,1);

the new image object

copy

Gives back the average, minimum, maximum color value, and the sum of all pixel's color value.

sum() values can wrap! Most systems only have 31 bits available for positive integers. (Meaning, be careful with images that have more than 8425104 pixels.)

average() and sumf() may also wrap, but on a line basis. (Meaning, be careful with images that are wider than 8425104 pixels.) These functions may have a precision problem instead, during to limits in the 'double' C type and/or 'float' Pike type.

scales the image with a factor, without smoothing. This routine is faster than scale, but gives less correct results

original	bitscale(0.75)	scale(0.75)

factor to use for both x and y

separate factors for x and y

the new image object

scales the image to a specified new size, if one of newxsize or newysize is 0, the image aspect ratio is preserved.

new image size in pixels

the new image object

resulting image will be 1x1 pixels, at least

A special case of apply_matrix that creates a blur effect. About four times faster than the generic apply_matrix. @[no_pass] is the number of times the blur matrix is applied.

original	blur(1)	blur(5)

apply_matrix, grey_blur

Draws a filled rectangle on the image.

original	->box (40,10, 10,80, 0,255,0)	->box (40,10, 10,80, 255,0,0,75)

box corners

color of the box

alpha value

the object called

Cast the image to another datatype. Currently supported are string ("rgbrgbrgb...") and array (double array of Image.Color objects).

Image.Color, Image.X

Changes one color (exact match) to another. If non-exact-match is preferred, check distancesq and paste_alpha_color.

destination color and next current color

source color, default is current color

a new (the destination) image object

Draws a circle on the image. The circle is not antialiased.

original	->circle (50,50, 30,50, 0,255,255)

circle center

circle radius in pixels

color

alpha value

the object called

gives a new, cleared image with the same size of drawing area

original	->clear (0,128,255)

color of the new image

new default alpha channel value

copy, clone

Copies to or initialize a new image object.

original	clone	clone(50,50)

size of (new) image in pixels, called image is cropped to that size

current color of the new image, default is black. Will also be the background color if the cloned image is empty (no drawing area made).

new default alpha channel value

the new object

copy, create

Colorize an image.

The red, green and blue values of the pixels are multiplied with the given value(s). This works best on a grey image...

The result is divided by 255, giving correct pixel values.

If no arguments are given, the current color is used as factors.

original	->color(128,128,255);

red, green, blue factors

Color object with factors

factor

the new image object

grey, `*, modify_by_intensity

Copies this part of the image. The requested area can be smaller, giving a cropped image, or bigger - the new area will be filled with the given or current color.

original	->copy (5,5, XSIZE-6,YSIZE-6)	->copy (-5,-5, XSIZE+4,YSIZE+4, 10,75,10)

The requested new area. Default is the old image size.

color of the new image

new default alpha channel value

a new image object

clone(void) and copy(void) does the same operation

clone, autocrop

Initializes a new image object.

Image.Image (XSIZE,YSIZE)	Image.Image (XSIZE,YSIZE,255,128,0)

The image can also be calculated from some special methods, for convinience:

channel modes; followed by a number of 1-char-per-pixel strings
or image objects (where red channel will be used),
or an integer value:
  "grey" : make a grey image (needs 1 source: grey)
  "rgb"  : make an rgb image (needs 3 sources: red, green and blue)
  "cmyk" : make a rgb image from cmyk (cyan, magenta, yellow, black)
  "adjusted_cmyk" : make a rgb image from cmyk
           (cyan, magenta, yellow, black) where the colors aren't
           100% pure (C: 009ee0, M: e2007a, Y: ffec00, K: 1a171b).
  "raw"  : make an image from a binary string
 
generate modes; all extra arguments is given to the
generation function. These has the same name as the method:
  "<ref>test</ref>,"
  "<ref>gradients</ref>"
  "<ref>noise</ref>"
  "<ref>turbulence</ref>"
  "<ref>random</ref>"
  "<ref>randomgrey</ref>"
specials cases:
  "<ref>tuned_box</ref>" (coordinates is automatic)

Image to clone.

size of (new) image in pixels

background color (will also be current color), default color is black

default alpha channel value

SIGSEGVS can be caused if the size is too big, due to unchecked overflow - (xsize*ysize)&MAXINT is small enough to allocate.

copy, clone, Image.Image

Scales the image to a new size.

Method for scaling is rather complex; the image is transformed via a cosine transform, and then resampled back.

This gives a quality-conserving upscale, but the algorithm used is n*n+n*m, where n and m is pixels in the original and new image.

Recommended wrapping algorithm is to scale overlapping parts of the image-to-be-scaled.

This functionality is actually added as an true experiment, but works...

new image size in pixels

the new image object

Do NOT use this function if you don't know what you're dealing with! Read some signal theory first...

It doesn't use any fct (compare: fft) algorithms.

Makes an grey-scale image, for alpha-channel use.

The given value (or current color) are used for coordinates in the color cube. Each resulting pixel is the distance from this point to the source pixel color, in the color cube, squared, rightshifted 8 steps:

p = pixel color
o = given color
d = destination pixel
d.red=d.blue=d.green=
    ((o.red-p.red)²+(o.green-p.green)²+(o.blue-p.blue)²)>>8

original	distance² to cyan	...to purple	...to yellow

red, green, blue coordinates

the new image object

select_from

Gives back the position of the minimum or maximum pixel value, weighted to grey.

weight of color, default is r=87,g=127,b=41, same as the grey() method.

Calculate pixels in image by gamma curve.

Intensity of new pixels are calculated by:
i' = i^g

For example, you are viewing your image on a screen with gamma 2.2. To correct your image to the correct gamma value, do something like:

my_display_image(my_image()->gamma(1/2.2);

gamma value

a new image object

grey, `*, color

position of the pixel

color of the requested pixel -- ({int red,int green,int blue})

the new image

Makes a grey-scale image (with weighted values).

original	->grey();	->grey(0,0,255);

weight of color, default is r=87,g=127,b=41, which should be pretty accurate of what the eyes see...

the new image object

color, `*, modify_by_intensity

Works like blur, but only operates on the r color channel. A faster alternative to blur for grey scale images. @[no_pass] is the number of times the blur matrix is applied.

original	grey_blur(1)	grey_blur(5)

blur

Converts RGB data to HSV data, or the other way around. When converting to HSV, the resulting data is stored like this: pixel.r = h; pixel.g = s; pixel.b = v;

When converting to RGB, the input data is asumed to be placed in the pixels as above.

original	->hsv_to_rgb();	->rgb_to_hsv();
tuned box (below)	the rainbow (below)	same, but rgb_to_hsv()

HSV to RGB calculation:

in = input pixel
out = destination pixel
h=-pos*c_angle*3.1415/(float)NUM_SQUARES;
out.r=(in.b+in.g*cos(in.r));
out.g=(in.b+in.g*cos(in.r + pi*2/3));
out.b=(in.b+in.g*cos(in.r + pi*4/3));

RGB to HSV calculation: Hmm.

Example: Nice rainbow.

 object i = Image.Image(200,200);
 i = i->tuned_box(0,0, 200,200,
                  ({ ({ 255,255,128 }), ({ 0,255,128 }),
                     ({ 255,255,255 }), ({ 0,255,255 })}))
      ->hsv_to_rgb();
 

the new image object

Invert an image. Each pixel value gets to be 255-x, where x is the old value.

original	->invert();	->rgb_to_hsv()->invert()->hsv_to_rgb();

the new image object

Draws a line on the image. The line is not antialiased.

original	->line (50,10, 10,50, 255,0,0)

line endpoints

color

alpha value

the object called

This method creates a string that looks like the image. Example:

   //Stina is an image with a cat.
   array(object) Stina4=Stina->orient4();
   Stina4[1]*=215;
   Stina4[3]*=215;
   string foo=Stina->make_ascii(@Stina4,40,4,8);

some nice ASCII art.

experimental status; may not be exact the same output in later versions

      |      /    -    \
     hue=  0     64   128  192  (=red in an hsv image)

orient, orient4

This method creates an image that describes the match in every pixel in the image and the needle-Image.

   new pixel value =
     sum( my_abs(needle_pixel-haystack_pixel))

The new image only have the red rgb-part set.

Every pixel is divided with this value. Note that a proper value here depends on the size of the neadle.

The image to use for the matching.

This image should be the same size as the image itselves. A non-white-part of the haystack_cert-image modifies the output by lowering it.

The same, but for the needle-image.

This image should be the same size as the image itselves. If foo is less than the red value in haystack_avoid the corresponding matching-calculating is not calculated. The avoided parts are drawn in the color 0,100,0.

the new image object

experimental status; may not be exact the same output in later versions

phasev, phaseh

mirrors an image:

original	->mirrorx();

the new image object

mirrors an image:

original	->mirrory();

Recolor an image from intensity values.

For each color an intensity is calculated, from r, g and b factors (see grey), this gives a value between 0 and max.

The color is then calculated from the values given, v1 representing the intensity value of 0, vn representing max, and colors between representing intensity values between, linear.

original	->grey()->modify_by_intensity(1,0,0, 0,({255,0,0}),({0,255,0}));

red, green, blue intensity factors

destination color

the new image object

grey, `*, color

Gives a new image with the old image's size, filled width a 'noise' pattern.

The random seed may be different with each instance of pike.

Example: ->noise( ({0,({255,0,0}), 0.3,({0,255,0}), 0.6,({0,0,255}), 0.8,({255,255,0})}), 0.2,0.0,0.0,1.0 );

colorrange table

default value is 0.1

default value is 0,0

default value is 1

turbulence

Draws images describing the orientation of the current image.

orient gives an HSV image (run a hsv_to_rgb pass on it to get a viewable image). corresponding to the angle of the orientation:

      |      /    -    \
     hue=  0     64   128  192  (=red in an hsv image)
         purple cyan green red

If you first use orient4 you can give its output as input to this function.

The orient4 function gives back 4 image objects, corresponding to the amount of different directions, see above.

an image or an array of the four new image objects

experimental status; may not be exact the same output in later versions

Makes an outline of this image, ie paints with the given color around the non-background pixels.

Default is to paint above, below, to the left and the right of these pixels.

You can also run your own outline mask.

The outline_mask function gives the calculated outline as an alpha channel image of white and black instead.

original	masked through threshold	...and outlined with red

mask matrix. Default is ({({0,1,0}),({1,1,1}),({0,1,0})}).

outline color. Default is current.

background color (what color to outline to); default is color of pixel 0,0.

division factor, default is 1.0.

the new image object

no antialias!

Pastes a given image over the current image.

image to paste (may be empty, needs to be an image object)

where to paste the image; default is 0,0

the object called

paste_mask, paste_alpha, paste_alpha_color

Pastes a given image over the current image, with the specified alpha channel value.

An alpha channel value of 0 leaves nothing of the original image in the paste area, 255 is meaningless and makes the given image invisible.

image to paste

alpha channel value

where to paste the image; default is 0,0

the object called

paste_mask, paste, paste_alpha_color

Pastes a given color over the current image, using the given mask as opaque channel.

A pixel value of 255 makes the result become the color given, 0 doesn't change anything.

The masks red, green and blue values are used separately. If no color are given, the current is used.

mask image

what color to paint with; default is current

where to paste the image; default is 0,0

the object called

paste_mask, paste_alpha, paste_alpha_color

Pastes a given image over the current image, using the given mask as opaque channel.

A pixel value of 255 makes the result become a pixel from the given image, 0 doesn't change anything.

The masks red, green and blue values are used separately.

image to paste

mask image

where to paste the image; default is 0,0

the object called

paste, paste_alpha, paste_alpha_color

Draws images describing the phase of the current image. phaseh gives the horizontal phase and phasev the vertical phase.

phaseh gives an image where

       max  falling   min  rising
value=  0     64      128   192

0 is set if there is no way to determine if it is rising or falling. This is done for the every red, green and blue part of the image.

Phase images can be used to create ugly effects or to find meta-information in the orginal image.

original	phaseh()	phasev()	phasevh()	phasehv()

the new image object

experimental status; may not be exact the same output in later versions

0 should not be set as explained above.

fills an area with the current color

curve(s), ({x1,y1,x2,y2,...,xn,yn}), automatically closed.

If any given curve is inside another, it will make a hole.

Image.Image(100,100)->setcolor(255,0,0,128)->
  polyfill( ({ 20,20, 80,20, 80,80 }) );

the current object

Lines in the polygon may not be crossed without the crossing coordinate specified in both lines.

Inverted lines reported on Intel and Alpha processors.

setcolor

Gives a randomized image;

original	->random()	->random(17)	greyed (same again)	color(red) (same again)	...red channel

Use with ->grey() or ->color() for one-color-results.

a new image

test, noise

These functions read/write in the least significant bit of the image pixel values. The _rgb() functions read/write on each of the red, green and blue values, and the grey keeps the same lsb on all three.

The string is nullpadded or cut to fit.

the hidden message

the current object or the read string

Converts RGB data to YUV (YCrCb) data, or the other way around. When converting to YUV, the resulting data is stored like this: pixel.r = v (cr); pixel.g = y; pixel.b = u (cb);

When converting to RGB, the input data is asumed to be placed in the pixels as above.

original	->yuv_to_rgb();	->rgb_to_yuv();
tuned box (below)	the rainbow (below)	same, but rgb_to_yuv()

RGB to YUB calculation (this follows CCIR.601):

in = input pixel
out = destination pixel
Ey = 0.299*in.r+0.587*in.g+0.114*in.b
Ecr = 0.713*(in.r - Ey) = 0.500*in.r-0.419*in.g-0.081*in.b
Ecb = 0.564*(in.b - Ey) = -0.169*in.r-0.331*in.g+0.500*in.b
out.r=0.875*Ecr+128
out.g=0.86*Ey+16
out.b=0.875*Ecb+128

Example: Nice rainbow.

 object i = Image.Image(200,200);
 i = i->tuned_box(0,0, 200,200,
                  ({ ({ 255,255,128 }), ({ 0,255,128 }),
                     ({ 255,255,255 }), ({ 0,255,255 })}))
      ->yuv_to_rgb();
 

the new image object

Rotates an image a certain amount of degrees (360° is a complete rotation) counter-clockwise:

original	->rotate(15,255,0,0);	->rotate_expand(15);

The "expand" variant of functions stretches the image border pixels rather then filling with the given or current color.

This rotate uses the skewx() and skewy() functions.

the number of degrees to rotate

color to fill with; default is current

the new image object

rotates an image counter-clockwise, 90 degrees.

original	->rotate_ccw();

the new image object

rotates an image clockwise, 90 degrees.

original	->rotate_cw();

the new image object

scales the image with a factor, 0.5 is an optimized case.

factor to use for both x and y

separate factors for x and y

the new image object

scales the image to a specified new size, if one of newxsize or newysize is 0, the image aspect ratio is preserved.

new image size in pixels

the new image object

resulting image will be 1x1 pixels, at least

Makes an grey-scale image, for alpha-channel use.

This is very close to a floodfill.

The image is scanned from the given pixel, filled with 255 if the color is the same, or 255 minus distance in the colorcube, squared, rightshifted 8 steps (see distancesq).

When the edge distance is reached, the scan is stopped. Default edge value is 30. This value is squared and compared with the square of the distance above.

35, 35, 16	35, 35, 32	35, 35, 64	35, 35, 96	35, 35, 128	35, 35, 192	35, 35, 256

original	original * select_from(35,35,200)

originating pixel in the image

the new image object

distancesq

set the current color

new color

new alpha value

the object called

position of the pixel

color

alpha value

the object called

Skews an image an amount of pixels or a factor; a skew-x is a transformation:

original	->skewx(15,255,0,0);	->skewx_expand(15);

the number of pixels The "expand" variant of functions stretches the image border pixels rather then filling with the given or current color.

best described as: x=yfactor*this->ysize()

color to fill with; default is current

the new image object

Skews an image an amount of pixels or a factor; a skew-y is a transformation:

original	->skewy(15,255,0,0);	->skewy_expand(15);

The "expand" variant of functions stretches the image border pixels rather then filling with the given or current color.

the number of pixels

best described as: t=xfactor*this->xsize()

color to fill with; default is current

the new image object

Generates a test image, currently random gradients.

original	->test()	...and again

the new image

May be subject to change or cease without prior warning.

gradients, tuned_box

Makes a black-white image.

If any of red, green, blue parts of a pixel is larger then the given value, the pixel will become white, else black.

This method works fine with the grey method.

If no arguments are given, it will paint all non-black pixels white. (Ie, default is 0,0,0.)

original	->threshold(100);	->threshold(0,100,0);

the new image object

The above statement "any ..." was changed from "all ..." in Pike 0.7 (9906). It also uses 0,0,0 as default input, instead of current color. This is more useful.

grey

Draws a filled rectangle with colors (and alpha values) tuned between the corners.

Tuning function is (1.0-x/xw)*(1.0-y/yw) where x and y is the distance to the corner and xw and yw are the sides of the rectangle.

original	tuned box	solid tuning (blue,red,green,yellow)	tuning transparency (as left + 255,128,128,0)

rectangle corners

colors of the corners:

({x1y1,x2y1,x1y2,x2y2})

({r,g,b}) or ({r,g,b,alpha})

the object called

gives a new image with the old image's size, filled width a 'turbulence' pattern

The random seed may be different with each instance of pike.

Example:
->turbulence( ({0,({229,204,204}), 0.9,({229,20,20}), 0.9,Color.black}) );

colorrange table

default value is 3

default value is 0.1

default value is 0,0

default value is 1

noise, Image.Color

the width of the image

the height of the image

layers

Set/change/get image and alpha channel for the layer. You could also cancel the channels giving 0 instead of an image object.

image and alpha channel must be of the same size, or canceled.

Set/get the general alpha value of this layer. This is a float value between 0 and 1, and is multiplied with the alpha channel.

This crops (of finds) a suitable crop, non-destructive crop. The layer alpha channel is checked, and edges that is transparent is removed.

(What really happens is that the image and alpha channel is checked, and edges equal the fill setup is cropped away.)

find_autocrop() returns an array of xoff,yoff,xsize,ysize, which can be fed to crop().

A tiled image will not be cropped at all.

left...bottom arguments can be used to tell what sides cropping are ok on.

crop, Image.Image->autocrop

Set/get layer mode. Mode is one of these:

top layer
bottom layer
normal
	D=L applied with alpha: D=(L*aL+S*(1-aL)*aS) / (aL+(1-aL)*aS), aD=(aL+(1-aL)*aS)
add
	D=L+S applied with alpha, aD=aS
subtract
	D=S-L applied with alpha, aD=aS
multiply
	D=S*L applied with alpha, aD=aS
divide
	D=S/L applied with alpha, aD=aS
negdivide
	D=1.0-S/L applied with alpha, aD=aS
modulo
	D=S%L applied with alpha, aD=aS
invsubtract
	D=L-S applied with alpha, aD=aS
invdivide
	D=L/S applied with alpha, aD=aS
invmodulo
	D=L%S applied with alpha, aD=aS
imultiply
	D=(1-L)*S applied with alpha, aD=aS
idivide
	D=S/(1-L) applied with alpha, aD=aS
invidivide
	D=L/(1-S) applied with alpha, aD=aS
difference
	D=abs(L-S) applied with alpha, aD=aS
max
	D=max(L,S) applied with alpha, aD=aS
min
	D=min(L,S) applied with alpha, aD=aS
bitwise_and
	D=L&S applied with alpha, aD=aS
bitwise_or
	D=L|S applied with alpha, aD=aS
bitwise_xor
	D=L^S applied with alpha, aD=aS
replace
	D=(L*aL+S*(1-aL)*aS) / (aL+(1-aL)*aS), aD=aS
red
	Dr=(Lr*aLr+Sr*(1-aLr)*aSr) / (aLr+(1-aLr)*aSr), Dgb=Sgb, aD=aS
green
	Dg=(Lg*aLg+Sg*(1-aLg)*aSg) / (aLg+(1-aLg)*aSg), Drb=Srb, aD=aS
blue
	Db=(Lb*aLb+Sb*(1-aLb)*aSb) / (aLb+(1-aLb)*aSb), Drg=Srg, aD=aS
hardlight
	Like photoshop hardlight layer mode, aD=aS
replace_hsv
	Dhsv=Lhsv apply with alpha, aD=aS
hue
	Dh=Lh apply with alpha, Dsv=Lsv, aD=aS
saturation
	Ds=Ls apply with alpha, Dhv=Lhv, aD=aS
value
	Dv=Lv apply with alpha, Dhs=Lhs, aD=aS
color
	Dhs=Lhs apply with alpha, Dv=Lv, aD=aS
value_mul
	Dv=Lv*Sv apply with alpha, Dhs=Lhs, aD=aS
darken
	Dv=min(Lv,Sv) apply with alpha, Dhs=Lhs, aD=aS
lighten
	Dv=max(Lv,Sv) apply with alpha, Dhs=Lhs, aD=aS
saturate
	Ds=max(Ls,Ss) apply with alpha, Dhv=Lhv, aD=aS
desaturate
	Ds=min(Ls,Ss) apply with alpha, Dhv=Lhv, aD=aS
hls_replace
	Dhls=Lhls apply with alpha, aD=aS
hls_hue
	Dh=Lh apply with alpha, Dsv=Lsv, aD=aS
hls_saturation
	Ds=Ls apply with alpha, Dhv=Lhv, aD=aS
hls_lightness
	Dl=Ll apply with alpha, Dhs=Lhs, aD=aS
hls_color
	Dhs=Lhs apply with alpha, Dl=Ll, aD=aS
hls_lightness_mul
	Dl=Ll*Sl apply with alpha, Dhs=Lhs, aD=aS
hls_darken
	Dl=min(Ll,Sl) apply with alpha, Dhs=Lhs, aD=aS
hls_lighten
	Dl=max(Ll,Sl) apply with alpha, Dhs=Lhs, aD=aS
hls_saturate
	Ds=max(Ls,Ss) apply with alpha, Dhl=Lhl, aD=aS
hls_desaturate
	Ds=min(Ls,Ss) apply with alpha, Dhl=Lhl, aD=aS
dissolve
	i=random 0 or 1, D=i?L:S, aD=i+aS
behind
	D=(S*aS+L*(1-aS)*aL) / (aS+(1-aS)*aL), aD=(aS+(1-aS)*aL); simply swap S and L
erase
	D=S, aD=aS*(1-aL)
screen
	1-(1-S)*(1-L) applied with alpha, aD=aS
overlay
	(1-(1-a)*(1-b)-a*b)*a+a*b applied with alpha, aD=aS
burn_alpha
	aD=aL+aS applied with alpha, D=L+S; experimental, may change or be removed
equal
	each channel D=max if L==S, 0 otherwise, apply with alpha
not_equal
	each channel D=max if L!=S, 0 otherwise, apply with alpha
less
	each channel D=max if L<S, 0 otherwise, apply with alpha
more
	each channel D=max if L>S, 0 otherwise, apply with alpha
less_or_equal
	each channel D=max if L<=S, 0 otherwise, apply with alpha
more_or_equal
	each channel D=max if L>=S, 0 otherwise, apply with alpha
logic_equal
	logic: D=white and opaque if L==S, black and transparent otherwise
logic_not_equal
	logic: D=white and opaque if any L!=S, black and transparent otherwise
logic_strict_less
	logic: D=white and opaque if all L<S, black and transparent otherwise
logic_strict_more
	logic: D=white and opaque if all L>S, black and transparent otherwise
logic_strict_less_equal
	logic: D=white and opaque if all L<=L, black and transparent otherwise
logic_strict_more_equal
	logic: D=white and opaque if all L>=L, black and transparent otherwise

available_modes() simply gives an array containing the names of these modes.

image and alpha channel must be of the same size, or canceled.

([ "xsize":int, "ysize":int, "image":image, "alpha":image, "xoffset":int, "yoffset":int, "fill":image, "fill_alpha":image "tiled":int, "mode":string ])

Creates a copy of the called object.

the copy

The Layer construct either three arguments, the image object, alpha channel and mode, or a mapping with optional elements:

"image":image,
        // default: black
 
"alpha":alpha,
        // alpha channel object
        // default: full opaque
 
"mode":string mode,
        // layer mode, see <ref>mode</ref>.
        // default: "normal"
 
"alpha_value":float(0.0-1.0),
        // layer general alpha value
        // default is 1.0; this is multiplied
        // with the alpha channel.
 
"xoffset":int,
"yoffset":int,
        // offset of this layer
 
"fill":Color,
"fill_alpha":Color,
        // fill color, ie what color is used
        // "outside" the image. default: black
        // and black (full transparency).
 
"tiled":int(0|1),
        // select tiling; if 1, the image
        // will be tiled. deafult: 0, off

All values can be modified after object creation.

image and alpha channel must be of the same size.

Crops this layer at this offset and size. Offset is not relative the layer offset, so this can be used to crop a number of layers simuntaneously.

The fill values are used if the layer is enlarged.

a new layer object

The new layer object may have the same image object, if there was no cropping to be done.

Layer descriptions

Set/query fill color and alpha, ie the color used "outside" the image. This is mostly useful if you want to "frame" a layer.

Set or query misc. attributes for the layer.

As an example, the XCF and PSD image decoders set the 'name' attribute to the name the layer had in the source file.

Set/query layer offset.

Set/query tiled flag. If set, the image and alpha channel will be tiled rather then framed by the fill values.

Query layer offset. This is the same as layer image/alpha image size.

Short technical documentation on a font file: This object adds the text-drawing and -creation capabilities of the Image module.

For simple usage, see write and load.

	       struct file_head
	       {
		  unsigned INT32 cookie;   - 0x464f4e54
		  unsigned INT32 version;  - 1
		  unsigned INT32 chars;    - number of chars
		  unsigned INT32 height;   - height of font
		  unsigned INT32 baseline; - font baseline
		  unsigned INT32 o[1];     - position of char_head's
	       } *fh;
	       struct char_head
	       {
		  unsigned INT32 width;    - width of this character
		  unsigned INT32 spacing;  - spacing to next character
		  unsigned char data[1];   - pixmap data (1byte/pixel)
	       } *ch;

            version 2:


            	  On-disk syntax (everything in N.B.O), int is 4 bytes, a byte is 8 bits:

            pos
            	0   int cookie = 'FONT';     or 0x464f4e54
            	4   int version = 2;         1 was the old version without the last four chars
            	8   int numchars;            Always 256 in this version of the dump program
            12   int height;              in (whole) pixels
            16   int baseline;            in (whole) pixels
            20   char direction;          1==right to left, 0 is left to right
            21   char format;             Font format
            22   char colortablep;        Colortable format
            23   char kerningtablep;      Kerning table format

            24   int offsets[numchars];   pointers into the data, realative to &cookie.
            	    [colortable]
            	    [kerningtable]

            	  At each offset:


            0   int width;               in pixels
            4   int spacing;             in 1/1000:th of a pixels
            8   char data[];             Enough data to plot width * font->height pixels
            				    Please note that if width is 0, there is no data.

            Font formats:
            	id type
            	 0 Raw 8bit data
            	 1 RLE encoded data,  char length, char data,   70% more compact than raw data
            	 2 ZLib compressed data                         60% more compact than RLE

            Colortable types:
            	 0 No colortable		 (the data is an alpha channel)
            	 1 24bit RGB with alpha         (index->color, 256*4 bytes, rgba)
            	 2 8bit Greyscale with alpha    (index->color, 256*2 bytes)

            Kerningtable types:
            	 0 No kerning table
            	 1 numchars*numchars entries, each a signed char with the kerning value
            	 2 numchar entries, each with a list of kerning pairs, like this:
            	    int len
            	    len * (short char, short value)
 

Image, Image.Image

Returns font baseline (pixels from top)

height, text_extents

Loads a font file to this font object. Similar to load().

Returns the font height.

baseline, text_extents

Loads a font file to this font object.

Returns zero upon failure and a font object upon success.

The path to the font file.

write

Set spacing scale to write characters closer or more far away. This does not change scale of character, only the space between them.

Calculate extents of a text-image, that would be created by calling write with the same arguments. One or more lines of text may be provided.

write, height, baseline

Writes some text; thus creating an image object that can be used as mask or as a complete picture. One or more text lines may be provided.

text_extents, load, Image.Image->paste_mask, Image.Image->paste_alpha_color

This object keeps colortable information, mostly for image re-coloring (quantization).

The object has color reduction, quantisation, mapping and dithering capabilities.

Image, Image.Image, Image.Font, Image.GIF

Map colors in an image object to the colors in the colortable, and creates a new image with the closest colors.

						no dither
						floyd_steinberg dither
						ordered dither
						randomcube dither
original	2	4	8	16	32 colors

a new image object

Flat (not cube) colortable and not 'full' method: this method does figure out the data needed for the lookup method, which may take time the first use of the colortable - the second use is quicker.

cubicles, full

sums colortables

Colortable object with colors to add

the resulting new Colortable object

subtracts colortables

Colortable object with colors to subtract

the resulting new Colortable object

create initiates a colortable object. Default is that no colors are in the colortable.

add takes the same argument(s) as create, thus adding colors to the colortable.

The colortable is mostly a list of colors, or more advanced, colors and weight.

The colortable could also be a colorcube, with or without additional scales. A colorcube is the by-far fastest way to find colors.

Example:

ct=colortable(my_image,256); // the best 256 colors
ct=colortable(my_image,256,({0,0,0})); // black and the best other 255
 
ct=colortable(({({0,0,0}),({255,255,255})})); // black and white
 
ct=colortable(6,7,6); // a colortable of 252 colors
ct=colortable(7,7,5, ({0,0,0}),({255,255,255}),11);
        // a colorcube of 245 colors, and a greyscale of the rest -> 256

list of colors

colortable to copy colors from.

source image

number of colors to get from the image

0 (zero) gives all colors in the image.

Default value is 256.

needed colors (to optimize selection of others to these given)

this will add to the total number of colors (see argument 'number')

size of sides in the colorcube, must (of course) be equal or larger than 2 - if smaller, the cube is ignored (no colors). This could be used to have only scales (like a greyscale) in the output.

This is to add the possibility of adding a scale of colors to the colorcube; for instance a grayscale using the arguments ({0,0,0}),({255,255,255}),17, adding a scale from black to white in 17 or more steps.

Colors already in the cube is used again to add the number of steps, if possible.

The total number of colors in the table is therefore r*b*g+step1+...+stepn.

max hash size is (probably, set by a #define) 32768 entries, giving maybe half that number of colors as maximum.

cast the colortable to an array or mapping, the array consists of Image.Color objects and are not in index order. The mapping consists of index:Image.Color pairs, where index is the index (int) of that color.

example: (mapping)Image.Colortable(img)

must be "string", "array" or "mapping".

Gives the eight corners in rgb colorspace as an array. The "black" and "white" corners are the first two.

Set the colortable to use the cubicles algorithm to lookup the closest color. This is a mostly very fast and very accurate way to find the correct color, and the default algorithm.

The colorspace is divided in small cubes, each cube containing the colors in that cube. Each cube then gets a list of the colors in the cube, and the closest from the corners and midpoints between corners.

When a color is needed, the algorithm first finds the correct cube and then compares with all the colors in the list for that cube.

example: colors=Image.Colortable(img)->cubicles();

algorithm time: between O[m] and O[m * n], where n is numbers of colors and m is number of pixels

The arguments can be heavy trimmed for the usage of your colortable; a large number (10×10×10 or bigger) of cubicles is recommended when you use the colortable repeatedly, since the calculation takes much more time than usage.

recommended values:

image size  setup
100×100     cubicles(4,5,4) (default)
1000×1000   cubicles(12,12,12) (factor 2 faster than default)

In some cases, the full method is faster.

original	default cubicles, 16 colors	accuracy=200

Size, ie how much the colorspace is divided. Note that the size of each cubicle is at least about 8b, and that it takes time to calculate them. The number of cubicles are r*g*b, and default is 4,5,4, ie 80 cubicles. This works good for 200±100 colors.

Accuracy when checking sides of cubicles. Default is 16. A value of 1 gives complete accuracy, ie cubicle() method gives exactly the same result as full(), but takes (in worst case) 16× the time to calculate.

the object being called

this method doesn't figure out the cubicles, this is done on the first use of the colortable.

Not applicable to colorcube types of colortable.

Set dithering method to floyd_steinberg.

The arguments to this method is for fine-tuning of the algorithm (for computer graphics wizards).

original	floyd_steinberg to a 4×4×4 colorcube	floyd_steinberg to 16 chosen colors

Set algorithm direction of forward. -1 is backward, 1 is forward, 0 for toggle of direction each line (default).

Set error correction directions. Default is forward=7, downforward=1, down=5, downback=3.

Error keeping factor. Error will increase if more than 1.0 and decrease if less than 1.0. A value of 0.0 will cancel any dither effects. Default is 0.95.

the object being called

Set the colortable to use full scan to lookup the closest color.

example: colors=Image.Colortable(img)->full();

algorithm time: O[n*m], where n is numbers of colors and m is number of pixels

the object being called

Not applicable to colorcube types of colortable.

cubicles, map

Returns true if this colortable only contains greyscale.

cast the colortable to an image object

each pixel in the image object is an entry in the colortable

the resulting image object

Set no dithering (default).

the object being called

Set ordered dithering, which gives a position-dependent error added to the pixel values.

original	mapped to Image.Colortable(6,6,6)->
	ordered (42,42,42,2,2)	ordered()	ordered (42,42,42, 8,8, 0,0, 0,1, 1,0)

The maximum error. Default is 32, or colorcube steps (256/size).

Size of error matrix. Default is 8×8. Only values which factors to multiples of 2 and 3 are possible to choose (2,3,4,6,8,12,...).

Offset for the error matrix. x and y is for both red, green and blue values, the other is individual.

the object being called

randomcube, nodither, floyd_steinberg, create

Set random cube dithering. Color choosen is the closest one to color in picture plus (flat) random error; color±random(error).

The randomgrey method uses the same random error on red, green and blue and the randomcube method has three random errors.

original	mapped to Image.Colortable(4,4,4)->
	randomcube()	randomgrey()

The maximum error. Default is 32, or colorcube step.

the object being called

randomgrey method needs colorcube size to be the same on red, green and blue sides to work properly. It uses the red colorcube value as default.

ordered, nodither, floyd_steinberg, create

reduces the number of colors

All needed (see create) colors are kept.

reduce_fs creates and keeps the outmost corners of the color space, to improve floyd-steinberg dithering result. (It doesn't work very well, though.)

target number of colors

the new Colortable object

this algorithm assumes all colors are different to begin with (!)

reduce_fs keeps the "corners" as "needed colors".

corners

Set the colortable to use the "rigid" method of looking up colors.

This is a very simple way of finding the correct color. The algorithm initializes a cube with r x g x b colors, where every color is chosen by closest match to the corresponding coordinate.

This format is not recommended for exact match, but may be usable when it comes to quickly view pictures on-screen.

It has a high init-cost and low use-cost. The structure is initiated at first usage.

the object being called

Not applicable to colorcube types of colortable.

cubicles, map, full