                                Pike module:

                                    image

                       Pontus Hagland law@infovav.se
                         Per Hedbor per@infovav.se
                        David Kågedal kg@infovav.se
----------------------------------------------------------------------------
This package adds two Pike progams:

   * "precompiled/image" and
   * "precompiled/font".

----------------------------------------------------------------------------

methods in precompiled/image:

Methods resulting in a new object:
object clone( [int xsize,int ysize [,int r,int g,int b] ] );

object copy( [int x1,int y1,int x2,int y2 [,int r,int g,int b] ] );
object autocrop( [int border_width [,int left,int right,int top,int bottom]
[,int r,int g,int b] ] );

object gray();
object color(int r,int g,int b);
object invert();

object mirrorx(void);
object mirrory(void);
object rotate_cw(void);
object rotate_ccw(void);
object threshold([int r,int g,int b]);
object apply_matrix(array(array(int)) matrix,[int r,int g,int b[,int div]]);

object scale(float factor);
object scale(float factorx,float factory);
object scale(int newx|0,int newy|0);

Methods operating on current object:
string toppm(void);
string|object fromppm(string s);
string togif( [int r,inr g,int b] );

object paste(object img [,int x,int y])
object paste_alpha(object img, int alpha [,int x, int y]);
object paste_mask(object img, object alpha_mask [,int x,int y]);

object setcolor(int r,int g,int b);
object setpixel(int x,int y [,int r,int g,int b] );
object line(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] );
object circle(int x,int y,int radx,int rady [,int r,int b,int g] );
object tuned_box(int x1,int y1,int x2,int y2,array(array(int)) corner_rgb);

Information giving methods:
object xsize();
object ysize();
----------------------------------------------------------------------------

METHOD
     object apply_matrix(array(array(int)) matrix,[int r,int g,int b[,int
     div]]);
DESCRIPTION
     This method applies a matrix on the image. Each surrounding pixel is
     multiplied with the value of the matrix element in that point, these
     values are added and divided by the total sum of the matrix values (and
     the div argument) and stored on the pixel (eventually added to the
     r,g,b argument given as 'mean' value).

     It is possible to use a matrix of RGB groups (ie an array of three
     integers) instead of the simple values, this making it possible to
     apply different matrices on red, green and blue channel.
RETURN VALUE
     the new object
EXAMPLE
     A 'blur' operation (3x3, gaussian):

     blurred=image->apply_matrix( ({ ({1,2,1}), ({2,3,2}), ({1,2,1}) }) );

     A 'Emboss' operation (3x3):

     emossed=image->apply_matrix(({ ({0,1,8}), ({-1,0,1}), ({-8,-1,0}) }), 128,128,128, 15 );

     Here i'm using 128,128,128 (gray) as a mean, because i get negative
     values.
     A division by 15 is good to give 'normal' edges.
BUGS
     not known

----------------------------------------------------------------------------

METHOD
     object autocrop( [int border_width [,int left,int right,int top,int
     bottom] [,int r,int g,int b] ] );
DESCRIPTION
     Crops away unneccesary borders from the image. The border argument is
     to define the new thickness of the surrounding border and the r,g,b is
     the newly created border color.

     The left, right, ... arguments is used to tell which edges should be
     autocropped.
RETURN VALUE
     the new object
EXAMPLE

     cropped=image->autocrop();

BUGS
     now known

----------------------------------------------------------------------------

METHOD
     object box(int x1,int y1,int x2,int y2 [,int r,int g,int b] );
DESCRIPTION
     Draw a box of the default or specified color.
RETURN VALUE
     the image object
EXAMPLE
BUGS

----------------------------------------------------------------------------

METHOD
     object circle(int x,int y,int radx,int rady [,int r,int b,int g] );
DESCRIPTION
     Draw a circle. The coordinates given are the center of the image and
     the radius in x (horisontal) and y (vertical), this making it possible
     to draw an ellipse too. :-)
RETURN VALUE
     the image object
EXAMPLE
BUGS

----------------------------------------------------------------------------

METHOD
     object clone( [int xsize,int ysize [,int r,int g,int b] ] );
DESCRIPTION
     make a new object and return it
        o no arguments -> old image is copied
        o size is given -> old image is copied cropped
        o color is given -> new default color
