To contents Next section

12.1 Image.Image

CLASS
Image.Image

DESCRIPTION
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,

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

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

SEE ALSO
Image, Image.Font, Image.Colortable and Image.X

METHOD
Image.Image.apply_matrix

SYNTAX
object apply_matrix(array(array(int|array(int))) matrix)
object apply_matrix(array(array(int|array(int))) matrix, int r, int g, int b)
object apply_matrix(array(array(int|array(int))) matrix, int r, int g, int b, int|float div)

DESCRIPTION
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.

ARGUMENTS
argument(s)description
array(array(int|array(int)))
the matrix; innermost is a value or an array with red, green, blue values for red, green, blue separation.
int r
int g
int b
base level of result, default is zero
int|float div
division factor, default is 1.0.

RETURNS
the new image object

METHOD
Image.Image.apply_max

SYNTAX
object apply_max(array(array(int|array(int))) matrix)
object apply_max(array(array(int|array(int))) matrix, int r, int g, int b)
object apply_max(array(array(int|array(int))) matrix, int r, int g, int b, int|float div)

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

This function is not very fast.

ARGUMENTS
argument(s)description
array(array(int|array(int)))
the matrix; innermost is a value or an array with red, green, blue values for red, green, blue separation.
int r
int g
int b
base level of result, default is zero
int|float div
division factor, default is 1.0.

RETURNS
the new image object

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

METHOD
Image.Image.autocrop,
Image.Image.find_autocrop

SYNTAX
object autocrop()
object autocrop(int border)
object autocrop(int border, Color color)
object autocrop(int border, int left, int right, int top, int bottom)
object autocrop(int border, int left, int right, int top, int bottom, Color color)
array(int) find_autocrop()
array(int) find_autocrop(int border)
array(int) find_autocrop(int border, int left, int right, int top, int bottom)

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

"Unneccesary" 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.)

ARGUMENTS
argument(s)description
int border
int left
int right
int top
int bottom
which borders to scan and cut the image; a typical example is removing the top and bottom unneccesary pixels:
img=img->autocrop(0, 0,0,1,1);

RETURNS
the new image object

SEE ALSO
copy

METHOD
Image.Image.max,
Image.Image.min,
Image.Image.sumf,
Image.Image.sum,
Image.Image.average

SYNTAX
array(float) average()
array(int) min()
array(int) max()
array(int) sum()
array(float) sumf()

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

NOTE
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.

METHOD
Image.Image.bitscale

SYNTAX
object bitscale(float factor)
object bitscale(float xfactor, float yfactor)

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

ARGUMENTS
argument(s)description
float factor
factor to use for both x and y
float xfactor
float yfactor
separate factors for x and y

RETURNS
the new image object

METHOD
Image.Image.bitscale

SYNTAX
object bitscale(int newxsize, int newysize)
object bitscale(0, int newysize)
object bitscale(int newxsize, 0)

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

ARGUMENTS
argument(s)description
int newxsize
int newysize
new image size in pixels

RETURNS
the new image object

NOTE
resulting image will be 1x1 pixels, at least

METHOD
Image.Image.box

SYNTAX
object box(int x1, int y1, int x2, int y2)
object box(int x1, int y1, int x2, int y2, int r, int g, int b)
object box(int x1, int y1, int x2, int y2, int r, int g, int b, int alpha)

DESCRIPTION
Draws a filled rectangle on the image.

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

ARGUMENTS
argument(s)description
int x1
int y1
int x2
int y2
box corners
int r
int g
int b
color of the box
int alpha
alpha value

RETURNS
the object called

METHOD
Image.Image.cast

SYNTAX
string cast(string type)

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

SEE ALSO
Image.Color and Image.X

METHOD
Image.Image.change_color

SYNTAX
object change_color(int tor, int tog, int tob)
object change_color(int fromr, int fromg, int fromb,  int tor, int tog, int tob)

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

