Site icon k5n.us

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):

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:

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:

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:

Output Parameters:

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:

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:

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:

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:

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:

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:

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:

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:

IDrawPoint

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

Draws a single point on the image.

Returns: IError

Input Parameters:

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:

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:

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:

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:

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:

IDuplicateImage

IError IDuplicateImage ( IImage image, IImage *image_return )

Creates a duplicate of the original image.

Returns: IError

Input Parameters:

Output Parameters:

IErrorString

char * IErrorString ( IError err )

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

Returns: char *

Input Parameters:

IFileType

IError IFileType ( char *file, IFileFormat *format_return )

Determine the type of image by the file extension.

Returns: IError

Input Parameters:

Output Parameters:

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:

IFillCircle

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

Fill a circle.

Returns: IError

Input Parameters:

IFillEllipse

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

Fill an ellipse.

Returns: IError

Input Parameters:

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:

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:

IFloodFill

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

Flood fill an area.

Returns: IError

Input Parameters:

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:

Output Parameters:

IFreeColor

IError IFreeColor ( IColor color )

Frees a color no longer in use.

Returns: IError

Input Parameters:

IFreeFont

IError IFreeFont ( IFont font )

Frees a font no longer in use.

Returns: IError

Input Parameters:

IFreeGC

IError IFreeGC ( IGC gc )

Frees a graphic context no longer in use.

Returns: IError

Input Parameters:

IFreeImage

IError IFreeImage ( IImage image )

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

Returns: IError

Input Parameters:

IGetComment

IError IGetComment ( IImage image, char **comment )

Get the comment (if there is one).

Returns: IError

Input Parameters:

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:

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:

Output Parameters:

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:

Output Parameters:

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:

Output Parameters:

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:

ISetComment

IError ISetComment ( IImage image, char *comment )

Set the comment.

Returns: IError

Input Parameters:

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:

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:

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:

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:

ISetTextStyle

IError ISetTextStyle ( IGC gc, ITextStyle text_style )

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

(This applies to IDrawString and IDrawStringRotated.)

Returns: IError

Input Parameters:

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:

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:

Output Parameters:

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:

Output Parameters:

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:

Output Parameters:

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:

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.

Exit mobile version