RETURN VALUE
     the new object
SEE ALSO
     copy, clear
EXAMPLE
BUGS

----------------------------------------------------------------------------

METHOD
     object color(int r,int g,int b);
DESCRIPTION
     Apply a color filter on the image.
RETURN VALUE
     the new object
EXAMPLE

     cyan=image->color(64,255,192);

     This function is most usable on a image that has been grayed first.
BUGS

----------------------------------------------------------------------------

METHOD
     object copy( [int x1,int y1,int x2,int y2 [,int r,int g,int b] ] );
DESCRIPTION
     Make a copy, or a copy of a part of the image. It is possible to copy
     more then the image, to extend the image, this area is filled with the
     current (or given) color.
RETURN VALUE
     the new image object
EXAMPLE

     copy=image->copy();

     copy=image->copy(-10,-10,image->xsize()+9,image->ysize()+9);

BUGS

----------------------------------------------------------------------------

METHOD
     string|object fromppm(string s);
DESCRIPTION
     Import a ppm image.
RETURN VALUE
     0 (object) upon success, else the error message (string).
EXAMPLE

     image=clone( (program)"precompiled/image" );
     image->fromppm(read_bytes("my_image.ppm",0,10000000));

BUGS

----------------------------------------------------------------------------

METHOD
     object gray([int r,int g,int b]);
DESCRIPTION
     Make this image gray (each r,g,b gets the same value).
     If a color is given, that specifies the amount of r, g, and b that is
     used to compute the gray level. Default is 87,127,41.
RETURN VALUE
     the new object
EXAMPLE

     gray=image->gray()

BUGS

----------------------------------------------------------------------------

METHOD
     object invert();
DESCRIPTION
     Invert the image.
RETURN VALUE
     the new object
EXAMPLE

     inverted=image->invert()

BUGS

----------------------------------------------------------------------------

METHOD
     object line(int x1,int y1,int x2,int y2 [,int r,int g,int b] );
DESCRIPTION
     Draw a line from x1,y1 to x2,y2.
RETURN VALUE
     the image object
EXAMPLE

     image->line(17,100,42,1000);

BUGS

----------------------------------------------------------------------------

METHOD
     object mirrorx(void);
     object mirrory(void);
DESCRIPTION
     Mirrors the image, horisontally or vertically.
RETURN VALUE
     the new image object
EXAMPLE

     mirrored=image->mirrorx();

BUGS

----------------------------------------------------------------------------

METHOD
     object rotate_cw(void);
     object rotate_ccw(void);
DESCRIPTION
     Rotate the image, clockwise or counterclockwise, 90 degrees.
     This operation is very fast compared to rotating any angle.
RETURN VALUE
     the new image object
EXAMPLE

     snurr=image->rotate_cw();

BUGS

----------------------------------------------------------------------------

METHOD
     object paste(object img [,int x,int y])
     object paste_alpha(object img, int alpha [,int x, int y]);
     object paste_mask(object img, object alpha_mask [,int x,int y]);
DESCRIPTION
     Paste an image on this image. Use the specified alpha channel value or
     the second specified image as an alpha channel.
     The first argument is the image that will be pasted.
RETURN VALUE
     the image object this function doesn't return anything
EXAMPLE

     image->paste(other_smaller_image,17,42);

     image->paste_mask(other_image,alpha_channel_image);

     Paste a dog on a landscape:

     landscape->paste(dog,dog_alpha_channel,xpos,ypos);

     Write some text:

     text=font->write("some text");
     foreground=text->clear(255,255,255); // white
     background->paste(foreground,text,xpos,ypos);

BUGS

----------------------------------------------------------------------------

