You Are Here

ILib

About Ilib

What is it?

Ilib is a library (and some tools and examples) written in C that can read, create, manipulate and save images. It is capable of using X11 BDF fonts for drawing text. (X11 BDF fonts are part of the UNIX-based X11 Windows System, original developed at MIT in the early 1990s.) That means you get lots (208, to be exact) of fonts to use. You can even create your own if you know how to create an X11 BDF font. It can read and write PPM, XPM, GIF, PNG and JPG image format.

There is a Perl module included with the distribution. It does not yet support the complete Ilib API, but it’s a start

What can I use it for?

It’s great for generating graphs and creating GIF output from CGIs. There are also some useful applications bundled with it. For example, there’s a tool for generating index images (aka “thumbnails”). See the Screenshots to see what the output looks like.

What platforms does it run on?

It is portable enough to work with the old K&R C compilers and it will compile under ANSI C. It has been compiled and run on both UNIX and Windows 95/98/2000/NT/XP (MS Visual C++ and win32 gcc).

What image formats does it support?

It natively supports PGM, PPM, PAM and XPM. With optional external libraries it supports other formats as outlined in the table below.

FormatReadWrite
PAMYesYes
PPM (raw)YesYes
PPM (ascii)NoYes
PGM (raw)YesYes
BMPYesNo
XPMYesYes
GIF87Yes1Yes1
GIF89aYes1Yes1
PNGYes2Yes2
JPEGYes3Yes3

1With optional Giflib/Libungif 
2With optional libpng (does not support writing colormapped images) 
3With optional libjpeg

Who can use it?

Anyone. Just follow the guidelines of the GNU General Public License.

Is it hard to use?

It’s fairly simple to use. Here’s a simple program to fill a rectangle, draw some lines and then some text: sample.c.

The API is available online.

What’s the latest version?

Version 1.1.9 was released on 25 Oct 2004.

Support

For Ilib support, the following resources are available on Github:

Screenshots

Here are some sample images from the included client applications ifontdisplay (displays X11 BDF font), ifraggraph (graph of QuakeWorld efficiency over time), iwebreprt (displays web server usage), and iindex (displays thumbnails of images):

ILib Image Index Example
ILib Web Report Example
ILib Frag Graph
ILib Font ncenR14

Downloads

The most recent public release is version 1.1.9.

Source code has been transitioning from SourceForge.net to github. Go to the github page to download the source or checkout the repo from the git repo:

https://github.com/craigk5n/ilib

You can download a zip of the latest code in git from:

https://github.com/craigk5n/ilib/archive/master.zip

You can clone the git repo with:

git clone https://github.com/craigk5n/ilib.git

Ilib can make use of any properly formatted BDF font file. XFree86 used to provide BDF font files on their ftp server; however, they don’t seem to be there anymore. I’d suggest searching Google.

Competing Libraries

Below is a list of libraries that offer similar functionality to Ilib.

API

IAllocColor

IColor IAllocColor ( unsigned int red, unsigned int green, unsigned int blue )

Allocates a color to be used for drawing. (See ISetForeground).

Returns: IColor

Input Parameters:

  • unsigned int red – red value (0-255)
  • unsigned int green – green value (0-255)
  • unsigned int blue – blue value (0-255)

IAllocNamedColor

IError IAllocNamedColor ( char *colorname, IColor *color_ret )

Allocates a color by name (i.e. “blue”) to be used for drawing. (See ISetForeground).

Returns: IError

Input Parameters:

  • char *colorname – color name (“red, “orange”, etc.)
  • IColor *color_ret – resulting color

IArcProperties

IError IArcProperties ( IGC gc, int x, int y, int r1, int r2, double a1, double a2, int *a1_x, int *a1_y, int *a2_x, int *a2_y, int *middle_x, int *middle_y )

Determines the x-y coordinates of the starting, stopping and middle point of an arc. Any of the pointers may be NULL if you’re not interested in obtaining the value.

