PNGwriter Manual

PNGwriter Quick Reference Manual

Version 0.5.3 (24/ I / 2005)

http://pngwriter.sourceforge.net/

. . . . . . . . . . Introduction . . . . . . . . . .

This is the PNGwriter Quick Reference Manual. It is mostly a summary of the functions that PNGwriter provides, but also contains useful information on compilation and usage tips. Note that the pngwriter.h header file is also well commented. Be sure to look at the Examples section on the website, and to check the examples in /usr/local/share/doc/pngwriter/.

Note: This document assumes that PNGwriter was installed in /usr/local (in /usr/local/lib, /usr/local/share, etc.). This is the default location. If you chose another installation location, then please keep this in mind as you read the Manual. This is important for knowing what header and library directories you must include at compile time, where the documentation and examples are, where the included fonts are, etc. For example, if you installed PNGwriter from the Debian package, it is installed under /usr (in /usr/lib, /usr/share, etc.). Or if when installing from source, you gave the command make install PREFIX=$HOME for example, where $HOME is the path to your home directory, you'll find PNGwriter's files installed under $HOME/lib, $HOME/share, etc.

. . . . . . . . . . Summary . . . . . . . . . .

PNGwriter is a very easy to use open source graphics library that uses PNG as its output format. The interface has been designed to be as simple and intuitive as possible. It supports plotting and reading in the RGB (red, green, blue), HSV (hue, saturation, value/brightness) and CMYK (cyan, magenta, yellow, black) colour spaces, basic shapes, scaling, bilinear interpolation, full TrueType antialiased and rotated text support, bezier curves, opening existing PNG images and more. Documentation in English and Spanish. Runs under Linux, Unix, Mac OS X and Windows. Requires libpng and optionally FreeType2 for the text support.

. . . . . . . . . . Contents . . . . . . . . . .

This document is divided into the following main sections:

- General Notes

- Constructor and assignment operator

- Plotting

- Reading

- Figures

- Text

- Image Size

- File and PNG-specific functions

. . . . . . . . . . Help and Support . . . . . . . . . .

If you have a problem, question or suggestion, you can post to or join the PNGwriter mailing list. I'd suggest the latter, since that way my response will reach you immediately and you will remain up to date on new PNGwriter releases. You can also email me directly.

PNGwriter's documentation consists of this PDF Manual, the README, the pngwriter.h header file, the two complete examples included with the source code, and of course, the website, which contains a Frequently Asked Questions section and quite a few interesting examples, among other things.

. . . . . . . . . . General Notes . . . . . . . . . .

Basic Usage

The most basic use of PNGwriter would be the following:

#include <pngwriter.h>

int main()

{

pngwriter image(200, 200, 1.0, "out.png");

image.plot(30, 40, 1.0, 0.0, 0.0);

image.close();

return 0;

}

This would plot a red dot (1 pixel) in the lower-left corner of the image, on a white background. The file created will be called "out.png".

To get started, read about the constructor, plot(), dread() and close(). Explore the other functions when you feel confident with these.

It is important to remember that all functions that accept an argument of type "const char *" will also accept "char *". This is done so you can have a changing filename (to make many PNG images in series with a different name, for example), and to allow you to use string type objects which can be easily turned into const char * (if theString is an object of type string, then it can be used as a const char * by calling theString.c_str()).

It is also important to remember that whenever a function has a colour coeffiecient as its argument, that argument can be either an int from 0 to 65535 or a double from 0.0 to 1.0. You must make sure that you are calling the function with the type that you want. Remember that 1 is an int, while 1.0 is a double, and will thus determine what version of the function will be used. Do not make the mistake of calling (for example) plot(x, y, 0.0, 0.0, 65535), because there is no plot(int, int, double, double, int). Also, please note that plot() and read() (and the functions that use them internally) are protected against entering, for example, a colour coefficient that is over 65535 or over 1.0. Similarly, they are protected against negative coefficients. read() will return 0 when called outside the image range. This is actually useful as zero-padding should you need it.

Compilation

A typical compilation, assuming PNGwriter was installed in its default location (under /usr/local) would look like this:

g++ my_program.cc -o my_program `freetype-config --cflags`

-I/usr/local/include -L/usr/local/lib -lpng -lpngwriter -lz -lfreetype

Otherwise, replace /usr/local above with whatever location you chose at install time.

If you did not compile PNGwriter with FreeType support, then remove the FreeType-related flags and add -DNO_FREETYPE above.

The website has additional information about compiling under Windows.

Constructor

The constructor requires the width and the height of the image, the background colour for the image and the filename of the file (a pointer or simply "myfile.png"). The default constructor creates a PNGwriter instance that is 250x250, white background, and filename "out.png". Tip: The filename can be given as easily as: pngwriter mypng(300, 300, 0.0, "myfile.png"); Tip: If you are going to create a PNGwriter instance for reading in a file that already exists, then width and height can be 1 pixel, and the size will be automatically adjusted once you use readfromfile().

pngwriter();