ARGUMENTS
argument(s)description
int tor
int tog
int tob
destination color and next current color
int fromr
int fromg
int fromb
source color, default is current color

RETURNS
a new (the destination) image object

METHOD
Image.Image.circle

SYNTAX
object circle(int x, int y, int rx, int ry)
object circle(int x, int y, int rx, int ry, int r, int g, int b)
object circle(int x, int y, int rx, int ry, int r, int g, int b, int alpha)

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

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

ARGUMENTS
argument(s)description
int x
int y
circle center
int rx
int ry
circle radius in pixels
int r
int g
int b
color
int alpha
alpha value

RETURNS
the object called

METHOD
Image.Image.clear

SYNTAX
void clear()
void clear(int r, int g, int b)
void clear(int r, int g, int b, int alpha)

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

original ->clear(0,128,255)

ARGUMENTS
argument(s)description
int r
int g
int b
color of the new image
int alpha
new default alpha channel value

SEE ALSO
copy and clone

METHOD
Image.Image.clone

SYNTAX
object clone()
object clone(int xsize, int ysize)
object clone(int xsize, int ysize, int r, int g, int b)
object clone(int xsize, int ysize, int r, int g, int b, int alpha)

DESCRIPTION
Copies to or initialize a new image object.

original clone clone(50,50)

ARGUMENTS
argument(s)description
int xsize
int ysize
size of (new) image in pixels, called image is cropped to that size
int r
int g
int b
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).
int alpha
new default alpha channel value

RETURNS
the new object

SEE ALSO
copy and create

METHOD
Image.Image.color

SYNTAX
object color()
object color(int value)
object color(int r, int g, int b)

DESCRIPTION
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);

ARGUMENTS
argument(s)description
int r
int g
int b
red, green, blue factors
int value
factor

RETURNS
the new image object

SEE ALSO
grey, `* and modify_by_intensity

METHOD
Image.Image.copy

SYNTAX
object copy()
object copy(int x1, int y1, int x2, int y2)
object copy(int x1, int y1, int x2, int y2, int r, int g, int b)
object copy(int x1, int y1, int x2, int y2, int r, int g, int b, int alpha)

DESCRIPTION
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)

ARGUMENTS
argument(s)description
int x1
int y1
int x2
int y2
The requested new area. Default is the old image size.
int r
int g
int b
color of the new image
int alpha
new default alpha channel value

RETURNS
a new image object

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

SEE ALSO
clone and autocrop

METHOD
Image.Image.create

SYNTAX
void create()
void create(int xsize, int ysize)
void create(int xsize, int ysize, Color color)
void create(int xsize, int ysize, int r, int g, int b)
void create(int xsize, int ysize, int r, int g, int b, int alpha)
void create(int xsize, int ysize, string method, method ...)

DESCRIPTION
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)

generate modes; all extra arguments is given to the generation function. These has the same name as the method: "test," "gradients" "noise" "turbulence" "random" "randomgrey" specials cases: "tuned_box" (coordinates is automatic)

ARGUMENTS
argument(s)description
int xsize
int ysize
size of (new) image in pixels
Color color
int r
int g
int b
background color (will also be current color), default color is black
int alpha
default alpha channel value

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

SEE ALSO
copy, clone and Image.Image

METHOD
Image.Image.dct

SYNTAX
object dct(int newx, int newy)

DESCRIPTION
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...

ARGUMENTS
argument(s)description
int newx
int newy
new image size in pixels

RETURNS
the new image object

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

It write's dots on stderr, to indicate some sort of progress. It doesn't use any fct (compare: fft) algorithms.

METHOD
Image.Image.distancesq

SYNTAX
object distancesq()
object distancesq(int r, int g, int b)

DESCRIPTION
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

ARGUMENTS
argument(s)description
int r
int g
int b
red, green, blue coordinates

RETURNS
the new image object

SEE ALSO
select_from

METHOD
Image.Image.find_min,
Image.Image.find_max

SYNTAX
array(int) find_min()
array(int) find_max()
array(int) find_min(int r, int g, int b)
array(int) find_max(int r, int g, int b)

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

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

METHOD
Image.Image.gamma

SYNTAX
object gamma(float g)
object gamma(float gred, ggreen, gblue)

DESCRIPTION
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);

ARGUMENTS
argument(s)description
int g
int gred
int ggreen
int gblue
gamma value

RETURNS
a new image object

SEE ALSO
grey, `* and color

