pike.git
/
src
/
modules
/
Image
/
doc.txt
version
»
Context lines:
10
20
40
80
file
none
3
pike.git/src/modules/Image/doc.txt:1:
+
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;
+
}
Newline at end of file added.