pngwriter(const pngwriter &rhs);

pngwriter(int width, int height, int backgroundcolour, char * filename);

pngwriter( int width, int height, double backgroundcolour, char * filename);

pngwriter( int width, int height, int backgroundcolour, const char * filename);

pngwriter( int width, int height, double backgroundcolour, const char * filename);

Assignment Operator

PNGwriter overloads the assignment operator =.

pngwriter & operator = (const pngwriter & rhs);

Version Number

Returns the PNGwriter version number.

double version(void);

. . . . . . . . . . Plotting . . . . . . . . . .

Plot

The pixels are numbered starting from (1, 1) and go to (width, height). If the colour coefficients are of type int, they go from 0 to 65535. If they are of type double, they go from 0.0 to 1.0. Tip: To plot using red, then specify plot(x, y, 1.0, 0.0, 0.0). To make pink, just add a constant value to all three coefficients, like this: plot(x, y, 1.0, 0.4, 0.4). Tip: If nothing is being plotted to your PNG file, make sure that you remember to close() the instance before your program is finished, and that the x and y position is actually within the bounds of your image. If either is not, then PNGwriter will not complain-- it is up to you to check for this! Tip: If you try to plot with a colour coefficient out of range, a maximum or minimum coefficient will be assumed, according to the given coefficient. For example, attempting to plot plot(x, y, 0.5,-0.2,3.7) will set the green coefficient to 0.0 and the blue coefficient to 1.0.

void plot(int x, int y, int red, int green, int blue);

void plot(int x, int y, double red, double green, double blue);

Plot Blend

Plots the colour given by red, green blue, but blended with the existing pixel value at that position. opacity is a double that goes from 0.0 to 1.0. For example, 0.0 will not change the pixel at all, and 1.0 will plot the given colour. Anything in between will be a blend of both pixel levels.

void plot_blend( int x, int y, double opacity,

int red, int green, int blue);

void plot_blend( int x, int y, double opacity,

double red, double green, double blue);

Blended Functions

All these functions are identical to their non-blended types. They take an extra argument, opacity, which is a double from 0.0 to 1.0 and represents how much of the original pixel value is retained when plotting the new pixel. In other words, if opacity is 0.7, then after plotting, the new pixel will be 30% of the original colour the pixel was, and 70% of the new colour, whatever that may be. As usual, each function is available in int or double versions.

void plotHSV_blend( int x, int y, double opacity,

double hue, double saturation, double value);

void plotHSV_blend( int x, int y, double opacity,

int hue, int saturation, int value);

void line_blend( int xfrom, int yfrom, int xto, int yto,

double opacity, int red, int green,int blue);

void line_blend( int xfrom, int yfrom, int xto, int yto,

double opacity, double red, double green,double blue);

void square_blend( int xfrom, int yfrom, int xto, int yto,

double opacity, int red, int green,int blue);

void square_blend( int xfrom, int yfrom, int xto, int yto,

double opacity, double red, double green, double blue);

void filledsquare_blend( int xfrom, int yfrom, int xto, int yto,

double opacity,

int red, int green,int blue);

void filledsquare_blend( int xfrom, int yfrom, int xto, int yto,

double opacity,

double red, double green,double blue);

void circle_blend( int xcentre, int ycentre, int radius,

double opacity, int red, int green, int blue);

void circle_blend( int xcentre, int ycentre, int radius,

double opacity, double red, double green, double blue);

void filledcircle_blend( int xcentre, int ycentre, int radius,

double opacity,

int red, int green, int blue);

void filledcircle_blend( int xcentre, int ycentre, int radius,

double opacity,

double red, double green, double blue);

void bezier_blend( int startPtX, int startPtY,

int startControlX, int startControlY,

int endPtX, int endPtY,

int endControlX, int endControlY,

double opacity,

double red, double green, double blue);

void bezier_blend( int startPtX, int startPtY,

int startControlX, int startControlY,

int endPtX, int endPtY,

int endControlX, int endControlY,

double opacity,

int red, int green, int blue);

void plot_text_blend( char * face_path, int fontsize,

int x_start, int y_start, double angle, char * text,

double opacity,

double red, double green, double blue);

void plot_text_blend( char * face_path, int fontsize,

int x_start, int y_start, double angle, char * text,

double opacity,

int red, int green, int blue);

void plot_text_utf8_blend(char * face_path, int fontsize,

int x_start, int y_start, double angle, char * text,

double opacity,

double red, double green, double blue);

void plot_text_utf8_blend(char * face_path, int fontsize,

int x_start, int y_start, double angle, char * text,

double opacity,

int red, int green, int blue);

void boundary_fill_blend(int xstart, int ystart,

double opacity,

double boundary_red, double boundary_green, double boundary_blue, double fill_red, double fill_green, double fill_blue);

void boundary_fill_blend(int xstart, int ystart,

double opacity,

int boundary_red, int boundary_green, int boundary_blue,

int fill_red, int fill_green, int fill_blue);