METHOD
Image.Image.getpixel

SYNTAX
array(int) getpixel(int x, int y)

DESCRIPTION

ARGUMENTS
argument(s)description
int x
int y
position of the pixel

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

METHOD
Image.Image.gradients

SYNTAX
int gradients(array(int) point,  ...)
int gradients(array(int) point,  ...,  float grad)

DESCRIPTION
original 2 color
gradient
10 color
gradient
3 colors,
grad=4.0
3 colors,
grad=1.0
3 colors,
grad=0.25

RETURNS
the new image

METHOD
Image.Image.grey

SYNTAX
object grey()
object grey(int r, int g, int b)

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

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

ARGUMENTS
argument(s)description
int r
int g
int b
weight of color, default is r=87,g=127,b=41, which should be pretty accurate of what the eyes see...

RETURNS
the new image object

SEE ALSO
color, `* and modify_by_intensity

METHOD
Image.Image.rgb_to_hsv,
Image.Image.hsv_to_rgb

SYNTAX
object rgb_to_hsv()
object hsv_to_rgb()

DESCRIPTION
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();

RETURNS
the new image object

METHOD
Image.Image.invert

SYNTAX
object invert()

DESCRIPTION
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();

RETURNS
the new image object

METHOD
Image.Image.line

SYNTAX
object line(int x1, int y1, int x2, int y2)
object line(int x1, int y1, int x2, int y2, int r, int g, int b)
object line(int x1, int y1, int x2, int y2, int r, int g, int b, int alpha)

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

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

ARGUMENTS
argument(s)description
int x1
int y1
int x2
int y2
line endpoints
int r
int g
int b
color
int alpha
alpha value

RETURNS
the object called

METHOD
Image.Image.make_ascii

SYNTAX
string make_ascii(object orient1,  object orient2,  object orient3,  object orient4,  int|void xsize,  int|void ysize)

DESCRIPTION
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);

RETURNS
some nice acsii-art.

NOTE
experimental status; may not be exact the same output in later versions
      |      /    -    \
hue=  0     64   128  192  (=red in an hsv image)

SEE ALSO
orient and orient4

METHOD
Image.Image.map_closest,
Image.Image.select_colors,
Image.Image.map_fast,
Image.Image.map_fs

SYNTAX
object map_closest(array(array(int)) colors)
object map_fast(array(array(int)) colors)
object map_fs(array(array(int)) colors)
array select_colors(int num)

DESCRIPTION
Compatibility functions. Do not use!

Replacement examples:

Old code:

img=map_fs(img->select_colors(200));
New code:
img=Image.Colortable(img,200)->floyd_steinberg()->map(img);

Old code:

img=map_closest(img->select_colors(17)+({({255,255,255}),({0,0,0})}));
New code:
img=Image.Colortable(img,19,({({255,255,255}),({0,0,0})}))->map(img);

METHOD
Image.Image.match

SYNTAX
object match(int|float scale,  object needle)
object match(int|float scale,  object needle,  object haystack_cert,  object needle_cert)
object match(int|float scale,  object needle,  object haystack_avoid,  int foo)
object match(int|float scale,  object needle,  object haystack_cert,  object needle_cert,  object haystack_avoid,  int foo)

DESCRIPTION
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.

ARGUMENTS
argument(s)description
int|float scale
Every pixel is divided with this value. Note that a proper value here depends on the size of the neadle.
object needle
The image to use for the matching.
object haystack_cert
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.
object needle_cert
The same, but for the needle-image.
int foo
object haystack_avoid
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.

RETURNS
the new image object

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

SEE ALSO
phasev and phaseh

METHOD
Image.Image.mirrorx

SYNTAX
object mirrorx()

DESCRIPTION
mirrors an image:
original ->mirrorx();

RETURNS
the new image object

METHOD
Image.Image.mirrory

SYNTAX
object mirrory()

DESCRIPTION
mirrors an image:
original ->mirrory();

METHOD
Image.Image.modify_by_intensity

SYNTAX
object modify_by_intensity(int r, int g, int b, int|array(int) v1, ..., int|array(int) vn)

DESCRIPTION
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}));

ARGUMENTS
argument(s)description
int r
int g
int b
red, green, blue intensity factors
int|array(int) v1
int|array(int) vn
destination color

RETURNS
the new image object

SEE ALSO
grey, `* and color

