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 "unneccesary" borders around the image, adds one of its own if wanted to, in selected directions.

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

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

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

    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

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

    Description

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

      original | ->clear (0,128,255)

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

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

    Description

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

    Note

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

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

    See also

      orient, 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 randomgrey()`
      `object random(greyint seed)`

    Description

      Gives a randomized image;

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

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

    Returns

      a new image

    See also

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

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

    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 description

      `array(string) description()`

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

    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.

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

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

      Returns

        the new color object

      Note

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

      Method cast

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

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

        `array(int) get(string|Stdio.File file)`

      Description

        Read dimensions from a JPEG, GIF, PNG, 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.

        As a compatibility measure, if the file is a path to an image file, it will be loaded and processed once the processing of the path as data has failed.

      Returns

        Array
        `int 0` | Image width.
        `int 1` | Image height.
        `string 2` | Image type. Any of `"gif"`, `"png"`, `"tiff"`, `"jpeg"` and `"psd"`.

      Method get_GIF

        `array(int) get_GIF(Stdio.File 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.File 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) get_PNG(Stdio.File 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) get_PSD(Stdio.File 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) get_TIFF(Stdio.File 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.

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

        Method create

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

        Variable file
        Variable size

          `protected string Image.Fonts.Font.file`
          `protected int Image.Fonts.Font.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, 0|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

        `object decode_layers(string data)`
        `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.

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

      Inherit "____Image_JPEG"

        inherit "____Image_JPEG" : "____Image_JPEG"

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

      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.

      Variable _encode

        `function(:void) Image.PS._encode`

      Description

        Same as encode. 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 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.

      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..1)|int(8..8)|int(16..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

      Inherit _PSD

        inherit Image._PSD : _PSD

      Method translate_mode

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

      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`

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

      Inherit "____Image_TIFF"

        inherit "____Image_TIFF" : "____Image_TIFF"

    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.

      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

        `GimpImage __decode(string|mapping what)`

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

      Inherit _XCF

        inherit Image._XCF : _XCF

      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

          `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

        Method create

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

        Variable name
        Variable flags
        Variable data

          `string Image.XCF.Parasite.name`
          `int Image.XCF.Parasite.flags`
          `string Image.XCF.Parasite.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).

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

      Inherit _XPM

        inherit Image._XPM : _XPM

    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.