gdimage Class Reference


The gdimage class is an interface layer to the GD library. Most of the library functions are implemented as compiled class methods, and the rest can be added easily if needed as interpreted methods because the internal structure of the class is just a standard property list. The gdimage class also adds a Turtle Graphics capability to GD.

The Coordinate System of a gdimage is twofold: GD coordinates and Turtle coordinates.

GD Coordinates: A gdimage object has its x and y origin [0,0] at the upper left corner of the image. The units are pixels. This means that an image has the same the coordinate system and displacement units in gdimage as in The Gimp photo manipulation software. The interfacing with GD library is also straight forward. The coordinates are expressed in integer but the methods accept float and unsigned integers as well.

Turtle Coordinates: A second Coordinate System is used by the Turtle Graphics capability. The turtle can be manipulated, like in the Logo language, in order to draw vector graphics. The gdimage-constructor sets by default the origin or home of the turtle at the center of the image rectangle, but if needed, the method gdimage-sethome sets the [0,0] turtle home or origin at the x and y position on the gdimage object, relative to the gdimage object native coordinates which has its coordinates [0,0] at the upper left corner of the image. A turtle position [1,1] will be above and at the right of the home position, ie at a lower Y coordinate in the gdimage coordinate system. The two Coordinates Systems might look difficult to use at first, but thanks to a few specific methods the conversion between the two systems is easy, so one can take advantage of the classical logo-style orientation for vector graphics programming. The coordinates, headings, distances are expressed preferably in float for the best precision in the calculations, but integers and unsigned integers are accepted.

The coordinates, either GD or Turtle, and the numeric arguments, being float, integer or unsignedinteger, are actually objects of the scalar class, hence accepting the subclasses float, integer or unsignedinteger and their own subclasses.