void flood_fill_blend( int xstart, int ystart, double opacity,

double fill_red, double fill_green, double fill_blue);

void flood_fill_blend( int xstart, int ystart, double opacity,

int fill_red, int fill_green, int fill_blue);

void polygon_blend(int * points, int number_of_points, double opacity,

double red, double green, double blue);

void polygon_blend(int * points, int number_of_points, double opacity,

int red, int green, int blue);

void plotCMYK_blend(int x, int y, double opacity,

double cyan, double magenta, double yellow, double black);

void plotCMYK_blend(int x, int y, double opacity,

int cyan, int magenta, int yellow, int black);

Plot HSV

With this function a pixel at coordinates (x, y) can be set to the desired colour, but with the colour coefficients given in the Hue, Saturation, Value colourspace.

void plotHSV(int x, int y, double hue, double saturation, double value);

void plotHSV(int x, int y, int hue, int saturation, int value);

Plot CMYK

Plot a point in the Cyan, Magenta, Yellow, Black colourspace. Please note that this colourspace is lossy, i.e. it cannot reproduce all colours on screen that RGB can. The difference, however, is barely noticeable. The algorithm used is a standard one. The colour components are either doubles from 0.0 to 1.0 or ints from 0 to 65535.

void plotCMYK( int x, int y,

double cyan, double magenta, double yellow, double black);

void plotCMYK( int x, int y,

int cyan, int magenta, int yellow, int black);

Clear

The whole image is set to black.

void clear(void);

Invert

Inverts the image in RGB colourspace.

void invert(void);

Boundary Fill

All pixels adjacent to the start pixel will be filled with the fill colour, until the boundary colour is encountered. For example, calling boundary_fill() with the boundary colour set to red, on a pixel somewhere inside a red circle, will fill the entire circle with the desired fill colour. If, on the other hand, the circle is not the boundary colour, the rest of the image will be filled. The colour components are either double from 0.0 to 1.0 or int from 0 to 65535.

void boundary_fill(int xstart, int ystart,

double boundary_red, double boundary_green, double boundary_blue,

double fill_red, double fill_green, double fill_blue);

void boundary_fill( int xstart, int ystart,

int boundary_red, int boundary_green, int boundary_blue,

int fill_red, int fill_green, int fill_blue) ;

Flood Fill

All pixels adjacent to the start pixel will be filled with the fill colour, if they are the same colour as the start pixel. For example, calling flood_fill() somewhere in the interior of a solid blue rectangle will colour the entire rectangle the fill colour. The colour components are either double from 0.0 to 1.0 or int from 0 to 65535.

void flood_fill( int xstart, int ystart,

double fill_red, double fill_green, double fill_blue);

void flood_fill( int xstart, int ystart,

int fill_red, int fill_green, int fill_blue) ;

Laplacian

This function applies a discrete laplacian to the image, multiplied by a constant factor. The kernel used in this case is:

1.0 1.0 1.0

1.0 -8.0 1.0

1.0 1.0 1.0

Basically, this works as an edge detector. The current pixel is assigned the sum of all neighbouring

pixels, multiplied by the corresponding kernel element. For example, imagine a pixel and its 8 neighbours:

1.0 1.0 1.0 0.0 0.0

1.0 1.0 ->1.0<- 0.0 0.0

1.0 1.0 1.0 0.0 0.0

This represents a border between white and black, black is on the right. Applying the laplacian to he pixel specified above pixel gives:

1.0*1.0 + 1.0*1.0 + 0.0*1.0 +

1.0*1.0 + 1.0*-8.0 + 0.0*1.0 +

1.0*1.0 + 1.0*1.0 + 0.0*1.0 = -3.0

Applying this to the pixel to the right of the pixel considered previously, we get a sum of 3.0. That is, after passing over an edge, we get a high value for the pixel adjacent to the edge. Since PNGwriter limits the colour components if they are off-scale, and the result of the laplacian may be negative, a scale factor and an offset value are included. This might be useful for keeping things within range or for bringing out more detail in the edge detection. The final pixel value will be given by:

final value = laplacian(original pixel)*k + offset

Tip: Try a value of 1.0 for k to start with, and then experiment with other values. Tip: It would be difficult to foresee all possible uses of this function, so please feel free to look at the source code and perhaps implement your own if it does not suit your needs.

void laplacian(double k, double offset);

. . . . . . . . . . Reading . . . . . . . . . .

Read

With this function we find out what colour the pixel (x, y) is. If "colour" is 1, it will return the red coefficient, if it is set to 2, the green one, and if it set to 3, the blue colour coefficient will be returned, and this returned value will be of type int and be between 0 and 65535.

int read(int x, int y, int colour);

Read, Average

Same as the above, only that the average of the three colour coefficients is returned.

int read(int x, int y);

dRead

Same as read(), but the returned value will be of type double and be between 0.0 and 1.0.

double dread(int x, int y, int colour);

dRead, Average

Same as the above, only that the average of the three colour coefficients is returned.

double dread(int x, int y);