[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
MathGL is ...
1.1 Why I have written MathGL? | ||
1.2 MathGL features | ||
1.3 Installation and using | ||
1.4 General concepts | ||
1.5 FAQ | ||
1.6 Thanks |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
MathGL can be installed by 3 ways.
./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
.
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] | [ ? ] |
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:
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.
1.4.1 Coordinate axes | ||
1.4.2 Line styles | ||
1.4.3 Color scheme | ||
1.4.4 Font style |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
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.
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).
Arrow styles.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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).
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 Cmin – Cmax (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:
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 Min – Max 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] | [ ? ] |
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] | [ ? ] |
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).
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.
No. The MathGL library is self-consistent and does not require the knowledge of external libraries.
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.
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 function – void mgl_fplot(HMGL graph, const char *fy, const char *stl, int n);
AT&T function – void mgl_fplot_(uintptr_t *graph, const char *fy, const char *stl, int *n, int ly, int ls);
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");
.
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 ‘.’.
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.
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.
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).
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");
.
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().
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.
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.
Just set negative value for TickLen. For example, use gr->SetTickLen(-0.1);
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Build Daemon user on March 5, 2010 using texi2html 1.82.