The color or colorindex and R, G, B arguments are of the types integer or unsignedinteger.


  • gdimage-arc
  • gdimage-back
  • gdimage-blur
  • gdimage-chromakey
  • gdimage-constructor
  • gdimage-copy
  • gdimage-crop
  • gdimage-destructor
  • gdimage-fill
  • gdimage-filledellipse
  • gdimage-filledpolygon
  • gdimage-filledrectangle
  • gdimage-filltoborder
  • gdimage-forward
  • gdimage-getpixel
  • gdimage-heading
  • gdimage-home
  • gdimage-left
  • gdimage-leftcurve
  • gdimage-line
  • gdimage-makeanimatedgif
  • gdimage-makegif
  • gdimage-makejpeg
  • gdimage-makepng
  • gdimage-merge
  • gdimage-openpolygon
  • gdimage-pack
  • gdimage-pendown
  • gdimage-penup
  • gdimage-polygon
  • gdimage-pos
  • gdimage-rectangle
  • gdimage-resize
  • gdimage-right
  • gdimage-rightcurve
  • gdimage-rotate
  • gdimage-setbrush
  • gdimage-setcolor
  • gdimage-setheading
  • gdimage-sethome
  • gdimage-setpixel
  • gdimage-setpos
  • gdimage-setthickness
  • gdimage-setx
  • gdimage-setxy
  • gdimage-sety
  • gdimage-towards
  • gdimage-writeanimatedgif
  • gdimage-writegif
  • gdimage-writejpeg
  • gdimage-writepng
  • gdimage-xabs
  • gdimage-xcor
  • gdimage-yabs
  • gdimage-ycor

    • List of all Inherited Classes

  • class

    • gdimage-arc

    (arc img x y w h s e color)

    Function Type subr
    Arguments a gdimage object, scalar x, scalar y, scalar width, scalar height, scalar start angle, scalar end angle, integer or unsignedinteger for colorindex or RGB
    Return Value nil
    Description draws a partial ellipse on the gdimage object;

    the center is located at the x and y gdimage coordinates, the start and end angles define the limits between which the arc is drawn, clockwise, and the ellipse is bounded by the width and height values;

    as the GD library does not provide a way to rotate the rectangle, the axis of the ellipse are always aligned with the x and y directions;

    the start and end angle are counted clockwise from North (upper direction), like the heading in Turtle Graphics;

    the arc is drawn with the selected color

    uses GD coordinates
    Example (arc img 150 100 50 50 0 90 0xff00ff)

    gdimage-back

    (back img dist )

    Function Type subr
    Arguments a gdimage object, a scalar
    Return Value nil
    Description makes the turtle-pen go backwards the distance in pixels given by the second argument; the pen draws or not;

    uses Turtle coordinates
    Example (back img 20.0)

    gdimage-blur

    (blur img )

    Function Type subr
    Arguments a gdimage object
    Return Value a gdimage object
    Description creates and returns a new gdimage object identical to the one passed as argument, but applies a fixed gaussian blur to the new image; the original image is unchanged;
    Example (blur img)

    gdimage-chromakey

    (chromakey img color )

    Function Type subr
    Arguments a gdimage object, an unsignedinteger color
    Return Value a gdimage object
    Description modifies a gdimage object by replacing each pixel value equal to the second argument by 0x7f000000, which means that the pixel is transparent without color; sets also the adequate flag in the GD image structure; the user can draw a shape on an image with the drawing functions, then fill the outside of the shape with filltoborder , and then replace the fill color by a transparent background thanks to the chromakey function, and use the shape as a sprite merged in another image
    Example (chromakey img 0xff0000)

    gdimage-constructor

    (make-instance gdimage w h ... argn )

    Function Type subr
    Arguments the symbol gdimage, an integer, an integer, an optional list of keywords
    Return Value a gdimage object
    Description never call gdimage-constructor directly but always through make-instance ; the arguments w and h give the width and height in pixels of the image to be constructed;

    the optional keyword 'truecolor indicates that the picture will be of the truecolor type; this is the default option when this keyword is omitted;

    the optional keyword 'palette indicates that the picture is based on a limited palette of selected colors;

    the optional keyword 'from followed by a string containing a filename or by a stream object or by a binary block or by an imgbuffer object indicates the source of the image to build; in that case, the dimensions w and h may be omitted because the real dimensions are always taken from the existing image source

    the optional keyword 'transparent initializes the empty image to a totally transparent background, and sets the flags in order to continue to process the image as transparent

    the Turtle Graphics is also initialized so that home is at the center of the picture and heading points to North
    Example (make-instance gdimage 300 200 'truecolor)

    gdimage-copy

    (copy img )

    Function Type subr
    Arguments a gdimage object
    Return Value a gdimage object
    Description creates a new gdimage object identical to the one passed as argument
    Example (copy img)

    gdimage-crop

    (crop img x y w h )

    Function Type subr
    Arguments a gdimage object, an integer x, an integer y, an integer w, an integer h
    Return Value a gdimage object
    Description creates and returns a new gdimage object containing an extract of the image passed as argument; x and y are the coordinates of the upper left corner of the extracted rectangle, w and h being the width and height; the new image size is w and h
    Example (crop img 0 0 100 50)

    gdimage-destructor

    (destroy-instance img )

    Function Type subr
    Arguments a gdimage object
    Return Value nil
    Description never call gdimage-destructor directly but always through destroy-instance ; destroys a gdimage object, releasing properly the associated memory resources
    Example (destroy-instance img)

    gdimage-fill

    (fill img x y color )

    Function Type subr
    Arguments a gdimage object, scalar x, scalar y, integer or unsignedinteger for colorindex or RGB
    Return Value nil
    Description floods the image with the color given as last argument, from the point [x,y], stopping at the boundary of the region of the same color as the point [x,y]

    uses GD coordinates
    Example (fill img 150 100 0x00ff00)

    gdimage-filledellipse

    (filledellipse img x y w h color )

    Function Type subr
    Arguments a gdimage object, scalar x, scalar y, scalar width, scalar height, integer or unsignedinteger for colorindex or RGB
    Return Value nil
    Description draws an ellipse on the gdimage object; the center is located at the x and y gdimage coordinates, the ellipse is bounded by the width and height values; the ellipse is drawn with the selected color and filled with the same color;

    uses GD coordinates
    Example (filledellipse img 150 100 60 40 0xff00ff)

    gdimage-filledpolygon

    (filledpolygon img xy-pairs color )

    Function Type subr
    Arguments a gdimage object, a list of scalar x and scalar y pairs, an integer or unsignedinteger for colorindex or RGB
    Return Value nil
    Description draws a closed polygon on the gdimage object; the vertices are determined by the second argument which is a list of pairs of coordinates; the polygon is drawn with the selected color and filled with the same color;

    uses GD coordinates
    Example (filledpolygon img '(10 10 20 10 20 20 10 20) 0xff00ff)

    gdimage-filledrectangle

    (filledrectangle img x1 y1 x2 y2 color )

    Function Type subr
    Arguments a gdimage object, four scalars, an integer or unsignedinteger for colorindex or RGB
    Return Value nil
    Description draws a rectangle on the gdimage object; the upper-left and lower-right vertices are determined by the second up to fifth arguments; the rectangle is drawn with the selected color and filled with the same color;

    uses GD coordinates
    Example (filledrectangle img 10 10 100 50 0xff00ff)

    gdimage-filltoborder

    (filltoborder img x y bcolor fcolor )

    Function Type subr
    Arguments a gdimage object, scalar x, scalar y, an integer or unsignedinteger for colorindex or RGB, an integer or unsignedinteger for colorindex or RGB
    Return Value nil
    Description floods a portion of the image given as first argument beginning at the point [x,y] specified by the second and third arguments and stopping at the border color specified by the fourth argument, and filling with the color given as fifth argument;

    uses GD coordinates
    Example (filltoborder img 50 50 0xff 0xff00ff)

    gdimage-forward

    (forward img dist )

    Function Type subr
    Arguments a gdimage object, a scalar
    Return Value nil
    Description makes the turtle-pen go forward the distance in pixels given by the second argument; the pen draws or not;

    uses Turtle coordinates
    Example (forward img 20.0)

    gdimage-getpixel

    (getpixel img x y )

    Function Type subr
    Arguments a gdimage object, a pair of scalars
    Return Value an unsignedinteger
    Description gets the RGB value or the colorindex of the pixel at the [x,y] coordinates given by the second and third arguments;

    uses GD coordinates
    Example (getpixel img 10 10)

    gdimage-heading

    (heading img )

    Function Type subr
    Arguments a gdimage object
    Return Value a float
    Description returns the current heading of the turtle; a heading of 0.000000 means that the turtle is facing north;

    uses Turtle coordinates
    Example (heading img)

    gdimage-home

    (home img )

    Function Type subr
    Arguments a gdimage object
    Return Value nil
    Description returns the turtle to the home coordinates; if the property 'pendown is true, the segment is drawn with the current color and pen;

    uses Turtle coordinates
    Example (home img)

    gdimage-left

    (left img angle )

    Function Type subr
    Arguments a gdimage object, a scalar
    Return Value nil
    Description makes the turtle-pen to turn to the left of an angle given by the second argument; the angle is in degrees; the current heading is changed;

    uses Turtle coordinates
    Example (left img 45.0)

    gdimage-leftcurve

    (leftcurve img angle radius )

    Function Type subr
    Arguments a gdimage object, a scalar, a scalar
    Return Value nil
    Description makes the turtle-pen draw a curve winding to the left starting from the current position and orientation and finishing in a new position and with a new orientation; the curve is drawn to the left if the radius argument is positive; if it is zero or negative, the function degenerates to (left); the angle argument in degrees defines altogether the arc drawn and the angle between the new direction and the original direction;

    uses Turtle coordinates
    Example (leftcurve img 90.000000 10)

    gdimage-line

    (line img x1 y1 x2 y2 color )

    Function Type subr
    Arguments a gdimage object, four scalars, an integer or unsignedinteger for colorindex or RGB
    Return Value nil
    Description draws a line segment on the gdimage object; the starting and ending vertices are determined by the second up to fifth arguments; the segment is drawn with the selected color;

    uses GD coordinates
    Example (line img 10 10 100 50 0xff00ff)

    gdimage-makeanimatedgif

    (makeanimatedgif img imglist arg1 ... argn )

    Function Type subr
    Arguments a gdimage object, a list of gdimage objects, a series of optional keywords with their values
    Return Value an imgbuffer object
    Description creates an animated gif from the images given in the list as second argument; the first image of the list is a repetition of the object passed as first argument; the third and further arguments are keywords followed by their values;

    the keyword 'globalcm followed by an integer value from -1 to 1 indicates if a global colormap must be used or if a colormap must be held for each image, or the default is chosen, which is also global;

    the keyword 'loops followed by a positive integer indicates how many cycle the image list must be shown;default is 0 which is infinite loop

    the keyword 'delay followed by a positive integer greater or equal than 4, indicates the delay between frames in 100th of seconds; default i 4 which is equal to 25 frames per seconds;

    the keyword 'maxbuffer which must be greater or equal to 1024 indicates the size of the work buffer allocated to create the animated image; if the buffer is too small the building of the animated gif will fail, so it is a matter of trial and error; usually the default value of 1 MB is enough and the parameter can be ignored;

    the result is stored in an imgbuffer object which is a subclass of binary block;
    Example (makeanimatedgif img list1)

    gdimage-makegif

    (makegif img )

    Function Type subr
    Arguments a gdimage object
    Return Value an imgbuffer object
    Description creates a gif file stored in an imgbuffer object, which is actually a binary block subclass
    Example (makegif img)

    gdimage-makejpeg

    (makejpeg img )

    Function Type subr
    Arguments a gdimage object
    Return Value an imgbuffer object
    Description creates a jpeg file stored in an imgbuffer object, which is actually a binary block subclass
    Example (makejpeg img)

    gdimage-makepng

    (makepng img )

    Function Type subr
    Arguments a gdimage object
    Return Value an imgbuffer object
    Description the function returns an imgbuffer object containing a png image built from the gdimage object given as argument; the png image can be stored as such in a png file, or used directly from memory
    Example (makepng img)

    gdimage-merge

    (merge img img2 x y ... argn )

    Function Type subr
    Arguments a gdimage object, a gdimage object, integer x, integer y, optional keywords
    Return Value a gdimage object
    Description modifies the image passed as first argument by merging in it the image passed as second argument; the coordinates x and y are where in the target image the source is merged; the size of the merged source is the original size of the source image; returns the merged image

    the keyword 'merge followed by an integer value from 0 to 100 indicates the percentage of the source image to merge in the target;

    transparent image can also be merged
    Example (merge img1 img2 0 0 'merge 50)

    gdimage-openpolygon

    (openpolygon img xy-pairs color )

    Function Type subr
    Arguments a gdimage object, a list of scalar x and scalar y pairs, an integer or unsignedinteger for colorindex or RGB
    Return Value nil
    Description draws an open polygon on the gdimage object; the vertices are determined by the second argument which is a list of pairs of coordinates; the polygon is drawn with the selected color;

    uses GD coordinates
    Example (openpolygon img '(10 10 20 10 20 20 10 20) 0xff00ff)

    gdimage-pack

    (pack img x1 y1 ... xn yn )

    Function Type subr
    Arguments 1 to n pairs of [x,y] vertices coordinates
    Return Value a binary block object
    Description returns a binary block containing an array of 2n integers of 32 bits length, suitable for passing vertices coordinates to the polygon functions of the GD library;

    uses GD coordinates
    Example (pack img 10 10 20 10 20 20 10 20 10 10)

    gdimage-pendown

    (pendown img )

    Function Type subr
    Arguments a gdimage object
    Return Value nil
    Description sets the pen down so that any further movement of the pen will draw
    Example (pendown img)

    gdimage-penup

    (penup img )

    Function Type subr
    Arguments a gdimage object
    Return Value nil
    Description sets the pen up so that any further movement of the pen will not draw
    Example (penup img)

    gdimage-polygon

    (polygon img xy-pairs color )

    Function Type subr
    Arguments a gdimage object, a list of scalar x and scalar y pairs, an integer or unsignedinteger for colorindex or RGB
    Return Value nil
    Description draws a closed polygon on the gdimage object; the vertices are determined by the second argument which is a list of pairs of coordinates; the polygon is drawn with the selected color;

    uses GD coordinates
    Example (polygon img '(10 10 20 10 20 20 10 20) 0xff00ff)

    gdimage-pos

    (pos img )

    Function Type subr
    Arguments a gdimage object
    Return Value a list of two floats
    Description returns the current [x,y] position of the turtle;

    uses Turtle coordinates;
    Example (pos img)

    gdimage-rectangle

    (rectangle img x1 y1 x2 y2 color )

    Function Type subr
    Arguments a gdimage object, four scalars, an integer or unsignedinteger for colorindex or RGB
    Return Value nil
    Description draws a rectangle on the gdimage object; the upper-left and lower-right vertices are determined by the second up to fifth arguments; the rectangle is drawn with the selected color;

    uses GD coordinates
    Example (rectangle img 10 10 100 50 0xff00ff)

    gdimage-resize

    (resize img w h )

    Function Type subr
    Arguments a gdimage object, an integer w, an integer h
    Return Value a gdimage object
    Description returns a new gdimage with the new width and height dimensions given as argument; the image is streched or compressed accordingly if needed; the original image is unchanged
    Example (resize img 100 50)

    gdimage-right

    (right img angle )

    Function Type subr
    Arguments a gdimage object, a scalar
    Return Value nil
    Description makes the turtle-pen to turn to the right of an angle given by the second argument; the angle is in degrees; the current heading is changed;

    uses Turtle coordinates
    Example (right img 45.0)

    gdimage-rightcurve

    (rightcurve img angle radius )

    Function Type subr
    Arguments a gdimage object, a scalar, a scalar
    Return Value nil
    Description makes the turtle-pen draw a curve winding to the right starting from the current position and orientation and finishing in a new position and with a new orientation; the curve is drawn to the right if the radius argument is positive; if it is zero or negative, the function degenerates to (right); the angle argument in degrees defines altogether the arc drawn and the angle between the new direction and the original direction;

    uses Turtle coordinates
    Example (turn img 90.000000 10)

    gdimage-rotate

    (rotate img angle ... argn )

    Function Type subr
    Arguments a gdimage object, a float angle, keywords
    Return Value a gdimage object
    Description returns a new gdimage object containing the image given as argument rotated clockwise of the angle in degrees given as second argument;the size of the new image will be the rectangular enveloppe of the rotated image

    the keyword 'transparent indicates that the new image must have a transparent background;
    Example (rotate img 45.000000 'transparent)

    gdimage-setbrush

    (setbrush img img2 )

    Function Type subr
    Arguments a gdimage object, a gdimage object
    Return Value nil
    Description sets the gdimage given as second argument as the brush; from then on, lines and shapes will be drawn using elements of the brush image as pixels values
    Example (setbrush img1 img2)

    gdimage-setcolor

    (setcolor img r g b )

    Function Type subr
    Arguments a gdimage object, a scalar, a scalar, a scalar
    Return Value nil
    Description allocates a color into the gdimage object and returns the color index; sets the object's property 'lastcolor; if the object is in true color, returns the RGB value of the color
    Example (setcolor img 0xff 0x0 0xff)

    gdimage-setheading

    (setheading img angle )

    Function Type subr
    Arguments a gdimage object, a scalar
    Return Value nil
    Description sets a new heading for the turtle-pen; a heading of 0.000000 orients the turtle towards the north on the image;

    uses Turtle coordinates
    Example (setheading img 0.0)

    gdimage-sethome

    (sethome img x y )

    Function Type subr
    Arguments a gdimage object, scalar x, scalar y
    Return Value a list of integers
    Description sets a new position in GD coordinates for the Turtle's home; for the Turtle, the home is always at [0,0] in Turtle's coordinates but the absolute position of the home can be placed anywhere on the image, at the desired GD coordinates; the function returns the old coordinates as a list
    Example (sethome img 50 50)

    gdimage-setpixel

    (setpixel img x y color )

    Function Type subr
    Arguments a gdimage object, a pair of scalars, an integer or unsigned integer colorindex or RGB value
    Return Value nil
    Description sets the pixel at the [x,y] coordinates given by the second and third arguments to the color or colorindex given by the fourth argument;

    uses GD coordinates
    Example (setpixel img 10 10 0xffffff)

    gdimage-setpos

    (setpos img pos )

    Function Type subr
    Arguments a gdimage object, a list of a pair of scalars x y
    Return Value nil
    Description sets the current position of the turtle to [x,y] while drawing if the pen is down;

    uses Turtle coordinates
    Example (setpos img '(10 10))

    gdimage-setthickness

    (setthickness img thickness )

    Function Type subr
    Arguments a gdimage object, an integer thickness
    Return Value nil
    Description sets the thickness of the brush or pen to the number of pixels passed as second argument
    Example (setthickness img 10)

    gdimage-setx

    (setx img x )

    Function Type subr
    Arguments a gdimage object, scalar x
    Return Value nil
    Description moves the turtle laterally to a new X position, while drawing if the pen is down;

    uses Turtle coordinates
    Example (setx img 0)

    gdimage-setxy

    (setxy img x y )

    Function Type subr
    Arguments a gdimage object, scalar x, scalar y
    Return Value nil
    Description moves the turtle-pen to a new [x,y] position while drawing if the pen is down;

    uses Turtle coordinates
    Example (setxy img 10 10)

    gdimage-sety

    (sety img y )

    Function Type subr
    Arguments a gdimage object, scalar y
    Return Value nil
    Description moves the turtle vertically to a new Y position, while drawing if the pen is down;

    uses Turtle coordinates
    Example (sety img 0)

    gdimage-towards

    (towards img pos )

    Function Type subr
    Arguments a gdimage object, a list of a pair of scalars x, y
    Return Value a float
    Description returns the heading which points towards the position given as second argument, from the current position of the turtle;

    uses Turtle coordinates;
    Example (towards img '(10 10))

    gdimage-writeanimatedgif

    (writeanimatedgif img file imglist arg1 ... argn )

    Function Type subr
    Arguments a gdimage object, a stream or string, a list of gdimage objects, a series of optional keywords with their values
    Return Value nil
    Description creates an animated gif from the images given in the list as second argument; the first image of the list is a repetition of the object passed as first argument; the third and further arguments are keywords followed by their values;

    the keyword 'globalcm followed by an integer value from -1 to 1 indicates if a global colormap must be used or if a colormap must be held for each image, or the default is chosen, which is also global;

    the keyword 'loops followed by a positive integer indicates how many cycle the image list must be shown;default is 0 which is infinite loop

    the keyword 'delay followed by a positive integer greater or equal than 4, indicates the delay between frames in 100th of seconds; default i 4 which is equal to 25 frames per seconds;
    Example (writeanimatedgif img "myfile.gif" list1 'loops 5 'delay 10)

    gdimage-writegif

    (writegif img file )

    Function Type subr
    Arguments a gdimage object, a string or stream
    Return Value nil
    Description creates a gif file in the stream passed as second argument
    Example (writegif img "myfile.gif")

    gdimage-writejpeg

    (writejpeg img file )

    Function Type subr
    Arguments a gdimage object, a string or a stream
    Return Value nil
    Description creates a jpeg file in the stream passed as second argument
    Example (writejpeg img "myfile.jpeg")

    gdimage-writepng

    (writepng img file )

    Function Type subr
    Arguments a gdimage object, a string or a stream
    Return Value nil
    Description the function creates a png file in the stream passed as second argument
    Example (writepng img "myfile.png")

    gdimage-xabs

    (xabs img )

    Function Type subr
    Arguments a gdimage object
    Return Value a float
    Description returns the current turtle position x in GD coordinates
    Example (xabs img)

    gdimage-xcor

    (xcor img )

    Function Type subr
    Arguments a gdimage object
    Return Value a float
    Description returns the current turtle position x in turtle coordinates
    Example (xcor img)

    gdimage-yabs

    (yabs img )

    Function Type subr
    Arguments a gdimage object
    Return Value a float
    Description returns the current turtle position y in GD coordinates
    Example (yabs img)

    gdimage-ycor

    (ycor img )

    Function Type subr
    Arguments a gdimage object
    Return Value a float
    Description returns the current turtle position y in turtle coordinates
    Example (ycor img)
    Updated 08/11/2008 Copyright © 2008 Walther Waeles
    SourceForge.net Logo