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
  - no arguments -> old image is copied
  - size is given -> old image is copied cropped
  - 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;
      }

  ## Undocumented, yet:

      object image->select_from(int x,int y);
      object image->distancesq(int r,int g,int b);
      array(int) image->getpixel(int x,int y);
      object image->skewx(int diff,rgb);
      object image->skewy(int diff,rgb);
      object image->skewx_expand(int diff,rgb);
      object image->skewy_expand(int diff,rgb);
      object image->rotate(int|float angle,rgb);
      object image->rotate_expand(int|float angle,rgb);
      object image->turbulence(colorrange,int octaves=3,float scale=1,
      			 float xdiff=0,float ydiff=0,float cscale=1);
      object image->noise(colorrange,float scale=0.1,
      	 	    float xdiff=0,float ydiff=0,float cscale=1);
          where colorrange is ({ float position=0..1, ({r,g,b}),
             			   float position=0..1, ({r,g,b}), ... })