[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. Overview

MathGL is ...


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Why I have written MathGL?

The code for making high-quality scientific graphics under Linux and Windows. The code for the fast handling and plotting of large data arrays. The code for working in window and console regimes and for easy including into another program. The code with large and renewal set of graphics. Exactly such code I was looking for during last years. Exactly such code I tried to realize in MathGL library.

At this version (1.9) MathGL has more than 20000 code strings, more than 40 general types of graphics for 1d, 2d and 3d data arrays. It can export graphics to bitmap and vector (EPS or SVG) files. It has OpenGL interface and can be used from console programs. It has functions for data handling and script MGL language for simplification of data plotting. Also it has several types of transparency and smoothed lightning, vector fonts and TeX-like symbol parsing, arbitrary curvilinear coordinate system and many over useful things (see pictures section at homepage). Finally it is a platform independent and free (under GPL v.2.0 or later license).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 MathGL features

MathGL can plot wide range of graphics. It includes:

In fact, I created functions for drawing of all scientific plots that I know. The list of plots is enlarging, so if you need some special type of plot then write me e-mail and it will appear in new version.

I tried to make plots as well-looking as possible: surface can be transparent and highlighted by several (up to 10) light sources. Most of drawing functions have 2 variants: simple one for the fast plotting of data, complex one for specifying of the exact position of plot (including parametric representation). Resulting image can be saved in bitmap (with the help of mglGraphZB, mglGraphGL) PNG, JPEG, TIFF, BMP format or in vector EPS or SVG format (with the help of mglGraphPS), or in IDTF format (with the help of mglGraphIDTF) which can be converted in U3D.

All text are drawn by vector font, that allows high scalability and portability. Text may contain commands for: some of TeX-like symbols, changing index (upper or lower indexes) and style of font inside the text string (see section mglFont class). Texts of ticks are rotated with axis rotation. It is possible to create a legend of plot and put text in arbitrary position of plot. An arbitrary text encoding (by help of function setlocale()) and UTF-16 encoding are supported.

Special mglData class is used for data encapsulation (see section mglData class). Except safe creation and deletion of data arrays it includes functions for data processing (smoothing, differentiating, integrating, interpolating and so on) and reading of data files with automatic size determination. Class mglData can handle arrays with up to three dimensions (arrays which depend up to 3 independent indexes a_ijk). Using an array with higher number of dimensions is not reasonable because I do not know how it can be plotted. Data filling and modifying may be fulfilled manually or by textual formulas.

Class mglFormula class allows the fast evaluation of a textual mathematical expression (see section mglFormula class). It is based on string precompilation to tree-like code at creation of class instance. At evaluation stage code performs only fast tree-walk and returns the value of the expression. Except changing data values, textual formulas are used for drawing in arbitrary curvilinear coordinates. A set of such curvilinear coordinates is limited only by user imagination but not a fixed list like polar, parabolic, spherical and so on.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Installation and using

MathGL can be installed by 3 ways.

  1. Compile from sources. The standard script for autoconf/automake tools is included in library beginning from version 1.2.1. For its running one should execute 3 commands: ./configure after it make and make install with root/sudo rights. Script ./configure have several additional options which is switched off by default. They are: --enable-fltk, --enable-glut, --enable-qt for ebabling FLTK, GLUT and/or Qt windows; --enable-jpeg, --enable-tiff, --enable-hdf5 for enabling corresponded file formats; --enable-all for enabling all additional features. The full list of options can be viewed by command ./configure --help.
  2. Use precompiled binary. There are binaries for MinGW (platform Win32). For precompiled variant one needs only to unpack the archive to the compiler location (or in any other folder and setup paths). By default precompiled versions include the support of GSL (www.gsl.org) and PNG. So, one needs to have these libraries installed on system.
  3. Install precompiled versions from standard packages (RPM, deb, DevPak and so on, see Download section at homepage).

At the own program compilation one needs to specify the linker key -lmgl for compilation in console program or with the external (not MathGL) window library. If one wants to use FLTK or GLUT windows then he needs to add the keys -lmgl-fltk or -lmgl-glut. Fortran users also should add C++ library by option -lstdc++.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 General concepts

The set of MathGL features is rather reach – just the number of basic graphics types is more than 40. Also there are functions for data handling, plot setup and so on. In spite of it I tried to keep the similar style in function names and in the order of arguments. Mostly it is regarded for different drawing functions.

There are six most general (base) concepts:

  1. Any picture is created in memory firstly. The internal (memory) representation can be different: bitmap picture or the list of vector primitives. After it user may decide what he want: save to file, display on the screen, run animation, do additional editing and so on. This approach provides high portability of the program – the source code will produce exactly the same picture in any OS. Another big positive consequence is the ability to create the picture in console program (without window creating)!
  2. Every plot settings (style of lines, font, color scheme) are specified by string. It provides convenience for user/programmer – short string with parameters is more comprehensible than a large set of parameters. Also it provides portability – the strings are the same in any OS so that it is not comprehensible to think about type of arguments.
  3. All functions have “simplified” and “advanced” forms. It is done for user convenience. One needs to specify the only one data array in “simplified” form and will see the result. But one may set parametric dependence of coordinates and produce rather complex curves and surfaces in “advanced” form. In both cases the order of function arguments are the same: firstly data arrays, secondly the string with plot parameters, and later optional arguments for plot tunning.
  4. All data arrays for plotting are encapsulated in class mglData class. It reduces the number of errors with memory working and provide the uniform interface for data of different types (float, double and so on) or for formulas plotting.
  5. All plots are vector plot. The MathGL library is intended for handling scientific data which have vectorial nature (there are lines, faces, matrices and so on). As result vectorial representation is used in any cases! In addition the vectorial representation allows one to scale easily the plot – change the canvas size by 2 times and the picture will proportionally scaled.
  6. New drawing never clears things drawn already. This, in some sense, is unexpected, idea allows to create a lot of “combined” graphics. For example, for making a surface with contour lines one need to call the function of surface plotting and the function of contour lines plotting (in any order). At this the special functions (as it done in Matlab and some other plotting system) for making this “combined” plots are useless. Much more examples of such plots can be found in section Hints and in home site (http://mathgl.sf.net/index.html).

Except general concept I want consider on some non-trivial or non-usual general ideas – plot positioning, axis specification and curvilinear coordinates, styles for lines, text and color scheme.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.1 Coordinate axes

There is twofold axes representation in MathGL. First one consists in normalizing of the data point coordinates in box MinxMax (see section Axis settings). If Cut is true then the outlied points are omitted otherwise they are projected to the bounding box (see section Cutting). Also, the point will be omitted if it lies inside the box defined by CutMinxCutMax or if the value of formula CutOff() is nonzero for its cooridnates. After it transformation formulas are applied to the data point (see section Transformation (curved coordinates)). Finally, the data point is plotted by one of function.

There is possibility to set members Max, Min directly but one should call RecalcBorder() function to setup plotting routines. The more safe way is to set these values by calling Axis() function. In this case the function RecalcBorder() is called automatically. Another way to specify the size of axis is to set it as a minimal or maximal value of data array. Functions XRange(), YRange(), ZRange() do it. The second (optional) argument sets to replace the axis range or to join with the existed range.

The axis origin is defined by variable Org and is applied for all consequent calls of axes or grid drawing. By default, if this point lies outside the bounding box then it is projected to the one (variable AutoOrg control it). In the case if one of values of Org is equal to NAN then the corresponding value will be selected automatically.

There is 4-th axis c (color axis or colorbar) in addition to usual axes x, y, z. It sets the range of values for the surface coloring. Its borders are automatically set to values of Min.z, Max.z during the call of Axis() function. Also, there are direct change of the color range by setting of variables Cmax, Cmax, or calling functions CAxis() or CRange(). Use Colorbar() function for showing the colorbar.

The form (appearence) of tick labels is controlled by SetTicks() function and few variables (see section Ticks). It have 3 arguments: first one d set the tick step (if positive) or tick number (if negative) or switch logarithmic ticks on (if zero); second one ns set the number of subticks; last one is the starting point for ticks (default is axis origin). The variable TuneTicks switches on/off ticks enhancing by the detaching of the common multiplier (for small, like from 0.001 to 0.002, or large, like from 1000 to 2000, coordinate values) or common component (for narrow range, like from 0.999 to 1.000). Finally, you may use variables xtt, ytt, ztt, ctt for setting templates for tick labels (it supports TeX symbols). Also, there is a possibility to print arbitrary text as tick labels if one defines the pointer (name) of function TickStr.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.2 Line styles

The line style is defined by the string which may contain specifications for color (‘wkrgbcymhRGBCYMHWlenupqLENUPQ’), dashing style (‘-|;:ji’ or space), width (‘0123456789’) and marks (‘o+xsd.^v’ and ‘#’ modifier). If one of type of information is omitted then default values with the previous color are used.

The color types are the same as described in mglColor class (see section mglColor class): ‘k’ – black, ‘r’ – red, ‘R’ – dark red, ‘g’ – green, ‘G’ – dark green, ‘b’ – blue, ‘B’ – dark blue, ‘c’ – cyan, ‘C’ – dark cyan, ‘m’ – magenta, ‘M’ – dark magenta, ‘y’ – yellow, ‘Y’ – dark yellow (gold), ‘h’ – gray, ‘H’ – dark gray, ‘w’ – white, ‘W’ – bright gray, ‘l’ – green-blue, ‘L’ – dark green-blue, ‘e’ – green-yellow, ‘E’ – dark green-yellow, ‘n’ – sky-blue, ‘N’ – dark sky-blue, ‘u’ – blue-violet, ‘U’ – dark blue-violet, ‘p’ – purple, ‘P’ – dark purple, ‘q’ – orange, ‘Q’ – dark orange (brown).

Dashing styles has the following meaning: space – no line (usable for plotting only marks), ‘-’ – solid line (################), ‘|’ – dashed line (########________), ‘;’ – small dashed line (####____####____), ‘:’ – dotted line (#___#___#___#___), ‘j’ – dash-dotted line (#######____#____), ‘i’ – small dash-dotted line (###__#__###__#__).

Marker types are: ‘o’ – circle, ‘+’ – cross, ‘x’ – skew cross, ‘s’ - square, ‘d’ - rhomb (or diamond), ‘.’ – point, ‘^’ – triangle up, ‘v’ – triangle down. If string contain symbol ‘#’ then the solid versions of markers are used.

png/sample5

Styles of lines and marks.

One may specify to draw a special symbol (an arrow) at the beginning and at the end of line. It is possible if the specification string contains one of the following symbols: ‘A’ – outer arrow, ‘V’ – inner arrow, ‘I’ – transverse hachures, ‘K’ – arrow with hachures, ‘T’ – triangle, ‘S’ – square, ‘D’ – rhomb, ‘O’ – circle, ‘_’ – nothing (it is default). At this, there is a rule: first symbol specifies the arrow at the end of line, second one specifies the arrow at the beginning of line. For example, ‘r-A’ defines a red solid line with usual arrow at the end, ‘b|AI’ defines a blue dash line with an arrow at the end and with hachures at the start, ‘_O’ defines a line with the current style and with a circle at the start. These styles are applicable during the graphics plotting too (for example, Plot).

png/sampled

Arrow styles.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3 Color scheme

The color scheme is used for determining the color of surfaces, isolines, isosurfaces and so on. The color scheme is defined by the string which may contain several characters that are color id (see section mglColor class or see section Line styles) or characters ‘d#:|’. Symbol ‘d’ denotes interpolation by 3d position instead of the coloring by amplitude. Symbol ‘#’ switch to mesh drawing or to wire plot. Symbol ‘|’ disable color interpolation in color scheme which can be usefull, for example, for sharp colors during matrix plotting. Symbol ‘:’ finishes the color scheme parsing. After it the user may put styles for text, rotation axis for curves/isolines and so on. Color scheme may contain up to 32 color values.

Also you may use “lighted” colors in color scheme specification (not in line style!). The “lighted” color contain 2 symbols: first one is usual symbol for color specification, second one is digit for its brightness. The digit can be in range ‘1’...‘9’. At this ‘5’ correspond to normal color, ‘1’ is very dark version of the color (practically black), ‘9’ is very bright version of the color (practically white).

png/colors

Colors and its ids.

For coloring by amplitude (most common) the final color is linear interpolation of color array. The color array is constructed from the string ids. The argument is the amplitude normalized between CminCmax (see section Ranges (bounding box)). For example, string containing 4 characters ‘bcyr’ corresponds to colorbar from blue (lowest value) through cyan (next value) through yellow (next value) to the red (highest value). String ‘kw’ corresponds to colorbar from black (lowest value) to white (highest value). String ‘m’ corresponds to a simple magenta color.

There are several useful combinations. String ‘kw’ corresponds to the simplest gray color scheme when higher values are brighter. String ‘wk’ presents the inverse gray color scheme when higher value is darker. Strings ‘kRryw’, ‘kGgw’, ‘kBbcw’ present well-known hot, summer and winter color schemes. Strings ‘BbwrR’ and ‘bBkRr’ allow to view bicolor figure on white or black background when negative values are blue and positive values are red. String ‘BbcyrR’ gives color scheme similar to well-known jet color scheme.

Examples of the most popular color schemes:

kw
png_static/kw
wk
png_static/wk
hHCcw
png_static/kHCcw
kRryw
png_static/kRryw
kGgew
png_static/kGgew
kBbcw
png_static/kBbcw
BbwrR
png_static/BbwrR
BbwgG
png_static/BbwgG
GgwmM
png_static/GgwmM
bcwyr
png_static/bcwyr
QqwcC
png_static/QqwcC
CcwyY
png_static/CcwyY
BbcyrR
png_static/BbcyrR
BbcwyrR
png_static/BbcwyrR
bwr
png_static/bwr
bcyr
png_static/bcyr
bgr
png_static/bgr
BbcyrR|
png_static/sharp

For the coloring by coordinate the final color is determined by position of the point in 3d space and is calculated by formula c=x*c[1] + y*c[2] + z*c[3]. Here c[1], c[2], c[3] are the first three elements of color array; x, y, z are normalized to MinMax coordinates of the point. This type of coloring is useful for isosurface plot when color may show the exact position of the peace of surface. For example, see section Surf3.

Also you may use “lighted” colors in color scheme specification (not in line style!). The “lighted” color contain 2 symbols: first one is usual symbol for color specification, second one is digit for its brightness. The digit can be in range ’1’...’9’. At this ‘5’ correspond to normal color, ‘1’ is very dark version of the color (practically black), ‘9’ is very bright version of the color (practically white). For example, the color scheme can be ‘b2b7wr7r2’.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.4 Font style

Text style is specified by the string which may contain several characters of font (‘ribwou’) and/or align (‘LRC’) specifications. The string also may contain the color id characters ‘wkrgbcymhRGBCYMHW’ (see section mglColor class) after the symbol ‘:’. For example, ‘biC:b’ sets the bold italic font text aligned at the center and with blue color.

The font types are: ‘r’ – roman font, ‘i’ – italic style, ‘b’ – bold style. By default roman roman font is used. The align types are: ‘L’ – align left (default), ‘C’ – align center, ‘R’ – align right. Additional font effects are: ‘w’ – wired, ‘o’ – over-lined, ‘u’ – underlined. Also a parsing of the LaTeX-like syntax is provided (for detail, see section mglFont class and Font settings).

The font size can be defined explicitly (if size>0) or relatively the base font size as |size|*FontSize (if size<0). The value size=0 specifies that the string will not be printed. The base font size is measured in internal “MathGL” units. Special functions SetFontSizePT(), SetFontSizeCM(), SetFontSizeIN() allow one to set it in more “common” variables for given dpi of the picture.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 FAQ

The plot does not appear

Check that points of the plot lie inside the bounding box and resize the bounding box by Axis() function. Check that the data have correct dimensions for selected type of plot. Be sure that Finish() is called after the plotting functions (or be sure that the plot is saved to file).

I can not find some special kind of plot.

Most of “new” type of plot can be created by using of the existing drawing functions. For example, the surface of curve rotation can be created by special function Torus() or as parametrically specified surface Surf(). See also, Hints and MathGL examples of MathGL. If you can not find some type of plot then e-mail me and this plot will appear in the next version of MathGL library.

Should I know some graphical libraries (like OpenGL) for the using of MathGL library?

No. The MathGL library is self-consistent and does not require the knowledge of external libraries.

In which language the library is written? For which languages the library has interface?

The core of MathGL library is written on C++. But there are interfaces for pure C, Fortran, Pascal, Forth languages and its own command language MGL. Also there are a large set of interpreter languages support (Python, Java, ALLEGROCL, CHICKEN, Lisp, CFFI, C#, Guile, Lua, Modula 3, Mzscheme, Ocaml, Octave, Perl, PHP, Pike, R, Ruby, Tcl). These interfaces are written via SWIG (both pure C functions and classes) but only interface for Python and Octave is included in autoconf/automake script. The matter that I don’t know any other interpreter languages :(. Note, the most of other languages can use (can link) pure C functions.

How I can use MathGL with Fortran?

You can use MathGL as is with gfortran because it use by default AT&T notation for external functions. For other compilers (like, Visual Fortran) you have to switch on AT&T notation manually. The AT&T notation require that symbol ‘_’ is added at the end of function name, function argument(s) is passed by pointers and string length(s) is passed at the end of argument list. For example:

C functionvoid mgl_fplot(HMGL graph, const char *fy, const char *stl, int n);

AT&T functionvoid mgl_fplot_(uintptr_t *graph, const char *fy, const char *stl, int *n, int ly, int ls);

I have class Foo and drawing method Foo::draw(mglGraph *gr). How I can use it in FLTK or GLUT window?

The member-functions of classes have hidden parameter (the pointer to a class instance) in C++. So, their direct usage is impossible. The solution is to write interface function:

 
int foo_draw(mglGraph *gr, void *par)
{   ((Foo *)foo)->draw(gr);    }

and to use it in the call of Window() function:

 
gr->Window(argc,argv,foo_draw,"Title",this);

Alternatively you can inherit yours class from mglDraw class and use functions like gr->Window(argc, argv, foo, "Title");.

How can I print in Russia/Spanish/Arabian/Japanese and so on?

The standard way is the using of Unicode encoding for the text output. But MathGL library also has interface for 8-bit (char *) strings with internal conversion to Unicode. This conversion depends on the current locale OS. You may change it by setlocale() function. For example, for Russian text in CP1251 encoding you may use setlocale(LC_CTYPE, "ru_RU.cp1251"); (under MS Windows the name of locale may differ – setlocale(LC_CTYPE, "russian_russia.1251")). I strongly recommend not to use the constant LC_ALL in conversion. Because it also changes the number format that may lead to mistakes in formulas writing and reading textual data files. For example, the program will await a ‘,’ as a decimal point but the user will enter ‘.’.

How can I exclude a point or a region of plot from the drawing?

There are 3 general ways. First, the point with NAN value of one of coordinate will never be plotted. Second, special variables CutMin, CutMax or function CutOff() define the condition when the points should be omitted (see section Cutting). Last, you may change the transparency of part of the plot by the help of functions SurfA(), Surf3A() (see section Dual plotting). In last case the transparency is switched on smoothly.

I use VisualStudio, CBuilder or some other compiler (not MinGW/gcc). How can I link MathGL library?

There are 2 ways. First is use the precompiled binary (*.dll). In this case you should make libraries for yours compiler from *.dll and *.def files. The corresponding command may look like lib.exe /def:libmgl.def. But such way provide you only pure C functions, not C++ classes. The matter is that there is no standard for C++ functions naming in object files. The standard was accepted only for C functions.

The second way is to compile the library from sources. MathGL library have some external dependencies (PNG, GSL, JPEG, TIFF, FLTK, GLUT, HDF5), but most of them is optional. Some libraries can be found here. But also you may exclude from the project the corresponding files to disable usage of JPEG, TIFF, FLTK, GLUT, HDF5 libraries. Also you may define NO_GSL at compilation stage for disabling GSL support. At this some special functions in formulas, Fourier transform and nonlinear fitting will be disabled also.

For excluding PNG support just comment the body of functions mgl_pnga_save(), mgl_png_save() in mgl_export.cpp. After it MathGL library will not depend on any external libraries. But in this case you should redirect the output to some window (as bitmap drawing from mglGraphZB|PS::GetBits() or mglGraphZB|PS::GetRGBA()) and save this bitmap to a file by yourself.

Finally! Please do not ask me Windows-specific questions. I do not use Windows. I know nothing about Visual Basic, Visual C++, CBuiled or .NET. Please find the appropriate Usenet discussion group and ask your question there.

How many people write this library?

The most of the library was written by one person. This is result of near a year of work (mostly in the evening and in holidays): half-year I spent for writing the kernel and half-year or year I spent for extending, improving and documentation writing. This process continues now :). The autoconf/automake script was written mostly by D.Kulagin, and export to IDTF was written mostly by M.Vidassov. Packages to particular platform (RPM or DEB) are prepared by other people (thanks to D. Kulagin, S. Plis, V. Lipatov and N. Troitsky).

How can I display a bitmap?

You can import data into a mglData instance and display it by Dens() function. For example, for black-and-white bitmap you can use the code: mglData bmp; bmp.Import("fname.png","wk"); gr->Dens(bmp,"wk");.

How can I use MathGL in Qt, FLTK, wxWidgets ...?

There are special classes (widgets) for these libraries: QMathGL for Qt, Fl_MathGL for FLTK and so on. If you don’t find the appropriate class then you can create yours own widget which display a bitmap from mglGraphAB::GetBits().

How can I create U3D file (make 3D in PDF)?

There are 2 steps: first you should create IDTF file, and later convert it to U3D. You can use U3D tools for converting IDTF file to U3D. It need libharu 2.1.0 or later. For installation use ./bootstrap, ./configure, make, sudo make install. It provide IDTFConverter program for converting textual files *.idtf to binary files *.u3d. Last ones can be included into PDF.

How I can change font family?

First, you should download new font files from here or from here. Next, you should load font files into mglGraph class instance gr by following command: gr->SetFont(new mglFont(fontname,path));. Here fontname is base font name like ‘STIX’ and path set the location of font files. Use gr->SetFont(NULL); for using default font.

How can I draw tick out of bounding box?

Just set negative value for TickLen. For example, use gr->SetTickLen(-0.1);.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6 Thanks


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Build Daemon user on March 5, 2010 using texi2html 1.82.