Returns: IError

Input Parameters:

  • IGC gc – graphics context
  • int x – arc center x coordinate
  • int y – arc center y coordinate
  • int r1 – angle 1 radius
  • int r2 – angle 2 radius
  • double a1 – first angle (in degrees)
  • double a2 – second angle (in degrees)

Output Parameters:

  • int *a1_x – x coordinate of edge of angle 1
  • int *a1_y – y coordinate of edge of angle 1
  • int *a2_x – x coordinate of edge of angle 2
  • int *a2_y – y coordinate of edge of angle 2
  • int *middle_x – x coordinate of edge center
  • int *middle_y – y coordinate of edge center

ICopyImage

IError ICopyImage ( IImage source, IImage dest, IGC gc, int src_x, int src_y, unsigned int width, unsigned int height, int dest_x, int dest_y )

Copies all or part of one image onto another image at a specified coordinate.

Returns: IError

Input Parameters:

  • IImage source – source image
  • IImage dest – destination image
  • IGC gc – graphics context
  • int src_x – x from source image
  • int src_y – y from source image
  • unsigned int width – width to copy
  • unsigned int height – height to copy
  • int dest_x – x coordinate on the destination image
  • int dest_y – y coordinate on the destination image

ICopyImageScaled

IError ICopyImageScaled ( IImage source, IImage dest, IGC gc, int src_x, int src_y, unsigned int src_width, unsigned int src_height, int dest_x, int dest_y, unsigned int dest_width, unsigned int dest_height )

Copies all of an image to another image by scaling it to fit.

Returns: IError

Input Parameters:

  • IImage source – source image
  • IImage dest – destination image
  • IGC gc – graphics context
  • int src_x – x from source image
  • int src_y – y from source image
  • unsigned int src_width – width of source image to copy
  • unsigned int src_height – height of source image to copy
  • int dest_x – x coordinate on the destination image
  • int dest_y – y coordinate on the destination image
  • unsigned int dest_width – width to copy to
  • unsigned int dest_height – height to copy to

ICreateGC

IGC ICreateGC ( )

Creates a graphic context for drawing on an image.

Returns: IGC

Input Parameters:

ICreateImage

IImage ICreateImage ( unsigned int width, unsigned int height, unsigned int options )

Create a blank (white) image of a specified width and height.

Returns: IImage

Input Parameters:

  • unsigned int width – image width
  • unsigned int height – image height
  • unsigned int options – options flags (IOPTION_GREYSCALE, etc.)

IDrawArc

IError IDrawArc ( IImage image, IGC gc, int x, int y, int r1, int r2, double a1, double a2 )

Draws an arc onto the image using the graphic context’s current line style ( see ISetLineStyle). In order to draw an arc that passes over 0 degrees, the first angle (a1) should be negative and the second angle (a2) should be positive.

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x – arc center x coordinate
  • int y – arc center y coordinate
  • int r1 – angle 1 radius
  • int r2 – angle 2 radius
  • double a1 – first angle (in degrees)
  • double a2 – second angle (in degrees)

IDrawCircle

IError IDrawCircle ( IImage image, IGC gc, int x, int y, int r )

Draws a circle onto the image using the graphic context’s current line style ( see ISetLineStyle).

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x – circle center x coordinate
  • int y – circle center y coordinate
  • int r – circle radius

IDrawEllipse

IError IDrawEllipse ( IImage image, IGC gc, int x, int y, int r1, int r2 )

Draws an ellipse onto the image using the graphic context’s current line style ( see ISetLineStyle).

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x – ellipse center x coordinate
  • int y – ellipse center y coordinate
  • int r1 – x radius
  • int r2 – y radius

IDrawEnclosedArc

IError IDrawEnclosedArc ( IImage image, IGC gc, int x, int y, int r1, int r2, double a1, double a2 )

