Pike Manual

12. Image Module

Class Image.Image

Class Image.Layer

Class Image.Font

Class Image.Colortable

Module Image.Color

Class Image.Color.Color

Module Colors

Module Image.ANY

Module Image

Module Image.AVS

Module Image.BMP

Module Image.DSI

Module Image.DWG

Module Image.Dims

Module Image.Fonts

Class Image.Fonts.FTFont

Class Image.Fonts.Font

Class Image.Fonts.TTFont

Module Image.FreeType

Class Image.FreeType.Face

Module Image.GIF

Module Image.HRZ

Module Image.ILBM

Module Image.JPEG

Class Image.JPEG.Marker

Module Image.NEO

Module Image.PCX

Module Image.PNG

Module Image.PNM

Module Image.PS

Module Image.PSD

Class Image.PSD.Layer

Module Image.PVR

Module Image.RAS

Module Image.SVG

Module Image.TGA

Module Image.TIFF

Module Image.TIM

Module Image.TTF

Class Image.TTF.Face

Class Image.TTF.FaceInstance

Module Image.WBMP

Module Image.WebP

Module Image.X

Module Image.XBM

Module Image.XCF

Class Image.XCF.Channel

Class Image.XCF.GimpImage

Class Image.XCF.Guide

Class Image.XCF.Hierarchy

Class Image.XCF.Layer

Class Image.XCF.LayerMask

Class Image.XCF.Parasite

Class Image.XCF.Path

Class Image.XCF.PathPoint

Module Image.XFace

Module Image.XPM

Module Image.XWD

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

See also

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

Method`/ Method`%: object res = Image.Image() / operand
object res = Image.Image() / color
object res = Image.Image() / value
object res = Image.Image() % operand
object res = Image.Image() % color
object res = Image.Image() % value
Description: Divides pixel values and creates a new image from the result or the rest.
Parameter operand: the other image to divide with; the images must have the same size.
Parameter color
Parameter 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: `-, `+, `|, `&, `*, Image.Layer

Method`&: object res = Image.Image() & operand
object res = Image.Image() & color
object res = Image.Image() & value
Description: makes a new image out of the minimum pixels values
Parameter operand: the other image to compare with; the images must have the same size.
Parameter color: an array in format ({r,g,b}), this is equal to using an uniform-colored image.
Parameter value: equal to ({value,value,value}).
Returns: the new image object
See also: `-, `+, `|, `*, Image.Layer

Method`*

object res = Image.Image() * operand
object res = Image.Image() * color
object res = Image.Image() * value
object res = Image.Image() * 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;

Parameter operand

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

Parameter color

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

Parameter value

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

Returns

the new image object

See also

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

Method`+: object res = Image.Image() + operand
object res = Image.Image() + color
object res = Image.Image() + value
Description: adds two images; values are truncated at 255.
Parameter operand: the image which to add.
Parameter color: an array in format ({r,g,b}), this is equal to using an uniform-colored image.
Parameter value: equal to ({value,value,value}).
Returns: the new image object
See also: `-, `|, `&, `*, Image.Layer

Method`-: object res = Image.Image() - operand
object res = Image.Image() - color
object res = Image.Image() - value
Description: makes a new image out of the difference
Parameter operand: the other image to compare with; the images must have the same size.
Parameter color: an array in format ({r,g,b}), this is equal to using an uniform-colored image.
Parameter value: equal to ({value,value,value}).
Returns: the new image object
See also: `+, `|, `&, `*, Image.Layer, min, max, `==

Method`== Method`< Method`>

int res = Image.Image() == operand
int res = Image.Image() == color
int res = Image.Image() == value
int res = Image.Image() < operand
int res = Image.Image() < color
int res = Image.Image() < value
int res = Image.Image() > operand
int res = Image.Image() > color
int res = Image.Image() > 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.)

Parameter operand

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

Parameter color

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

Parameter 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

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

Method`|: object res = Image.Image() | operand
object res = Image.Image() | color
object res = Image.Image() | value
Description: makes a new image out of the maximum pixels values
Parameter operand: the other image to compare with; the images must have the same size.
Parameter color: an array in format ({r,g,b}), this is equal to using an uniform-colored image.
Parameter value: equal to ({value,value,value}).
Returns: the new image object
See also: `-, `+, `&, `*, Image.Layer