METHOD
Image.Image.noise

SYNTAX
void noise(array(float|int|array(int)) colorrange)
void noise(array(float|int|array(int)) colorrange, float scale, float xdiff, float ydiff, float cscale)

DESCRIPTION
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 );

ARGUMENTS
argument(s)description
array(float|int|array(int)) colorrange
colorrange table
float scale
default value is 0.1
float xdiff
float ydiff
default value is 0,0
float cscale
default value is 1

SEE ALSO
turbulence

METHOD
Image.Image.orient,
Image.Image.orient4

SYNTAX
object orient(void|array(object))
array(object) orient4()

DESCRIPTION
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
Red, green and blue channels are added and not compared separately.

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.

RETURNS
an image or an array of the four new image objects

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

METHOD
Image.Image.outline,
Image.Image.outline_mask

SYNTAX
object outline()
object outline(int olr, int olg, int olb)
object outline(int olr, int olg, int olb, int bkgr, int bkgg, int bkgb)
object outline(array(array(int)) mask)
object outline(array(array(int)) mask, int olr, int olg, int olb)
object outline(array(array(int)) mask, int olr, int olg, int olb, int bkgr, int bkgg, int bkgb)
object outline_mask()
object outline_mask(int bkgr, int bkgg, int bkgb)
object outline_mask(array(array(int)) mask)
object outline_mask(array(array(int)) mask, int bkgr, int bkgg, int bkgb)

DESCRIPTION
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

ARGUMENTS
argument(s)description
array(array(int)) mask
mask matrix. Default is ({({0,1,0}),({1,1,1}),({0,1,0})}).
int olr
int olg
int olb
outline color. Default is current.
int bkgr
int bkgg
int bkgb
background color (what color to outline to); default is color of pixel 0,0.
int|float div
division factor, default is 1.0.

RETURNS
the new image object

NOTE
no antialias!

METHOD
Image.Image.paste

SYNTAX
object paste(object image)
object paste(object image, int x, int y)

DESCRIPTION
Pastes a given image over the current image.

ARGUMENTS
argument(s)description
object image
image to paste (may be empty, needs to be an image object)
int x
int y
where to paste the image; default is 0,0

RETURNS
the object called

SEE ALSO
paste_mask, paste_alpha and paste_alpha_color

METHOD
Image.Image.paste_alpha

SYNTAX
object paste_alpha(object image, int alpha)
object paste_alpha(object image, int alpha, int x, int y)

DESCRIPTION
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.

ARGUMENTS
argument(s)description
object image
image to paste
int alpha
alpha channel value
int x
int y
where to paste the image; default is 0,0

RETURNS
the object called

SEE ALSO
paste_mask, paste and paste_alpha_color

METHOD
Image.Image.paste_alpha_color

SYNTAX
object paste_alpha_color(object mask)
object paste_alpha_color(object mask, int x, int y)
object paste_alpha_color(object mask, int r, int g, int b)
object paste_alpha_color(object mask, int r, int g, int b, int x, int y)
object paste_alpha_color(object mask, Color color)
object paste_alpha_color(object mask, Color color, int x, int y)