Draws an arc and connects the arc to the center point using the graphic context’s current line style ( see ISetLineStyle). This function is intended to be used drawing pie charts. In order to draw an arc that passes over 0 degrees, the first angle (a1) should be negative and the second angle (a2) should be positive.

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x – arc center x coordinate
  • int y – arc center y coordinate
  • int r1 – angle 1 radius
  • int r2 – angle 2 radius
  • double a1 – first angle (in degrees)
  • double a2 – second angle (in degrees)

IDrawLine

IError IDrawLine ( IImage image, IGC gc, int x1, int y1, int x2, int y2 )

Draws a line onto the image using the graphics context’s current line style ( see ISetLineStyle).

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x1 – 1st coordinate
  • int y1 – 1st coordinate
  • int x2 – 2nd coordinate
  • int y2 – 2nd coordinate

IDrawPoint

IError IDrawPoint ( IImage image, IGC gc, int x, int y )

Draws a single point on the image.

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x – x coordinate
  • int y – y coordinate

IDrawPolygon

IError IDrawPolygon ( IImage image, IGC gc, IPoint *points, int npoints )

Draws a polygon onto the image using the graphics context’s current line style ( see ISetLineStyle).

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • IPoint *points – array of points
  • int npoints – size of above array

IDrawRectangle

IError IDrawRectangle ( IImage image, IGC gc, int x, int y, unsigned int width, unsigned int height )

Draws a rectangle onto the image of the specified width and height using the graphic context’s current line stlye ( see ISetLineStyle).

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x – x coordinate
  • int y – y coordinate
  • unsigned int width – width
  • unsigned int height – height

IDrawString

IError IDrawString ( IImage image, IGC gc, int x, int y, char *text, unsigned int len )

Draws text onto the image at the specified coordinate. See the font definition file to determine which characters are supported.
Note: the font is set with ISetFont.

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x – x coordinate (lower left of text)
  • int y – y coordinate (lower left of text)
  • char *text – pointer to text
  • unsigned int len – length of text

IDrawStringRotated

IError IDrawStringRotated ( IImage image, IGC gc, int x, int y, char *text, unsigned int len, ITextDirection direction )

Draws text onto the image at the specified coordinate using one of the angles: ITEXT_LEFT_TO_RIGHT, ITEXT_TOP_TO_BOTTOM, or ITEXT_BOTTOM_TO_TOP. See the font definition file to determine which characters are supported.
Note: the font is set with ISetFont. The x-y coordinates always specify the starting point to draw from (the lower left spot of the first character). For example, for ITEXT_TOP_TO_BOTTOM the x-y would represent the upper left area of the box where text will be drawn.

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x – x coordinate
  • int y – y coordinate
  • char *text – pointer to text
  • unsigned int len – length of text
  • ITextDirection direction – direction to draw text

IDrawStringRotatedAngle

IError IDrawStringRotatedAngle ( IImage image, IGC gc, int x, int y, char *text, unsigned int len, double angle )

Draws text onto the image at the specified coordinate using one the specified angle. This is slightly slower than IDrawStringRotated, so only use this function if you’re drawing something other than 90, 180, or 270 degrees. See the font definition file to determine which characters are supported.
Note: the font is set with ISetFont. The x-y coordinates always specify the starting point to draw from (the lower left spot of the first character).

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x – x coordinate
  • int y – y coordinate
  • char *text – pointer to text
  • unsigned int len – length of text
  • double angle – angle to rotate text

IDuplicateImage

IError IDuplicateImage ( IImage image, IImage *image_return )

Creates a duplicate of the original image.

Returns: IError

Input Parameters:

  • IImage image – image to duplicate

Output Parameters:

  • IImage *image_return – pointer to new image

IErrorString

char * IErrorString ( IError err )

Convert an IError value into text suitable for printing in an error message.

Returns: char *

Input Parameters:

  • IError err – error value

IFileType

IError IFileType ( char *file, IFileFormat *format_return )

Determine the type of image by the file extension.

Returns: IError

Input Parameters:

  • char *file – filename

