12. Image Module

Class Image.Image

Description

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

basic:
clear, clone, create, xsize, ysize

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

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

pasting images:
paste, paste_alpha, paste_alpha_color, paste_mask

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

calculation by pixels:
apply_matrix, change_color, color, distancesq, grey, invert, modify_by_intensity, outline select_from, rgb_to_hsv, hsv_to_rgb, 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

`-, `+, `|, `&amp;, `*, 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

`-, `+, `|, `&amp;, 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

`-, `|, `&amp;, `*, 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

`+, `|, `&amp;, `*, 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

`-, `+, `|, `*, `&amp;


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

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


Method apply_curve

object apply_curve(object array(int(0..255)
object apply_curve(object array(int(0..255)
object apply_curve(object stringchannel, object array(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


Method apply_matrix

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

Description

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

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

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

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

This function is not very fast.

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


Method apply_max

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

Description

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

This function is not very fast.

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


Method autocrop
Method find_autocrop

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

Description

Removes "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


Method average
Method min
Method max
Method sum
Method sumf

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

Description

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

Note

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

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


Method bitscale

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

Description

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

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


Method bitscale

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

Description

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

Parameter newxsize
Parameter newysize

new image size in pixels

Returns

the new image object

Note

resulting image will be 1x1 pixels, at least


Method blur

string blur(int no_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


Method box

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

Description

Draws a filled rectangle on the image.

original ->box
(40,10,
10,80,
0,255,0)
->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


Method cast

(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


Method change_color

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

Description

Changes one color (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


Method circle

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

Description

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

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

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


Method clear

object clear()
object clear(int r, int g, int b)
object clear(int r, int g, int b, int alpha)

Description

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

original ->clear
(0,128,255)

Parameter r
Parameter g
Parameter b

color of the new image

Parameter alpha

new default alpha channel value

See also

copy, clone


Method clone

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

Description

Copies to or initialize a new image object.

original clone clone(50,50)

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


Method color

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

Description

Colorize an image.

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

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

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

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

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


Method copy

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

Description

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

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

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


Method create

Image.Image Image.Image()
Image.Image Image.Image(Image.Image image)
Image.Image Image.Image(int xsize, int ysize)
Image.Image Image.Image(int xsize, int ysize, Color color)
Image.Image Image.Image(int xsize, int ysize, int r, int g, int b)
Image.Image Image.Image(int xsize, int ysize, int r, int g, int b, int alpha)
Image.Image Image.Image(int xsize, int ysize, string method, method ...)

Description

Initializes a new image object.

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

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

channel modes; followed by a number of 1-char-per-pixel strings
or image objects (where red channel will be used),
or an integer value:
  "grey" : make a grey image (needs 1 source: grey)
  "rgb"  : make an rgb image (needs 3 sources: red, green and blue)
  "cmyk" : make a rgb image from cmyk (cyan, magenta, yellow, black)
  "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


Method dct

object dct(int newx, int newy)

Description

Scales the image to a new size.

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

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

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

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

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.


Method distancesq

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

Description

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

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

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

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

Parameter r
Parameter g
Parameter b

red, green, blue coordinates

Returns

the new image object

See also

select_from


Method find_min
Method find_max

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

Description

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

Parameter r
Parameter g
Parameter b

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


Method gamma

object gamma(float g)
object gamma(float gred, object floatggreen, object floatgblue)

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


Method getpixel

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

Parameter x
Parameter y

position of the pixel

Returns

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


Method gradients

int gradients(array(int) point, object ...)
int gradients(array(int) point, object ..., object floatgrad)

Description

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

Returns

the new image


Method grey

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

Description

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

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

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


Method grey_blur

object grey_blur(int no_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


Method rgb_to_hsv
Method hsv_to_rgb

object rgb_to_hsv()
object hsv_to_rgb()

Description

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

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

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

HSV to RGB calculation:

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

RGB to HSV calculation: Hmm.

Example: Nice rainbow.

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

Returns

the new image object


Method invert

object invert()

Description

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

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

Returns

the new image object


Method line

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

Description

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

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

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


Method make_ascii

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

Description

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

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

Returns

some nice 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


Method match

object match(int|float scale, object objectneedle)
object match(int|float scale, object objectneedle, object objecthaystack_cert, object objectneedle_cert)
object match(int|float scale, object objectneedle, object objecthaystack_avoid, object intfoo)
object match(int|float scale, object objectneedle, object objecthaystack_cert, object objectneedle_cert, object objecthaystack_avoid, object intfoo)

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


Method mirrorx

object mirrorx()

Description

mirrors an image:

original ->mirrorx();

Returns

the new image object


Method mirrory

object mirrory()

Description

mirrors an image:

original ->mirrory();


Method modify_by_intensity

object modify_by_intensity(int r, int g, int b, 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


Method noise

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

Description

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

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

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

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


Method orient
Method orient4

object orient(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


Method outline
Method outline_mask

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

Description

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

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

You can also run your own outline mask.

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

original masked
through
threshold
...and
outlined
with red

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!


Method paste

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

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


Method paste_alpha

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

Description

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

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

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


Method paste_alpha_color

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

Description

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

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

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

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


Method paste_mask

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

Description

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

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

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

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


Method phaseh
Method phasev
Method phasevh
Method phasehv

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

Description

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

phaseh gives an image where

       max  falling   min  rising
value=  0     64      128   192

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

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

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

Returns

the new image object

Note

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

Bugs

0 should not be set as explained above.


Method polyfill

object polyfill(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


Method random
Method randomgrey

object random()
object random(int seed)
object random(function(int:string) random)
object randomgrey()
object randomgrey(int seed)
object randomgrey(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


Method write_lsb_rgb
Method write_lsb_grey
Method read_lsb_rgb
Method read_lsb_grey

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

Description

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

The string is nullpadded or cut to fit.

Parameter what

the hidden message

Returns

the current object or the read string


Method rgb_to_yuv
Method yuv_to_rgb

object rgb_to_yuv()
object yuv_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


Method rotate
Method rotate_expand

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

Description

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

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

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

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

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


Method rotate_ccw

object rotate_ccw()

Description

rotates an image counter-clockwise, 90 degrees.

original ->rotate_ccw();

Returns

the new image object


Method rotate_cw

object rotate_cw()

Description

rotates an image clockwise, 90 degrees.

original ->rotate_cw();

Returns

the new image object


Method scale

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

Description

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

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


Method scale

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

Description

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

Parameter newxsize
Parameter newysize

new image size in pixels

Returns

the new image object

Note

resulting image will be 1x1 pixels, at least


Method select_from

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

Description

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

This is very close to a floodfill.

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

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

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


Method setcolor

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

Description

set the current color

Parameter r
Parameter g
Parameter b

new color

Parameter alpha

new alpha value

Returns

the object called


Method setpixel

object setpixel(int x, int y)
object setpixel(int x, int y, Image.Color c)
object setpixel(int x, int y, int r, int g, int b)
object setpixel(int x, int y, int r, int g, int b, int alpha)

Description

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

Parameter x
Parameter y

position of the pixel

Parameter r
Parameter g
Parameter b

color

Parameter alpha

alpha value

Returns

the object called


Method skewx
Method skewx_expand

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

Description

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

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

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


Method skewy
Method skewy_expand

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

Description

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

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

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

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


Method test

object test()
object test(int seed)
object test(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


Method threshold

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

Description

Makes a black-white image.

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

This method works fine with the grey method.

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

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

Returns

the new image object

Note

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

See also

grey


Method tuned_box

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

Description

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

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

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

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


Method turbulence

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

Description

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

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

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

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


Method xsize

int xsize()

Returns

the width of the image


Method ysize

int ysize()

Returns

the height of the image

Class Image.Layer

See also

layers


Method set_image
Method image
Method alpha

object set_image(Image.Image image)
object set_image(Image.Image image, Image.Image alpha_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.


Method set_alpha_value
Method alpha_value

object set_alpha_value(float value)
float alpha_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.


Method autocrop
Method find_autocrop

object autocrop()
object autocrop(bool left, bool right, bool top, bool bottom)
array(int) find_autocrop()
array(int) find_autocrop(bool left, bool right, bool top, bool bottom)

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


Method set_mode
Method mode
Method available_modes

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


Method cast

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


Method clone

object clone()

Description

Creates a copy of the called object.

Returns

the copy


Method create

Image.Layer Image.Layer(object image, object alpha, string mode)
Image.Layer Image.Layer(mapping info)
Image.Layer Image.Layer()
Image.Layer Image.Layer(int xsize, int ysize, object color)
Image.Layer Image.Layer(object color)

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.


Method crop

object crop(int xoff, int yoff, int xsize, int ysize)

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.


Method descriptions

array(string) descriptions()

Description

Layer descriptions


Method set_fill
Method fill
Method fill_alpha

object set_fill(Color color)
object set_fill(Color color, Color alpha)
object fill()
object fill_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.


Method set_misc_value
Method get_misc_value

mixed set_misc_value(object mixedwhat, object mixedto)
mixed get_misc_value(object mixedwhat)

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.


Method set_offset
Method xoffset
Method yoffset

object set_offset(int x, int y)
int xoffset()
int yoffset()

Description

Set/query layer offset.


Method set_tiled
Method tiled

object set_tiled(int yes)
int tiled()

Description

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


Method xsize
Method ysize

int xsize()
int ysize()

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


Method baseline

int baseline()

Description

Returns font baseline (pixels from top)

See also

height, text_extents


Method center

void center()

FIXME

Document this function.


Method create

Image.Font Image.Font(string filename)

Description

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


Method height

int height()

Description

Returns the font height.

See also

baseline, text_extents


Method left

void left()

FIXME

Document this function.


Method load

Image.Font|int load(string filename)

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


Method right

void right()

FIXME

Document this function.


Method set_xspacing_scale
Method set_yspacing_scale

void set_xspacing_scale(float scale)
void set_yspacing_scale(float scale)

Description

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


Method text_extents

array(int) text_extents(string text, 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
int width
int height
See also

write, height, baseline


Method write

Image.Image write(string text, 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


Method map
Method `*
Method ``*

object map(object image)
object res = Image.Colortable() * image
object res = image * Image.Colortable()
object map(string data, int xsize, int ysize)
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.

no dither
floyd_steinberg dither
ordered dither
randomcube dither
original 2 4 8 16 32 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


Method create
Method add

Image.Colortable Image.Colortable()
Image.Colortable Image.Colortable(array(array(int)) colors)
Image.Colortable Image.Colortable(Image.Colortable colortable)
Image.Colortable Image.Colortable(Image.Image image, int number)
Image.Colortable Image.Colortable(Image.Image image, int number, array(array(int)) needed)
Image.Colortable Image.Colortable(int r, int g, int b)
Image.Colortable Image.Colortable(int r, int g, int b, object array(int)
object add(array(array(int)) colors)
object add(Image.Colortable colortable)
object add(Image.Image image, int number)
object add(Image.Image image, int number, array(array(int)) needed)
object add(int r, int g, int b)
object add(int r, int g, int b, object array(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.


Method cast

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


Method corners

array(object) corners()

Description

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


Method cubicles

object cubicles()
object cubicles(int r, int g, int b)
object cubicles(int r, int g, int b, int accuracy)

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.


Method floyd_steinberg

object floyd_steinberg()
object floyd_steinberg(int bidir, int|float forward, int|float downforward, int|float down, int|float downback, int|float factor)

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


Method full

object full()

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


Method greyp

bool greyp()

Description

Returns true if this colortable only contains greyscale.


Method image

object image()

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


Method nodither

object nodither()

Description

Set no dithering (default).

Returns

the object being called


Method ordered

object ordered()
object ordered(int r, int g, int b)
object ordered(int r, int g, int b, int xsize, int ysize)
object ordered(int r, int g, int b, int xsize, int ysize, int x, int y)
object ordered(int r, int g, int b, int xsize, int ysize, int rx, int ry, int gx, int gy, int bx, int by)

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


Method randomcube
Method randomgrey

object randomcube()
object randomcube(int r, int g, int b)
object randomgrey()
object randomgrey(int err)

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


Method reduce
Method reduce_fs

object reduce(int colors)
object reduce_fs(int colors)

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


Method rigid

object rigid()
object rigid(int r, int g, int b)

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


Method spacefactors

object spacefactors(int r, int g, int b)

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


Method rgb
Method hsv
Method cmyk
Method greylevel
Method html

object rgb(int red, object intgreen, object intblue)
object hsv(int hue, object intsaturation, object intvalue)
object cmyk(float c, float m, float y, float k)
object greylevel(int level)
object html(string html_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.


Method guess

object guess(string color)

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


Method bits

int bits(object intrbits, object intgbits, object intbbits, object intrshift, object intgshift, object intbshift)

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.


Method light
Method dark
Method neon
Method bright
Method dull

object light()
object dark()
object neon()
object bright()
object dull()

Description

Color modification methods. These returns a new color.

methodeffect hsvas
light raise light level±0 ±0+50
dark lower light level±0 ±0-50
brightbrighter color ±0+50+50
dull greyer color ±0-50-50
neon set to extreme ±0maxmax

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.


Method cast

(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


Method rgb
Method rgbf
Method hsv
Method hsvf
Method cmyk
Method greylevel

array(int) rgb()
array(float) rgbf()
array(int) hsv()
array(float) hsvf()
array(float) cmyk()
int greylevel()
int greylevel(int r, object intg, object intb)

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


Method create

Image.Color.Color Image.Color.Color(int r, int g, int b)

Description

This is the main Image.Color.Color creation method, mostly for internal use.


Method grey

object grey()
object grey(int red, int green, int blue)

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


Method hex
Method name
Method html

string hex()
string hex(int n)
string name()
string html()

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


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


Method color_name

string color_name(array(3:int(8bit))|zero rgb)

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.


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


Method parse_color

array(3:int(8bit)) parse_color(string|zero name, array(3:int(8bit))|void def)

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.


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


Method rgb_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
Method decode
Method decode_alpha

mapping _decode(string data)
object decode(string data)
object decode_alpha(string data)

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.


Method decode_header

mapping decode_header(string data)

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
"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(string data, bool|void exif)

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|string file)

Description

Loads a file with load_file and decodes it with _decode.


Method decode

Image.Image decode(string data)

Description

Attempts to decode data as image data. The heuristics has some limited ability to decode macbinary files as well.


Method decode_layers

array(Image.Layer)|zero decode_layers(string data, mapping|void opt)

Description

Attempts to decode data as image layer data. Additional arguments to the various formats decode_layers method can be passed through opt.


Method exif_decode

mapping exif_decode(string data)

Description

Like _decode() but decodes EXIF and applies the rotation.


Method filled_circle
Method filled_circle_layer

Image.Image filled_circle(int d)
Image.Image filled_circle(int xd, int yd)
Image.Layer filled_circle_layer(int d)
Image.Layer filled_circle_layer(int xd, int yd)
Image.Layer filled_circle_layer(int d, Image.Color.Color color)
Image.Layer filled_circle_layer(int xd, int yd, Image.Color.Color color)
Image.Layer filled_circle_layer(int d, int r, int g, int b)
Image.Layer filled_circle_layer(int xd, int yd, int r, int g, int b)

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


Method lay

Image.Layer lay(array(Image.Layer|mapping) layers)
Image.Layer lay(array(Image.Layer|mapping) layers, int xoffset, int yoffset, int xsize, int ysize)

Description

Combine layers.

Returns

a new layer object.

See also

Image.Layer


Method load

Image.Image load(void|object|string file)

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.


Method load_file

local string load_file(void|object|string file)

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.


Method load_layer

Image.Layer load_layer(void|object|string file)

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.


Method load_layers

array(Image.Layer) load_layers(void|object|string file, mixed|void opts)

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.


Method read_file

string read_file(string file)

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.


Method decode
Method _decode
Method encode

object decode(string data)
mapping _decode(string data)
string encode(object image, object object|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


Method decode
Method _decode
Method decode_header

object decode(string data)
mapping _decode(string data)
mapping decode_header(string data)
object decode(string data, mapping options)
mapping _decode(string data, mapping options)
mapping decode_header(string data, mapping options)

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


Method encode

string encode(object image)
string encode(object image, mapping options)
string encode(object image, object colortable)
string encode(object image, int bpp)

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

Description

Decode the DSI image.

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


Method decode

Image.Image decode(string data)

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

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

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.


Method decode

Image.Image decode(string data)

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.


Method exif_get

array(int) exif_get(string|Stdio.BlockFile file)

Description

Like get(), but returns the dimensions flipped if Image.JPEG.exif_decode() would flip them


Method exif_get_JPEG

array(int) exif_get_JPEG(Stdio.BlockFile f)

Description

Like get_JPEG(), but returns the dimensions flipped if Image.JPEG.exif_decode() would flip them


Method get

array(int|string)|zero get(string|Stdio.BlockFile file, bool|void exif)

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
int 0

Image width.

int 1

Image height.

string 2

Image type. Any of "gif", "png", "tiff", "jpeg", "webp" and "psd".


Method get_GIF

array(int)|zero get_GIF(Stdio.BlockFile f)

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.


Method get_JPEG

array(int) get_JPEG(Stdio.BlockFile f)

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.


Method get_PNG

array(int)|zero get_PNG(Stdio.BlockFile f)

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.


Method get_PSD

array(int)|zero get_PSD(Stdio.BlockFile f)

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.


Method get_TIFF

array(int)|zero get_TIFF(Stdio.BlockFile f)

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.


Method get_WebP

array(int)|zero get_WebP(Stdio.BlockFile f)

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.


Constant BLACK

constant int Image.Fonts.BLACK

Description

The font is/should be black.

Note

This also implies BOLD.


Constant BOLD

constant int Image.Fonts.BOLD

Description

The font is/should be bold.


Constant ITALIC

constant int Image.Fonts.ITALIC

Description

The font is/should be italic.


Constant NO_FAKE

constant int Image.Fonts.NO_FAKE

Description

Used in open_font() to specify that no fake bold or italic should be attempted.


Method list_fonts

mapping list_fonts()

Description

Returns a list of all the fonts as a mapping.


Method open_font

Font open_font(string fontname, int size, int flags, int|void force)

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.


Method set_font_dirs

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


Variable file
Variable size

protected string Image.Fonts.Font.file
protected int Image.Fonts.Font.size


Method __create__

protected local void __create__(string file, int size)


Method create

Image.Fonts.Font Image.Fonts.Font(string file, int size)


Method info

mapping info()

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.


Method set_fake_bold

int set_fake_bold(int fb)

Description

The amount of 'boldness' that should be added to the font when text is rendered.


Method set_fake_italic

int set_fake_italic(bool fi)

Description

If true, make the font italic.


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


Method write

Image.Image write(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/


Constant FACE_FLAG_SCALABLE
Constant FACE_FLAG_FIXED_WIDTH
Constant FACE_FLAG_SFNT
Constant FACE_FLAG_HORIZONTAL
Constant FACE_FLAG_VERTICAL
Constant FACE_FLAG_KERNING
Constant FACE_FLAG_FAST_GLYPHS
Constant FACE_FLAG_MULTIPLE_MASTERS
Constant FACE_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


Constant STYLE_FLAG_ITALIC
Constant STYLE_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.


Method attach_file

void attach_file(string file)


Method create

Image.FreeType.Face Image.FreeType.Face(string(8bit) font, int(0..)|void face_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.


Method get_kerning

int get_kerning(int l, int r)


Method info

mapping info()

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
"style_flags" : int

The sum of all face/style flags respectively.


Method list_encodings

array(string) list_encodings()


Method select_encoding

void select_encoding(string|int encoding)


Method set_size

Face set_size(int width, int height)


Method write_char

Image.Image write_char(int char)

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(string gifdata)
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(array data)

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(int transparency, int transparency_index, int delay, int user_input, int disposal)

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(int x, int y, int xsize, int ysize, int bpp, string indices, zero|string colortable, int interlace)

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


Method decode

object decode(string data)
object decode(array _decoded)
object decode(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


Method decode_layers
Method decode_layer

array(object) decode_layers(string data)
array(object) decode_layers(array _decoded)
object decode_layer(string data)
object decode_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


Method decode_map

mapping decode_map(string|array layers)

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


Method encode
Method encode_trans

string encode(object img)
string encode(object img, int colors)
string encode(object img, object colortable)
string encode_trans(object img, object alpha)
string encode_trans(object img, int tr_r, int tr_g, int tr_b)
string encode_trans(object img, int colors, object alpha)
string encode_trans(object img, int colors, int tr_r, int tr_g, int tr_b)
string encode_trans(object img, int colors, object alpha, int tr_r, int tr_g, int tr_b)
string encode_trans(object img, object colortable, object alpha)
string encode_trans(object img, object colortable, int tr_r, int tr_g, int tr_b)
string encode_trans(object img, object colortable, object alpha, int a_r, int a_g, int a_b)
string encode_trans(object img, object colortable, int transp_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.


Method end_block

string end_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


Method header_block

string header_block(int xsize, int ysize, int numcolors)
string header_block(int xsize, int ysize, object colortable)
string header_block(int xsize, int ysize, object colortable, int background_color_index, int gif87a, int aspectx, int aspecty)
string header_block(int xsize, int ysize, object colortable, int background_color_index, int gif87a, int aspectx, int aspecty, int r, int g, int b)

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


Method netscape_loop_block

string netscape_loop_block()
string netscape_loop_block(int number_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.


Method render_block

string render_block(object img, object colortable, int x, int y, int localpalette)
string render_block(object img, object colortable, int x, int y, int localpalette, object alpha)
string render_block(object img, object colortable, int x, int y, int localpalette, object alpha, int r, int g, int b)
string render_block(object img, object colortable, int x, int y, int localpalette, int delay, int transp_index, int interlace, int user_input, int disposal)
string render_block(object img, object colortable, int x, int y, int localpalette, object alpha, int r, int g, int b, int delay, int interlace, int user_input, int disposal)

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.


Method decode
Method _decode
Method encode

object decode(string data)
mapping _decode(string data)
string encode(object image)

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|array data)

Description

Decode an ILBM image file.

Result is a mapping,

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

image is the stored image.


Method decode

object decode(string data)
object decode(array _decoded)
object decode(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


Method encode

string encode(object image)
string encode(object image, object mappingoptions)

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"


Constant DEFAULT

constant Image.JPEG.DEFAULT


Constant FASTEST

constant Image.JPEG.FASTEST


Constant FLIP_H

constant Image.JPEG.FLIP_H


Constant FLIP_V

constant Image.JPEG.FLIP_V


Constant FLOAT

constant Image.JPEG.FLOAT


Constant IFAST

constant Image.JPEG.IFAST


Constant ISLOW

constant Image.JPEG.ISLOW


Constant ROT_180

constant Image.JPEG.ROT_180


Constant ROT_270

constant Image.JPEG.ROT_270


Constant ROT_90

constant Image.JPEG.ROT_90


Constant TRANSPOSE

constant Image.JPEG.TRANSPOSE


Constant TRANSVERSE

constant Image.JPEG.TRANSVERSE


Method decode
Method _decode
Method decode_header

object decode(string data)
object decode(string data, mapping options)
mapping _decode(string data)
mapping _decode(string data, mapping options)
mapping decode_header(string data)

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.


Method encode

string encode(object image)
string encode(string|object image, mapping options)

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.


Method exif_decode

mapping exif_decode(string data, mapping|void options)

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


Method quant_tables

mapping(int:array(array(int))) quant_tables(int|void a)

FIXME

Document this function

Class Image.JPEG.Marker


Constant APP0

constant Image.JPEG.Marker.APP0


Constant APP1

constant Image.JPEG.Marker.APP1


Constant APP10

constant Image.JPEG.Marker.APP10


Constant APP11

constant Image.JPEG.Marker.APP11


Constant APP12

constant Image.JPEG.Marker.APP12


Constant APP13

constant Image.JPEG.Marker.APP13


Constant APP14

constant Image.JPEG.Marker.APP14


Constant APP15

constant Image.JPEG.Marker.APP15


Constant APP2

constant Image.JPEG.Marker.APP2


Constant APP3

constant Image.JPEG.Marker.APP3


Constant APP4

constant Image.JPEG.Marker.APP4


Constant APP5

constant Image.JPEG.Marker.APP5


Constant APP6

constant Image.JPEG.Marker.APP6


Constant APP7

constant Image.JPEG.Marker.APP7


Constant APP8

constant Image.JPEG.Marker.APP8


Constant APP9

constant Image.JPEG.Marker.APP9


Constant COM

constant Image.JPEG.Marker.COM


Constant EOI

constant Image.JPEG.Marker.EOI


Constant RST0

constant Image.JPEG.Marker.RST0

Module Image.NEO

Description

Decodes images from the Atari image editor Neochrome.


Method _decode

mapping _decode(string data)

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


Method decode

Image.Image decode(string data)

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

Description

Decodes a PCX image to a mapping.

Note

Throws upon error in data.


Method encode
Method _encode

string encode(object image)
string encode(object image, object mappingoptions)
string _encode(object image)
string _encode(object image, object mappingoptions)

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)


Method decode

object decode(string data)

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(string data)
array __decode(string data, int dontcheckcrc)

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
string 0

The type of the chunk, e.g. "IHDR" or "IDAT".

string 1

The actual chunk data.

bool 2

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(string type, string data)

Description

Encodes a PNG chunk.

Note

Please read about the PNG file format.


Method _decode

mapping _decode(string|array data)
mapping _decode(string|array data, mapping options)

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.


Method decode

Image.Image decode(string data)
Image.Image decode(string data, mapping(string:mixed) options)

Description

Decodes a PNG image. The options mapping is the as for _decode.

Throws

Throws upon error in data.


Method decode_alpha

Image.Image decode_alpha(string data, 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.


Method decode_header

mapping decode_header(string data)

Description

Decodes only the PNG headers.

See also

_decode


Method encode

string encode(Image.Image image)
string encode(Image.Image image, mapping options)

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


Method decode

object decode(string data)

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


Method encode
Method encode_binary
Method encode_ascii
Method encode_P1
Method encode_P2
Method encode_P3
Method encode_P4
Method encode_P5
Method encode_P6

string encode(object image)
string encode_binary(object image)
string encode_ascii(object image)
string encode_P1(object image)
string encode_P2(object image)
string encode_P3(object image)
string encode_P4(object image)
string encode_P5(object image)
string encode_P6(object image)

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(string data, mapping|void options)

Description

Calls decode and returns the image in the "image" index of the mapping. This method is present for API reasons.


Method decode

object decode(string data, mapping|void options)

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.


Method decode_header

mapping|zero decode_header(string data)

Description

Decodes the header of the postscript data into a mapping.

"xsize" : int

Size of image

"ysize" : int
"type" : string

File type information as MIME type. Always "application/postscript".

"color_space" : string

Color space of image. "GRAYSCALE", "LAB", RGB", "CMYK" or "UNKNOWN"


Method encode

string encode(object img, mapping|void options)

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|mapping data)

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|mapping data, mapping|void options)

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


Method decode

Image.Image decode(string data)

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.


Method decode_layers

array(Image.Layer) decode_layers(string data, mapping|void options)

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


Method translate_mode

string|zero translate_mode(string mode)

Description

Convert a photoshop mode name to pike Image.lay mode names

Class Image.PSD.Layer


Variable alpha

object Image.PSD.Layer.alpha


Variable flags

int Image.PSD.Layer.flags


Variable width
Variable height

int Image.PSD.Layer.width
int Image.PSD.Layer.height


Variable image

object Image.PSD.Layer.image


Variable mask_default_color

int Image.PSD.Layer.mask_default_color


Variable mask_flags

int Image.PSD.Layer.mask_flags


Variable mask_width
Variable mask_height

int Image.PSD.Layer.mask_width
int Image.PSD.Layer.mask_height


Variable mask_xoffset
Variable mask_yoffset

int Image.PSD.Layer.mask_xoffset
int Image.PSD.Layer.mask_yoffset


Variable mode
Variable name

string Image.PSD.Layer.mode
string Image.PSD.Layer.name


Variable opacity

int Image.PSD.Layer.opacity


Variable xoffset
Variable yoffset

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.


Method decode
Method decode_alpha
Method decode_header
Method _decode

object decode(string data)
object decode_alpha(string data)
mapping decode_header(string data)
mapping _decode(string data)

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)


Method encode

string encode(object image)
string encode(object image, mapping options)

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


Method decode

object decode(string data)

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


Method encode

string encode(object image)
string encode(object image, object mappingoptions)

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(string data, void|mapping options)

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


Method decode

Image.Image decode(string data, void|mapping options)

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


Method decode_header

mapping decode_header(string data, void|mapping options)

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


Method decode_layers

array(Image.Layer) decode_layers(string data, void|mapping options)

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

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.


Method decode

object decode(string data)

Description

Decodes a Targa image.

Note

Throws upon error in data.


Method encode

string encode(object image)
string encode(object image, object mappingoptions)

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"


Constant COMPRESSION_CCITTFAX3

constant Image.TIFF.COMPRESSION_CCITTFAX3


Constant COMPRESSION_CCITTFAX4

constant Image.TIFF.COMPRESSION_CCITTFAX4


Constant COMPRESSION_CCITTRLE

constant Image.TIFF.COMPRESSION_CCITTRLE


Constant COMPRESSION_CCITTRLEW

constant Image.TIFF.COMPRESSION_CCITTRLEW


Constant COMPRESSION_JPEG

constant Image.TIFF.COMPRESSION_JPEG


Constant COMPRESSION_LZW

constant Image.TIFF.COMPRESSION_LZW


Constant COMPRESSION_NEXT

constant Image.TIFF.COMPRESSION_NEXT


Constant COMPRESSION_NONE

constant Image.TIFF.COMPRESSION_NONE


Constant COMPRESSION_PACKBITS

constant Image.TIFF.COMPRESSION_PACKBITS


Constant COMPRESSION_THUNDERSCAN

constant Image.TIFF.COMPRESSION_THUNDERSCAN


Variable tiff_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(string data)

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.


Method encode
Method _encode

string encode(object image)
string encode(object image, mapping options)
string _encode(object image)
string _encode(object image, mapping options)

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


Method decode

object decode(string data)

Description

Decodes a TIFF image.

Throws

Throws upon error in data.


Method decode_header

mapping|zero decode_header(string data)

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.


Method decode
Method decode_alpha
Method decode_header
Method _decode

object decode(string data)
object decode_alpha(string data)
mapping decode_header(string data)
mapping _decode(string data)

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 `()(string filename)
object `()(string filename, mapping options)

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.


Method names
Method _names

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


Method flush

object flush()

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


Method properties

mapping properties()

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.


Method create

Image.TTF.FaceInstance Image.TTF.FaceInstance(object face)

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

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 

Method encode
Method _encode

string encode(object image, void|mapping args)
string _encode(object image, void|mapping args)

Description

Encode the given image as a WBMP image. All pixels that are not black will be encoded as white.


Method decode

Image.Image decode(string image)

Description

Decode the given image


Method decode_header

mapping decode_header(string image)

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

Description

Decode a WebP image.

Returns
"alpha" : Image.Image
"image" : Image.Image
"format" : string
"width" : int(1..16384)
"height" : int(1..16384)

Method decode

Image.Image decode(string data)

Description

Decode a WebP image, like _decode.

Returns

The decoded image or an error


Method encode

string encode(Image.Image image, mapping(string:int|float|Image.Image)|void options)

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


Method decode_pseudocolor

object decode_pseudocolor(string data, int width, int height, int bpp, int alignbits, int swapbytes, object colortable)

Description

lazy support for pseudocolor ZPixmaps

Note

currently, only byte-aligned pixmaps are supported


Method decode_truecolor
Method decode_truecolor_masks

object decode_truecolor(string data, int width, int height, int bpp, int alignbits, int swapbytes, int rbits, int rshift, int gbits, int gshift, int bbits, int bshift)
object decode_truecolor_masks(string data, int width, int height, int bpp, int alignbits, int swapbytes, int rmask, int gmask, int bmask)

Description

lazy support for truecolor ZPixmaps

Note

currently, only byte-aligned masks are supported


Method encode_pseudocolor

string encode_pseudocolor(object image, int bpp, int alignbits, int vbpp, object colortable)
string encode_pseudocolor(object image, int bpp, int alignbits, int vbpp, object colortable, string translate)

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.


Method encode_truecolor
Method encode_truecolor_masks

string encode_truecolor(object image, int bpp, int alignbits, int swapbytes, int rbits, int rshift, int gbits, int gshift, int bbits, int bshift)
string encode_truecolor_masks(object image, int bpp, int alignbits, int swapbytes, int rmask, int gmask, int bmask)
string encode_truecolor(object image, int bpp, int alignbits, int swapbytes, int rbits, int rshift, int gbits, int gshift, int bbits, int bshift, object ct)
string encode_truecolor_masks(object image, int bpp, int alignbits, int swapbytes, int rmask, int gmask, int bmask, object ct)

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(string data)
object _decode(string data, object mappingoptions)

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.


Method decode

object decode(string data)

Description

Decodes a XBM image.

Note

Throws upon error in data.


Method encode

string encode(object image)
string encode(object image, object mappingoptions)

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


Constant NORMAL_MODE
Constant DISSOLVE_MODE
Constant BEHIND_MODE
Constant MULTIPLY_MODE
Constant SCREEN_MODE
Constant OVERLAY_MODE
Constant DIFFERENCE_MODE
Constant ADDITION_MODE
Constant SUBTRACT_MODE
Constant DARKEN_ONLY_MODE
Constant LIGHTEN_ONLY_MODE
Constant HUE_MODE
Constant SATURATION_MODE
Constant COLOR_MODE
Constant VALUE_MODE
Constant DIVIDE_MODE
Constant REPLACE_MODE
Constant ERASE_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


Constant Red
Constant Green
Constant Blue
Constant Gray
Constant Indexed
Constant Auxillary

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|mapping data)

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|mapping data, object mapping|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|object data, mapping|void options)

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(string gimp_image_data, mapping(string:mixed)|void opts)
mapping(string:Image.Image|string) _decode(GimpImage gimp_image, mapping(string:mixed)|void opts)
mapping(string:Image.Image|string) _decode(mapping(string:mixed) gimp_image_chunks, mapping(string:mixed)|void opts)

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


Method decode

object decode(string data)

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


Method decode

Image.Image decode(string what, mapping|void opts)

Description

See _decode. This function returns the image member of the return mapping of that function.


Method decode_header

mapping decode_header(string|mapping|GimpImage data)

Description

Return information about the given image (xsize, ysize and type). Somewhat inefficient, it actually decodes the image completely.


Method decode_layers

array(object) decode_layers(object stringdata)
array(object) decode_layers(object stringdata, object mappingoptions)

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,


Method decode_layers

array(Image.Layer) decode_layers(string gimp_image_data, mapping(string:mixed)|void opts)
array(Image.Layer) decode_layers(GimpImage gimp_image, mapping(string:mixed)|void opts)
array(Image.Layer) decode_layers(mapping(string:mixed) gimp_image_chunks, mapping(string:mixed)|void opts)

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) 

Method translate_mode

string translate_mode(int mode)

Description

Convert a GIMP layer mode to an Image.Layer layer mode

Class Image.XCF.Channel


Variable r
Variable g
Variable b

int Image.XCF.Channel.r
int Image.XCF.Channel.g
int Image.XCF.Channel.b


Variable flags

mapping Image.XCF.Channel.flags


Variable width
Variable height

int Image.XCF.Channel.width
int Image.XCF.Channel.height


Variable image_data

Hierarchy Image.XCF.Channel.image_data


Variable name

string Image.XCF.Channel.name


Variable opacity

int Image.XCF.Channel.opacity


Variable parasites

array(Parasite) Image.XCF.Channel.parasites


Variable parent

object Image.XCF.Channel.parent


Variable tattoo

int Image.XCF.Channel.tattoo

Class Image.XCF.GimpImage


Variable active_channel

Channel Image.XCF.GimpImage.active_channel


Variable active_layer

Layer Image.XCF.GimpImage.active_layer


Variable channels

array(Channel) Image.XCF.GimpImage.channels


Variable colormap

Image.Colortable Image.XCF.GimpImage.colormap


Variable compression

int Image.XCF.GimpImage.compression


Variable guides

array(Guide) Image.XCF.GimpImage.guides


Variable width
Variable height

int Image.XCF.GimpImage.width
int Image.XCF.GimpImage.height


Variable layers

array(Layer) Image.XCF.GimpImage.layers


Variable meta_colormap

Image.Colortable Image.XCF.GimpImage.meta_colormap


Variable parasites

array(Parasite) Image.XCF.GimpImage.parasites


Variable paths

array(Path) Image.XCF.GimpImage.paths


Variable res_unit

int Image.XCF.GimpImage.res_unit


Variable selection

Channel Image.XCF.GimpImage.selection


Variable tattoo_state

int Image.XCF.GimpImage.tattoo_state


Variable type

int Image.XCF.GimpImage.type


Variable xres
Variable yres

float Image.XCF.GimpImage.xres
float Image.XCF.GimpImage.yres

Class Image.XCF.Guide

Description

A single guideline


Variable pos

int Image.XCF.Guide.pos


Variable vertical

int Image.XCF.Guide.vertical

Class Image.XCF.Hierarchy


Variable width
Variable height
Variable bpp
Variable tiles
Variable compression
Variable ct

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__

protected local void __create__(int width, int height, int bpp, array tiles, int compression, Image.Colortable ct)


Method create

Image.XCF.Hierarchy Image.XCF.Hierarchy(int width, int height, int bpp, array tiles, int compression, Image.Colortable ct)


Method get_layer

Image.Layer get_layer(int|void shrink)

Class Image.XCF.Layer


Variable flags

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


Variable width
Variable height

int Image.XCF.Layer.width
int Image.XCF.Layer.height


Variable image

Hierarchy Image.XCF.Layer.image


Variable mask

LayerMask Image.XCF.Layer.mask


Variable mode

int Image.XCF.Layer.mode


Variable name

string Image.XCF.Layer.name


Variable opacity

int Image.XCF.Layer.opacity


Variable parasites

array(Parasite) Image.XCF.Layer.parasites


Variable parent

GimpImage Image.XCF.Layer.parent


Variable tattoo

int Image.XCF.Layer.tattoo


Variable type

int Image.XCF.Layer.type


Variable xoffset
Variable yoffset

int Image.XCF.Layer.xoffset
int Image.XCF.Layer.yoffset

Class Image.XCF.LayerMask


Inherit Channel

inherit Channel : Channel

Class Image.XCF.Parasite


Variable name
Variable flags
Variable data

string Image.XCF.Parasite.name
int Image.XCF.Parasite.flags
string Image.XCF.Parasite.data


Method __create__

protected local void __create__(string name, int flags, string data)


Method create

Image.XCF.Parasite Image.XCF.Parasite(string name, int flags, string data)

Class Image.XCF.Path

Description

A path


Variable closed

int Image.XCF.Path.closed


Variable locked

int Image.XCF.Path.locked


Variable name

string Image.XCF.Path.name


Variable points

array(PathPoint) Image.XCF.Path.points


Variable ptype

int Image.XCF.Path.ptype


Variable state

int Image.XCF.Path.state


Variable tattoo

int Image.XCF.Path.tattoo

Class Image.XCF.PathPoint

Description

A point on a path


Variable type

int Image.XCF.PathPoint.type


Variable x
Variable y

float Image.XCF.PathPoint.x
float Image.XCF.PathPoint.y

Module Image.XFace

Description

Note

This module uses libgmp.


Method decode

object decode(string data)
object decode(string data, object mappingoptions)

Description

Decodes an X-Face image.

The options argument may be a mapping containing zero options.


Method decode_header

object decode_header(string data)
object decode_header(string data, object mappingoptions)

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.


Method encode

string encode(object img)
string encode(object img, object mappingoptions)

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(string bytes, mapping|void options)

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.Image img, Image.Image alpha, int bpc, 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
string 0

Size information on the format (sprintf("%d %d %d %d", h, w, ncolors, bpn)).

string 1..ncolors

Same as colors.

string ncolors_plus_one..ncolors_plus_h

Line information. Strings of length bpn*w with encoded pixels for each line.


Method decode

Image.Image decode(string bytes)


Method encode

string encode(Image.Image image, mapping|void options)

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
Method decode_header

mapping _decode(string data)
mapping decode_header(string data)

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. :) /mirar+pike@mirar.org

Returns

the decoded image as an image object

Note

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

See also

decode


Method decode

object decode(string data)

Description

Simple decodes a XWD image file.