DESCRIPTION
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.

ARGUMENTS
argument(s)description
object mask
mask image
int r
int g
int b
what color to paint with; default is current
int x
int y
where to paste the image; default is 0,0

RETURNS
the object called

SEE ALSO
paste_mask, paste_alpha and paste_alpha_color

METHOD
Image.Image.paste_mask

SYNTAX
object paste_mask(object image, object mask)
object paste_mask(object image, object mask, int x, int y)

DESCRIPTION
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.

ARGUMENTS
argument(s)description
object image
image to paste
object mask
mask image
int x
int y
where to paste the image; default is 0,0

RETURNS
the object called

SEE ALSO
paste, paste_alpha and paste_alpha_color

METHOD
Image.Image.phasev,
Image.Image.phaseh,
Image.Image.phasehv,
Image.Image.phasevh

SYNTAX
object phaseh()
object phasev()
object phasevh()
object phasehv()

DESCRIPTION
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()

RETURNS
the new image object

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

BUGS
0 should not be set as explained above.

METHOD
Image.Image.polyfill

SYNTAX
object polyfill(array(int|float) ... curve)

DESCRIPTION
fills an area with the current color

ARGUMENTS
argument(s)description
array(int|float) curve
curve(s), ({x1,y1,x2,y2,...,xn,yn}), automatically closed.

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

RETURNS
the current object

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

BUGS
Inverted lines reported on Intel and Alpha processors.

SEE ALSO
setcolor

METHOD
Image.Image.random,
Image.Image.randomgrey

SYNTAX
object random()
object random(int seed)
object randomgrey()
object random(greyint seed)

DESCRIPTION
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.

RETURNS
a new image

SEE ALSO
test and noise

METHOD
Image.Image.write_lsb_rgb,
Image.Image.read_lsb_grey,
Image.Image.write_lsb_grey,
Image.Image.read_lsb_rgb

SYNTAX
object write_lsb_rgb(string what)
object write_lsb_grey(string what)
string read_lsb_rgb()
string read_lsb_grey()

DESCRIPTION
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.

ARGUMENTS
argument(s)description
string what
the hidden message

RETURNS
the current object or the read string

METHOD
Image.Image.rotate,
Image.Image.rotate_expand

SYNTAX
object rotate(int|float angle)
object rotate(int|float angle, int r, int g, int b)
object rotate_expand(int|float angle)
object rotate_expand(int|float angle, int r, int g, int b)

DESCRIPTION
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.

ARGUMENTS
argument(s)description
int|float angle
the number of degrees to rotate
int r
int g
int b
color to fill with; default is current

RETURNS
the new image object

METHOD
Image.Image.rotate_ccw

SYNTAX
object rotate_ccw()

DESCRIPTION
rotates an image counter-clockwise, 90 degrees.

original ->rotate_ccw();

RETURNS
the new image object

METHOD
Image.Image.rotate_cw

SYNTAX
object rotate_cw()

DESCRIPTION
rotates an image clockwise, 90 degrees.

original ->rotate_cw();

RETURNS
the new image object

METHOD
Image.Image.scale

SYNTAX
object scale(float factor)
object scale(0.5)
object scale(float xfactor, float yfactor)

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

ARGUMENTS
argument(s)description
float factor
factor to use for both x and y
float xfactor
float yfactor
separate factors for x and y

RETURNS
the new image object

METHOD
Image.Image.scale

SYNTAX
object scale(int newxsize, int newysize)
object scale(0, int newysize)
object scale(int newxsize, 0)

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

ARGUMENTS
argument(s)description
int newxsize
int newysize
new image size in pixels

RETURNS
the new image object

NOTE
resulting image will be 1x1 pixels, at least

METHOD
Image.Image.select_from