Methodapply_curve: objectapply_curve(objectarray(int(0..255)
objectapply_curve(objectarray(int(0..255)
objectapply_curve(objectstringchannel, objectarray(int(0..255)
Description: 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.
Parameter curve_r
Parameter curve_g
Parameter curve_b
Parameter curve: 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.
Parameter channel: one of "red", "green", "blue", "value", "saturation" and "hue".
Returns: a new image object
See also: gamma, `*, modify_by_intensity

Methodapply_matrix

objectapply_matrix(array(array(int|array(int))) matrix)
objectapply_matrix(array(array(int|array(int))) matrix, intr, intg, intb)
objectapply_matrix(array(array(int|array(int))) matrix, intr, intg, intb, int|floatdiv)

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.

Parameter array

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

Parameter r

Parameter g

Parameter b

base level of result, default is zero

Parameter div

division factor, default is 1.0.

Returns

the new image object

Methodapply_max

objectapply_max(array(array(int|array(int))) matrix)
objectapply_max(array(array(int|array(int))) matrix, intr, intg, intb)
objectapply_max(array(array(int|array(int))) matrix, intr, intg, intb, int|floatdiv)

Description

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

This function is not very fast.

Parameter array

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

Parameter r

Parameter g

Parameter b

base level of result, default is zero

Parameter 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

Methodautocrop Methodfind_autocrop

objectautocrop()
objectautocrop(intborder)
objectautocrop(intborder, Colorcolor)
objectautocrop(intborder, intleft, intright, inttop, intbottom)
objectautocrop(intborder, intleft, intright, inttop, intbottom, Colorcolor)
array(int) find_autocrop()
array(int) find_autocrop(intborder)
array(int) find_autocrop(intborder, intleft, intright, inttop, intbottom)

Description

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

Parameter border

Parameter left

Parameter right

Parameter top

Parameter bottom

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

Returns

the new image object

See also

copy

Methodaverage Methodmin Methodmax Methodsum Methodsumf

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.

Methodbitscale

objectbitscale(floatfactor)
objectbitscale(floatxfactor, floatyfactor)

Description

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)

Parameter factor

factor to use for both x and y

Parameter xfactor

Parameter yfactor

separate factors for x and y

Returns

the new image object

Methodbitscale: objectbitscale(intnewxsize, intnewysize)
objectbitscale(0, intnewysize)
objectbitscale(intnewxsize, 0)
Description: scales the image to a specified new size, if one of newxsize or newysize is 0, the image aspect ratio is preserved.
Parameter newxsize
Parameter newysize: new image size in pixels
Returns: the new image object
Note: resulting image will be 1x1 pixels, at least

Methodblur

stringblur(intno_pass)

Description

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)

See also

apply_matrix, grey_blur

Methodbox

objectbox(intx1, inty1, intx2, inty2)
objectbox(intx1, inty1, intx2, inty2, intr, intg, intb)
objectbox(intx1, inty1, intx2, inty2, intr, intg, intb, intalpha)

Description

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)

Parameter x1

Parameter y1

Parameter x2

Parameter y2

box corners

Parameter r

Parameter g

Parameter b

color of the box

Parameter alpha

alpha value

Returns

the object called

Methodcast: (string)Image.Image() (array)Image.Image()
Description: Cast the image to another datatype. Currently supported are string ("rgbrgbrgb...") and array (double array of Image.Color objects).
See also: Image.Color, Image.X

Methodchange_color: objectchange_color(inttor, inttog, inttob)
objectchange_color(intfromr, intfromg, intfromb, inttor, inttog, inttob)
Description: Changes one color (exact match) to another. If non-exact-match is preferred, check distancesq and paste_alpha_color.
Parameter tor
Parameter tog
Parameter tob: destination color and next current color
Parameter fromr
Parameter fromg
Parameter fromb: source color, default is current color
Returns: a new (the destination) image object

Methodcircle

objectcircle(intx, inty, intrx, intry)
objectcircle(intx, inty, intrx, intry, intr, intg, intb)
objectcircle(intx, inty, intrx, intry, intr, intg, intb, intalpha)

Description

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


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

Parameter x

Parameter y

circle center

Parameter rx

Parameter ry

circle radius in pixels

Parameter r

Parameter g

Parameter b

color

Parameter alpha

alpha value

Returns

the object called

Methodclear

objectclear()
objectclear(intr, intg, intb)
objectclear(intr, intg, intb, intalpha)

Description

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


original	->clear (0,128,255)

Parameter r

Parameter g

Parameter b

color of the new image

Parameter alpha

new default alpha channel value

See also

copy, clone

Methodclone

objectclone()
objectclone(intxsize, intysize)
objectclone(intxsize, intysize, intr, intg, intb)
objectclone(intxsize, intysize, intr, intg, intb, intalpha)

Description

Copies to or initialize a new image object.


original	clone	clone(50,50)

Parameter xsize

Parameter ysize

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

Parameter r

Parameter g

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

Parameter alpha

new default alpha channel value

Returns

the new object

See also

copy, create

Methodcolor

objectcolor()
objectcolor(intvalue)
objectcolor(Colorcolor)
objectcolor(intr, intg, intb)

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

Parameter r

Parameter g

Parameter b

red, green, blue factors

Parameter color

Color object with factors

Parameter value

factor

Returns

the new image object

See also

grey, `*, modify_by_intensity

Methodcopy

objectcopy()
objectcopy(intx1, inty1, intx2, inty2)
objectcopy(intx1, inty1, intx2, inty2, intr, intg, intb)
objectcopy(intx1, inty1, intx2, inty2, intr, intg, intb, intalpha)

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)

Parameter x1

Parameter y1

Parameter x2

Parameter y2

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

Parameter r

Parameter g

Parameter b

color of the new image

Parameter alpha

new default alpha channel value

Returns

a new image object

Note

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

See also

clone, autocrop

Methodcreate

Image.ImageImage.Image()
Image.ImageImage.Image(Image.Imageimage)
Image.ImageImage.Image(intxsize, intysize)
Image.ImageImage.Image(intxsize, intysize, Colorcolor)
Image.ImageImage.Image(intxsize, intysize, intr, intg, intb)
Image.ImageImage.Image(intxsize, intysize, intr, intg, intb, intalpha)
Image.ImageImage.Image(intxsize, intysize, stringmethod, 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)
  "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)

Parameter image

Image to clone.

Parameter xsize

Parameter ysize

size of (new) image in pixels

Parameter color

Parameter r

Parameter g

Parameter b

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

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

Methoddct

objectdct(intnewx, intnewy)

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

Parameter newx

Parameter 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 doesn't use any fct (compare: fft) algorithms.

Methoddistancesq

objectdistancesq()
objectdistancesq(intr, intg, intb)

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

Parameter r

Parameter g

Parameter b

red, green, blue coordinates

Returns

the new image object

See also

select_from

Methodfind_min Methodfind_max: array(int) find_min()
array(int) find_max()
array(int) find_min(intr, intg, intb)
array(int) find_max(intr, intg, intb)
Description: Gives back the position of the minimum or maximum pixel value, weighted to grey.
Parameter r
Parameter g
Parameter b: weight of color, default is r=87,g=127,b=41, same as the grey() method.

Methodgamma

objectgamma(floatg)
objectgamma(floatgred, objectfloatggreen, objectfloatgblue)

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

Parameter g

Parameter gred

Parameter ggreen

Parameter gblue

gamma value

Returns

a new image object

See also

grey, `*, color

Methodgetpixel: array(int) getpixel(intx, inty)
Parameter x
Parameter y: position of the pixel
Returns: color of the requested pixel -- ({int red,int green,int blue})

Methodgradients

intgradients(array(int) point, object...)
intgradients(array(int) point, object..., objectfloatgrad)

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

Methodgrey

objectgrey()
objectgrey(intr, intg, intb)

Description

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


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

Parameter r

Parameter g

Parameter 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, `*, modify_by_intensity

Methodgrey_blur

objectgrey_blur(intno_pass)

Description

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)

See also

blur

Methodrgb_to_hsv Methodhsv_to_rgb

objectrgb_to_hsv()
objecthsv_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

Methodinvert

objectinvert()

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

Methodline

objectline(intx1, inty1, intx2, inty2)
objectline(intx1, inty1, intx2, inty2, intr, intg, intb)
objectline(intx1, inty1, intx2, inty2, intr, intg, intb, intalpha)

Description

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


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

Parameter x1

Parameter y1

Parameter x2

Parameter y2

line endpoints

Parameter r

Parameter g

Parameter b

color

Parameter alpha

alpha value

Returns

the object called

Methodmake_ascii

stringmake_ascii(objectorient1, objectorient2, objectorient3, objectorient4, int|voidtlevel, int|voidxsize, int|voidysize)

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 ASCII 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, orient4

Methodmatch

objectmatch(int|floatscale, objectobjectneedle)
objectmatch(int|floatscale, objectobjectneedle, objectobjecthaystack_cert, objectobjectneedle_cert)
objectmatch(int|floatscale, objectobjectneedle, objectobjecthaystack_avoid, objectintfoo)
objectmatch(int|floatscale, objectobjectneedle, objectobjecthaystack_cert, objectobjectneedle_cert, objectobjecthaystack_avoid, objectintfoo)

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.

Parameter scale

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

Parameter needle

The image to use for the matching.

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

Parameter needle_cert

The same, but for the needle-image.

Parameter foo

Parameter 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, phaseh

Methodmirrorx

objectmirrorx()

Description

mirrors an image:


original	->mirrorx();

Returns

the new image object

Methodmirrory

objectmirrory()

Description

mirrors an image:


original	->mirrory();

Methodmodify_by_intensity

objectmodify_by_intensity(intr, intg, intb, 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}));

Parameter r

Parameter g

Parameter b

red, green, blue intensity factors

Parameter v1

Parameter vn

destination color

Returns

the new image object

See also

grey, `*, color

Methodnoise

voidnoise(array(float|int|array(int)) colorrange)
voidnoise(array(float|int|array(int)) colorrange, floatscale, floatxdiff, floatydiff, floatcscale)

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

Parameter colorrange

colorrange table

Parameter scale

default value is 0.1

Parameter xdiff

Parameter ydiff

default value is 0,0

Parameter cscale

default value is 1

See also

turbulence

Methodorient Methodorient4

objectorient(void|array(object) something)
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

Methodoutline Methodoutline_mask

objectoutline()
objectoutline(intolr, intolg, intolb)
objectoutline(intolr, intolg, intolb, intbkgr, intbkgg, intbkgb)
objectoutline(array(array(int)) mask)
objectoutline(array(array(int)) mask, intolr, intolg, intolb)
objectoutline(array(array(int)) mask, intolr, intolg, intolb, intbkgr, intbkgg, intbkgb)
objectoutline_mask()
objectoutline_mask(intbkgr, intbkgg, intbkgb)
objectoutline_mask(array(array(int)) mask)
objectoutline_mask(array(array(int)) mask, intbkgr, intbkgg, intbkgb)

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

Parameter mask

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

Parameter olr

Parameter olg

Parameter olb

outline color. Default is current.

Parameter bkgr

Parameter bkgg

Parameter bkgb

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

Parameter div

division factor, default is 1.0.

Returns

the new image object

Note

no antialias!

Methodpaste: objectpaste(objectimage)
objectpaste(objectimage, intx, inty)
Description: Pastes a given image over the current image.
Parameter image: image to paste (may be empty, needs to be an image object)
Parameter x
Parameter y: where to paste the image; default is 0,0
Returns: the object called
See also: paste_mask, paste_alpha, paste_alpha_color

Methodpaste_alpha

objectpaste_alpha(objectimage, intalpha)
objectpaste_alpha(objectimage, intalpha, intx, inty)

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.

Parameter image

image to paste

Parameter alpha

alpha channel value

Parameter x

Parameter y

where to paste the image; default is 0,0

Returns

the object called

See also

paste_mask, paste, paste_alpha_color

Methodpaste_alpha_color

objectpaste_alpha_color(objectmask)
objectpaste_alpha_color(objectmask, intx, inty)
objectpaste_alpha_color(objectmask, intr, intg, intb)
objectpaste_alpha_color(objectmask, intr, intg, intb, intx, inty)
objectpaste_alpha_color(objectmask, Colorcolor)
objectpaste_alpha_color(objectmask, Colorcolor, intx, inty)

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.

Parameter mask

mask image

Parameter r

Parameter g

Parameter b

what color to paint with; default is current

Parameter x

Parameter y

where to paste the image; default is 0,0

Returns

the object called

See also

paste_mask, paste_alpha, paste_alpha_color

Methodpaste_mask

objectpaste_mask(objectimage, objectmask)
objectpaste_mask(objectimage, objectmask, intx, inty)

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.

Parameter image

image to paste

Parameter mask

mask image

Parameter x

Parameter y

where to paste the image; default is 0,0

Returns

the object called

See also

paste, paste_alpha, paste_alpha_color

Methodphaseh Methodphasev Methodphasevh Methodphasehv

objectphaseh()
objectphasev()
objectphasevh()
objectphasehv()

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.

Methodpolyfill

objectpolyfill(array(int|float) ... curve)

Description

fills an area with the current color

Parameter curve

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

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

Methodrandom Methodrandomgrey

objectrandom()
objectrandom(intseed)
objectrandom(function(int:string) random)
objectrandomgrey()
objectrandomgrey(intseed)
objectrandomgrey(function(int:string) random)

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

Methodwrite_lsb_rgb Methodwrite_lsb_grey Methodread_lsb_rgb Methodread_lsb_grey

objectwrite_lsb_rgb(stringwhat)
objectwrite_lsb_grey(stringwhat)
stringread_lsb_rgb()
stringread_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.

Parameter what

the hidden message

Returns

the current object or the read string

Methodrgb_to_yuv Methodyuv_to_rgb

objectrgb_to_yuv()
objectyuv_to_rgb()

Description

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

Returns

the new image object

Methodrotate Methodrotate_expand

objectrotate(int|floatangle)
objectrotate(int|floatangle, intr, intg, intb)
objectrotate_expand(int|floatangle)
objectrotate_expand(int|floatangle, intr, intg, intb)

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.

Parameter angle

the number of degrees to rotate

Parameter r

Parameter g

Parameter b

color to fill with; default is current

Returns

the new image object

Methodrotate_ccw

objectrotate_ccw()

Description

rotates an image counter-clockwise, 90 degrees.


original	->rotate_ccw();

Returns

the new image object

Methodrotate_cw

objectrotate_cw()

Description

rotates an image clockwise, 90 degrees.


original	->rotate_cw();

Returns

the new image object

Methodscale: objectscale(floatfactor)
objectscale(0.5)
objectscale(floatxfactor, floatyfactor)
Description: scales the image with a factor, 0.5 is an optimized case.
Parameter factor: factor to use for both x and y
Parameter xfactor
Parameter yfactor: separate factors for x and y
Returns: the new image object

Methodscale: objectscale(intnewxsize, intnewysize)
objectscale(0, intnewysize)
objectscale(intnewxsize, 0)
Description: scales the image to a specified new size, if one of newxsize or newysize is 0, the image aspect ratio is preserved.
Parameter newxsize
Parameter newysize: new image size in pixels
Returns: the new image object
Note: resulting image will be 1x1 pixels, at least

Methodselect_from

objectselect_from(intx, inty)
objectselect_from(intx, inty, intedge_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.


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)

Parameter x

Parameter y

originating pixel in the image

Returns

the new image object

See also

distancesq

Methodsetcolor: objectsetcolor(intr, intg, intb)
objectsetcolor(intr, intg, intb, intalpha)
Description: set the current color
Parameter r
Parameter g
Parameter b: new color
Parameter alpha: new alpha value
Returns: the object called

Methodsetpixel

objectsetpixel(intx, inty)
objectsetpixel(intx, inty, Image.Colorc)
objectsetpixel(intx, inty, intr, intg, intb)
objectsetpixel(intx, inty, intr, intg, intb, intalpha)

Description


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

Parameter x

Parameter y

position of the pixel

Parameter r

Parameter g

Parameter b

color

Parameter alpha

alpha value

Returns

the object called

Methodskewx Methodskewx_expand

objectskewx(intx)
objectskewx(floatyfactor)
objectskewx(intx, intr, intg, intb)
objectskewx(floatyfactor, intr, intg, intb)
objectskewx_expand(intx)
objectskewx_expand(floatyfactor)
objectskewx_expand(intx, intr, intg, intb)
objectskewx_expand(floatyfactor, intr, intg, intb)

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

Parameter x

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

Parameter yfactor

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

Parameter r

Parameter g

Parameter b

color to fill with; default is current

Returns

the new image object

Methodskewy Methodskewy_expand

objectskewy(inty)
objectskewy(floatxfactor)
objectskewy(inty, intr, intg, intb)
objectskewy(floatxfactor, intr, intg, intb)
objectskewy_expand(inty)
objectskewy_expand(floatxfactor)
objectskewy_expand(inty, intr, intg, intb)
objectskewy_expand(floatxfactor, intr, intg, intb)

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.

Parameter y

the number of pixels

Parameter xfactor

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

Parameter r

Parameter g

Parameter b

color to fill with; default is current

Returns

the new image object

Methodtest

objecttest()
objecttest(intseed)
objecttest(function(int:string) random)

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

Methodthreshold

objectthreshold()
objectthreshold(intlevel)
objectthreshold(intr, intg, intb)
objectthreshold(Colorcolor)

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

Methodtuned_box

objecttuned_box(intx1, inty1, intx2, inty2, 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)

Parameter x1

Parameter y1

Parameter x2

Parameter y2

rectangle corners

Parameter 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

Methodturbulence

voidturbulence(array(float|int|array(int)) colorrange)
voidturbulence(array(float|int|array(int)) colorrange, intoctaves, floatscale, floatxdiff, floatydiff, floatcscale)

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

Parameter colorrange

colorrange table

Parameter octaves

default value is 3

Parameter scale

default value is 0.1

Parameter xdiff

Parameter ydiff

default value is 0,0

Parameter cscale

default value is 1

See also

noise, Image.Color

Methodxsize: intxsize()
Returns: the width of the image

Methodysize: intysize()
Returns: the height of the image

Class Image.Layer

See also: layers

Methodset_image Methodimage Methodalpha: objectset_image(Image.Imageimage)
objectset_image(Image.Imageimage, Image.Imagealpha_channel)
object|int(0..)image()
object|int(0..)alpha()
Description: Set/change/get image and alpha channel for the layer. You could also cancel the channels giving 0 instead of an image object.
Note: image and alpha channel must be of the same size, or canceled.

Methodset_alpha_value Methodalpha_value: objectset_alpha_value(floatvalue)
floatalpha_value()
Description: 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.

Methodautocrop Methodfind_autocrop

objectautocrop()
objectautocrop(boolleft, boolright, booltop, boolbottom)
array(int) find_autocrop()
array(int) find_autocrop(boolleft, boolright, booltop, boolbottom)

Description

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

Note

A tiled image will not be cropped at all.

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

See also

crop, Image.Image->autocrop

Methodset_mode Methodmode Methodavailable_modes

objectset_mode(stringmode)
stringmode()
array(string) available_modes()

Description

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

All channels are calculated separately, if nothing else is specified.

top layer

bottom layer

normal
	D=L applied with alpha: D=(LaL+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&amp;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=(LaL+S(1-aL)aS) / (aL+(1-aL)aS), aD=aS
red
	Dr=(LraLr+Sr(1-aLr)aSr) / (aLr+(1-aLr)aSr), Dgb=Sgb, aD=aS
green
	Dg=(LgaLg+Sg(1-aLg)aSg) / (aLg+(1-aLg)aSg), Drb=Srb, aD=aS
blue
	Db=(LbaLb+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=(SaS+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)-ab)a+ab 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&lt;S, 0 otherwise, apply with alpha
more
	each channel D=max if L&gt;S, 0 otherwise, apply with alpha
less_or_equal
	each channel D=max if L&lt;=S, 0 otherwise, apply with alpha
more_or_equal
	each channel D=max if L&gt;=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&lt;S, black and transparent otherwise
logic_strict_more
	logic: D=white and opaque if all L&gt;S, black and transparent otherwise
logic_strict_less_equal
	logic: D=white and opaque if all L&lt;=L, black and transparent otherwise
logic_strict_more_equal
	logic: D=white and opaque if all L&gt;=L, black and transparent otherwise

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

Note

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

Methodcast: (mapping(string:mixed))Image.Layer() (string)Image.Layer()
Description: ([ "xsize":int, "ysize":int, "image":image, "alpha":image, "xoffset":int, "yoffset":int, "fill":image, "fill_alpha":image "tiled":int, "mode":string ])

Methodclone: objectclone()
Description: Creates a copy of the called object.
Returns: the copy

Methodcreate

Image.LayerImage.Layer(objectimage, objectalpha, stringmode)
Image.LayerImage.Layer(mappinginfo)
Image.LayerImage.Layer()
Image.LayerImage.Layer(intxsize, intysize, objectcolor)
Image.LayerImage.Layer(objectcolor)

Description

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

The layer can also be created "empty", either giving a size and color - this will give a filled opaque square, or a color, which will set the "fill" values and fill the whole layer with an opaque color.

All values can be modified after object creation.

Note

image and alpha channel must be of the same size.

Methodcrop

objectcrop(intxoff, intyoff, intxsize, intysize)

Description

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.

Returns

a new layer object

Note

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

Methoddescriptions: array(string) descriptions()
Description: Layer descriptions

Methodset_fill Methodfill Methodfill_alpha: objectset_fill(Colorcolor)
objectset_fill(Colorcolor, Coloralpha)
objectfill()
objectfill_alpha()
Description: Set/query fill color and alpha, ie the color used "outside" the image. This is mostly useful if you want to "frame" a layer.

Methodset_misc_value Methodget_misc_value

mixedset_misc_value(objectmixedwhat, objectmixedto)
mixedget_misc_value(objectmixedwhat)

Description

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.

Methodset_offset Methodxoffset Methodyoffset: objectset_offset(intx, inty)
intxoffset()
intyoffset()
Description: Set/query layer offset.

Methodset_tiled Methodtiled: objectset_tiled(intyes)
inttiled()
Description: Set/query tiled flag. If set, the image and alpha channel will be tiled rather then framed by the fill values.

Methodxsize Methodysize: intxsize()
intysize()
Description: Query layer offset. This is the same as layer image/alpha image size.

Class Image.Font

Description

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.

Note

	       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)

See also

Image, Image.Image

Methodbaseline: intbaseline()
Description: Returns font baseline (pixels from top)
See also: height, text_extents

Methodcenter: voidcenter()
FIXME: Document this function.

Methodcreate: Image.FontImage.Font(stringfilename)
Description: Loads a font file to this font object. Similar to load().

Methodheight: intheight()
Description: Returns the font height.
See also: baseline, text_extents

Methodleft: voidleft()
FIXME: Document this function.

Methodload: Image.Font|intload(stringfilename)
Description: Loads a font file to this font object.
Returns: Returns zero upon failure and a font object upon success.
Parameter filename: The path to the font file.
See also: write

Methodright: voidright()
FIXME: Document this function.

Methodset_xspacing_scale Methodset_yspacing_scale: voidset_xspacing_scale(floatscale)
voidset_yspacing_scale(floatscale)
Description: Set spacing scale to write characters closer or more far away. This does not change scale of character, only the space between them.

Methodtext_extents

array(int) text_extents(stringtext, string ... more_text_lines)

Description

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.

Returns

Array

intwidth

intheight

See also

write, height, baseline

Methodwrite: Image.Imagewrite(stringtext, string ... more_text_lines)
Description: 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.
See also: text_extents, load, Image.Image->paste_mask, Image.Image->paste_alpha_color

Class Image.Colortable

Description

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

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

See also

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

Methodmap Method`* Method``*

objectmap(objectimage)
object res = Image.Colortable() * image
object res = image * Image.Colortable()
objectmap(stringdata, intxsize, intysize)
object res = Image.Colortable() * data
object res = data * Image.Colortable()

Description

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

Returns

a new image object

Note

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.

See also

cubicles, full

Method`+: object res = Image.Colortable() + with
Description: sums colortables
Parameter with: Colortable object with colors to add
Returns: the resulting new Colortable object

Method`-: object res = Image.Colortable() - with
Description: subtracts colortables
Parameter with: Colortable object with colors to subtract
Returns: the resulting new Colortable object

Methodcreate Methodadd

Image.ColortableImage.Colortable()
Image.ColortableImage.Colortable(array(array(int)) colors)
Image.ColortableImage.Colortable(Image.Colortablecolortable)
Image.ColortableImage.Colortable(Image.Imageimage, intnumber)
Image.ColortableImage.Colortable(Image.Imageimage, intnumber, array(array(int)) needed)
Image.ColortableImage.Colortable(intr, intg, intb)
Image.ColortableImage.Colortable(intr, intg, intb, objectarray(int)
objectadd(array(array(int)) colors)
objectadd(Image.Colortablecolortable)
objectadd(Image.Imageimage, intnumber)
objectadd(Image.Imageimage, intnumber, array(array(int)) needed)
objectadd(intr, intg, intb)
objectadd(intr, intg, intb, objectarray(int)

Description

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

Parameter colors

list of colors

Parameter colortable

colortable to copy colors from.

Parameter image

source image

Parameter number

number of colors to get from the image

0 (zero) gives all colors in the image.

Default value is 256.

Parameter needed

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

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

Parameter r

Parameter g

Parameter b

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.

Parameter fromi

Parameter toi

Parameter stepi

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.

Note

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

Methodcast

(array)Image.Colortable() (mapping)Image.Colortable()

Description

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)

Parameter to

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

Methodcorners: array(object) corners()
Description: Gives the eight corners in rgb colorspace as an array. The "black" and "white" corners are the first two.

Methodcubicles

objectcubicles()
objectcubicles(intr, intg, intb)
objectcubicles(intr, intg, intb, intaccuracy)

Description

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

Parameter r

Parameter g

Parameter b

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.

Parameter accuracy

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.

Returns

the object being called

Note

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.

Methodfloyd_steinberg

Description

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

Parameter bidir

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

Parameter forward

Parameter downforward

Parameter down

Parameter downback

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

Parameter factor

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.

Returns

the object being called

Methodfull

objectfull()

Description

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

Returns

the object being called

Note

Not applicable to colorcube types of colortable.

See also

cubicles, map

Methodgreyp: boolgreyp()
Description: Returns true if this colortable only contains greyscale.

Methodimage

objectimage()

Description

cast the colortable to an image object

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

Returns

the resulting image object

Methodnodither: objectnodither()
Description: Set no dithering (default).
Returns: the object being called

Methodordered

objectordered()
objectordered(intr, intg, intb)
objectordered(intr, intg, intb, intxsize, intysize)
objectordered(intr, intg, intb, intxsize, intysize, intx, inty)
objectordered(intr, intg, intb, intxsize, intysize, intrx, intry, intgx, intgy, intbx, intby)

Description

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

Parameter r

Parameter g

Parameter b

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

Parameter xsize

Parameter ysize

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

Parameter x

Parameter y

Parameter rx

Parameter ry

Parameter gx

Parameter gy

Parameter bx

Parameter by

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

Returns

the object being called

See also

randomcube, nodither, floyd_steinberg, create

Methodrandomcube Methodrandomgrey

objectrandomcube()
objectrandomcube(intr, intg, intb)
objectrandomgrey()
objectrandomgrey(interr)

Description

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

Parameter r

Parameter g

Parameter b

Parameter err

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

Returns

the object being called

Note

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.

See also

ordered, nodither, floyd_steinberg, create

Methodreduce Methodreduce_fs

objectreduce(intcolors)
objectreduce_fs(intcolors)

Description

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

Parameter colors

target number of colors

Returns

the new Colortable object

Note

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

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

See also

corners

Methodrigid

objectrigid()
objectrigid(intr, intg, intb)

Description

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.

Returns

the object being called

Note

Not applicable to colorcube types of colortable.

See also

cubicles, map, full

Methodspacefactors

objectspacefactors(intr, intg, intb)

Description

Colortable tuning option, this sets the color space distance factors. This is used when comparing distances in the colorspace and comparing grey levels.

Default factors are 3, 4 and 1; blue is much darker than green. Compare with Image.Image->grey().

Returns

the object being called

Note

This has no sanity check. Some functions may bug if the factors are to high - color reduction functions sums grey levels in the image, this could exceed maxint in the case of high factors. Negative values may also cause strange effects. *grin*

Module Image.Color

Description

This module keeps names and easy handling for easy color support. It gives you an easy way to get colors from names.

A color is here an object, containing color information and methods for conversion, see below.

Image.Color can be called to make a color object. Image.Color() takes the following arguments:

    Image.Color(string name)          // "red"
    Image.Color(string prefix_string) // "lightblue"
    Image.Color(string hex_name)      // "#ff00ff"
    Image.Color(string cmyk_string)   // "%17,42,0,19.4"
    Image.Color(string hsv_string)    // "@327,90,32"
    Image.Color(int red, int green, int blue)

The color names available can be listed by using indices on Image.Color. The colors are available by name directly as Image.Color.name, too:

    ...Image.Color.red...
    ...Image.Color.green...
    or, maybe
    import Image.Color;
    ...red...
    ...green...
    ...lightgreen...

Giving red, green and blue values is equal to calling Image.Color.rgb().

The prefix_string method is a form for getting modified colors, it understands all modifiers (light, dark, bright, dull and neon). Simply use "method"+"color"; (as in lightgreen, dullmagenta, lightdullorange).

The hex_name form is a simple #rrggbb form, as in HTML or X-program argument. A shorter form (#rgb) is also accepted. This is the inverse to the Image.Color.Color->hex() method.

The cmyk_string is a string form of giving cmyk (cyan, magenta, yellow, black) color. These values are floats representing percent.

The hsv_string is another hue, saturation, value representation, but in floats; hue is in degree range (0..360), and saturation and value is given in percent. This is not the same as returned or given to the hsv() methods!

This table lists all the different named colors available in Image.Color. The first column shows the actual color while the five following columns demonstrates the modifiers neon, light, dark, bright and dull. The color begind the name of the color is produced by calling neon()->dark()->dark()->dark() from the color object itself, i.e. Image.Color.mintcream->neon()->dark()->dark()->dark().

Note

Image.Color["something"] will never(!) generate an error, but a zero_type 0, if the color is unknown. This is enough to give the error "not present in module", if used as Image.Color.something, though.

If you are using colors from for instance a webpage, you might want to create the color from Image.Color.guess(), since that method is more tolerant for mistakes and errors.

Image.Color() is case- and space-sensitive. Use Image.Color.guess() to catch all variants.

and subtract with a space (lower_case(x)-" ") to make sure you get all variants.

See also

Image.Color.Color->name, Image.Color.Color->rgb, colors, Image.Color.Color, Image.Color.guess, Image, Image.Colortable

Method_indices Method_values: array(string) _indices()
array(object) _values()
Description: (ie as indices(Image.Color) or values(Image.Color)) indices gives a list of all the known color names, values gives there corresponding objects.
See also: Image.Color

Methodrgb Methodhsv Methodcmyk Methodgreylevel Methodhtml

objectrgb(intred, objectintgreen, objectintblue)
objecthsv(inthue, objectintsaturation, objectintvalue)
objectcmyk(floatc, floatm, floaty, floatk)
objectgreylevel(intlevel)
objecthtml(stringhtml_color)

Description

Creates a new color object from given red, green and blue, hue, saturation and value, or greylevel, in color value range. It could also be created from cmyk values in percent.

The html() method only understands the HTML color names, or the #rrggbb form. It is case insensitive.

Returns

the created object.

Methodguess: objectguess(stringcolor)
Description: This is equivalent to Image.Color(lower_case(str)-" "), and tries the color with a prepending '#' if no corresponding color is found.
Returns: a color object or zero_type

Class Image.Color.Color

Description: This is the color object. It has six readable variables, r, g, b, for the red, green and blue values, and h, s, v, for the hue, saturation anv value values.

Method`==

int res = Image.Color.Color() == other_color
int res = Image.Color.Color() == rgb
int res = Image.Color.Color() == greylevel
int res = Image.Color.Color() == name

Description

Compares this object to another color, or color name. Example:

object red=Image.Color.red;
object other=Image.Color. ...;
object black=Image.Color.black;
 
if (red==other) ...
if (red==({255,0,0})) ...
if (black==0) ...
if (red=="red") ...

Returns

1 or 0

Note

The other datatype (not color object) must be to the right!

See also

rgb, grey, name

Methodbits: intbits(objectintrbits, objectintgbits, objectintbbits, objectintrshift, objectintgshift, objectintbshift)
Description: Returns the color as an integer. The first three parameters state how many bits to use for red, green and blue respectively. The last three state how many bits each colour should be shifted. For instance, Image.Color("#AABBCC")->bits(8, 8, 8, 16, 8, 0) returns the integer 11189196, that is, 0xAABBCC.

Methodlight Methoddark Methodneon Methodbright Methoddull

objectlight()
objectdark()
objectneon()
objectbright()
objectdull()

Description

Color modification methods. These returns a new color.

method	effect	h	s	v
light	raise light level	±0	±0	+50
dark	lower light level	±0	±0	-50
bright	brighter color	±0	+50	+50
dull	greyer color	±0	-50	-50
neon	set to extreme	±0	max	max

light and dark lower/highers saturation when value is min-/maximised respective.

Returns

the new color object

Note

The opposites may not always take each other out. The color is maximised at white and black levels, so, for instance Image.Color.white->light()->dark() doesn't give the white color back, but the equal to Image.Color.white->dark(), since white can't get any lighter.

Methodcast: (array)Image.Color.Color() (string)Image.Color.Color()
Description: cast the object to an array, representing red, green and blue (equal to ->rgb()), or to a string, giving the name (equal to ->name()).
Returns: the name as string or rgb as array
See also: rgb, name

Methodrgb Methodrgbf Methodhsv Methodhsvf Methodcmyk Methodgreylevel

array(int) rgb()
array(float) rgbf()
array(int) hsv()
array(float) hsvf()
array(float) cmyk()
intgreylevel()
intgreylevel(intr, objectintg, objectintb)

Description

This is methods of getting information from an Image.Color.Color object.

They give an array of red, green and blue (rgb) values (color value),
hue, saturation and value (hsv) values (range as color value),
cyan, magenta, yellow, black (cmyk) values (in percent)
or the greylevel value (range as color value).

The greylevel is calculated by weighting red, green and blue. Default weights are 87, 127 and 41, respective, and could be given by argument.

Returns

array(int) respective int

See also

Image.Color.Color, grey

Methodcreate: Image.Color.ColorImage.Color.Color(intr, intg, intb)
Description: This is the main Image.Color.Color creation method, mostly for internal use.

Methodgrey: objectgrey()
objectgrey(intred, intgreen, intblue)
Description: Gives a new color, containing a grey color, which is calculated by the greylevel method.
Returns: a new Image.Color.Color object
See also: greylevel

Methodhex Methodname Methodhtml

stringhex()
stringhex(intn)
stringname()
stringhtml()

Description

Information methods.

hex() simply gives a string on the #rrggbb format. If n is given, the number of significant digits is set to this number. (Ie, n=3 gives #rrrgggbbb.)

name() is a simplified method; if the color exists in the database, the name is returned, per default is the hex() method use.

html() gives the HTML name of the color, or the hex(2) if it isn't one of the 16 HTML colors.

Returns

a new Image.Color.Color object

See also

rgb, hsv, Image.Color

Module Colors

Methodcmyk_to_rgb: array(int(8bit)) cmyk_to_rgb(array(int(0..100)) cmyk)
array(int(8bit)) cmyk_to_rgb(int(0..100)c, int(0..100)m, int(0..100)y, int(0..100)k)
Description: This function return the RGB value of the color describe by the provided CMYK value. It is essentially calling Image.Color.cmyk(c,m,y,k)->rgb()
See also: Colors.rgb_to_cmyk()Image.Color.cmyk()

Methodcolor_name: stringcolor_name(array(3:int(8bit))|zerorgb)
Description: Tries to find a name to color described by the provided RGB values. Partially an inverse function to Colors.parse_color(), although it can not find all the names that Colors.parse_color() can find RGB values for. Returns the colors rgb hex value prepended with "#" upon failure.

Methodhsv_to_rgb: array(int(8bit)) hsv_to_rgb(array(int(8bit)) hsv)
array(int(8bit)) hsv_to_rgb(int(8bit)h, int(8bit)s, int(8bit)v)
Description: This function returns the RGB value of the color described by the provided HSV value. It is essentially calling Image.Color.hsv(h,s,v)->rgb().
See also: Colors.rgb_to_hsv()Image.Color.hsv()

Methodparse_color: array(3:int(8bit)) parse_color(string|zeroname, array(3:int(8bit))|voiddef)
Description: This function returns the RGB values that corresponds to the color that is provided by name to the function. It is essentially calling Image.Color.guess(), but returns the default value (or black if none is provided) if it failes.

Methodrgb_to_cmyk: array(int(0..100)) rgb_to_cmyk(array(int(8bit)) rgb)
array(int(0..100)) rgb_to_cmyk(int(8bit)r, int(8bit)g, int(8bit)b)
Description: This function returns the CMYK value of the color described by the provided RGB value. It is essentially calling Image.Color.rgb(r,g,b)->cmyk().
See also: Colors.cmyk_to_rgb()Image.Color.Color.cmyk()

Methodrgb_to_hsv: array(int(8bit)) rgb_to_hsv(array(int(8bit)) rgb)
array(int(8bit)) rgb_to_hsv(int(8bit)r, int(8bit)g, int(8bit)b)
Description: This function returns the HSV value of the color described by the provided RGB value. It is essentially calling Image.Color.rgb(r,g,b)->hsv().
See also: Colors.hsv_to_rgb()Image.Color.Color.hsv()

Module Image.ANY

Description: These method calls other decoding methods and has some heuristics for what type of image this is.

Method_decode Methoddecode Methoddecode_alpha

mapping_decode(stringdata)
objectdecode(stringdata)
objectdecode_alpha(stringdata)

Description

Tries heuristics to find the correct method of decoding the data, then calls that method.

The result of _decode() is a mapping that contains

`"type" : string`	File type information as MIME type (ie "image/jpeg" or similar)
`"image" : Image.Image`	the image object
`alpha : int`	the alpha channel or 0 if N/A

Note

Throws upon failure.

Methoddecode_header

mappingdecode_header(stringdata)

Description

Tries heuristics to find the correct method of decoding the header, then calls that method.

The resulting mapping depends on wich decode_header method that is executed, but these keys will probably exist

`"xsize" : int`	Size of image
`"ysize" : int`	Size of image
`"type" : string`	File type information as MIME type.
`"color_space" : string`	Color space of image.

Note

Throws upon failure.

Module Image

Description

Image processing, decoding/loading and encoding/saving.

Some starting points: Image.Image - The main image object
Image.load, Image.load_layers - Loads and decodes data
Image.lay - The base image layer compositing method

Method_decode: mapping|zero_decode(stringdata, bool|voidexif)
Description: Attempts to decode data as image data. The heuristics has some limited ability to decode macbinary files as well.

Method_load: mapping_load(void|object|stringfile)
Description: Loads a file with load_file and decodes it with _decode.

Methoddecode: Image.Imagedecode(stringdata)
Description: Attempts to decode data as image data. The heuristics has some limited ability to decode macbinary files as well.

Methoddecode_layers: array(Image.Layer)|zerodecode_layers(stringdata, mapping|voidopt)
Description: Attempts to decode data as image layer data. Additional arguments to the various formats decode_layers method can be passed through opt.

Methodexif_decode: mappingexif_decode(stringdata)
Description: Like _decode() but decodes EXIF and applies the rotation.

Methodfilled_circle Methodfilled_circle_layer: Image.Imagefilled_circle(intd)
Image.Imagefilled_circle(intxd, intyd)
Image.Layerfilled_circle_layer(intd)
Image.Layerfilled_circle_layer(intxd, intyd)
Image.Layerfilled_circle_layer(intd, Image.Color.Colorcolor)
Image.Layerfilled_circle_layer(intxd, intyd, Image.Color.Colorcolor)
Image.Layerfilled_circle_layer(intd, intr, intg, intb)
Image.Layerfilled_circle_layer(intxd, intyd, intr, intg, intb)
Description: Generates a filled circle of the dimensions xd x yd (or d x d). The Image is a white circle on black background; the layer function defaults to a white circle (the background is transparent).

Methodlay: Image.Layer lay(array(Image.Layer|mapping) layers)
Image.Layer lay(array(Image.Layer|mapping) layers, intxoffset, intyoffset, intxsize, intysize)
Description: Combine layers.
Returns: a new layer object.
See also: Image.Layer

Methodload: Image.Imageload(void|object|stringfile)
Description: Helper function to load an image from a file. If no filename is given, Stdio.stdin is used. The loaded file is decoded with _decode.

Methodload_file: localstringload_file(void|object|stringfile)
Description: Loads in a file, which need not be an image file. If no argument is given the data will be taken from stdin. If a file object is given, it will be read to the end of the file. If a string is given the function will first attempt to load a file with that name, then try to download data with the string as URL. Zero will be returned upon failure.

Methodload_layer: Image.Layerload_layer(void|object|stringfile)
Description: Helper function to load an image layer from a file. If no filename is given, Stdio.stdin is used. The loaded file is decoded with _decode.

Methodload_layers: array(Image.Layer) load_layers(void|object|stringfile, mixed|voidopts)
Description: Helper function to load all image layers from a file. If no filename is given, Stdio.stdin is used. The loaded file is decoded with decode_layers. Extra arguments to the image types layer decoder, e.g. for XCF files, can be given in the opts mapping.

Methodread_file: stringread_file(stringfile)
Description: Reads the file file and, if the file is compressed with gzip or bzip, attempts to decompress it by calling gzip and bzip2 in a Process.create_process call.

Module Image.AVS

Description

An AVS file is a raw (uncompressed) 24 bit image file with alpha.

The file starts with width and height as 32-bit ingegers, followed by 4 x width x height bytes of image data. The format is big endian.

Methoddecode Method_decode Methodencode

objectdecode(stringdata)
mapping_decode(stringdata)
stringencode(objectimage, objectobject|voidalpha)

Description

Handle encoding and decoding of AVS-X images. AVS is rather trivial, and not really useful, but:

An AVS file is a raw (uncompressed) 24 bit image file with alpha. The alpha channel is 8 bit, and there is no separate alpha for r, g and b.

Module Image.BMP

Description

This submodule keeps the BMP (Windows Bitmap) encode/decode capabilities of the Image module.

BMP is common in the Windows environment.

Simple encoding:
encode

See also

Image, Image.Image, Image.Colortable

Methoddecode Method_decode Methoddecode_header

objectdecode(stringdata)
mapping_decode(stringdata)
mappingdecode_header(stringdata)
objectdecode(stringdata, mappingoptions)
mapping_decode(stringdata, mappingoptions)
mappingdecode_header(stringdata, mappingoptions)

Description

Decode a BMP.

decode gives an image object, _decode gives a mapping in the format

        "type":"image/x-MS-bmp",
        "image":image object,
        "colortable":colortable object (if applicable)
 
        "xsize":int,
        "ysize":int,
        "compression":int,
        "bpp":int,
        "windows":int,

Returns

the encoded image as a string

Bugs

Doesn't support all BMP modes. At all.

See also

encode

Methodencode

stringencode(objectimage)
stringencode(objectimage, mappingoptions)
stringencode(objectimage, objectcolortable)
stringencode(objectimage, intbpp)

Description

Make a BMP. It default to a 24 bpp BMP file, but if a colortable is given, it will be 8bpp with a palette entry.

option is a mapping that may contain:

"colortable": Image.Colortable   - palette
"bpp":        1|4|8|24           - force this many bits per pixel
"rle":        0|1                - run-length encode (default is 0)

Parameter image

Source image.

Parameter colortable

Colortable object, shortcut for "colortable" in options.

Returns

the encoded image as a string

Bugs

Doesn't support old BMP mode, only "windows" mode.

See also

decode

Module Image.DSI

Description

Decode-only support for the Dream SNES image file format.

This is a little-endian 16 bitplane image format that starts with two 32-bit integers, width and height, followed by w*h*2 bytes of image data.

Each pixel is r5g6b5, a special case is the color r=31,g=0,b=31 (full red, full blue, no green), which is transparent (chroma-keying)

Method_decode

mapping(string:Image.Image) _decode(stringdata)

Description

Decode the DSI image.

This function will treat pixels with full red, full blue, no green as transparent.

Methoddecode: Image.Imagedecode(stringdata)
Description: Decode the DSI image, without alpha decoding.

Module Image.DWG

Description: This module decodes the thumbnail raster images embedded in AutoCAD DWG files for AutoCAD version R13, R14 and R2000 (which equals to file version 12, 14 and 15). Implemented according to specifications from http://www.opendwg.org/.

Method__decode

mapping__decode(stringdata)

Description

Decodes the DWG data into a mapping.

`"version" : int`	The version of the DWG file. One of 12, 14 and 15.
`"bmp" : array(string)`	An array with the raw BMP data.
`"wmf" : array(string)`	An array with the raw WMF data.

Throws

This functions throws an error when decoding somehow fails.

Method_decode: mapping_decode(stringdata)
Description: Works like __decode, but in addition it has the element "image" in the result mapping, containing the first successfully decoded bitmap image. to the result of decode(data).
Throws: If no preview was stored, or no preview could be decoded an error is thrown.

Methoddecode: Image.Imagedecode(stringdata)
Description: Returns the first successfully decoded bitmap image.
Throws: If no preview was stored, or no preview could be decoded an error is thrown.

Module Image.Dims

Description: Reads the dimensions of images of various image formats without decoding the actual image.

Methodexif_get: array(int) exif_get(string|Stdio.BlockFilefile)
Description: Like get(), but returns the dimensions flipped if Image.JPEG.exif_decode() would flip them

Methodexif_get_JPEG: array(int) exif_get_JPEG(Stdio.BlockFilef)
Description: Like get_JPEG(), but returns the dimensions flipped if Image.JPEG.exif_decode() would flip them

Methodget

array(int|string)|zeroget(string|Stdio.BlockFilefile, bool|voidexif)

Description

Read dimensions from a JPEG, GIF, PNG, WebP, TIFF or PSD file and return an array with width and height, or if the file isn't a valid image, 0. The argument file should be file object or the data from a file. The offset pointer will be assumed to be at the start of the file data and will be modified by the function.

Returns

Array
`int0`	Image width.
`int1`	Image height.
`string2`	Image type. Any of `"gif"`, `"png"`, `"tiff"`, `"jpeg"`, `"webp"` and `"psd"`.

Methodget_GIF: array(int)|zeroget_GIF(Stdio.BlockFilef)
Description: Reads the dimensions from a GIF file and returns an array with width and height, or if the file isn't a valid image, 0.

Methodget_JPEG: array(int) get_JPEG(Stdio.BlockFilef)
Description: Reads the dimensions from a JPEG file and returns an array with width and height, or if the file isn't a valid image, 0.

Methodget_PNG: array(int)|zeroget_PNG(Stdio.BlockFilef)
Description: Reads the dimensions from a PNG file and returns an array with width and height, or if the file isn't a valid image, 0.

Methodget_PSD: array(int)|zeroget_PSD(Stdio.BlockFilef)
Description: Reads the dimensions from a PSD file and returns an array with width and height, or if the file isn't a valid image, 0.

Methodget_TIFF: array(int)|zeroget_TIFF(Stdio.BlockFilef)
Description: Reads the dimensions from a TIFF file and returns an array with width and height, or if the file isn't a valid image, 0.

Methodget_WebP: array(int)|zeroget_WebP(Stdio.BlockFilef)
Description: Reads the dimensions from a WebP file and returns an array with width and height, or if the file isn't a valid image, 0.

Module Image.Fonts

Description: Abstracted Font-handling support. Should be used instead of accessing the FreeType, TTF and Image.Font modules directly.

ConstantBLACK: constantint Image.Fonts.BLACK
Description: The font is/should be black.
Note: This also implies BOLD.

ConstantBOLD: constantint Image.Fonts.BOLD
Description: The font is/should be bold.

ConstantITALIC: constantint Image.Fonts.ITALIC
Description: The font is/should be italic.

ConstantNO_FAKE: constantint Image.Fonts.NO_FAKE
Description: Used in open_font() to specify that no fake bold or italic should be attempted.

Methodlist_fonts: mappinglist_fonts()
Description: Returns a list of all the fonts as a mapping.

Methodopen_font

Fontopen_font(stringfontname, intsize, intflags, int|voidforce)

Description

Find a suitable font in the directories specified with set_font_dirs.

flags is a bitwise or of 0 or more of ITALIC, BOLD and NO_FAKE.

fontname is the human-readable name of the font.

If force is true, a font is always returned (defaulting to arial or the pike builtin font), even if no suitable font is found.

Methodset_font_dirs: voidset_font_dirs(array(string) directories)
Description: Set the directories where fonts can be found.

Class Image.Fonts.FTFont

Description: FreeType 2.x font.

Class Image.Fonts.Font

Description: The abstract Font class. The file is a valid font-file, size is in pixels, but the size of the characters to be rendered, not the height of the finished image (the image is generally speaking bigger then the size of the characters).

Variablefile Variablesize: protectedstring Image.Fonts.Font.file
protectedint Image.Fonts.Font.size

Method__create__: protectedlocalvoid__create__(stringfile, intsize)

Methodcreate: Image.Fonts.FontImage.Fonts.Font(stringfile, intsize)

Methodinfo: mappinginfo()
Description: Returns some information about the font. Always included: file: Filename specified when the font was opened size: Size specified when the font was opened family: Family name style: Bitwise or of the style flags, i.e. ITALIC and BOLD.

Methodset_fake_bold: intset_fake_bold(intfb)
Description: The amount of 'boldness' that should be added to the font when text is rendered.

Methodset_fake_italic: intset_fake_italic(boolfi)
Description: If true, make the font italic.

Methodtext_extents: array(int) text_extents(string ... lines)
Description: Returns ({ xsize, ysize }) of the image that will result if lines is sent as the argument to write.

Methodwrite: Image.Imagewrite(string ... line)
Description: Render the text strings sent as line as an alpha-channel image.

Class Image.Fonts.TTFont

Description: FreeType 1.x font.

Module Image.FreeType

Description: Pike glue for the FreeType2 library, http://www.freetype.org/

ConstantFACE_FLAG_SCALABLE ConstantFACE_FLAG_FIXED_WIDTH ConstantFACE_FLAG_SFNT ConstantFACE_FLAG_HORIZONTAL ConstantFACE_FLAG_VERTICAL ConstantFACE_FLAG_KERNING ConstantFACE_FLAG_FAST_GLYPHS ConstantFACE_FLAG_MULTIPLE_MASTERS ConstantFACE_FLAG_GLYPH_NAMES: constant Image.FreeType.FACE_FLAG_SCALABLE
constant Image.FreeType.FACE_FLAG_FIXED_WIDTH
constant Image.FreeType.FACE_FLAG_SFNT
constant Image.FreeType.FACE_FLAG_HORIZONTAL
constant Image.FreeType.FACE_FLAG_VERTICAL
constant Image.FreeType.FACE_FLAG_KERNING
constant Image.FreeType.FACE_FLAG_FAST_GLYPHS
constant Image.FreeType.FACE_FLAG_MULTIPLE_MASTERS
constant Image.FreeType.FACE_FLAG_GLYPH_NAMES

ConstantSTYLE_FLAG_ITALIC ConstantSTYLE_FLAG_BOLD: constant Image.FreeType.STYLE_FLAG_ITALIC
constant Image.FreeType.STYLE_FLAG_BOLD

Class Image.FreeType.Face

Description: A FreeType font face. We recommend using the more generic font handling interfaces in Image.Fonts instead.

Methodattach_file: voidattach_file(stringfile)

Methodcreate: Image.FreeType.FaceImage.FreeType.Face(string(8bit)font, int(0..)|voidface_number)
Parameter font: The path of the font file to use
Parameter face_number: The face number within the font to load, if supported by the font format.

Methodget_kerning: intget_kerning(intl, intr)

Methodinfo

mappinginfo()

Returns

`"family" : string`	The font family, or the string "unknown"
`"style_name" : string`	The name of the font style, or "unknown"
`"face_flags" : int`	The number of faces contained within the font file.
`"face_count" : int`	The number of faces contained within the font file.
`"style_flags" : int`	The sum of all face/style flags respectively.

Methodlist_encodings: array(string) list_encodings()

Methodselect_encoding: voidselect_encoding(string|intencoding)

Methodset_size: Faceset_size(intwidth, intheight)

Methodwrite_char: Image.Imagewrite_char(intchar)

Module Image.GIF

Description

This submodule keep the GIF encode/decode capabilities of the Image module.

GIF is a common image storage format, usable for a limited color palette - a GIF image can only contain as most 256 colors - and animations.

Simple encoding: encode, encode_trans

Advanced stuff: render_block, header_block, end_block, netscape_loop_block

Very advanced stuff: _render_block, _gce_block

See also

Image, Image.Image, Image.Colortable

Method__decode

array__decode()

Description

Decodes a GIF image structure down to chunks and

({int xsize,int ysize,      // 0: size of image drawing area
  int numcol,               // 2: suggested number of colors
  void|string colortable,   // 3: opt. global colortable
  ({ int aspx, int aspy,    // 4,0: aspect ratio or 0, 0 if not set
     int background }),     //   1: index of background color

followed by any number these blocks in any order:

  ({ GIF.EXTENSION,         //   0: block identifier
     int extension,         //   1: extension number
     string data })         //   2: extension data
 
  ({ GIF.RENDER,            //   0: block identifier
     int x, int y,          //   1: position of render
     int xsize, int ysize,  //   3: size of render
     int interlace,         //   5: interlace flag
     void|string colortbl,  //   6: opt. local colortable
     int lzwsize,           //   7: lzw code size
     string lzwdata })      //   8: packed lzw data

and possibly ended with one of these:

  ({ GIF.ERROR_PREMATURE_EOD })   // premature end-of-data
 
  ({ GIF.ERROR_TOO_MUCH_DATA,     // data following end marker
     string data })               // (rest of file)
 
  ({ GIF.ERROR_UNKNOWN_DATA,      // unknown data
     string data })               // (rest of file)

Returns

the above array

Note

May throw errors if the GIF header is incomplete or illegal.

This is in the very advanced sector of the GIF support; please read about how GIF files works.

Method_decode

array_decode(stringgifdata)
array_decode(array__decoded)

Description

Decodes a GIF image structure down to chunks, and also decode the images in the render chunks.

({int xsize,int ysize,    // 0: size of image drawing area
  void|object colortable, // 2: opt. global colortable
  ({ int aspx, int aspy,  // 3 0: aspect ratio or 0, 0 if not set
     int background }),   //   2: index of background color

followed by any number these blocks in any order (gce chunks are decoded and incorporated in the render chunks):

  ({ GIF.RENDER,          //   0: block identifier
    int x, int y,         //   1: position of render
    object image,         //   3: render image
    void|object alpha,    //   4: 0 or render alpha channel
    object colortable,    //   5: colortable (may be same as global)
 
    int interlace,        //   6: interlace flag
    int trans_index,      //   7: 0 or transparent color index
    int delay,            //   8: 0 or delay in centiseconds
    int user_input,       //   9: user input flag
    int disposal})        //  10: disposal method number (0..7)
 
  ({ GIF.EXTENSION,       //   0: block identifier
     int extension,       //   1: extension number
     string data })       //   2: extension data

and possibly ended with one of these:

  ({ GIF.ERROR_PREMATURE_EOD })   // premature end-of-data
 
  ({ GIF.ERROR_TOO_MUCH_DATA,     // data following end marker
     string data })               // (rest of file)
 
  ({ GIF.ERROR_UNKNOWN_DATA,      // unknown data
     string data })               // (rest of file)

The decode method uses this data in a way similar to this program:

import Image;
 
object my_decode_gif(string data)
{
   array a=GIF._decode(data);
   object img=image(a[0],a[1]);
   foreach (a[4..],array b)
      if (b[0]==GIF.RENDER)
         if (b[4]) img->paste_alpha(b[3],b[4],b[1],b[2]);
         else img->paste(b[3],b[1],b[2]);
   return img;
}

Parameter gifdata

GIF data (with header and all)

Parameter __decoded

GIF data as from __decode

Returns

the above array

Note

May throw errors if the GIF header is incomplete or illegal.

This is in the very advanced sector of the GIF support; please read about how GIF files works.

Method_encode: string_encode(arraydata)
Description: Encodes GIF data; reverses _decode.
Parameter data: data as returned from _encode
Note: Some given values in the array are ignored. This function does not give the _exact_ data back!

Method_gce_block

string_gce_block(inttransparency, inttransparency_index, intdelay, intuser_input, intdisposal)

Description

This function gives back a Graphic Control Extension block. A GCE block has the scope of the following render block.

Parameter transparency

Parameter transparency_index

The following image has transparency, marked with this index.

Parameter delay

View the following rendering for this many centiseconds (0..65535).

Parameter user_input

Wait the delay or until user input. If delay is zero, wait indefinitely for user input. May sound the bell upon decoding.

Parameter disposal

Disposal method number;

Note

This is in the very advanced sector of the GIF support; please read about how GIF files works.

Most decoders just ignore some or all of these parameters.

See also

_render_block, render_block

Method_render_block: string_render_block(intx, inty, intxsize, intysize, intbpp, stringindices, zero|stringcolortable, intinterlace)
Description: Advanced (!) method for writing renderblocks for placement in a GIF file. This method only applies LZW encoding on the indices and makes the correct headers.
Parameter x
Parameter y: Position of this image.
Parameter xsize
Parameter ysize: Size of the image. Length if the indices string must be xsize*ysize.
Parameter bpp: Bits per pixels in the indices. Valid range 1..8.
Parameter indices: The image indices as an 8bit indices.
Parameter colortable: Colortable with colors to write as palette. If this argument is zero, no local colortable is written. Colortable string len must be 1<<bpp.
Parameter interlace: Interlace index data and set interlace bit. The given string should _not_ be pre-interlaced.
Note: This is in the very advanced sector of the GIF support; please read about how GIF files works.
See also: encode, _encode, header_block, end_block

Methoddecode: objectdecode(stringdata)
objectdecode(array_decoded)
objectdecode(array__decoded)
Description: Decodes GIF data and creates an image object.
Returns: the decoded image as an image object
Note: This function may throw errors upon illegal GIF data. This function uses __decode, _decode, Image.Image->paste and Image.Image->paste_alpha internally.
See also: encode

Methoddecode_layers Methoddecode_layer: array(object) decode_layers(stringdata)
array(object) decode_layers(array_decoded)
objectdecode_layer(stringdata)
objectdecode_layer(array_decoded)
Description: Decodes GIF data and creates an array of layers or the resulting layer.
Note: The resulting layer may not have the same size as the gif image, but the resulting bounding box of all render chunks in the gif file. The offset should be correct, though.
See also: encode, decode_map

Methoddecode_map

mappingdecode_map(string|arraylayers)

Description

Returns a mapping similar to other decoders _decode function.

    "image":the image
    "alpha":the alpha channel
 
    "xsize":int
    "ysize":int
        size of image
    "type":"image/gif"
        file type information as MIME type

Note

The weird name of this function (not _decode as the other decoders) is because gif was the first decoder and was written before the API was finally defined. Sorry about that. /Mirar

Methodencode Methodencode_trans

stringencode(objectimg)
stringencode(objectimg, intcolors)
stringencode(objectimg, objectcolortable)
stringencode_trans(objectimg, objectalpha)
stringencode_trans(objectimg, inttr_r, inttr_g, inttr_b)
stringencode_trans(objectimg, intcolors, objectalpha)
stringencode_trans(objectimg, intcolors, inttr_r, inttr_g, inttr_b)
stringencode_trans(objectimg, intcolors, objectalpha, inttr_r, inttr_g, inttr_b)
stringencode_trans(objectimg, objectcolortable, objectalpha)
stringencode_trans(objectimg, objectcolortable, inttr_r, inttr_g, inttr_b)
stringencode_trans(objectimg, objectcolortable, objectalpha, inta_r, inta_g, inta_b)
stringencode_trans(objectimg, objectcolortable, inttransp_index)

Description

Create a complete GIF file.

The latter (encode_trans) functions add transparency capabilities.

Example:

img=<ref>Image.Image</ref>([...]);
[...] // make your very-nice image
write(<ref>Image.GIF.encode</ref>(img)); // write it as GIF on stdout

Parameter img

The image which to encode.

Parameter colors

Parameter colortable

These arguments decides what colors the image should be encoded with. If a number is given, a colortable with be created with (at most) that amount of colors. Default is '256' (GIF maximum amount of colors).

Parameter alpha

Alpha channel image (defining what is transparent); black color indicates transparency. GIF has only transparent or nontransparent (no real alpha channel). You can always dither a transparency channel: Image.Colortable(my_alpha, ({({0,0,0}),({255,255,255})})) ->full() ->floyd_steinberg() ->map(my_alpha)

Parameter tr_r

Parameter tr_g

Parameter tr_b

Use this (or the color closest to this) color as transparent pixels.

Parameter a_r

Parameter a_g

Parameter a_b

Encode transparent pixels (given by alpha channel image) to have this color. This option is for making GIFs for the decoders that doesn't support transparency.

Parameter transp_index

Use this color no in the colortable as transparent color.

Note

For advanced users:

Image.GIF.encode_trans(img,colortable,alpha);

is equivalent of using

Image.GIF.header_block(img->xsize(),img->ysize(),colortable)+
Image.GIF.render_block(img,colortable,0,0,0,alpha)+
Image.GIF.end_block();

and is actually implemented that way.

Methodend_block

stringend_block()

Description

This function gives back a GIF end (trailer) block.

Returns

the end block as a string.

Note

This is in the advanced sector of the GIF support; please read some about how GIFs are packed.

The result of this function is always ";" or "\x3b", but I recommend using this function anyway for code clearity.

See also

header_block, end_block

Methodheader_block

stringheader_block(intxsize, intysize, intnumcolors)
stringheader_block(intxsize, intysize, objectcolortable)
stringheader_block(intxsize, intysize, objectcolortable, intbackground_color_index, intgif87a, intaspectx, intaspecty)
stringheader_block(intxsize, intysize, objectcolortable, intbackground_color_index, intgif87a, intaspectx, intaspecty, intr, intg, intb)

Description

This function gives back a GIF header block.

Giving a colortable to this function includes a global palette in the header block.

Parameter xsize

Parameter ysize

Size of drawing area. Usually same size as in the first (or only) render block(s).

Parameter background_color_index

This color in the palette is the background color. Background is visible if the following render block(s) doesn't fill the drawing area or are transparent. Most decoders doesn't use this value, though.

Parameter gif87a

If set, write 'GIF87a' instead of 'GIF89a' (default 0 == 89a).

Parameter aspectx

Parameter aspecty

Aspect ratio of pixels, ranging from 4:1 to 1:4 in increments of 1/16th. Ignored by most decoders. If any of aspectx or aspecty is zero, aspectratio information is skipped.

Parameter r

Parameter g

Parameter b

Add this color as the transparent color. This is the color used as transparency color in case of alpha-channel given as image object. This increases (!) the number of colors by one.

Returns

the created header block as a string

Note

This is in the advanced sector of the GIF support; please read some about how GIFs are packed.

This GIF encoder doesn't support different size of colors in global palette and color resolution.

See also

header_block, end_block

Methodnetscape_loop_block: stringnetscape_loop_block()
stringnetscape_loop_block(intnumber_of_loops)
Description: Creates a application-specific extention block; this block makes netscape and compatible browsers loop the animation a certain amount of times.
Parameter number_of_loops: Number of loops. Max and default is 65535.

Methodrender_block

stringrender_block(objectimg, objectcolortable, intx, inty, intlocalpalette)
stringrender_block(objectimg, objectcolortable, intx, inty, intlocalpalette, objectalpha)
stringrender_block(objectimg, objectcolortable, intx, inty, intlocalpalette, objectalpha, intr, intg, intb)
stringrender_block(objectimg, objectcolortable, intx, inty, intlocalpalette, intdelay, inttransp_index, intinterlace, intuser_input, intdisposal)
stringrender_block(objectimg, objectcolortable, intx, inty, intlocalpalette, objectalpha, intr, intg, intb, intdelay, intinterlace, intuser_input, intdisposal)

Description

This function gives a image block for placement in a GIF file, with or without transparency. The some options actually gives two blocks, the first with graphic control extensions for such things as delay or transparency.

Example:

img1=<ref>Image.Image</ref>([...]);
img2=<ref>Image.Image</ref>([...]);
[...] // make your very-nice images
nct=<ref>Image.Colortable</ref>([...]); // make a nice colortable
write(<ref>Image.GIF.header_block</ref>(xsize,ysize,nct)); // write a GIF header
write(<ref>Image.GIF.render_block</ref>(img1,nct,0,0,0,10)); // write a render block
write(<ref>Image.GIF.render_block</ref>(img2,nct,0,0,0,10)); // write a render block
[...]
write(<ref>Image.GIF.end_block</ref>()); // write end block
// voila! A GIF animation on stdout.

The above animation is thus created:

object nct=Image.Colortable(lena,32,({({0,0,0})}));
string s=GIF.header_block(lena->xsize(),lena->ysize(),nct);
foreach ( ({lena->xsize(),
            (int)(lena->xsize()*0.75),
            (int)(lena->xsize()*0.5),
            (int)(lena->xsize()*0.25),
            (int)(1),
            (int)(lena->xsize()*0.25),
            (int)(lena->xsize()*0.5),
            (int)(lena->xsize()*0.75)}),int xsize)
{
   object o=lena->scale(xsize,lena->ysize());
   object p=lena->clear(0,0,0);
   p->paste(o,(lena->xsize()-o->xsize())/2,0);
   s+=Image.GIF.render_block(p,nct,0,0,0,25);
}
s+=Image.GIF.netscape_loop_block(200);
s+=Image.GIF.end_block();
write(s);

Parameter img

The image.

Parameter colortable

Colortable with colors to use and to write as palette.

Parameter x

Parameter y

Position of this image.

Parameter localpalette

If set, writes a local palette.

Parameter alpha

Alpha channel image; black is transparent.

Parameter r

Parameter g

Parameter b

Color of transparent pixels. Not all decoders understands transparency. This is ignored if localpalette isn't set.

Parameter delay

View this image for this many centiseconds. Default is zero.

Parameter transp_index

Index of the transparent color in the colortable. -1 indicates no transparency.

Parameter user_input

If set: wait the delay or until user input. If delay is zero, wait indefinitely for user input. May sound the bell upon decoding. Default is non-set.

Parameter disposal

Disposal method number;

Note

This is in the advanced sector of the GIF support; please read some about how GIFs are packed.

The user_input and disposal method are unsupported in most decoders.

See also

encode, header_block, end_block

Module Image.HRZ

Description

HRZ is rather trivial, and not really useful, but:

The HRZ file is always 256x240 with RGB values from 0 to 63. No compression, no header, just the raw RGB data. HRZ is (was?) used for amateur radio slow-scan TV.

Methoddecode Method_decode Methodencode: objectdecode(stringdata)
mapping_decode(stringdata)
stringencode(objectimage)
Description: Handle encoding and decoding of HRZ images.

Module Image.ILBM

Description

This submodule keep the ILBM encode/decode capabilities of the Image module.

ILBM is a subtype of the Interchange File Format (IFF) used for storing picture data. ILBM stands for InterLeaved BitMap which refers to the way the pictures are stored. The image data is stored as a varying number of bitplanes, each storing one bit of data for each pixel in the image. The format supports horizontal and vertical RLE (Run Length Encoding) compression.

The format also natively supports images using the somewhat esoteric image modes of the original Commodore Amiga, such as HAM (Hold And Modify)

The format was commonly used for images on the Amiga.

See also

Image, Image.Image, Image.Colortable

Method__decode

array__decode()

Description

Decodes an ILBM image structure down to chunks and

({int xsize,int ysize,      // 0: size of image drawing area
  string bitmapheader,      // 2: BMHD chunk
  void|string colortable,   // 3: opt. colortable chunk (CMAP)
  void|string colortable,   // 4: opt. colormode chunk (CAMG)
  string body,              // 5: BODY chunk
  mapping more_chunks})     // 6: mapping with other chunks

Returns

the above array

Note

May throw errors if the ILBM header is incomplete or illegal.

Method_decode

array_decode(string|arraydata)

Description

Decode an ILBM image file.

Result is a mapping,

([
   "image": object image,
 
   ... more ...
])

image is the stored image.

Methoddecode: objectdecode(stringdata)
objectdecode(array_decoded)
objectdecode(array__decoded)
Description: Decodes ILBM data and creates an image object.
Returns: the decoded image as an image object
Note: This function may throw errors upon illegal ILBM data. This function uses __decode and _decode internally.
See also: encode

Methodencode

stringencode(objectimage)
stringencode(objectimage, objectmappingoptions)

Description

Encodes an ILBM image.

The options argument may be a mapping containing zero or more encoding options:

normal options:
    "alpha":image object
        Use this image as mask
        (Note: ILBM mask is boolean.
         The values are calculated by (r+2g+b)/4>=128.)
 
    "palette":colortable object
        Use this as palette for pseudocolor encoding

Module Image.JPEG

Note: This module uses libjpeg, a software from Independent JPEG Group.

Inherit"____Image_JPEG": inherit "____Image_JPEG" : "____Image_JPEG"

ConstantDEFAULT: constant Image.JPEG.DEFAULT

ConstantFASTEST: constant Image.JPEG.FASTEST

ConstantFLIP_H: constant Image.JPEG.FLIP_H

ConstantFLIP_V: constant Image.JPEG.FLIP_V

ConstantFLOAT: constant Image.JPEG.FLOAT

ConstantIFAST: constant Image.JPEG.IFAST

ConstantISLOW: constant Image.JPEG.ISLOW

ConstantROT_180: constant Image.JPEG.ROT_180

ConstantROT_270: constant Image.JPEG.ROT_270

ConstantROT_90: constant Image.JPEG.ROT_90

ConstantTRANSPOSE: constant Image.JPEG.TRANSPOSE

ConstantTRANSVERSE: constant Image.JPEG.TRANSVERSE

Methoddecode Method_decode Methoddecode_header

objectdecode(stringdata)
objectdecode(stringdata, mappingoptions)
mapping_decode(stringdata)
mapping_decode(stringdata, mappingoptions)
mappingdecode_header(stringdata)

Description

Decodes a JPEG image. The simple decode function simply gives the image object, the other functions gives a mapping of information (see below).

The options argument may be a mapping containing zero or more decoding options:

`"block_smoothing" : bool`	Do interblock smoothing. Default is on (1).
`"fancy_upsampling" : bool`	Do fancy upsampling of chroma components. Default is on (1).
`"method" : int`	DCT method to use. Any of `IFAST`, `ISLOW`, `FLOAT`, `DEFAULT` or `FASTEST`. `DEFAULT` and `FASTEST` is from the jpeg library, probably `ISLOW` and `IFAST` respective.
`"scale_num" : int(1..)`	Rescale the image when read from JPEG data. My (Mirar) version (6a) of jpeglib can only handle 1/1, 1/2, 1/4 and 1/8.
`"scale_denom" : int(1..)`

_decode and decode_header gives a mapping as result, with this content:

"comment" : string

Comment marker of JPEG file, if present.

"xsize" : int

Size of image

"ysize" : int

"xdpi" : float

Image dpi, if known.

"ydpi" : float

"type" : string

File type information as MIME type. Always "image/jpeg".

"num_compontents" : int

Number of channels in JPEG image.

"color_space" : string

Color space of JPEG image. Any of "GRAYSCALE", "RGB", "YUV", "CMYK", "YCCK" or "UNKNOWN".

"density_unit" : int(0..2)

The unit used for x_density and y_density.

`0`	No unit
`1`	dpi
`2`	dpcm

"x_density" : int

Density of image.

"y_density" : int

"adobe_marker" : bool

If the file has an Adobe marker.

"quant_tables" : mapping(int:array(array(int)))

JPEG quant tables.

"quality" : int(0..100)

JPEG quality guess.

"marker" : mapping(int(8bit):string(8bit)|array(string(8bit)))

Mapping from application and comment markers to their values.

Methodencode

stringencode(objectimage)
stringencode(string|objectimage, mappingoptions)

Description

Encodes an image object with JPEG compression. The image may also be a string containing a raw JPEG image. In the The options argument may be a mapping containing zero or more encoding options:

"quality" : int(0..100)

Set quality of result. Default is 75.

"optimize" : bool

Optimize Huffman table. Default is on (1) for images smaller than 50kpixels.

"progressive" : bool

Make a progressive JPEG. Default is off (0).

"grayscale" : bool

Make a grayscale JPEG instead of color (YCbCr).

"smooth" : int(1..100)

Smooth input. Value is strength.

"method" : int

DCT method to use. Any of IFAST, ISLOW, FLOAT, DEFAULT or FASTEST. DEFAULT and FASTEST is from the jpeg library, probably ISLOW and IFAST respectively.

"density_unit" : int(0..2)

The unit used for x_density and y_density.

`0`	No unit
`1`	dpi
`2`	dpcm

"x_density" : int

Density of image.

"y_density" : int

"comment" : string

Comment to be written in the JPEG file. Must not be a wide string.

"baseline" : bool

Force baseline output. Useful for quality<25. Default is off for quality<25.

"quant_tables" : mapping(int:array(array(int)))

Tune quantisation tables manually.

"marker" : mapping(int:string(8bit)|array(string(8bit)))

Application and comment markers; the integer should be one of Marker.COM, Marker.APP0, Marker.APP1, ..., Marker.APP15. The string is up to the application; most notable are Adobe and Photoshop markers.

"transform" : int

Lossless image transformation. Has only effect when supplying a JPEG file as indata.

`FLIP_H`	Flip image horizontally
`FLIP_V`	Flip image vertically
`ROT_90`	Rotate image 90 degrees clockwise
`ROT_180`	Rotate image 180 degrees clockwise
`ROT_270`	Rotate image 270 degrees clockwise
`TRANSPOSE`	Transpose image
`TRANSVERSE`	Transverse image

Note

Please read some about JPEG files. A quality setting of 100 does not mean the result is lossless.

Methodexif_decode: mappingexif_decode(stringdata, mapping|voidoptions)
Description: Decodes the image as _decode would and then proceeds to decode any EXIF information in the image. If it contain any Orientation information the image will be flipped/rotated according to it. The EXIF data will be returned as a mapping under the key "exif". If an error is encountered during the processing of EXIF information, the backtrace will be returned under the key "error".

Methodquant_tables: mapping(int:array(array(int))) quant_tables(int|voida)
FIXME: Document this function

Class Image.JPEG.Marker

ConstantAPP0: constant Image.JPEG.Marker.APP0

ConstantAPP1: constant Image.JPEG.Marker.APP1

ConstantAPP10: constant Image.JPEG.Marker.APP10

ConstantAPP11: constant Image.JPEG.Marker.APP11

ConstantAPP12: constant Image.JPEG.Marker.APP12

ConstantAPP13: constant Image.JPEG.Marker.APP13

ConstantAPP14: constant Image.JPEG.Marker.APP14

ConstantAPP15: constant Image.JPEG.Marker.APP15

ConstantAPP2: constant Image.JPEG.Marker.APP2

ConstantAPP3: constant Image.JPEG.Marker.APP3

ConstantAPP4: constant Image.JPEG.Marker.APP4

ConstantAPP5: constant Image.JPEG.Marker.APP5

ConstantAPP6: constant Image.JPEG.Marker.APP6

ConstantAPP7: constant Image.JPEG.Marker.APP7

ConstantAPP8: constant Image.JPEG.Marker.APP8

ConstantAPP9: constant Image.JPEG.Marker.APP9

ConstantCOM: constant Image.JPEG.Marker.COM

ConstantEOI: constant Image.JPEG.Marker.EOI

ConstantRST0: constant Image.JPEG.Marker.RST0

Module Image.NEO

Description: Decodes images from the Atari image editor Neochrome.

Method_decode

mapping_decode(stringdata)

Description

Low level decoding of the NEO file contents in data.

Returns

`"image" : Image.Image`	The decoded bitmap
`"images" : array(Image.Image)`	Coler cycled images.
`"filename" : string`	The filename stored into the file.
`"right_limit" : int(4bit)`	The palette color range to be color cycled.
`"left_limit" : int(4bit)`	The palette color range to be color cycled.
`"speed" : int(8bit)`	The animation speed, expressed as the number of VBLs per animation frame.
`"direction" : string`	Color cycling direction. Can be either `"left"` or `"right"`.
`"palette" : array(array(int(8bit)))`	The palette to be used for color cycling.

Methoddecode: Image.Imagedecode(stringdata)
Description: Decodes the image data into an Image.Image object.

Module Image.PCX

Description: PCX, standing for Personal Computer Exchange, is an image file format developed by the now-defunct ZSoft Corporation of Marietta, Georgia. It was the native file format for PC Paintbrush and became one of the first widely accepted DOS imaging standards, although it has since been succeeded by more sophisticated image formats, such as BMP, JPEG, and PNG. PCX files commonly stored palette-indexed images ranging from 2 or 4 colors to 16 and 256 colors, although the format has been extended to record true-color (24-bit) images as well.

Method_decode: mapping_decode(stringdata)
Description: Decodes a PCX image to a mapping.
Note: Throws upon error in data.

Methodencode Method_encode

stringencode(objectimage)
stringencode(objectimage, objectmappingoptions)
string_encode(objectimage)
string_encode(objectimage, objectmappingoptions)

Description

Encodes a PCX image. The _encode and the encode functions are identical

The options argument may be a mapping containing zero or more encoding options:

normal options:
    "raw":1
        Do not RLE encode the image
    "dpy":int
    "xdpy":int
    "ydpy":int
        Image resolution (in pixels/inch, integer numbers)
    "xoffset":int
    "yoffset":int
        Image offset (not used by most programs, but gimp uses it)

Methoddecode: objectdecode(stringdata)
Description: Decodes a PCX image.
Note: Throws upon error in data.

Module Image.PNG

Description: Support for encoding and decoding the Portable Network Graphics format, PNG.
Note: This module uses zlib.

Method__decode

array__decode(stringdata)
array__decode(stringdata, intdontcheckcrc)

Description

Splits a PNG file into chunks.

Returns

Result is an array of arrays, or 0 if data isn't a PNG file. Each element in the array is constructed as follows.

Array
`string0`	The type of the chunk, e.g. "IHDR" or "IDAT".
`string1`	The actual chunk data.
`bool2`	Set to 1 if the checksum is ok and `dontcheckcrc` isn't set.

Note

Please read about the PNG file format. Support for decoding cHRM, gAMA, sBIT, hIST, pHYs, tIME, tEXt and zTXt chunks are missing.

Method_chunk: string_chunk(stringtype, stringdata)
Description: Encodes a PNG chunk.
Note: Please read about the PNG file format.

Method_decode

mapping_decode(string|arraydata)
mapping_decode(string|arraydata, mappingoptions)

Description

Decode a PNG image file.

Parameter options

"colortable" : string|array|Image.Colortable

A replacement color table to be used instead of the one in the PNG file, if any.

Returns

"image" : Image.Image

The decoded image.

"bpp" : int

Number of bitplanes in the image. One of 1, 2, 4, 8 and 16.

"type" : int

Image color type. Bit values are:

`1`	Palette used.
`2`	Color used.
`4`	Alpha channel used.

Valid values are 0, 2, 3, 4 and 6.

"xsize" : int

Image dimensions.

"ysize" : int

"background" : array(int)

The background color, if any. An array of size three with the RGB values.

"alpha" : Image.Image

The alpha channel, if any.

Throws

Throws an error if the image data is erroneous.

Note

Please read about the PNG file format. This function ignores any checksum errors in the file. A PNG of higher color resolution than the Image module supports (8 bit) will lose that information in the conversion.

Methoddecode: Image.Imagedecode(stringdata)
Image.Imagedecode(stringdata, mapping(string:mixed) options)
Description: Decodes a PNG image. The options mapping is the as for _decode.
Throws: Throws upon error in data.

Methoddecode_alpha: Image.Imagedecode_alpha(stringdata, void|mapping(string:mixed) options)
Description: Decodes the alpha channel in a PNG file. The options mapping is the same as for _decode.
Throws: Throws upon error in data.

Methoddecode_header: mappingdecode_header(stringdata)
Description: Decodes only the PNG headers.
See also: _decode

Methodencode

stringencode(Image.Imageimage)
stringencode(Image.Imageimage, mappingoptions)

Description

Encodes a PNG image.

Parameter options

`"alpha" : Image.Image`	Use this image as alpha channel (Note: PNG alpha channel is grey. The values are calculated by (r+2g+b)/4.)
`"palette" : Image.Colortable`	Use this as palette for pseudocolor encoding (Note: encoding with alpha channel and pseudocolor at the same time are not supported)
`"zlevel" : int(0..9)`	The level of z-compression to be applied. Default is 9.
`"zstrategy" : int`	The type of LZ77 strategy to be used. Possible values are `Gz.DEFAULT_STRATEGY`, `Gz.FILTERED`, `Gz.HUFFMAN_ONLY`, `Gz.RLE`, `Gz.FIXED`. Default is `Gz.DEFAULT_STRATEGY`.

See also

__decode

Note

Please read some about PNG files.

Module Image.PNM

Description

This submodule keeps the PNM encode/decode capabilities of the Image module.

PNM is a common image storage format on unix systems, and is a very simple format.

This format doesn't use any color palette.

The format is divided into seven subformats;

P1(PBM) - ascii bitmap (only two colors)
P2(PGM) - ascii greymap (only grey levels)
P3(PPM) - ascii truecolor
P4(PBM) - binary bitmap
P5(PGM) - binary greymap
P6(PPM) - binary truecolor
P7 - binary truecolor (used by xv for thumbnails)

Simple encoding:
encode,
encode_binary,
encode_ascii

Simple decoding:
decode

Advanced encoding:
encode_P1,
encode_P2,
encode_P3,
encode_P4,
encode_P5,
encode_P6

See also

Image, Image.Image, Image.GIF

Methoddecode: objectdecode(stringdata)
Description: Decodes PNM (PBM/PGM/PPM) data and creates an image object.
Returns: the decoded image as an image object
Note: This function may throw errors upon illegal PNM data.
See also: encode

Methodencode Methodencode_binary Methodencode_ascii Methodencode_P1 Methodencode_P2 Methodencode_P3 Methodencode_P4 Methodencode_P5 Methodencode_P6

stringencode(objectimage)
stringencode_binary(objectimage)
stringencode_ascii(objectimage)
stringencode_P1(objectimage)
stringencode_P2(objectimage)
stringencode_P3(objectimage)
stringencode_P4(objectimage)
stringencode_P5(objectimage)
stringencode_P6(objectimage)

Description

Make a complete PNM file from an image.

encode_binary() and encode_ascii() uses the most optimized encoding for this image (bitmap, grey or truecolor) - P4, P5 or P6 respective P1, P2 or P3.

encode_P1/encode_P4 assumes the image is black and white. Use Image.Image->threshold() or something like Image.Colortable( ({({0,0,0}),({255,255,255})}) ) ->floyd_steinberg() ->map(my_image) to get a black and white image.

encode_P2/encode_P5 assumes the image is greyscale. Use Image.Image->grey() to get a greyscale image.

Returns

the encoded image as a string

Note

encode() is equal to encode_binary(), but may change in a future release.

See also

decode

Module Image.PS

Description: Codec for the Adobe page description language PostScript. Uses Ghostscript for decoding or built-in support.

Variable_encode: function(:void) Image.PS._encode
Description: Same as encode. Present for API reasons.

Method_decode: mapping_decode(stringdata, mapping|voidoptions)
Description: Calls decode and returns the image in the "image" index of the mapping. This method is present for API reasons.

Methoddecode

objectdecode(stringdata, mapping|voidoptions)

Description

Decodes the postscript data into an image object using Ghostscript.

Parameter options

Optional decoding parameters.

`"dpi" : int`	The resolution the image should be rendered in. Defaults to 100.
`"device" : string`	The selected Ghostscript device. Defaults to "ppmraw".
`"binary" : string`	Path to the Ghostscript binary to be used. If missing the environment paths will be searched for a file "gs" to be used instead.
`"force_gs" : bool`	Forces use of Ghostscript for EPS files instead of Pikes native support.
`"eps_crop" : bool`	Use -dEPSCrop option to Ghostscript to crop the BoundingBox for a EPS file.
`"cie_color" : bool`	Use -dUseCIEColor option to Ghostscript for mapping color values through a CIE color space.
`"file" : string`	Filename to read. If this is specified, it will be passed along to the `gs` binary, so that it can read the file directly. If this is specified `data` may be set to `0` (zero).

Note

Some versions of gs on MacOS X have problems with reading files on stdin. If this occurrs, try writing to a plain file and specifying the file option.

Note

gs versions 7.x and earlier don't support rendering of EPSes if they are specified with the file option. If this is a problem, upgrade to gs version 8.x or later.

Methoddecode_header

mapping|zerodecode_header(stringdata)

Description

Decodes the header of the postscript data into a mapping.

`"xsize" : int`	Size of image
`"ysize" : int`	Size of image
`"type" : string`	File type information as MIME type. Always "application/postscript".
`"color_space" : string`	Color space of image. "GRAYSCALE", "LAB", RGB", "CMYK" or "UNKNOWN"

Methodencode

stringencode(objectimg, mapping|voidoptions)

Description

Encodes the image object img as a postscript 3.0 file.

Parameter options

Optional extra encoding parameters.

`"dpi" : int`	The resolution of the encoded image. Defaults to 100.
`"eps" : bool`	If the resulting image should be an eps instead of ps. Defaults to 0, no.

Module Image.PSD

Description: PhotoShop Document image format.

Inherit_PSD: inherit Image._PSD : _PSD

Method__decode

mapping__decode(string|mappingdata)

Description

Decodes a PSD image to a mapping, defined as follows.

"channels" : int(1..24)

The number of channels in the image, including any alpha channels.

"height" : int(1..30000)

The image dimensions.

"width" : int(1..30000)

"compression" : bool

1 if the image is compressed, 0 if not.

"depth" : int(1)|int(8)|int(16)

The number of bits per channel.

"mode" : int(0..4)|int(7..9)

The color mode of the file.

`0`	Bitmap
`1`	Greyscale
`2`	Indexed
`3`	RGB
`4`	CMYK
`7`	Multichannel
`8`	Duotone
`9`	Lab

"color_data" : string

Raw color data.

"image_data" : string

Ram image data.

"resources" : mapping(string|int:mixed)

Additional image data. See mappping below.

"layers" : array(Layer)

An array with the layers of the image. See mapping below.

The resources mapping. Unknown resources will be identified by their ID number (as an int).

"caption" : string

Image caption.

"url" : string

Image associated URL.

"active_layer" : int

Which layer is active.

"guides" : array(mapping(string:int))

An array with all guides stored in the image file.

`"pos" : int`	The position of the guide.
`"vertical" : bool`	1 if the guide is vertical, 0 if it is horizontal.

"resinfo" : mapping(string:int)

Resolution information

`"hres" : int`	FIXME: Document these.
`"hres_unit" : int`
`"width_unit" : int`
`"vres" : int`
`"vres_unit" : int`
`"height_unit" : int`

The layer members:

"top" : int

The rectangle containing the contents of the layer.

"left" : int

"right" : int

"bottom" : int

"mask_top" : int

FIXME: Document these

"mask_left" : int

"mask_right" : int

"mask_bottom" : int

"mask_flags" : int

"opacity" : int(8bit)

0=transparent, 255=opaque.

"clipping" : int

0=base, 1=non-base.

"flags" : int

bit 0=transparency protected bit 1=visible

"mode" : string

Blend mode.

`"norm"`	Normal
`"dark"`	Darken
`"lite"`	Lighten
`"hue "`	Hue
`"sat "`	Saturation
`"colr"`	Color
`"lum "`	Luminosity
`"mul "`	Multiply
`"scrn"`	Screen
`"diss"`	Dissolve
`"over"`	Overlay
`"hLit"`	Hard light
`"sLit"`	Soft light
`"diff"`	Difference

"extra_data" : string

Raw extra data.

"name" : string

The name of the layer

"channels" : array(mapping(string:int|string))

The channels of the layer. Each array element is a mapping as follows

"id" : int

The ID of the channel

`-2`	User supplied layer mask
`-1`	Transparency mask
`0`	Red
`1`	Green
`2`	Blue

"data" : string

The image data

Method_decode

mapping_decode(string|mappingdata, mapping|voidoptions)

Description

Decodes a PSD image to a mapping, with at least an 'image' and possibly an 'alpha' object. Data is either a PSD image, or a mapping (as received from __decode)

Parameter options

`"background" : array(int)\|Image.Color`	Sets the background to the given color. Arrays should be in the format ({r,g,b}).
`"draw_all_layers" : bool`	Draw invisible layers as well.
`"draw_guides" : bool`	Draw the guides.
`"draw_selection" : bool`	Mark the selection using an overlay.
`"ignore_unknown_layer_modes" : bool`	Do not asume 'Normal' for unknown layer modes.
`"mark_layers" : bool`	Draw an outline around all (drawn) layers.
`"mark_layer_names" : Image.Font`	Write the name of all layers using the font object,
`"mark_active_layer" : bool`	Draw an outline around the active layer

Returns

`"image" : Image.Image`	The image object.
`"alpha" : Image.Image`	The alpha channel image object.

Note

Throws upon error in data. For more information, see __decode

Methoddecode: Image.Imagedecode(stringdata)
Description: Decodes a PSD image to a single image object.
Note: Throws upon error in data. To get access to more information like alpha channels and layer names, see _decode and __decode.

Methoddecode_layers

array(Image.Layer) decode_layers(stringdata, mapping|voidoptions)

Description

Decodes a PSD image to an array of Image.Layer objects

The layer object have the following extra variables (to be queried using Image.Layer()->get_misc_value):

`"image_guides"`	Returns array containing guide definitions.
`"name"`	Returns string containing the name of the layer.
`"visible"`	Is 1 of the layer is visible and 0 if it is hidden.

Accepts these options:

`"draw_all_layers" : bool`	If included, all layers will be decoded, even the non-visible ones.
`"crop_to_bounds" : bool`	Remove areas that are outside the image boundaries in all layers
`"background" : Image.Color`	If included, include a solid background layer with the given color

Methodtranslate_mode: string|zerotranslate_mode(stringmode)
Description: Convert a photoshop mode name to pike Image.lay mode names

Class Image.PSD.Layer

Variablealpha: object Image.PSD.Layer.alpha

Variableflags: int Image.PSD.Layer.flags

Variablewidth Variableheight: int Image.PSD.Layer.width
int Image.PSD.Layer.height

Variableimage: object Image.PSD.Layer.image

Variablemask_default_color: int Image.PSD.Layer.mask_default_color

Variablemask_flags: int Image.PSD.Layer.mask_flags

Variablemask_width Variablemask_height: int Image.PSD.Layer.mask_width
int Image.PSD.Layer.mask_height

Variablemask_xoffset Variablemask_yoffset: int Image.PSD.Layer.mask_xoffset
int Image.PSD.Layer.mask_yoffset

Variablemode Variablename: string Image.PSD.Layer.mode
string Image.PSD.Layer.name

Variableopacity: int Image.PSD.Layer.opacity

Variablexoffset Variableyoffset: int Image.PSD.Layer.xoffset
int Image.PSD.Layer.yoffset

Module Image.PVR

Description

Handle encoding and decoding of PVR images.

PVR is the texture format of the NEC PowerVR system It is a rather simple, uncompressed, truecolor format.

Methoddecode Methoddecode_alpha Methoddecode_header Method_decode

objectdecode(stringdata)
objectdecode_alpha(stringdata)
mappingdecode_header(stringdata)
mapping_decode(stringdata)

Description

decodes a PVR image

The decode_header and _decode has these elements:

   "image":object            - image object    \- not decode_header
   "alpha":object            - decoded alpha   /
 
   "type":"image/x-pvr"      - image type
   "xsize":int               - horisontal size in pixels
   "ysize":int               - vertical size in pixels
   "attr":int                - texture attributes
   "global_index":int        - global index (if present)

Methodencode

stringencode(objectimage)
stringencode(objectimage, mappingoptions)

Description

encode a PVR image

options is a mapping with optional values:

   "alpha":object            - alpha channel
   "global_index":int        - global index
   "vq":int(0..1)            - Vector Quantification compression

Module Image.RAS

Description

This submodule keep the RAS (Sun Raster, files commonly use the 'sun' file extension) encode/decode capabilities of the Image module.

The format was commonly used in the 1990:s for images in reasearch papers and such, since SUN workstations was the standard computer in university settings.

The format uses RLE compression, supports rgb24, 8-bit palette, grayscale and monochrome without alpha channels.

See also

Image, Image.Image, Image.Colortable

Methoddecode: objectdecode(stringdata)
Description: Decodes RAS data and creates an image object.
Returns: the decoded image as an image object
Note: This function may throw errors upon illegal RAS data.
See also: encode

Methodencode

stringencode(objectimage)
stringencode(objectimage, objectmappingoptions)

Description

Encodes a RAS image.

The options argument may be a mapping containing zero or more encoding options:

normal options:
 
    "palette":colortable object
        Use this as palette for pseudocolor encoding

Module Image.SVG

Description: This is a glue against the librsvg-2.0 library, providing Scalable Vector Graphics (SVG) for Pike.

Method_decode

mapping_decode(stringdata, void|mappingoptions)

Description

Data is the SVG data, the charset must be unicode.

If options is specified, it contains one or more of the following options

`xsize : int`	If specified, gives the exact width in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.
`ysize : int`	If specified, gives the exact height in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.
`scale : float`	If specified, gives the scale the image will be drawn with. A scale of 2.0 will give an image that is twice as large.

The result is a mapping with the following members:

`type : string`	Always image/svg
`xsize : int`	The width of the image, in pixels
`ysize : int`	The height of the image, in pixels
`image : Image.Image`	The image data
`alpha : Image.Image`	The alpha channel data

Methoddecode

Image.Imagedecode(stringdata, void|mappingoptions)

Description

Data is the SVG data, the charset must be unicode.

If options is specified, it contains one or more of the following options

`xsize : int`	If specified, gives the exact width in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.
`ysize : int`	If specified, gives the exact height in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.
`scale : float`	If specified, gives the scale the image will be drawn with. A scale of 2.0 will give an image that is twice as large.

Returns the image member of the mapping returned by _decode

Methoddecode_header

mappingdecode_header(stringdata, void|mappingoptions)

Description

Data is the SVG data, the charset must be unicode.

If options is specified, it contains one or more of the following options

`xsize : int`	If specified, gives the exact width in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.
`ysize : int`	If specified, gives the exact height in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.
`scale : float`	If specified, gives the scale the image will be drawn with. A scale of 2.0 will give an image that is twice as large.

The result is a mapping with the following members:

`type : string`	Always image/svg
`xsize : int`	The width of the image, in pixels
`ysize : int`	The height of the image, in pixels

Methoddecode_layers

array(Image.Layer) decode_layers(stringdata, void|mappingoptions)

Description

Data is the SVG data, the charset must be unicode.

If options is specified, it contains one or more of the following options

`xsize : int`	If specified, gives the exact width in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.
`ysize : int`	If specified, gives the exact height in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.
`scale : float`	If specified, gives the scale the image will be drawn with. A scale of 2.0 will give an image that is twice as large.

The result is an array of Image.Layer objects. For now there is always at most one member in the array.

Module Image.TGA

Description

TrueVision TGA image decoding and encoding support.

Truevision TGA, often referred to as TARGA, is a raster graphics file format created by Truevision Inc. It was the native format of TARGA and VISTA boards, which were the first graphic cards for IBM-compatible PCs to support Highcolor/truecolor display.

@note TGA images were commonly used for screenshots in games, although since about 2010 most games have started to migrate to PNG images.

Method_decode: object_decode(stringdata)
Description: Decodes a Targa image to a mapping. The mapping follows this format: ([ "image":img_object, "alpha":alpha_channel ])
Note: Throws upon error in data.

Methoddecode: objectdecode(stringdata)
Description: Decodes a Targa image.
Note: Throws upon error in data.

Methodencode

stringencode(objectimage)
stringencode(objectimage, objectmappingoptions)

Description

Encodes a Targa image.

The options argument may be a mapping containing zero or more encoding options:

normal options:
    "alpha":image object
        Use this image as alpha channel
        (Note: Targa alpha channel is grey.
         The values are calculated by (r+2g+b)/4.)
 
    "raw":1
        Do not RLE encode the image

Module Image.TIFF

Inherit"____Image_TIFF": inherit "____Image_TIFF" : "____Image_TIFF"

ConstantCOMPRESSION_CCITTFAX3: constant Image.TIFF.COMPRESSION_CCITTFAX3

ConstantCOMPRESSION_CCITTFAX4: constant Image.TIFF.COMPRESSION_CCITTFAX4

ConstantCOMPRESSION_CCITTRLE: constant Image.TIFF.COMPRESSION_CCITTRLE

ConstantCOMPRESSION_CCITTRLEW: constant Image.TIFF.COMPRESSION_CCITTRLEW

ConstantCOMPRESSION_JPEG: constant Image.TIFF.COMPRESSION_JPEG

ConstantCOMPRESSION_LZW: constant Image.TIFF.COMPRESSION_LZW

ConstantCOMPRESSION_NEXT: constant Image.TIFF.COMPRESSION_NEXT

ConstantCOMPRESSION_NONE: constant Image.TIFF.COMPRESSION_NONE

ConstantCOMPRESSION_PACKBITS: constant Image.TIFF.COMPRESSION_PACKBITS

ConstantCOMPRESSION_THUNDERSCAN: constant Image.TIFF.COMPRESSION_THUNDERSCAN

Variabletiff_tags

mapping(int:mapping(string:mixed)) Image.TIFF.tiff_tags

Description

Defines TIFF tags to parse.

tag : mapping(string:string|TYPE|array(TYPE))

For each supported TIFF tag the following information is kept:

`"name" : string`	Name of the tag. Currently only used to aid the programmer when reading the rules.
`"type" : TYPE\|array(TYPE)`	Defines what types a tag can have.
`"prop" : string\|array(string)`	The property name that the value of tag will be displayed as in the resulting mapping.
`"fn" : function(:void)`	Optional function to do processing on the tag value. Can return a single value or a mapping. If mapping, that mapping is added to the resulting mapping. Note that the first argument can either be an integer or a string.

Method_decode

mapping(string:mixed) _decode(stringdata)

Description

Decodes a TIFF image to a mapping with at least the members image and alpha.

"image" : Image.Image

The actual image.

"alpha" : Image.Image

Image alpha channel.

"xres" : float

Resolution

"yres" : float

"unit" : string

"unitless"

"pixels/inch"

"pixels/cm"

"xdpy" : float

Resolution

"ydpy" : float

"xposition" : int

"yposition" : int

"photometric" : string

Type of photometric. Can be "unknown".

"extra_samples" : array(int|string)

Array elements are either integers or any of

"unspecified"

"assoc-alpha"

"unassoc-alpha"

"threshholding" : string

"halftone_hints" : array(int)

Array is always two elements.

"artist" : string

"datetime" : string

"hostcomputer" : string

"software" : string

"name" : string

"comment" : string

"make" : string

"model" : string

"page_name" : string

"page_number" : array(int)

Array is always two elements.

"colormap" : array(array(int))

Array of array of RGB values.

"whitepoint" : array(int)

Array is always two elements.

"primary_chromaticities" : array(float)

Array is always six elements.

"reference_black_white" : array(array(float))

Array of array of two elements.

Throws

Throws upon error in data.

Methodencode Method_encode

stringencode(objectimage)
stringencode(objectimage, mappingoptions)
string_encode(objectimage)
string_encode(objectimage, mappingoptions)

Description

Encode an image object into a TIFF file. [encode] and _encode are identical.

The options argument may be a mapping containing zero or more encoding options. See _decode.

Example

Image.TIFF.encode(img, ([
	    "compression":Image.TIFF.COMPRESSION_LZW,
	    "name":"an image name",
	    "comment":"an image comment",
	    "alpha":An alpha channel,
	    "dpy":Dots per inch (as a float),
	    "xdpy":Horizontal dots per inch (as a float),
	    "ydpy":Vertical dots per inch (as a float),
   ]));

Methoddecode: objectdecode(stringdata)
Description: Decodes a TIFF image.
Throws: Throws upon error in data.

Methoddecode_header

mapping|zerodecode_header(stringdata)

Description

Decodes the header of the TIFF data into a mapping.

`"xsize" : int`	Size of image in pixels.
`"ysize" : int`
`"ImageWidth" : int`
`"ImageLength" : int`
`"type" : string`	File type information as MIME type. Always `"image/tiff"`.
`"color_space" : string`	Color space of TIFF image. Either `"RGB"` or `"CMYK"`.
`"byte_order" : string`	Either `"II"` for Little Endian or `"MM"` for Big Endian.
`"NewSubfileType" : int`
`"BitsPerSample" : string`
`"Compression" : int`
`"PhotometricInterpretation" : int`
`"Make" : string`
`"Model" : string`
`"SamplesPerPixel" : int`
`"ResolutionUnit" : int`
`"Software" : string`
`"DateTime" : string`
`"Predictor" : int`
`"XMP" : string`

Module Image.TIM

Description

Handle decoding of TIM images.

TIM is the framebuffer format of the PSX game system. It is a simple, uncompressed, truecolor or CLUT format with a one bit alpha channel.

Methoddecode Methoddecode_alpha Methoddecode_header Method_decode

objectdecode(stringdata)
objectdecode_alpha(stringdata)
mappingdecode_header(stringdata)
mapping_decode(stringdata)

Description

decodes a TIM image

The decode_header and _decode has these elements:

   "image":object            - image object    \- not decode_header
   "alpha":object            - decoded alpha   /
 
   "type":"image/x-tim"      - image type
   "xsize":int               - horisontal size in pixels
   "ysize":int               - vertical size in pixels
   "attr":int                - texture attributes

Module Image.TTF

Description: This module adds TTF (Truetype font) capability to the Image module.
Note: This module needs the libttf "Freetype" library

Method`()

object`()(stringfilename)
object`()(stringfilename, mappingoptions)

Description

Makes a new TTF Face object.

Parameter filename

The filename of the TTF font or the TTC font collection.

Parameter options

advanced options:
    "face":int
        If opening a font collection,  '<tt>.TTC</tt>',
        this is used to get other fonts than the first.

Returns

0 if failed.

Class Image.TTF.Face

Description: This represents instances of TTF Faces.

Methodnames Method_names

mappingnames()
array(array) _names()

Description

Gives back the names or the complete name-list of this face.

The result from names() is a mapping, which has any or all of these indices:

"copyright":   ("Copyright the Foo Corporation...bla bla")
"family":      ("My Little Font")
"style":       ("Bold")
"full":        ("Foo: My Little Font: 1998")
"expose":      ("My Little Font Bold")
"version":     ("June 1, 1998; 1.00, ...")
"postscript":  ("MyLittleFont-Bold")
"trademark":   ("MyLittleFont is a registered...bla bla")

This is extracted from the information from _names(), and fit into pike-strings using unicode or iso-8859-1, if possible.

The result from _names() is a matrix, on this form:

     ({ ({ int platform, encoding, language, id, string name }),
        ({ int platform, encoding, language, id, string name }),
        ...
     })

Returns

the name as a mapping to string or the names as a matrix

Note

To use the values from _names(), check the TrueType standard documentation.

Method`(): object res = Image.TTF.Face()()
Description: This instantiates the face for normal usage - to convert font data to images.
Returns: a Image.TTF.FaceInstance object.

Methodflush: objectflush()
Description: This flushes all cached information. Might be used to save memory - the face information is read back from disk upon need.
Returns: the object being called

Methodproperties

mappingproperties()

Description

This gives back a structure of the face's properties. Most of this stuff is information you can skip.

The most interesting item to look at may be ->num_Faces, which describes the number of faces in a .TTC font collection.

Returns

a mapping of a lot of properties

Class Image.TTF.FaceInstance

Description: This is the instance of a face, with geometrics, encodings and stuff.

Methodcreate: Image.TTF.FaceInstanceImage.TTF.FaceInstance(objectface)
Description: creates a new Instance from a face.

Module Image.WBMP

Description

Wireless Application Protocol Bitmap Format - WAP bitmap format - WBMP.

Wireless Application Protocol Bitmap Format (shortened to Wireless Bitmap and with file extension .wbmp) is a monochrome graphics file format that was optimized for the extremely low-end mobile computing devices that were common in the early days of the mobile web.

Method_decode

mapping_decode(stringimage)

Description

Decode the given image

Returns

`"img" : Image.Image`	The MIME type and encoding for the image, e.g. "image/x-wap.wbmp; type=0".
`"format" : string`
`"xsize" : int`
`"ysize" : int`
`"fix_header_field" : int`
`"ext_header_field" : int`

Methodencode Method_encode: stringencode(objectimage, void|mappingargs)
string_encode(objectimage, void|mappingargs)
Description: Encode the given image as a WBMP image. All pixels that are not black will be encoded as white.

Methoddecode: Image.Imagedecode(stringimage)
Description: Decode the given image

Methoddecode_header

mappingdecode_header(stringimage)

Returns

`"format" : string`	The MIME type and encoding for the image, e.g. "image/x-wap.wbmp; type=0".
`"xsize" : int`
`"ysize" : int`
`"fix_header_field" : int`
`"ext_header_field" : int`

Module Image.WebP

Description

WebP is a truecolor image format with alpha channel support currently developed by Google.

This module supports decoding and encoding of lossy and lossless WebP images with and without alpha channels using the libwebp library.

WebP images are generally smaller than the same quality JPEG or PNG image, but takes longer to encode and decode, and support in various applications is less common.

Method_decode

mapping_decode(stringdata)

Description

Decode a WebP image.

Returns

"alpha" : Image.Image

"image" : Image.Image

"format" : string

"width" : int(1..16384)

"height" : int(1..16384)

Methoddecode: Image.Imagedecode(stringdata)
Description: Decode a WebP image, like _decode.
Returns: The decoded image or an error

Methodencode

stringencode(Image.Imageimage, mapping(string:int|float|Image.Image)|voidoptions)

Description

Encode an image using the WebP format.

The image to encode has to be at most 16384 pixels in any direction.

Commonly used options:

`"alpha" : Image.Image`	If present, the alpha channel for the image will be the green component of this image. Has to be the same size as the `image`
`"preset" : int`	Initialization for the encoding options. One of PRESET_DEFAULT, PRESET_PICTURE, PRESET_PHOTO PRESET_DRAWING, PRESET_ICON and PRESET_TEXT
`"lossless" : bool`	If set, do lossless encoding.
`"quality" : float`	Between 0 and 99. If quality is 100+, lossless encoding with quality 70 will be used.

Additionally these advanced options are also supported:

`"image_hint" : int`	One of HINT_DEFAULT, HINT_PICTURE, HINT_PHOTO and HINT_GRAPH. Only used in lossless mode
`"target_size" : int`	If non zero, sets the desired filesize, in bytes. Takes precedence over quality.
`"target_PSNR" : int`	if non-zero, specifies the minimal distortion to try to achieve. Takes precedence over target_size.
`"segments" : int(1..4)`	maximum number of segments to use.
`"sns_strength" : int(0..100)`	Spatial Noise Shaping. 0=off, 100=maximum.
`"filter_strength" : int(0..100)`	0=off
`"filter_sharpness" : int(3bit)`	0=off
`"filter_type" : bool`	For the type, 0=simple, 1=strong.
`autofilter : bool`	If true, automatically adjust the filter strengths
`"alpha_compression" : bool`	Select alpha channel encoding format. Currently supported are 0: No alpha and 1: WebP lossless
`"alpha_filtering" : int(0..2)`	Select alpha filtering method. 0: none, 1: fast, 2: best. Default if 1.
`"alpha_quality" : int(0..100)`	Select the base image quality for the alpha channel.
`"pass" : int(1..10)`	The number of entropy analysis passes. Defaults to 1.
`"show_compressed" : bool`
`"preprocessing" : bool`	If true, do preprocessing (segment-smooth)
`"partitions" : int(2bit)`	log2(number of token partitions). Default is set to 0 for easier progressive decoding.
`"partition_limit" : int(0..100)`	quality degradation allowed to fit the 512k limit on prediction modes coding (0: no degradation, 100: maximum possible degradation).
`"emulate_jpeg_size" : bool`	If true, try to map the quality setting to generate similar sizes when compared to jpeg.
`"thread_level" : int`	The maximum number of extra threads to use. Defaults to 0
`"low_memory" : bool`	Decrease memory usage at the cost of encoding speed

Returns

Always returns the encoded image as a string or throws an error.

Module Image.X

Description: This submodule handles encoding and decoding of the binary formats of X11, and can also be used for other non-compressed image formats.
See also: Image, Image.Image, Image.Colortable

Methoddecode_pseudocolor: objectdecode_pseudocolor(stringdata, intwidth, intheight, intbpp, intalignbits, intswapbytes, objectcolortable)
Description: lazy support for pseudocolor ZPixmaps
Note: currently, only byte-aligned pixmaps are supported

Methoddecode_truecolor Methoddecode_truecolor_masks: objectdecode_truecolor(stringdata, intwidth, intheight, intbpp, intalignbits, intswapbytes, intrbits, intrshift, intgbits, intgshift, intbbits, intbshift)
objectdecode_truecolor_masks(stringdata, intwidth, intheight, intbpp, intalignbits, intswapbytes, intrmask, intgmask, intbmask)
Description: lazy support for truecolor ZPixmaps
Note: currently, only byte-aligned masks are supported

Methodencode_pseudocolor: stringencode_pseudocolor(objectimage, intbpp, intalignbits, intvbpp, objectcolortable)
stringencode_pseudocolor(objectimage, intbpp, intalignbits, intvbpp, objectcolortable, stringtranslate)
Parameter image: the image object to encode
Parameter bpp: bits per pixel, how many bits each pixel should take
Parameter vbpp: value bits per pixel; how many bits per pixel that really contains information
Parameter alignbits: the number of even bits each line should be padded to
Parameter colortable: colortable to get indices for pseudocolor
Parameter translate: translate table for colors. Length of this string should be 1<<vbpp (or 2<<vbpp if vbpp are greater than 8).
Note: currently, only upto 16 bits pseudocolor are supported.

Methodencode_truecolor Methodencode_truecolor_masks

stringencode_truecolor(objectimage, intbpp, intalignbits, intswapbytes, intrbits, intrshift, intgbits, intgshift, intbbits, intbshift)
stringencode_truecolor_masks(objectimage, intbpp, intalignbits, intswapbytes, intrmask, intgmask, intbmask)
stringencode_truecolor(objectimage, intbpp, intalignbits, intswapbytes, intrbits, intrshift, intgbits, intgshift, intbbits, intbshift, objectct)
stringencode_truecolor_masks(objectimage, intbpp, intalignbits, intswapbytes, intrmask, intgmask, intbmask, objectct)

Description

Pack an image into a truecolor string. You will get a string of packed red, green and blue bits; ie:

encode_truecolor(img, 12,32, 0, 3,5, 4,0, 3,8) will give (aligned to even 32 bits for each row):
0bbbrrr0 gggg0bbb rrr0gggg 0bbb...
<--pixel 1--><--pixel 2--> <--3-->
10987654 32101098 76543210 1098... <- bit position <-><-> <--> | | +--- 4,0: 4 bits green shifted 0 bits | +-------- 3,5: 3 bits red shifted 5 bits +----------- 3,8: 3 bits blue shifted 8 bits

The above call is equal to
encode_truecolor_masks(img, 12,32, 0, 224, 15, 768) and
encode_truecolor(img, 12,32, 0, 3,5,4,0,3,8, colortable(1<<3,1<<4,1<<3)).
The latter gives possibility to use dither algorithms, but is slightly slower.

Parameter image

the image object to encode

Parameter bpp

bits per pixel, how many bits each pixel should take

Parameter alignbits

the number of even bits each line should be padded to

Parameter rbits

Parameter gbits

Parameter bbits

bits for each basecolor

Parameter rshift

Parameter gshift

Parameter bshift

leftshifts for each basecolor

Parameter rmask

Parameter gmask

Parameter bmask

masks for each basecolor (xbits and gbits are calculated from this), needs to be massive (no zeroes among the ones in the mask).

Parameter ct

colortable object (for dithering, or whatever)

Parameter swapbytes

swap bytes for bpp==16,24,32, swaps bits in the bytes if bpp==1, for change of byte/bitorder between client and server.

Module Image.XBM

Description

Decode and encode X BitMap images.

This is a monochrome format historically used in the X Window System. It is a plain text image format, mainly used for storing cursor and icon bitmaps used in the X GUI. The XBM format was officially deprecated in 1989, replaced with the XPM format.

Method_decode

object_decode(stringdata)
object_decode(stringdata, objectmappingoptions)

Description

Decodes a XBM image to a mapping.

    Supported options:
   ([
      "fg":({fgcolor}),    // Foreground color. Default black
      "bg":({bgcolor}),    // Background color. Default white
      "invert":1,          // Invert the mask
    ])

Note

Throws upon error in data.

Methoddecode: objectdecode(stringdata)
Description: Decodes a XBM image.
Note: Throws upon error in data.

Methodencode

stringencode(objectimage)
stringencode(objectimage, objectmappingoptions)

Description

Encodes a XBM image.

The options argument may be a mapping containing zero or more encoding options.

normal options:
    "name":"xbm_image_name"
        The name of the XBM. Defaults to 'image'

Module Image.XCF

Description: eXperimental Computing Facility (aka GIMP native) format.

Inherit_XCF: inherit Image._XCF : _XCF

ConstantNORMAL_MODE ConstantDISSOLVE_MODE ConstantBEHIND_MODE ConstantMULTIPLY_MODE ConstantSCREEN_MODE ConstantOVERLAY_MODE ConstantDIFFERENCE_MODE ConstantADDITION_MODE ConstantSUBTRACT_MODE ConstantDARKEN_ONLY_MODE ConstantLIGHTEN_ONLY_MODE ConstantHUE_MODE ConstantSATURATION_MODE ConstantCOLOR_MODE ConstantVALUE_MODE ConstantDIVIDE_MODE ConstantREPLACE_MODE ConstantERASE_MODE: constant Image.XCF.NORMAL_MODE
constant Image.XCF.DISSOLVE_MODE
constant Image.XCF.BEHIND_MODE
constant Image.XCF.MULTIPLY_MODE
constant Image.XCF.SCREEN_MODE
constant Image.XCF.OVERLAY_MODE
constant Image.XCF.DIFFERENCE_MODE
constant Image.XCF.ADDITION_MODE
constant Image.XCF.SUBTRACT_MODE
constant Image.XCF.DARKEN_ONLY_MODE
constant Image.XCF.LIGHTEN_ONLY_MODE
constant Image.XCF.HUE_MODE
constant Image.XCF.SATURATION_MODE
constant Image.XCF.COLOR_MODE
constant Image.XCF.VALUE_MODE
constant Image.XCF.DIVIDE_MODE
constant Image.XCF.REPLACE_MODE
constant Image.XCF.ERASE_MODE
Description: The GIMP image layer modes

ConstantRed ConstantGreen ConstantBlue ConstantGray ConstantIndexed ConstantAuxillary: constant Image.XCF.Red
constant Image.XCF.Green
constant Image.XCF.Blue
constant Image.XCF.Gray
constant Image.XCF.Indexed
constant Image.XCF.Auxillary
Description: The GIMP channel types

Method___decode

object___decode(string|mappingdata)

Description

Decodes a XCF image to a mapping.

Structure reference
 
    ([
      "width":int,
      "height":int,
      "type":int,
      "properties":({
        ([
          "type":int,
          "data":string,
        ]),
        ...
      }),
      "layers":({
        ([
          "name":string,
          "width":int,
          "height":int,
          "type":type,
          "properties":({
            ([
              "type":int,
              "data":string,
            ]),
            ...
          }),
          "mask":0 || ([
            "name":string,
            "width":int,
            "height":int,
            "properties":({
              ([
                "type":int,
                "data":string,
              ]),
              ...
            }),
            "image_data":([
              "bpp":int,
              "width":int,
              "height":int,
              "tiles":({
                string,
                ...
              }),
            ]),
          ]),
          "image_data":([
            "bpp":int,
            "width":int,
            "height":int,
            "tiles":({
              string,
              ...
            }),
          ]),
        ]),
        ...
      }),
      "channels":({
        "name":string,
        "width":int,
        "height":int,
        "properties":({
          ([
            "type":int,
            "data":string,
          ]),
          ...
        }),
        "image_data":([
          "bpp":int,
          "width":int,
          "height":int,
          "tiles":({
            string,
            ...
          }),
        ]),
      }),
    ])

Method__decode

object__decode(string|mappingdata, objectmapping|voidoptions)

Description

Decodes a XCF image to a Image.XCF.GimpImage object.

Returned structure reference
 
   !class GimpImage
   {
     int width;
     int height;
     int compression;
     int type;
     int tattoo_state;
     float xres = 72.0;
     float yres = 72.0;
     int res_unit;
     Image.Colortable colormap;
     Image.Colortable meta_colormap;
     array(Layer) layers = ({});
     array(Channel) channels = ({});
     array(Guide) guides = ({});
     array(Parasite) parasites = ({});
     array(Path) paths = ({});
 
     Layer active_layer;
     Channel active_channel;
     Channel selection;
   }
 
   !class Layer
   {
     string name;
     int opacity;
     int type;
     int mode;
     int tattoo;
     mapping flags = ([]);
     int width, height;
     int xoffset, yoffset;
     array (Parasite) parasites;
     LayerMask mask;
     Hierarchy image;
   }
 
   !class Channel
   {
     string name;
     int width;
     int height;
     int opacity;
     int r, g, b;
     int tattoo;
     Hierarchy image_data;
     object parent;
     mapping flags = ([]);
     array (Parasite) parasites;
   }
 
   !class Hierarchy
   {
     Image.Image img;
     Image.Image alpha;
     int width;
     int height;
     int bpp;
   }
 
   !class Parasite
   {
     string name;
     int flags;
     string data;
   }
 
 
   !class Guide
   {
     int pos;
     int vertical;
   }
 
   !class Path
   {
     string name;
     int ptype;
     int tattoo;
     int closed;
     int state;
     int locked;
     array (PathPoint) points = ({});
   }
 
   !class PathPoint
   {
     int type;
     float x;
     float y;
   }

Method_decode

mapping_decode(string|objectdata, mapping|voidoptions)

Description

Decodes a XCF image to a mapping, with at least an 'image' and possibly an 'alpha' object. Data is either a XCF image, or a XCF.GimpImage object structure (as received from __decode)

 Supported options
 ([
    "background":({r,g,b})||Image.Color object
    "draw_all_layers":1,
         Draw invisible layers as well
 
    "draw_guides":1,
         Draw the guides
 
    "draw_selection":1,
          Mark the selection using an overlay
 
    "ignore_unknown_layer_modes":1
          Do not asume 'Normal' for unknown layer modes.
 
    "mark_layers":1,
         Draw an outline around all (drawn) layers
 
    "mark_layer_names":Image.Font object,
         Write the name of all layers using the font object,
 
    "mark_active_layer":1,
         Draw an outline around the active layer
  ])

Note

Throws upon error in data. For more information, see Image.XCF.__decode

Method_decode

mapping(string:Image.Image|string) _decode(stringgimp_image_data, mapping(string:mixed)|voidopts)
mapping(string:Image.Image|string) _decode(GimpImagegimp_image, mapping(string:mixed)|voidopts)
mapping(string:Image.Image|string) _decode(mapping(string:mixed) gimp_image_chunks, mapping(string:mixed)|voidopts)

Description

Decode the image data given as the first argument. If it is a string, it is a gimp image file.

If it is a mapping it is the value you get when calling ___decode()

The options can contain one or more of these options:

`"draw_all_layers" : bool`	If included, all layers will be decoded, even the non-visible ones.
`"shrink_fact" : int`	Shrink the image by a factor of X. Useful for previews.
`"draw_guides" : bool`	If true, draw the vertical and horizontal guides
`"mark_layers" : bool`	If true, draw boxes around layers
`"mark_layer_names" : bool`	If true, draw layer names in the image
`"mark_active_layer" : bool`	If true, highlight the active layer

The return value has this format:

`"type" : string`	"image/x-gimp-image"
`"img" : Image.Image`	The image
`"alpha" : Image.Image`	The alpha channel

Methoddecode: objectdecode(stringdata)
Description: Decodes a XCF image to a single image object.
Note: Throws upon error in data, you will loose quite a lot of information by doing this. See Image.XCF._decode and Image.XCF.__decode

Methoddecode: Image.Imagedecode(stringwhat, mapping|voidopts)
Description: See _decode. This function returns the image member of the return mapping of that function.

Methoddecode_header: mappingdecode_header(string|mapping|GimpImagedata)
Description: Return information about the given image (xsize, ysize and type). Somewhat inefficient, it actually decodes the image completely.

Methoddecode_layers

array(object) decode_layers(objectstringdata)
array(object) decode_layers(objectstringdata, objectmappingoptions)

Description

Decodes a XCF image to an array of Image.Layer objects

The layer object have the following extra variables (to be queried using get_misc_value):

image_xres, image_yres, image_colormap, image_guides, image_parasites, name, parasites, visible, active

Takes the same argument mapping as _decode,

Methoddecode_layers

array(Image.Layer) decode_layers(stringgimp_image_data, mapping(string:mixed)|voidopts)
array(Image.Layer) decode_layers(GimpImagegimp_image, mapping(string:mixed)|voidopts)
array(Image.Layer) decode_layers(mapping(string:mixed) gimp_image_chunks, mapping(string:mixed)|voidopts)

Description

Decode the image data given as the first argument. If it is a string, it is a gimp image file.

If it is a mapping it is the value you get when calling ___decode()

The options can contain one or more of these options:

`"draw_all_layers" : bool`	If included, all layers will be decoded, even the non-visible ones.
`"background" : Image.Color`	If included, include a solid background layer with the given color
`"shrink_fact" : int`	Shrink the image by a factor of X. Useful for previews.

The layers have a number of extra properties set on them:

`"image_xres" : int`	Values, global to all layers, copied from the GimpImage. Still present in all layers
`"image_yres" : int`
`"image_colormap" : Image.Colormap`
`"image_guides" : array(Guide)`
`"image_parasites" : array(Parasite)`
`"name" : string`
`"visible" : bool`
`"active" : bool`
`"tatoo" : int`
`"parasites" : array(Parasite)`

Methodtranslate_mode: stringtranslate_mode(intmode)
Description: Convert a GIMP layer mode to an Image.Layer layer mode

Class Image.XCF.Channel

Variabler Variableg Variableb: int Image.XCF.Channel.r
int Image.XCF.Channel.g
int Image.XCF.Channel.b

Variableflags: mapping Image.XCF.Channel.flags

Variablewidth Variableheight: int Image.XCF.Channel.width
int Image.XCF.Channel.height

Variableimage_data: Hierarchy Image.XCF.Channel.image_data

Variablename: string Image.XCF.Channel.name

Variableopacity: int Image.XCF.Channel.opacity

Variableparasites: array(Parasite) Image.XCF.Channel.parasites

Variableparent: object Image.XCF.Channel.parent

Variabletattoo: int Image.XCF.Channel.tattoo

Class Image.XCF.GimpImage

Variableactive_channel: Channel Image.XCF.GimpImage.active_channel

Variableactive_layer: Layer Image.XCF.GimpImage.active_layer

Variablechannels: array(Channel) Image.XCF.GimpImage.channels

Variablecolormap: Image.Colortable Image.XCF.GimpImage.colormap

Variablecompression: int Image.XCF.GimpImage.compression

Variableguides: array(Guide) Image.XCF.GimpImage.guides

Variablewidth Variableheight: int Image.XCF.GimpImage.width
int Image.XCF.GimpImage.height

Variablelayers: array(Layer) Image.XCF.GimpImage.layers

Variablemeta_colormap: Image.Colortable Image.XCF.GimpImage.meta_colormap

Variableparasites: array(Parasite) Image.XCF.GimpImage.parasites

Variablepaths: array(Path) Image.XCF.GimpImage.paths

Variableres_unit: int Image.XCF.GimpImage.res_unit

Variableselection: Channel Image.XCF.GimpImage.selection

Variabletattoo_state: int Image.XCF.GimpImage.tattoo_state

Variabletype: int Image.XCF.GimpImage.type

Variablexres Variableyres: float Image.XCF.GimpImage.xres
float Image.XCF.GimpImage.yres

Class Image.XCF.Guide

Description: A single guideline

Variablepos: int Image.XCF.Guide.pos

Variablevertical: int Image.XCF.Guide.vertical

Class Image.XCF.Hierarchy

Variablewidth Variableheight Variablebpp Variabletiles Variablecompression Variablect: int Image.XCF.Hierarchy.width
int Image.XCF.Hierarchy.height
int Image.XCF.Hierarchy.bpp
array Image.XCF.Hierarchy.tiles
int Image.XCF.Hierarchy.compression
Image.Colortable Image.XCF.Hierarchy.ct

Method__create__: protectedlocalvoid__create__(intwidth, intheight, intbpp, arraytiles, intcompression, Image.Colortablect)

Methodcreate: Image.XCF.HierarchyImage.XCF.Hierarchy(intwidth, intheight, intbpp, arraytiles, intcompression, Image.Colortablect)

Methodget_layer: Image.Layerget_layer(int|voidshrink)

Class Image.XCF.Layer

Variableflags: mapping(string:int) Image.XCF.Layer.flags

Variablewidth Variableheight: int Image.XCF.Layer.width
int Image.XCF.Layer.height

Variableimage: Hierarchy Image.XCF.Layer.image

Variablemask: LayerMask Image.XCF.Layer.mask

Variablemode: int Image.XCF.Layer.mode

Variablename: string Image.XCF.Layer.name

Variableopacity: int Image.XCF.Layer.opacity

Variableparasites: array(Parasite) Image.XCF.Layer.parasites

Variableparent: GimpImage Image.XCF.Layer.parent

Variabletattoo: int Image.XCF.Layer.tattoo

Variabletype: int Image.XCF.Layer.type

Variablexoffset Variableyoffset: int Image.XCF.Layer.xoffset
int Image.XCF.Layer.yoffset

Class Image.XCF.LayerMask

InheritChannel: inherit Channel : Channel

Class Image.XCF.Parasite

Variablename Variableflags Variabledata: string Image.XCF.Parasite.name
int Image.XCF.Parasite.flags
string Image.XCF.Parasite.data

Method__create__: protectedlocalvoid__create__(stringname, intflags, stringdata)

Methodcreate: Image.XCF.ParasiteImage.XCF.Parasite(stringname, intflags, stringdata)

Class Image.XCF.Path

Description: A path

Variableclosed: int Image.XCF.Path.closed

Variablelocked: int Image.XCF.Path.locked

Variablename: string Image.XCF.Path.name

Variablepoints: array(PathPoint) Image.XCF.Path.points

Variableptype: int Image.XCF.Path.ptype

Variablestate: int Image.XCF.Path.state

Variabletattoo: int Image.XCF.Path.tattoo

Class Image.XCF.PathPoint

Description: A point on a path

Variabletype: int Image.XCF.PathPoint.type

Variablex Variabley: float Image.XCF.PathPoint.x
float Image.XCF.PathPoint.y

Module Image.XFace

Description
Note: This module uses libgmp.

Methoddecode

objectdecode(stringdata)
objectdecode(stringdata, objectmappingoptions)

Description

Decodes an X-Face image.

The options argument may be a mapping containing zero options.

Methoddecode_header

objectdecode_header(stringdata)
objectdecode_header(stringdata, objectmappingoptions)

Description

Decodes an X-Face image header.

    "xsize":int
    "ysize":int
        size of image
    "type":"image/x-xface"
        file type information

The options argument may be a mapping containing zero options.

Note

There aint no such thing as a X-Face image header. This stuff tells the characteristics of an X-Face image.

Methodencode

stringencode(objectimg)
stringencode(objectimg, objectmappingoptions)

Description

Encodes an X-Face image.

The img argument must be an image of the dimensions 48 by 48 pixels. All non-black pixels will be considered white.

The options argument may be a mapping containing zero options.

Module Image.XPM

Description

X PixMap image format. Specifically, XPM3.

XPM1 and XPM2 are not supported. (XPM3 has been the standard since 1991).

Inherit_XPM: inherit Image._XPM : _XPM

Method_decode

mapping_decode(stringbytes, mapping|voidoptions)

Description

Decode the given XPM image.

"img" : Image.Image

"alpha" : Image.Image

"format" : string

No options are currently supported.

Method_xpm_trim_rows: array(string) _xpm_trim_rows(array(string) rows)

Method_xpm_write_rows

int(0)_xpm_write_rows(Image.Imageimg, Image.Imagealpha, intbpc, array(string) colors, array(string) pixels)

Description

Fills in img and alpha according to xpm data in bpc, colors and pixels.

Parameter bpc

Bytes per color. Number of bytes used to encode each color in pixels.

Parameter colors

Array of color definitions.

A color definition is on the format "ee c #RRGGBB", where ee is a bpc long string used to encode the color, c is a literal "c", and RRGGBB is a hexadecimal RGB code.

Parameter pixels

Raw picture information.

Array
`string0`	Size information on the format (`sprintf("%d %d %d %d", h, w, ncolors, bpn)`).
`string1..ncolors`	Same as `colors`.
`stringncolors_plus_one..ncolors_plus_h`	Line information. Strings of length `bpn`*w with encoded pixels for each line.

Methoddecode: Image.Imagedecode(stringbytes)

Methodencode

stringencode(Image.Imageimage, mapping|voidoptions)

Description

Encode the given image as a XPM image.

This will, at least currently, always produce a 2-characters-per-pixel XPM.

The supported options are:

"name" : string(1..128)

"colortable" : Image.Colortable

"alpha" : Image.Image

"comment" : string(1..128)

Module Image.XWD

Description

This submodule keeps the XWD (X Windows Dump) decode capabilities of the Image module.

XWD is the output format for the xwd program.

Simple decoding:
decode

Advanced decoding:
_decode

See also

Image, Image.Image, Image.PNM, Image.X

Method_decode Methoddecode_header

mapping_decode(stringdata)
mappingdecode_header(stringdata)

Description

Decodes XWD data and returns the result.

Supported XWD visual classes and encoding formats are TrueColor / ZPixmap DirectColor / ZPixmap PseudoColor / ZPixmap

If someone sends me files of other formats, these formats may be implemented. :) /[email protected]

Returns

the decoded image as an image object

Note

This function may throw errors upon illegal or unknown XWD data.

See also

decode

Methoddecode: objectdecode(stringdata)
Description: Simple decodes a XWD image file.

floyd_steinberg dither

ordered dither

randomcube dither