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

basic:
Image.Image.clear, Image.Image.clone, Image.Image.create, Image.Image.xsize, Image.Image.ysize

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

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

pasting images:
Image.Image.paste, Image.Image.paste_alpha, Image.Image.paste_alpha_color, Image.Image.paste_mask

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

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

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

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

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

mirrors an image:

original	->mirrorx();

the new image object

mirrors an image:

original	->mirrory();

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 Image.Image.skewx() and Image.Image.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

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

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

Image.Image.turbulence

Gives a randomized image;

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

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

a new image

Image.Image.test, Image.Image.noise

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

Image.Image.noise, Image.Image.Color

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

Image.Image.gamma, Image.Image.`*, Image.Image.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 Image.Image.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

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 Image.Image.copy later.)

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

the new image object

Image.Image.copy

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

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

Draws a filled rectangle on the image.

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

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.Image.Color objects).

Image.Image.Color, Image.Image.X

Changes one color (exakt match) to another. If non-exakt-match is preferred, check Image.Image.distancesq and Image.Image.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

Image.Image.copy, Image.Image.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

Image.Image.copy, Image.Image.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

factor

the new image object

Image.Image.grey, Image.Image.`*, Image.Image.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

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

Image.Image.clone, Image.Image.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)
 
generate modes; all extra arguments is given to the
generation function. These has the same name as the method:
  "Image.Image.test,"
  "Image.Image.gradients"
  "Image.Image.noise"
  "Image.Image.turbulence"
  "Image.Image.random"
  "Image.Image.randomgrey"
specials cases:
  "Image.Image.tuned_box" (coordinates is automatic)

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.

Image.Image.copy, Image.Image.clone, Image.Image.Image

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

Image.Image.select_from

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

Image.Image.grey, Image.Image.`*, Image.Image.color

position of the pixel

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

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

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

Image.Image.color, Image.Image.`*, Image.Image.modify_by_intensity

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

Compatibility functions. Do not use!

Replacement examples:

Old code:

img=map_fs(img->select_colors(200));

img=Image.Colortable(img,200)->floyd_steinberg()->map(img);

Old code:

img=map_closest(img->select_colors(17)+({({255,255,255}),({0,0,0})}));

img=Image.Colortable(img,19,({({255,255,255}),({0,0,0})}))->map(img);

Recolor an image from intensity values.

For each color an intensity is calculated, from r, g and b factors (see Image.Image.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

Image.Image.grey, Image.Image.`*, Image.Image.color

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!

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

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

originating pixel in the image

the new image object

Image.Image.distancesq

set the current color

new color

new alpha value

the object called

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

position of the pixel

color

alpha value

the object called

Generates a test image, currently random gradients.

original	->test()	...and again

the new image

May be subject to change or cease without prior warning.

Image.Image.gradients, Image.Image.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.

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

the width of the image

the height of the image

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

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 acsii-art.

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

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

Image.Image.orient, Image.Image.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

Image.Image.phasev, Image.Image.phaseh

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.

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.

Image.Image.setcolor

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

Image.Image.paste_mask, Image.Image.paste_alpha, Image.Image.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

Image.Image.paste_mask, Image.Image.paste, Image.Image.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