Output Parameters:

  • IFileFormat *format_return – format of file

IFillArc

IError IFillArc ( IImage image, IGC gc, int x, int y, int r1, int r2, double a1, double a2 )

Fill an arc. In order to draw an arc that passes over 0 degrees, the first angle (a1) should be negative and the second angle (a2) should be positive.

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x – arc center x coordinate
  • int y – arc center y coordinate
  • int r1 – angle 1 radius
  • int r2 – angle 2 radius
  • double a1 – first angle (in degrees)
  • double a2 – second angle (in degrees)

IFillCircle

IError IFillCircle ( IImage image, IGC gc, int x, int y, int r )

Fill a circle.

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x – arc center x coordinate
  • int y – arc center y coordinate
  • int r – radius

IFillEllipse

IError IFillEllipse ( IImage image, IGC gc, int x, int y, int r1, int r2 )

Fill an ellipse.

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x – arc center x coordinate
  • int y – arc center y coordinate
  • int r1 – angle 1 radius
  • int r2 – angle 2 radius

IFillPolygon

IError IFillPolygon ( IImage image, IGC gc, IPoint *points, int npoints )

Fill a polygon. Only convex, non-intersecting polygons are supported. Invalid polygons will return an error.

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • IPoint *points – array of points
  • int npoints – size of above array

IFillRectangle

IError IFillRectangle ( IImage image, IGC gc, int x, int y, unsigned int width, unsigned int height )

Fills a rectangle on the image using the graphics context’s foreground color (see ISetForeground).

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x – x coordinate
  • int y – y coordinate
  • unsigned int width – width
  • unsigned int height – height

IFloodFill

IError IFloodFill ( IImage image, IGC gc, int x, int y )

Flood fill an area.

Returns: IError

Input Parameters:

  • IImage image – image
  • IGC gc – graphics context
  • int x – x coordinate starting point
  • int y – y coordinate starting point

IFontSize

IError IFontSize ( IFont font, unsigned int *height_return )

Gets the pixel height of the font. (See ITextHeight for calculating the height of a multiline text.)

Returns: IError

Input Parameters:

  • IFont font – font

Output Parameters:

  • unsigned int *height_return – height in pixels of font

IFreeColor

IError IFreeColor ( IColor color )

Frees a color no longer in use.

Returns: IError

Input Parameters:

  • IColor color – color

IFreeFont

IError IFreeFont ( IFont font )

Frees a font no longer in use.

Returns: IError

Input Parameters:

  • IFont font – font to free

IFreeGC

IError IFreeGC ( IGC gc )

Frees a graphic context no longer in use.

Returns: IError

Input Parameters:

  • IGC gc – graphics context

IFreeImage

IError IFreeImage ( IImage image )

Frees the memory associated with an image that will not be used again.

Returns: IError

Input Parameters:

  • IImage image – pointer to image

IGetComment

IError IGetComment ( IImage image, char **comment )

Get the comment (if there is one).

Returns: IError

Input Parameters:

  • IImage image – pointer to image
  • char **comment – address to comment

IGetTransparent

IError IGetTransparent ( IImage image, IColor *color )

Get the transparent color of the image. If there is no transparent image set, then INoTransparentColor is returned.

Returns: IError

Input Parameters:

  • IImage image – image
  • IColor *color – returned color

ILoadFontFromData

IError ILoadFontFromData ( char *name, char **lines, IFont *font_return )

Loads a font from data passed in. This is identical to ILoadFontFromFile except the font data is passed in as an argument rather than a file. This allows the font to be embedded in the application rather than distributed as a separate file.

Returns: IError