SYNTAX
object select_from(int x, int y)
object select_from(int x, int y, int edge_value)

DESCRIPTION
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.

ARGUMENTS
argument(s)description
int x
int y
originating pixel in the image

RETURNS
the new image object

SEE ALSO
distancesq

METHOD
Image.Image.setcolor

SYNTAX
object setcolor(int r, int g, int b)
object setcolor(int r, int g, int b, int alpha)

DESCRIPTION
set the current color

ARGUMENTS
argument(s)description
int r
int g
int b
new color
int alpha
new alpha value

RETURNS
the object called

METHOD
Image.Image.setpixel

SYNTAX
object setpixel(int x, int y)
object setpixel(int x, int y, int r, int g, int b)
object setpixel(int x, int y, int r, int g, int b, int alpha)

DESCRIPTION
original ->setpixel(10,10,255,0,0)

ARGUMENTS
argument(s)description
int x
int y
position of the pixel
int r
int g
int b
color
int alpha
alpha value

RETURNS
the object called

METHOD
Image.Image.skewx,
Image.Image.skewx_expand

SYNTAX
object skewx(int x)
object skewx(int yfactor)
object skewx(int x, int r, int g, int b)
object skewx(int yfactor, int r, int g, int b)
object skewx_expand(int x)
object skewx_expand(int yfactor)
object skewx_expand(int x, int r, int g, int b)
object skewx_expand(int yfactor, int r, int g, int b)

DESCRIPTION
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);

ARGUMENTS
argument(s)description
int x
the number of pixels The "expand" variant of functions stretches the image border pixels rather then filling with the given or current color.
float yfactor
best described as: x=yfactor*this->ysize()
int r
int g
int b
color to fill with; default is current

RETURNS
the new image object

METHOD
Image.Image.skewy,
Image.Image.skewy_expand

SYNTAX
object skewy(int y)
object skewy(int xfactor)
object skewy(int y, int r, int g, int b)
object skewy(int xfactor, int r, int g, int b)
object skewy_expand(int y)
object skewy_expand(int xfactor)
object skewy_expand(int y, int r, int g, int b)
object skewy_expand(int xfactor, int r, int g, int b)

DESCRIPTION
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.

ARGUMENTS
argument(s)description
int y
the number of pixels
float xfactor
best described as: t=xfactor*this->xsize()
int r
int g
int b
color to fill with; default is current

RETURNS
the new image object

METHOD
Image.Image.test

SYNTAX
object test()
object test(int seed)

DESCRIPTION
Generates a test image, currently random gradients.

original ->test() ...and again

RETURNS
the new image

NOTE
May be subject to change or cease without prior warning.

SEE ALSO
gradients and tuned_box

METHOD
Image.Image.threshold

SYNTAX
object threshold()
object threshold(int level)
object threshold(int r, int g, int b)
object threshold(Color color)

DESCRIPTION
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);

RETURNS
the new image object

NOTE
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.

SEE ALSO
grey

METHOD
Image.Image.tuned_box

SYNTAX
object tuned_box(int x1, int y1, int x2, int y2, array(array(int)) corner_color)

DESCRIPTION
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)

ARGUMENTS
argument(s)description
int x1
int y1
int x2
int y2
rectangle corners
array(array(int)) corner_color
colors of the corners:
({x1y1,x2y1,x1y2,x2y2})
each of these is an array of integeres:
({r,g,b}) or ({r,g,b,alpha})
Default alpha channel value is 0 (opaque).

RETURNS
the object called

METHOD
Image.Image.turbulence

SYNTAX
void turbulence(array(float|int|array(int)) colorrange)
void turbulence(array(float|int|array(int)) colorrange, int octaves, float scale, float xdiff, float ydiff, float cscale)

DESCRIPTION
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}) );

ARGUMENTS
argument(s)description
array(float|int|array(int)) colorrange
colorrange table
int octaves
default value is 3
float scale
default value is 0.1
float xdiff
float ydiff
default value is 0,0
float cscale
default value is 1