METHOD
     object scale(float factor); (1
     object scale(float factorx,float factory); (2
     object scale(int newx|0,int newy|0); (3
DESCRIPTION
     Scale this image.
       1. scale the image with a (line scale) factor
       2. scale the image with different factors on x and y
       3. scale the image to a new size
          with newx or newy set to zero, just scale the image to fit the x
          or y size and keep proportions.
RETURN VALUE
     the new object this function doesn't return anything
EXAMPLE
BUGS

----------------------------------------------------------------------------
METHOD
     object setcolor(int r,int g,int b);
DESCRIPTION
     set the default color used for drawing lines, etc
RETURN VALUE
     the image object
EXAMPLE
BUGS

----------------------------------------------------------------------------
METHOD
     object setpixel(int x,int y [,int r,int g,int b] );
DESCRIPTION
     set the color of the specified pixel
RETURN VALUE
     the image object
EXAMPLE
BUGS

----------------------------------------------------------------------------

METHOD
     object threshold([int r,int g,int b]);
DESCRIPTION
     make image black-and-white using the given value as the threshold
RETURN VALUE
     the new object
EXAMPLE
BUGS

----------------------------------------------------------------------------

METHOD
     string togif( [int r,inr g,int b] );
DESCRIPTION
     export gif
     if the color are given, this is the transparent color
RETURN VALUE
     the gifimage as a string
EXAMPLE
BUGS

----------------------------------------------------------------------------

METHOD
     string toppm(object);
DESCRIPTION
     export ppm
RETURN VALUE
     the ppm image as a string
EXAMPLE
BUGS

----------------------------------------------------------------------------

METHOD
     object tuned_box(int x1,int y1,int x2,int y2,array(array(int))
     corner_rgb);
DESCRIPTION
     draw a box with the specified corner colours, and shade the colors
     between
RETURN VALUE
     the image object
EXAMPLE

     image->tuned_box(0,0,img->xsize()-1,img->ysize()-1,
                     ({({0,0,64}),({16,16,128}),
                       ({16,16,128}),({192,160,128})}));

BUGS

----------------------------------------------------------------------------

METHOD
     object xsize();
     object ysize();
DESCRIPTION
RETURN VALUE
     Gives the x- or the y-size (horisontal or vertical size) of the image.
EXAMPLE
BUGS

----------------------------------------------------------------------------

methods in precompiled/font:

int load(string file_name);
object write(string line, ...);
----------------------------------------------------------------------------

METHOD
     int load(string file_name);
DESCRIPTION
     load this font object with the font from the specified file
RETURN VALUE
     true on success
EXAMPLE
BUGS

----------------------------------------------------------------------------

METHOD
     object write(string line, ...);
DESCRIPTION
     make a new image object from the specified text, each argument
     representing a line
RETURN VALUE
     the new image object
EXAMPLE
BUGS

----------------------------------------------------------------------------

Example program:

(pike)

int main()
{
   object txt,o,shad,font;
   int i;

   txt =
      (font=clone((program)"/precompiled/font"))
      ->load("/usr/local/lib/pike/fonts/64/helvetica_bold_r")
      ->write("The Image Module")
      ->autocrop(20,0,0,0);

   shad=txt->mirrory()->scale(1.0,0.3)->color(64,64,64);

   o=clone((program)"/precompiled/image",
           txt->xsize(),txt->ysize(), 0,0,100)
        ->tuned_box(0,0,txt->xsize(),txt->ysize(),
                    ({({0,0,0}),({0,0,0}),
                      ({0,0,255}),({128,128,0})}));

   o->setcolor(255,255,255,200);
   for (i=0; i<30; i++)
      if (random(2))
         o->line(random(o->xsize()),o->ysize()-10-random(20+i*3),
                 o->xsize()-1-random(30),o->ysize()-1);
      else
         o->line(random(o->xsize()),o->ysize()-10-random(20+i),
                 random(30),o->ysize()-1);

   for (i=0; i<10; i++)
      o->box(random(o->xsize()),random(o->ysize()),
             random(o->xsize()),random(o->ysize()),
             random(256),random(256),random(256),220);

   o -> paste_mask(txt->clear(0,255,0),
                   shad,0,(int)(font->baseline()*0.7)+shad->ysize()-10)
     -> paste_mask(txt->clear(255,255,0),
                 txt->apply_matrix(({({1,2,1}),({2,4,2}),({1,2,1})}))
                 ->apply_matrix(({({1,2,1}),({2,4,2}),({1,2,1})}))
                 ->modify_by_intensity(1,0,0, 0,255,255,255,255,255))
     -> paste_mask(txt->clone()
                   ->tuned_box(0,0,txt->xsize()-1,txt->ysize()-1,
                               ({({128,128,128}),({64,128,0}),
                                 ({64,128,0}),({255,255,0})})),
                   txt);
   write(o->togif_fs());
   return 0;
}