Input Parameters:

  • char *name – name to use for reference (filename)
  • char **lines – font data (identical to file contents) as an array of character strings (one text line per array element terminated with a NULL element

Output Parameters:

  • IFont *font_return – pointer to returned font

ILoadFontFromFile

IError ILoadFontFromFile ( char *name, char *path, IFont *font_return )

Load a font from file. Currently, only BDF font files can be used. BDF font files can be found at: ftp://ftp.x.org/pub/R6.1/xc/fonts/bdf/75dpi/. (BDF fonts are part of the X11 Window System developed at MIT and used on almost all UNIX workstations.)

Returns: IError

Input Parameters:

  • char *name – name to use for reference (filename)
  • char *path – path to font file

Output Parameters:

  • IFont *font_return – returned font

IReadImageFile

IError IReadImageFile ( FILE *fp, IFileFormat format, IOptions options, IImage *image_return )

Creates an image from an image file. Currently can read raw PPM (IFORMAT_PPM), raw PGM (IFORMAT_PGM), XPM (IFORMAT_XPM), BMP (IFORMAT_BMP), GIF (IFORMAT_GIF), PNG (IFORMAT_PNG), and JPEG (IFORMAT_JPEG) files. The file is left open for the caller to close. (Note: you should set the file to binary mode on Win32 platforms by using something like:
   file = fopen ( filename, "rb" );

Returns: IError

Input Parameters:

  • FILE *fp – file pointer
  • IFileFormat format – output format (e.g. IFORMAT_GIF)
  • IOptions options – options

Output Parameters:

  • IImage *image_return – returned image on success

ISetBackground

IError ISetBackground ( IGC gc, IColor color )

Set the background color of a graphics context. This will affect colors when using text styles.

Returns: IError

Input Parameters:

  • IGC gc – graphics context
  • IColor color – color

ISetComment

IError ISetComment ( IImage image, char *comment )

Set the comment.

Returns: IError

Input Parameters:

  • IImage image – pointer to image
  • char *comment – new comment

ISetFont

IError ISetFont ( IGC gc, IFont font )

Sets the current drawing font for a graphics context. Subsequent calls to IDrawString will use the specified font.

Returns: IError

Input Parameters:

  • IGC gc – graphics context
  • IFont font – font

ISetForeground

IError ISetForeground ( IGC gc, IColor color )

Set the foreground color of a graphics context. This will set the drawing color for drawing functions (IDrawLine, IFillRectangle, etc.)

Returns: IError

Input Parameters:

  • IGC gc – graphics context
  • IColor color – color

ISetLineStyle

IError ISetLineStyle ( IGC gc, ILineStyle line_style )

Sets the current line drawing style for a graphics context. Currently support ILINE_SOLID (default) and ILINE_ON_OFF_DASH. (This applies to IDrawLine and IDrawRectangle.)

Returns: IError

Input Parameters:

  • IGC gc – graphics context
  • ILineStyle line_style – line style

ISetLineWidth

IError ISetLineWidth ( IGC gc, unsigned int line_width )

Sets the line drawing with for a graphics context. (This applies to IDrawLine and IDrawRectangle.)

Returns: IError

Input Parameters:

  • IGC gc – graphics context
  • unsigned int line_width – line width

ISetTextStyle

IError ISetTextStyle ( IGC gc, ITextStyle text_style )

Sets the curret text drawing style for a graphics context. Supported styles are:

  • ITEXT_NORMAL – default (no effects)
  • ITEXT_ETCHED_IN – draw text etched into background (does not use foreground color, just background)
  • ITEXT_ETCHED_OUT – draw text etched out of background (does not use foreground color, just background)
  • ITEXT_SHADOWED – draw text with a dark shadow to the lower left of the text.
(This applies to IDrawString and IDrawStringRotated.)

Returns: IError

Input Parameters:

  • IGC gc – graphics context
  • ITextStyle text_style – text style

ISetTransparent

IError ISetTransparent ( IImage image, IColor color )

Set the transparent color of the image. This is only relevant to images that are written to either GIF or XPM formats.

Returns: IError

Input Parameters:

  • IImage image – image
  • IColor color – color

ITextDimensions

IError ITextDimensions ( IGC gc, IFont font, char *text, unsigned int len, unsigned int *width_return, unsigned int *height_return )

Determines the width & height (in pixels) of the given text for the specified font. (useful for multiline text)

Returns: IError

Input Parameters:

  • IGC gc – graphics context
  • IFont font – font
  • char *text – text
  • unsigned int len – length of text

Output Parameters:

  • unsigned int *width_return – width in pixels of text
  • unsigned int *height_return – height in pixels of text

ITextHeight

IError ITextHeight ( IGC gc, IFont font, char *text, unsigned int len, unsigned int *height_return )

Determines the height (in pixels) of the given text for the specified font. This is useful for multiline text.

Returns: IError

Input Parameters:

  • IGC gc – graphics context
  • IFont font – font
  • char *text – text
  • unsigned int len – length of text

Output Parameters:

  • unsigned int *height_return – height in pixels of text

ITextWidth

IError ITextWidth ( IGC gc, IFont font, char *text, unsigned int len, unsigned int *width_return )

Determines the length (in pixels) of the given text for the specified font.

Returns: IError

Input Parameters:

  • IGC gc – graphics context
  • IFont font – font
  • char *text – text
  • unsigned int len – length of text

Output Parameters:

  • unsigned int *width_return – width in pixels of text

IWriteImageFile

IError IWriteImageFile ( FILE *fp, IImage image, IFileFormat format, IOptions options )

Writes an image to a file. Currently supports writing PPM (IFORMAT_PPM), PGM (IFORMAT_PGM), PAM (IFORMAT_PAM), XPM (IFORMAT_XPM), GIF (IFORMAT_GIF), PNG (IFORMAT_PNG) and JPEG (IFORMAT_JPEG) formats. The file is left open for the caller to close. (Note: you should set the file to binary mode on Win32 platforms.)

Returns: IError

Input Parameters:

  • FILE *fp – file pointer
  • IImage image – image
  • IFileFormat format – output format (e.g. IFORMAT_XPM)
  • IOptions options – options (e.g. IOPTION_INTERLACED)

FAQ

Last updated: 8 March 2004

Where can I get libpng?

Libpng is available at:

http://www.libpng.org/pub/png/libpng.html

Where can I get giflib/libungif?

Libungif is identical to Giflib except that it does not include the questionable LZW compression that Unisys owns the rights to. Images generated with Libungif will be uncompressed (larger). Libungif 4.X is available at:

http://gnuwin32.sourceforge.net/packages/libungif.htm

Giflib 4.X is available at:

http://www.catb.org/~esr/giflib/frontpage.html

Can I build Ilib with MS Visual Developer Studio?

Yes, it has been successfully built using MS Developer Studio on Windows NT. You must setup your own project for this.

Can I build Ilib with Cygnus’ Win32 GCC?

Yes, you can. However, you will also have to use GCC to build your application and you will need to distribute the required Cygnus runtime DLLs with it.

I get a bunch of X11-related link errors. What’s that all about?

Version 4.X of Giflib/Libungif requires you to add -lX11 to LIBS and all the makefiles. (Version 3.X did not require this.) You can get around this by building Giflib/Libungif without support for X11. (Try configure --help when building Giflib/Libungif for information on how to do this.)

What’s the purpose of the ifont2h utility?

The ifont2h utility allow you to embed a font within the application’s executable so that you do not need to distribute the BDF font file with the executable.

How can I create my own fonts??

There is likely more than one way to do this. However, you can try the font editor from the following site (requires Tk/Tcl). It allows you to either edit or create X11 BDF fonts.

http://hea-www.harvard.edu/~fine/Tech/bdfedit.html

Do you accept patches/modifications?

You bet… Just email any patches to cknudsen@cknudsen.com.

What are some of the features that can be added?

See the Plans page.

2 thoughts on “ILib”

    1. From your command line (Windows shell, linux terminal, etc.):

      git clone https://github.com/craigk5n/ilib.git

      You’ll need to have git installed before you can do that.

      Reply

Leave a Reply

Your email address will not be published. Required fields are marked *