SEE ALSO
noise and Image.Color

METHOD
Image.Image.xsize

SYNTAX
int xsize()

RETURNS
the width of the image

METHOD
Image.Image.ysize

SYNTAX
int ysize()

RETURNS
the height of the image

METHOD
Image.Image.`/,
Image.Image.`%

SYNTAX
object `/(object operand)
object `/(Color color)
object `/(int value)
object `%(object operand)
object `%(Color color)
object `%(int value)

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

ARGUMENTS
argument(s)description
object operand
the other image to divide with; the images must have the same size.
Color color
int value
if specified as color or value, it will act as a whole image of that color (or value).

RETURNS
the new image object

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

SEE ALSO
`-, `+, `|, `&, `* and Image.Layer

METHOD
Image.Image.`&

SYNTAX
object `&(object operand)
object `&(array(int) color)
object `&(int value)

DESCRIPTION
makes a new image out of the minimum pixels values

ARGUMENTS
argument(s)description
object operand
the other image to compare with; the images must have the same size.
array(int) color
an array in format ({r,g,b}), this is equal to using an uniform-colored image.
int value
equal to ({value,value,value}).

RETURNS
the new image object

SEE ALSO
`-, `+, `|, `* and Image.Layer

METHOD
Image.Image.`==,
Image.Image.`<,
Image.Image.`<

SYNTAX
int `==(object operand)
int `==(array(int) color)
int `==(int value)
int `<(object operand)
int `<(array(int) color)
int `<(int value)
int `>(object operand)
int `>(array(int) color)
int `>(int value)

DESCRIPTION
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.)

ARGUMENTS
argument(s)description
object operand
the other image to compare with; the images must have the same size.
array(int) color
an array in format ({r,g,b}), this is equal to using an uniform-colored image.
int value
equal to ({value,value,value}).

RETURNS
true (1) or false (0).

NOTE
`< 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).

SEE ALSO
`-, `+, `|, `* and `&

METHOD
Image.Image.`*

SYNTAX
object `*(object operand)
object `*(array(int) color)
object `*(int value)

DESCRIPTION
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;

ARGUMENTS
argument(s)description
object operand
the other image to multiply with; the images must have the same size.
array(int) color
an array in format ({r,g,b}), this is equal to using an uniform-colored image.
int value
equal to ({value,value,value}).

RETURNS
the new image object

SEE ALSO
`-, `+, `|, `& and Image.Layer

METHOD
Image.Image.`+

SYNTAX
object `+(object operand)
object `+(array(int) color)
object `+(int value)

DESCRIPTION
adds two images; values are truncated at 255.

ARGUMENTS
argument(s)description
object operand
the image which to add.
array(int) color
an array in format ({r,g,b}), this is equal to using an uniform-colored image.
int value
equal to ({value,value,value}).

RETURNS
the new image object

SEE ALSO
`-, `|, `&, `* and Image.Layer

METHOD
Image.Image.`-

SYNTAX
object `-(object operand)
object `-(array(int) color)
object `-(int value)

DESCRIPTION
makes a new image out of the difference

ARGUMENTS
argument(s)description
object operand
the other image to compare with; the images must have the same size.
array(int) color
an array in format ({r,g,b}), this is equal to using an uniform-colored image.
int value
equal to ({value,value,value}).

RETURNS
the new image object

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

METHOD
Image.Image.`|

SYNTAX
object `|(object operand)
object `|(array(int) color)
object `|(int value)

DESCRIPTION
makes a new image out of the maximum pixels values

ARGUMENTS
argument(s)description
object operand
the other image to compare with; the images must have the same size.
array(int) color
an array in format ({r,g,b}), this is equal to using an uniform-colored image.
int value
equal to ({value,value,value}).

RETURNS
the new image object

SEE ALSO
`-, `+, `&, `* and Image.Layer

To contents Next section