MathGL

2.1.1 Using MathGL window

The “interactive” way of drawing in MathGL consists in window creation with help of class mglQT, mglFLTK or mglGLUT (see Widget classes) and the following drawing in this window. There is a corresponding code:

#include <mgl2/qt.h>
int sample(mglGraph *gr)
{
  gr->Rotate(60,40);
  gr->Box();
  return 0;
}
//-----------------------------------------------------
int main(int argc,char **argv)
{
  mglQT gr(sample,"MathGL examples");
  return gr.Run();
}

Here callback function sample is defined. This function does all drawing. Other function main is entry point function for console program. For compilation, just execute the command

gcc test.cpp -lmgl-qt5 -lmgl

You can use "-lmgl-qt4" instead of "-lmgl-qt5", if Qt4 is installed.

Alternatively you can create yours own class inherited from mglDraw class and re-implement the function Draw() in it:

#include <mgl2/qt.h>
class Foo : public mglDraw
{
public:
  int Draw(mglGraph *gr);
};
//-----------------------------------------------------
int Foo::Draw(mglGraph *gr)
{
  gr->Rotate(60,40);
  gr->Box();
  return 0;
}
//-----------------------------------------------------
int main(int argc,char **argv)
{
  Foo foo;
  mglQT gr(&foo,"MathGL examples");
  return gr.Run();
}

Or use pure C-functions:

#include <mgl2/mgl_cf.h>
int sample(HMGL gr, void *)
{
  mgl_rotate(gr,60,40,0);
  mgl_box(gr);
}
int main(int argc,char **argv)
{
  HMGL gr;
  gr = mgl_create_graph_qt(sample,"MathGL examples",0,0);
  return mgl_qt_run();
/* generally I should call mgl_delete_graph() here,
 * but I omit it in main() function. */
}

The similar code can be written for mglGLUT window (function sample() is the same):

#include <mgl2/glut.h>
int main(int argc,char **argv)
{
  mglGLUT gr(sample,"MathGL examples");
  return 0;
}

The rotation, shift, zooming, switching on/off transparency and lighting can be done with help of tool-buttons (for mglQT, mglFLTK) or by hot-keys: ‘a’, ‘d’, ‘w’, ‘s’ for plot rotation, ‘r’ and ‘f’ switching on/off transparency and lighting. Press ‘x’ for exit (or closing the window).

In this example function sample rotates axes (Rotate(), see Subplots and rotation) and draws the bounding box (Box()). Drawing is placed in separate function since it will be used on demand when window canvas needs to be redrawn.

2.1.2 Drawing to file

Another way of using MathGL library is the direct writing of the picture to the file. It is most usable for plot creation during long calculation or for using of small programs (like Matlab or Scilab scripts) for visualizing repetitive sets of data. But the speed of drawing is much higher in comparison with a script language.

The following code produces a bitmap PNG picture:

#include <mgl2/mgl.h>
int main(int ,char **)
{
  mglGraph gr;
  gr.Alpha(true);   gr.Light(true);
  sample(&gr);              // The same drawing function.
  gr.WritePNG("test.png");  // Don't forget to save the result!
  return 0;
}

For compilation, you need only libmgl library not the one with widgets

gcc test.cpp -lmgl

This can be important if you create a console program in computer/cluster where X-server (and widgets) is inaccessible.

The only difference from the previous variant (using windows) is manual switching on the transparency Alpha and lightning Light, if you need it. The usage of frames (see Animation) is not advisable since the whole image is prepared each time. If function sample contains frames then only last one will be saved to the file. In principle, one does not need to separate drawing functions in case of direct file writing in consequence of the single calling of this function for each picture. However, one may use the same drawing procedure to create a plot with changeable parameters, to export in different file types, to emphasize the drawing code and so on. So, in future I will put the drawing in the separate function.

The code for export into other formats (for example, into vector EPS file) looks the same:

#include <mgl2/mgl.h>
int main(int ,char **)
{
  mglGraph gr;
  gr.Light(true);
  sample(&gr);              // The same drawing function.
  gr.WriteEPS("test.eps");  // Don't forget to save the result!
  return 0;
}

The difference from the previous one is using other function WriteEPS() for EPS format instead of function WritePNG(). Also, there is no switching on of the plot transparency Alpha since EPS format does not support it.

2.1.3 Animation

Widget classes (mglWindow, mglGLUT) support a delayed drawing, when all plotting functions are called once at the beginning of writing to memory lists. Further program displays the saved lists faster. Resulting redrawing will be faster but it requires sufficient memory. Several lists (frames) can be displayed one after another (by pressing ‘,’, ‘.’) or run as cinema. To switch these feature on one needs to modify function sample:

int sample(mglGraph *gr)
{
  gr->NewFrame();             // the first frame
  gr->Rotate(60,40);
  gr->Box();
  gr->EndFrame();             // end of the first frame
  gr->NewFrame();             // the second frame
  gr->Box();
  gr->Axis("xy");
  gr->EndFrame();             // end of the second frame
  return gr->GetNumFrame();   // returns the frame number
}

First, the function creates a frame by calling NewFrame() for rotated axes and draws the bounding box. The function EndFrame() must be called after the frame drawing! The second frame contains the bounding box and axes Axis("xy") in the initial (unrotated) coordinates. Function sample returns the number of created frames GetNumFrame().

Note, that animation can be also done as visualization of running calculations (see Draw and calculate).

Pictures with animation can be saved in file(s) as well. You can: export in animated GIF, or save each frame in separate file (usually JPEG) and convert these files into the movie (for example, by help of ImageMagic). Let me show both methods.

The simplest methods is making animated GIF. There are 3 steps: (1) open GIF file by StartGIF() function; (2) create the frames by calling NewFrame() before and EndFrame() after plotting; (3) close GIF by CloseGIF() function. So the simplest code for “running” sinusoid will look like this:

#include <mgl2/mgl.h>
int main(int ,char **)
{
  mglGraph gr;
  mglData dat(100);
  char str[32];
  gr.StartGIF("sample.gif");
  for(int i=0;i<40;i++)
  {
    gr.NewFrame();     // start frame
    gr.Box();          // some plotting
    for(int j=0;j<dat.nx;j++)
      dat.a[j]=sin(M_PI*j/dat.nx+M_PI*0.05*i);
    gr.Plot(dat,"b");
    gr.EndFrame();     // end frame
  }
  gr.CloseGIF();
  return 0;
}

The second way is saving each frame in separate file (usually JPEG) and later make the movie from them. MathGL have special function for saving frames – it is WriteFrame(). This function save each frame with automatic name ‘frame0001.jpg, frame0002.jpg’ and so on. Here prefix ‘frame’ is defined by PlotId variable of mglGraph class. So the similar code will look like this:

#include <mgl2/mgl.h>
int main(int ,char **)
{
  mglGraph gr;
  mglData dat(100);
  char str[32];
  for(int i=0;i<40;i++)
  {
    gr.NewFrame();     // start frame
    gr.Box();          // some plotting
    for(int j=0;j<dat.nx;j++)
      dat.a[j]=sin(M_PI*j/dat.nx+M_PI*0.05*i);
    gr.Plot(dat,"b");
    gr.EndFrame();     // end frame
    gr.WriteFrame();   // save frame
  }
  return 0;
}

Created files can be converted to movie by help of a lot of programs. For example, you can use ImageMagic (command ‘convert frame*.jpg movie.mpg’), MPEG library, GIMP and so on.

Finally, you can use mglconv tool for doing the same with MGL scripts (see Utilities for parsing MGL).

2.1.4 Drawing in memory

The last way of MathGL using is the drawing in memory. Class mglGraph allows one to create a bitmap picture in memory. Further this picture can be displayed in window by some window libraries (like wxWidgets, FLTK, Windows GDI and so on). For example, the code for drawing in wxWidget library looks like:

void MyForm::OnPaint(wxPaintEvent& event)
{
  int w,h,x,y;
  GetClientSize(&w,&h);   // size of the picture
  mglGraph gr(w,h);

  gr.Alpha(true);         // draws something using MathGL
  gr.Light(true);
  sample(&gr,NULL);

  wxImage img(w,h,gr.GetRGB(),true);
  ToolBar->GetSize(&x,&y);    // gets a height of the toolbar if any
  wxPaintDC dc(this);         // and draws it
  dc.DrawBitmap(wxBitmap(img),0,y);
}

The drawing in other libraries is most the same.

For example, FLTK code will look like

void Fl_MyWidget::draw()
{
  mglGraph gr(w(),h());
  gr.Alpha(true);         // draws something using MathGL
  gr.Light(true);
  sample(&gr,NULL);
  fl_draw_image(gr.GetRGB(), x(), y(), gr.GetWidth(), gr.GetHeight(), 3);
}

Qt code will look like

void MyWidget::paintEvent(QPaintEvent *)
{
  mglGraph gr(w(),h());

  gr.Alpha(true);         // draws something using MathGL
  gr.Light(true);         gr.Light(0,mglPoint(1,0,-1));
  sample(&gr,NULL);

  // Qt don't support RGB format as is. So, let convert it to BGRN.
  long w=gr.GetWidth(), h=gr.GetHeight();
  unsigned char *buf = new uchar[4*w*h];
  gr.GetBGRN(buf, 4*w*h)
  QPixmap pic = QPixmap::fromImage(QImage(*buf, w, h, QImage::Format_RGB32));

  QPainter paint;
  paint.begin(this);  paint.drawPixmap(0,0,pic);  paint.end();
  delete []buf;
}

2.1.5 Draw and calculate

MathGL can be used to draw plots in parallel with some external calculations. The simplest way for this is the usage of mglDraw class. At this you should enable pthread for widgets by setting enable-pthr-widget=ON at configure stage (it is set by default). First, you need to inherit you class from mglDraw class, define virtual members Draw() and Calc() which will draw the plot and proceed calculations. You may want to add the pointer mglWnd *wnd; to window with plot for interacting with them. Finally, you may add any other data or member functions. The sample class is shown below

class myDraw : public mglDraw
{
	mglPoint pnt;	// some variable for changeable data
	long i;			// another variable to be shown
	mglWnd *wnd;	// external window for plotting
public:
	myDraw(mglWnd *w=0) : mglDraw()	{	wnd=w;	}
	void SetWnd(mglWnd *w)	{	wnd=w;	}
	int Draw(mglGraph *gr)
	{
		gr->Line(mglPoint(),pnt,"Ar2");
		char str[16];	snprintf(str,15,"i=%ld",i);
		gr->Puts(mglPoint(),str);
		return 0;
	}
	void Calc()
	{
		for(i=0;;i++)	// do calculation
		{
			long_calculations();// which can be very long
			Check();	// check if need pause
			pnt.Set(2*mgl_rnd()-1,2*mgl_rnd()-1);
			if(wnd)	wnd->Update();
		}
	}
} dr;

There is only one issue here. Sometimes you may want to pause calculations to view result carefully, or save state, or change something. So, you need to provide a mechanism for pausing. Class mglDraw provide function Check(); which check if toolbutton with pause is pressed and wait until it will be released. This function should be called in a "safety" places, where you can pause the calculation (for example, at the end of time step). Also you may add call exit(0); at the end of Calc(); function for closing window and exit after finishing calculations. Finally, you need to create a window itself and run calculations.

int main(int argc,char **argv)
{
	mglFLTK gr(&dr,"Multi-threading test");	// create window
	dr.SetWnd(&gr);	// pass window pointer to yours class
	dr.Run();	// run calculations
	gr.Run();	// run event loop for window
	return 0;
}

Note, that you can reach the similar functionality without using mglDraw class (i.e. even for pure C code).

mglFLTK *gr=NULL;	// pointer to window
void *calc(void *)	// function with calculations
{
	mglPoint pnt;	// some data for plot
	for(long i=0;;i++)		// do calculation
	{
		long_calculations();	// which can be very long
		pnt.Set(2*mgl_rnd()-1,2*mgl_rnd()-1);
		if(gr)
		{
			gr->Clf();			// make new drawing
			// draw something
			gr->Line(mglPoint(),pnt,"Ar2");
			char str[16];	snprintf(str,15,"i=%ld",i);
			gr->Puts(mglPoint(),str);
			// don't forgot to update window
			gr->Update();
		}
	}
}
int main(int argc,char **argv)
{
	static pthread_t thr;
	pthread_create(&thr,0,calc,0);	// create separate thread for calculations
	pthread_detach(thr);			// and detach it
	gr = new mglFLTK;	// now create window
	gr->Run();			// and run event loop
	return 0;
}

This sample is exactly the same as one with mglDraw class, but it don’t have functionality for pausing calculations. If you need it then you have to create global mutex (like pthread_mutex_t *mutex = pthread_mutex_init(&mutex,NULL);), set it to window (like gr->SetMutex(mutex);) and periodically check it at calculations (like pthread_mutex_lock(&mutex); pthread_mutex_unlock(&mutex);).

Finally, you can put the event-handling loop in separate instead of yours code by using RunThr() function instead of Run() one. Unfortunately, such method work well only for FLTK windows and only if pthread support was enabled. Such limitation come from the Qt requirement to be run in the primary thread only. The sample code will be:

int main(int argc,char **argv)
{
	mglFLTK gr("test");
	gr.RunThr();	// <-- need MathGL version which use pthread for widgets
	mglPoint pnt;	// some data
	for(int i=0;i<10;i++)	// do calculation
	{
		long_calculations();// which can be very long
		pnt.Set(2*mgl_rnd()-1,2*mgl_rnd()-1);
		gr.Clf();			// make new drawing
		gr.Line(mglPoint(),pnt,"Ar2");
		char str[10] = "i=0";	str[3] = '0'+i;
		gr->Puts(mglPoint(),str);
		gr.Update();		// update window
	}
	return 0;	// finish calculations and close the window
}

2.1.6 Using QMathGL

MathGL have several interface widgets for different widget libraries. There are QMathGL for Qt, Fl_MathGL for FLTK. These classes provide control which display MathGL graphics. Unfortunately there is no uniform interface for widget classes because all libraries have slightly different set of functions, features and so on. However the usage of MathGL widgets is rather simple. Let me show it on the example of QMathGL.

First of all you have to define the drawing function or inherit a class from mglDraw class. After it just create a window and setup QMathGL instance as any other Qt widget:

#include <QApplication>
#include <QMainWindow>
#include <QScrollArea>
#include <mgl2/qmathgl.h>
int main(int argc,char **argv)
{
  QApplication a(argc,argv);
  QMainWindow *Wnd = new QMainWindow;
  Wnd->resize(810,610);  // for fill up the QMGL, menu and toolbars
  Wnd->setWindowTitle("QMathGL sample");
  // here I allow one to scroll QMathGL -- the case
  // then user want to prepare huge picture
  QScrollArea *scroll = new QScrollArea(Wnd);

  // Create and setup QMathGL
  QMathGL *QMGL = new QMathGL(Wnd);
//QMGL->setPopup(popup); // if you want to setup popup menu for QMGL
  QMGL->setDraw(sample);
  // or use QMGL->setDraw(foo); for instance of class Foo:public mglDraw
  QMGL->update();

  // continue other setup (menu, toolbar and so on)
  scroll->setWidget(QMGL);
  Wnd->setCentralWidget(scroll);
  Wnd->show();
  return a.exec();
}

2.1.7 OpenGL output

MathGL have possibility to draw resulting plot using OpenGL. This produce resulting plot a bit faster, but with some limitations (especially at use of transparency and lighting). Generally, you need to prepare OpenGL window and call MathGL functions to draw it. There is GLUT interface (see Widget classes) to do it by simple way. Below I show example of OpenGL usage basing on Qt libraries (i.e. by using QGLWidget widget).

First, one need to define widget class derived from QGLWidget and implement a few methods: resizeGL() called after each window resize, paintGL() for displaying the image on the screen, and initializeGL() for initializing OpenGL. The header file looks as following.

#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <QGLWidget>
#include <mgl2/mgl.h>

class MainWindow : public QGLWidget
{
  Q_OBJECT
protected:
  mglGraph *gr;         // pointer to MathGL core class
  void resizeGL(int nWidth, int nHeight);   // Method called after each window resize
  void paintGL();       // Method to display the image on the screen
  void initializeGL();  // Method to initialize OpenGL
public:
  MainWindow(QWidget *parent = 0);
  ~MainWindow();
};
#endif // MAINWINDOW_H

The class implementation is rather straightforward. One need to recreate the instance of mglGraph at initializing OpenGL, and ask MathGL to use OpenGL output (set argument 1 in mglGraph constructor). Of course, the mglGraph object should be deleted at destruction. The method resizeGL() just pass new sizes to OpenGL and update viewport sizes. All plotting functions are located in the method paintGL(). At this, one need to add 2 calls: gr->Clf() at beginning for clearing previous OpenGL primitives; and swapBuffers() for showing output on the screen. The source file looks as following.

#include "qgl_example.h"
#include <QApplication>
//#include <QtOpenGL>
//-----------------------------------------------------------------------------
MainWindow::MainWindow(QWidget *parent) : QGLWidget(parent)	{	gr=0;	}
//-----------------------------------------------------------------------------
MainWindow::~MainWindow()	{	if(gr)	delete gr;	}
//-----------------------------------------------------------------------------
void MainWindow::initializeGL()	// recreate instance of MathGL core
{
	if(gr)	delete gr;
	gr = new mglGraph(1);	// use '1' for argument to force OpenGL output in MathGL
}
//-----------------------------------------------------------------------------
void MainWindow::resizeGL(int w, int h) // standard resize replace
{
	QGLWidget::resizeGL(w, h);
	glViewport (0, 0, w, h);
}
//-----------------------------------------------------------------------------
void MainWindow::paintGL()	// main drawing function
{
	gr->Clf();	// clear previous OpenGL primitives
	gr->SubPlot(1,1,0);
	gr->Rotate(40,60);
	gr->Light(true);
	gr->AddLight(0,mglPoint(0,0,10),mglPoint(0,0,-1));
	gr->Axis();
	gr->Box();
	gr->FPlot("sin(pi*x)","i2");
	gr->FPlot("cos(pi*x)","|");
	gr->FSurf("cos(2*pi*(x^2+y^2))");
	gr->Finish();
	swapBuffers();	// show output on the screen
}
//-----------------------------------------------------------------------------
int main(int argc, char *argv[])	// create application
{
	mgl_textdomain(argv?argv[0]:NULL,"");
	QApplication a(argc, argv);
	MainWindow w;
	w.show();
	return a.exec();
}
//-----------------------------------------------------------------------------

2.1.8 MathGL and PyQt

Generally SWIG based classes (including the Python one) are the same as C++ classes. However, there are few tips for using MathGL with PyQt. Below I place a very simple python code which demonstrate how MathGL can be used with PyQt. This code is mostly written by Prof. Dr. Heino Falcke. You can just copy it to a file mgl-pyqt-test.py and execute it from python shell by command execfile("mgl-pyqt-test.py")

from PyQt4 import QtGui,QtCore
from mathgl import *
import sys
app = QtGui.QApplication(sys.argv)
qpointf=QtCore.QPointF()

class hfQtPlot(QtGui.QWidget):
    def __init__(self, parent=None):
        QtGui.QWidget.__init__(self, parent)
        self.img=(QtGui.QImage())
    def setgraph(self,gr):
        self.buffer='\t'
        self.buffer=self.buffer.expandtabs(4*gr.GetWidth()*gr.GetHeight())
        gr.GetBGRN(self.buffer,len(self.buffer))
        self.img=QtGui.QImage(self.buffer, gr.GetWidth(),gr.GetHeight(),QtGui.QImage.Format_ARGB32)
        self.update()
    def paintEvent(self, event):
        paint = QtGui.QPainter()
        paint.begin(self)
        paint.drawImage(qpointf,self.img)
        paint.end()

BackgroundColor=[1.0,1.0,1.0]
size=100
gr=mglGraph()
y=mglData(size)
#y.Modify("((0.7*cos(2*pi*(x+.2)*500)+0.3)*(rnd*0.5+0.5)+362.135+10000.)")
y.Modify("(cos(2*pi*x*10)+1.1)*1000.*rnd-501")
x=mglData(size)
x.Modify("x^2");

def plotpanel(gr,x,y,n):
    gr.SubPlot(2,2,n)
    gr.SetXRange(x)
    gr.SetYRange(y)
    gr.AdjustTicks()
    gr.Axis()
    gr.Box()
    gr.Label("x","x-Axis",1)
    gr.Label("y","y-Axis",1)
    gr.ClearLegend()
    gr.AddLegend("Legend: "+str(n),"k")
    gr.Legend()
    gr.Plot(x,y)


gr.Clf(BackgroundColor[0],BackgroundColor[1],BackgroundColor[2])
gr.SetPlotFactor(1.5)
plotpanel(gr,x,y,0)
y.Modify("(cos(2*pi*x*10)+1.1)*1000.*rnd-501")
plotpanel(gr,x,y,1)
y.Modify("(cos(2*pi*x*10)+1.1)*1000.*rnd-501")
plotpanel(gr,x,y,2)
y.Modify("(cos(2*pi*x*10)+1.1)*1000.*rnd-501")
plotpanel(gr,x,y,3)

gr.WritePNG("test.png","Test Plot")

qw = hfQtPlot()
qw.show()
qw.setgraph(gr)
qw.raise_()

2.1.9 MathGL and MPI

For using MathGL in MPI program you just need to: (1) plot its own part of data for each running node; (2) collect resulting graphical information in a single program (for example, at node with rank=0); (3) save it. The sample code below demonstrate this for very simple sample of surface drawing.

First you need to initialize MPI

#include <stdio.h>
#include <mgl2/mpi.h>
#include <mpi.h>

int main(int argc, char *argv[])
{
  // initialize MPI
  int rank=0, numproc=1;
  MPI_Init(&argc, &argv);
  MPI_Comm_size(MPI_COMM_WORLD,&numproc);
  MPI_Comm_rank(MPI_COMM_WORLD,&rank);
  if(rank==0) printf("Use %d processes.\n", numproc);

Next step is data creation. For simplicity, I create data arrays with the same sizes for all nodes. At this, you have to create mglGraph object too.

  // initialize data similarly for all nodes
  mglData a(128,256);
  mglGraphMPI gr;

Now, data should be filled by numbers. In real case, it should be some kind of calculations. But I just fill it by formula.

  // do the same plot for its own range
  char buf[64];
  sprintf(buf,"xrange %g %g",2.*rank/numproc-1,2.*(rank+1)/numproc-1);
  gr.Fill(a,"sin(2*pi*x)",buf);

It is time to plot the data. Don’t forget to set proper axis range(s) by using parametric form or by using options (as in the sample).

  // plot data in each node
  gr.Clf();   // clear image before making the image
  gr.Rotate(40,60);
  gr.Surf(a,"",buf);

Finally, let send graphical information to node with rank=0.

  // collect information
  if(rank!=0) gr.MPI_Send(0);
  else for(int i=1;i<numproc;i++)  gr.MPI_Recv(i);

Now, node with rank=0 have whole image. It is time to save the image to a file. Also, you can add a kind of annotations here – I draw axis and bounding box in the sample.

  if(rank==0)
  {
    gr.Box();   gr.Axis();   // some post processing
    gr.WritePNG("test.png"); // save result
  }

In my case the program is done, and I finalize MPI. In real program, you can repeat the loop of data calculation and data plotting as many times as you need.

  MPI_Finalize();
  return 0;
}

You can type ‘mpic++ test.cpp -lmgl-mpi -lmgl && mpirun -np 8 ./a.out’ for compilation and running the sample program on 8 nodes. Note, that you have to set enable-mpi=ON at MathGL configure to use this feature.

2.2.1 Subplots

Let me demonstrate possibilities of plot positioning and rotation. MathGL has a set of functions: subplot, inplot, title, aspect and rotate and so on (see Subplots and rotation). The order of their calling is strictly determined. First, one changes the position of plot in image area (functions subplot, inplot and multiplot). Secondly, you can add the title of plot by title function. After that one may rotate the plot (function rotate). Finally, one may change aspects of axes (function aspect). The following code illustrates the aforesaid it:

int sample(mglGraph *gr)
{
  gr->SubPlot(2,2,0); gr->Box();
  gr->Puts(mglPoint(-1,1.1),"Just box",":L");
  gr->InPlot(0.2,0.5,0.7,1,false);  gr->Box();
  gr->Puts(mglPoint(0,1.2),"InPlot example");
  gr->SubPlot(2,2,1); gr->Title("Rotate only");
  gr->Rotate(50,60);  gr->Box();
  gr->SubPlot(2,2,2); gr->Title("Rotate and Aspect");
  gr->Rotate(50,60);  gr->Aspect(1,1,2);  gr->Box();
  gr->SubPlot(2,2,3); gr->Title("Shear");
  gr->Box("c"); gr->Shear(0.2,0.1); gr->Box();
  return 0;
}

Here I used function Puts for printing the text in arbitrary position of picture (see Text printing). Text coordinates and size are connected with axes. However, text coordinates may be everywhere, including the outside the bounding box. I’ll show its features later in Text features.

More complicated sample show how to use most of positioning functions:

int sample(mglGraph *gr)
{
  gr->SubPlot(3,2,0); gr->Title("StickPlot");
  gr->StickPlot(3, 0, 20, 30);  gr->Box("r"); gr->Puts(mglPoint(0),"0","r");
  gr->StickPlot(3, 1, 20, 30);  gr->Box("g"); gr->Puts(mglPoint(0),"1","g");
  gr->StickPlot(3, 2, 20, 30);  gr->Box("b"); gr->Puts(mglPoint(0),"2","b");
  gr->SubPlot(3,2,3,"");  gr->Title("ColumnPlot");
  gr->ColumnPlot(3, 0); gr->Box("r"); gr->Puts(mglPoint(0),"0","r");
  gr->ColumnPlot(3, 1); gr->Box("g"); gr->Puts(mglPoint(0),"1","g");
  gr->ColumnPlot(3, 2); gr->Box("b"); gr->Puts(mglPoint(0),"2","b");
  gr->SubPlot(3,2,4,"");  gr->Title("GridPlot");
  gr->GridPlot(2, 2, 0);  gr->Box("r"); gr->Puts(mglPoint(0),"0","r");
  gr->GridPlot(2, 2, 1);  gr->Box("g"); gr->Puts(mglPoint(0),"1","g");
  gr->GridPlot(2, 2, 2);  gr->Box("b"); gr->Puts(mglPoint(0),"2","b");
  gr->GridPlot(2, 2, 3);  gr->Box("m"); gr->Puts(mglPoint(0),"3","m");
  gr->SubPlot(3,2,5,"");  gr->Title("InPlot");  gr->Box();
  gr->InPlot(0.4, 1, 0.6, 1, true); gr->Box("r");
  gr->MultiPlot(3,2,1, 2, 1,"");  gr->Title("MultiPlot and ShearPlot"); gr->Box();
  gr->ShearPlot(3, 0, 0.2, 0.1);  gr->Box("r"); gr->Puts(mglPoint(0),"0","r");
  gr->ShearPlot(3, 1, 0.2, 0.1);  gr->Box("g"); gr->Puts(mglPoint(0),"1","g");
  gr->ShearPlot(3, 2, 0.2, 0.1);  gr->Box("b"); gr->Puts(mglPoint(0),"2","b");
  return 0;
}

2.2.2 Axis and ticks

MathGL library can draw not only the bounding box but also the axes, grids, labels and so on. The ranges of axes and their origin (the point of intersection) are determined by functions SetRange(), SetRanges(), SetOrigin() (see Ranges (bounding box)). Ticks on axis are specified by function SetTicks, SetTicksVal, SetTicksTime (see Ticks). But usually

Function axis draws axes. Its textual string shows in which directions the axis or axes will be drawn (by default "xyz", function draws axes in all directions). Function grid draws grid perpendicularly to specified directions. Example of axes and grid drawing is:

int sample(mglGraph *gr)
{
  gr->SubPlot(2,2,0); gr->Title("Axis origin, Grid"); gr->SetOrigin(0,0);
  gr->Axis(); gr->Grid(); gr->FPlot("x^3");

  gr->SubPlot(2,2,1); gr->Title("2 axis");
  gr->SetRanges(-1,1,-1,1); gr->SetOrigin(-1,-1,-1);  // first axis
  gr->Axis(); gr->Label('y',"axis 1",0);  gr->FPlot("sin(pi*x)");
  gr->SetRanges(0,1,0,1);   gr->SetOrigin(1,1,1);   // second axis
  gr->Axis(); gr->Label('y',"axis 2",0);  gr->FPlot("cos(pi*x)");

  gr->SubPlot(2,2,3); gr->Title("More axis");
  gr->SetOrigin(NAN,NAN); gr->SetRange('x',-1,1);
  gr->Axis(); gr->Label('x',"x",0); gr->Label('y',"y_1",0);
  gr->FPlot("x^2","k");
  gr->SetRanges(-1,1,-1,1); gr->SetOrigin(-1.3,-1); // second axis
  gr->Axis("y","r");  gr->Label('y',"#r{y_2}",0.2);
  gr->FPlot("x^3","r");

  gr->SubPlot(2,2,2); gr->Title("4 segments, inverted axis");
  gr->SetOrigin(0,0);
  gr->InPlot(0.5,1,0.5,1);  gr->SetRanges(0,10,0,2);  gr->Axis();
  gr->FPlot("sqrt(x/2)");   gr->Label('x',"W",1); gr->Label('y',"U",1);
  gr->InPlot(0,0.5,0.5,1);  gr->SetRanges(1,0,0,2); gr->Axis("x");
  gr->FPlot("sqrt(x)+x^3"); gr->Label('x',"\\tau",-1);
  gr->InPlot(0.5,1,0,0.5);  gr->SetRanges(0,10,4,0);  gr->Axis("y");
  gr->FPlot("x/4"); gr->Label('y',"L",-1);
  gr->InPlot(0,0.5,0,0.5);  gr->SetRanges(1,0,4,0); gr->FPlot("4*x^2");
  return 0;
}

Note, that MathGL can draw not only single axis (which is default). But also several axis on the plot (see right plots). The idea is that the change of settings does not influence on the already drawn graphics. So, for 2-axes I setup the first axis and draw everything concerning it. Then I setup the second axis and draw things for the second axis. Generally, the similar idea allows one to draw rather complicated plot of 4 axis with different ranges (see bottom left plot).

At this inverted axis can be created by 2 methods. First one is used in this sample – just specify minimal axis value to be large than maximal one. This method work well for 2D axis, but can wrongly place labels in 3D case. Second method is more general and work in 3D case too – just use aspect function with negative arguments. For example, following code will produce exactly the same result for 2D case, but 2nd variant will look better in 3D.

// variant 1
gr->SetRanges(0,10,4,0);  gr->Axis();

// variant 2
gr->SetRanges(0,10,0,4);  gr->Aspect(1,-1);   gr->Axis();

Another MathGL feature is fine ticks tunning. By default (if it is not changed by SetTicks function), MathGL try to adjust ticks positioning, so that they looks most human readable. At this, MathGL try to extract common factor for too large or too small axis ranges, as well as for too narrow ranges. Last one is non-common notation and can be disabled by SetTuneTicks function.

Also, one can specify its own ticks with arbitrary labels by help of SetTicksVal function. Or one can set ticks in time format. In last case MathGL will try to select optimal format for labels with automatic switching between years, months/days, hours/minutes/seconds or microseconds. However, you can specify its own time representation using formats described in http://www.manpagez.com/man/3/strftime/. Most common variants are ‘%X’ for national representation of time, ‘%x’ for national representation of date, ‘%Y’ for year with century.

The sample code, demonstrated ticks feature is

int sample(mglGraph *gr)
{
  gr->SubPlot(3,3,0); gr->Title("Usual axis");  gr->Axis();
  gr->SubPlot(3,3,1); gr->Title("Too big/small range");
  gr->SetRanges(-1000,1000,0,0.001);  gr->Axis();
  gr->SubPlot(3,3,2); gr->Title("LaTeX-like labels");
  gr->Axis("F!");
  gr->SubPlot(3,3,3); gr->Title("Too narrow range");
  gr->SetRanges(100,100.1,10,10.01);  gr->Axis();
  gr->SubPlot(3,3,4); gr->Title("No tuning, manual '+'");
  // for version<2.3 you need first call gr->SetTuneTicks(0);
  gr->Axis("+!");
  gr->SubPlot(3,3,5); gr->Title("Template for ticks");
  gr->SetTickTempl('x',"xxx:%g"); gr->SetTickTempl('y',"y:%g");
  gr->Axis();
  // now switch it off for other plots
  gr->SetTickTempl('x',"");   gr->SetTickTempl('y',"");
  gr->SubPlot(3,3,6); gr->Title("No tuning, higher precision");
  gr->Axis("!4");
  gr->SubPlot(3,3,7); gr->Title("Manual ticks");  gr->SetRanges(-M_PI,M_PI, 0, 2);
  gr->SetTicks('x',M_PI,0,0,"\\pi");  gr->AddTick('x',0.886,"x^*");
  // alternatively you can use following lines
  //double val[]={-M_PI, -M_PI/2, 0, 0.886, M_PI/2, M_PI};
  //gr->SetTicksVal('x', mglData(6,val), "-\\pi\n-\\pi/2\n0\nx^*\n\\pi/2\n\\pi");
  gr->Axis();  gr->Grid();  gr->FPlot("2*cos(x^2)^2", "r2");
  gr->SubPlot(3,3,8); gr->Title("Time ticks");  gr->SetRange('x',0,3e5);
  gr->SetTicksTime('x',0);  gr->Axis();
}

The last sample I want to show in this subsection is Log-axis. From MathGL’s point of view, the log-axis is particular case of general curvilinear coordinates. So, we need first define new coordinates (see also Curvilinear coordinates) by help of SetFunc or SetCoor functions. At this one should wary about proper axis range. So the code looks as following:

int sample(mglGraph *gr)
{
  gr->SubPlot(2,2,0,"<_");  gr->Title("Semi-log axis");
  gr->SetRanges(0.01,100,-1,1); gr->SetFunc("lg(x)","");
  gr->Axis(); gr->Grid("xy","g"); gr->FPlot("sin(1/x)");
  gr->Label('x',"x",0); gr->Label('y', "y = sin 1/x",0);

  gr->SubPlot(2,2,1,"<_");  gr->Title("Log-log axis");
  gr->SetRanges(0.01,100,0.1,100);  gr->SetFunc("lg(x)","lg(y)");
  gr->Axis(); gr->Grid("!","h=");   gr->Grid();
  gr->FPlot("sqrt(1+x^2)"); gr->Label('x',"x",0);
  gr->Label('y', "y = \\sqrt{1+x^2}",0);

  gr->SubPlot(2,2,2,"<_");  gr->Title("Minus-log axis");
  gr->SetRanges(-100,-0.01,-100,-0.1);  gr->SetFunc("-lg(-x)","-lg(-y)");
  gr->Axis(); gr->FPlot("-sqrt(1+x^2)");
  gr->Label('x',"x",0); gr->Label('y', "y = -\\sqrt{1+x^2}",0);

  gr->SubPlot(2,2,3,"<_");  gr->Title("Log-ticks");
  gr->SetRanges(0.1,100,0,100); gr->SetFunc("sqrt(x)","");
  gr->Axis(); gr->FPlot("x");
  gr->Label('x',"x",1); gr->Label('y', "y = x",0);
  return 0;
}

You can see that MathGL automatically switch to log-ticks as we define log-axis formula (in difference from v.1.*). Moreover, it switch to log-ticks for any formula if axis range will be large enough (see right bottom plot). Another interesting feature is that you not necessary define usual log-axis (i.e. when coordinates are positive), but you can define “minus-log” axis when coordinate is negative (see left bottom plot).

2.2.3 Curvilinear coordinates

As I noted in previous subsection, MathGL support curvilinear coordinates. In difference from other plotting programs and libraries, MathGL uses textual formulas for connection of the old (data) and new (output) coordinates. This allows one to plot in arbitrary coordinates. The following code plots the line y=0, z=0 in Cartesian, polar, parabolic and spiral coordinates:

int sample(mglGraph *gr)
{
  gr->SetOrigin(-1,1,-1);

  gr->SubPlot(2,2,0); gr->Title("Cartesian"); gr->Rotate(50,60);
  gr->FPlot("2*t-1","0.5","0","r2");
  gr->Axis(); gr->Grid();

  gr->SetFunc("y*sin(pi*x)","y*cos(pi*x)",0);
  gr->SubPlot(2,2,1); gr->Title("Cylindrical"); gr->Rotate(50,60);
  gr->FPlot("2*t-1","0.5","0","r2");
  gr->Axis(); gr->Grid();

  gr->SetFunc("2*y*x","y*y - x*x",0);
  gr->SubPlot(2,2,2); gr->Title("Parabolic"); gr->Rotate(50,60);
  gr->FPlot("2*t-1","0.5","0","r2");
  gr->Axis(); gr->Grid();

  gr->SetFunc("y*sin(pi*x)","y*cos(pi*x)","x+z");
  gr->SubPlot(2,2,3); gr->Title("Spiral");  gr->Rotate(50,60);
  gr->FPlot("2*t-1","0.5","0","r2");
  gr->Axis(); gr->Grid();
  gr->SetFunc(0,0,0); // set to default Cartesian
  return 0;
}

2.2.4 Colorbars

MathGL handle colorbar as special kind of axis. So, most of functions for axis and ticks setup will work for colorbar too. Colorbars can be in log-scale, and generally as arbitrary function scale; common factor of colorbar labels can be separated; and so on.

But of course, there are differences – colorbars usually located out of bounding box. At this, colorbars can be at subplot boundaries (by default), or at bounding box (if symbol ‘I’ is specified). Colorbars can handle sharp colors. And they can be located at arbitrary position too. The sample code, which demonstrate colorbar features is:

int sample(mglGraph *gr)
{
  gr->SubPlot(2,2,0); gr->Title("Colorbar out of box"); gr->Box();
  gr->Colorbar("<");  gr->Colorbar(">");
  gr->Colorbar("_");  gr->Colorbar("^");

  gr->SubPlot(2,2,1); gr->Title("Colorbar near box");   gr->Box();
  gr->Colorbar("<I"); gr->Colorbar(">I");
  gr->Colorbar("_I"); gr->Colorbar("^I");

  gr->SubPlot(2,2,2); gr->Title("manual colors");
  mglData a,v;  mgls_prepare2d(&a,0,&v);
  gr->Box();  gr->ContD(v,a);
  gr->Colorbar(v,"<");  gr->Colorbar(v,">");
  gr->Colorbar(v,"_");  gr->Colorbar(v,"^");

  gr->SubPlot(2,2,3);   gr->Title(" ");
  gr->Puts(mglPoint(-0.5,1.55),"Color positions",":C",-2);
  gr->Colorbar("bwr>",0.25,0);  gr->Puts(mglPoint(-0.9,1.2),"Default");
  gr->Colorbar("b{w,0.3}r>",0.5,0); gr->Puts(mglPoint(-0.1,1.2),"Manual");

  gr->Puts(mglPoint(1,1.55),"log-scale",":C",-2);
  gr->SetRange('c',0.01,1e3);
  gr->Colorbar(">",0.75,0);  gr->Puts(mglPoint(0.65,1.2),"Normal scale");
  gr->SetFunc("","","","lg(c)");
  gr->Colorbar(">");    gr->Puts(mglPoint(1.35,1.2),"Log scale");
  return 0;
}

2.2.5 Bounding box

Box around the plot is rather useful thing because it allows one to: see the plot boundaries, and better estimate points position since box contain another set of ticks. MathGL provide special function for drawing such box – box function. By default, it draw black or white box with ticks (color depend on transparency type, see Types of transparency). However, you can change the color of box, or add drawing of rectangles at rear faces of box. Also you can disable ticks drawing, but I don’t know why anybody will want it. The sample code, which demonstrate box features is:

int sample(mglGraph *gr)
{
  gr->SubPlot(2,2,0); gr->Title("Box (default)"); gr->Rotate(50,60);
  gr->Box();
  gr->SubPlot(2,2,1); gr->Title("colored");   gr->Rotate(50,60);
  gr->Box("r");
  gr->SubPlot(2,2,2); gr->Title("with faces");  gr->Rotate(50,60);
  gr->Box("@");
  gr->SubPlot(2,2,3); gr->Title("both");  gr->Rotate(50,60);
  gr->Box("@cm");
  return 0;
}

2.2.6 Ternary axis

There are another unusual axis types which are supported by MathGL. These are ternary and quaternary axis. Ternary axis is special axis of 3 coordinates a, b, c which satisfy relation a+b+c=1. Correspondingly, quaternary axis is special axis of 4 coordinates a, b, c, d which satisfy relation a+b+c+d=1.

Generally speaking, only 2 of coordinates (3 for quaternary) are independent. So, MathGL just introduce some special transformation formulas which treat a as ‘x’, b as ‘y’ (and c as ‘z’ for quaternary). As result, all plotting functions (curves, surfaces, contours and so on) work as usual, but in new axis. You should use ternary function for switching to ternary/quaternary coordinates. The sample code is:

int sample(mglGraph *gr)
{
  gr->SetRanges(0,1,0,1,0,1);
  mglData x(50),y(50),z(50),rx(10),ry(10), a(20,30);
  a.Modify("30*x*y*(1-x-y)^2*(x+y<1)");
  x.Modify("0.25*(1+cos(2*pi*x))");
  y.Modify("0.25*(1+sin(2*pi*x))");
  rx.Modify("rnd"); ry.Modify("(1-v)*rnd",rx);
  z.Modify("x");

  gr->SubPlot(2,2,0); gr->Title("Ordinary axis 3D");
  gr->Rotate(50,60);    gr->Light(true);
  gr->Plot(x,y,z,"r2"); gr->Surf(a,"BbcyrR#");
  gr->Axis(); gr->Grid(); gr->Box();
  gr->Label('x',"B",1); gr->Label('y',"C",1); gr->Label('z',"Z",1);

  gr->SubPlot(2,2,1); gr->Title("Ternary axis (x+y+t=1)");
  gr->Ternary(1);
  gr->Plot(x,y,"r2"); gr->Plot(rx,ry,"q^ ");  gr->Cont(a,"BbcyrR");
  gr->Line(mglPoint(0.5,0), mglPoint(0,0.75), "g2");
  gr->Axis(); gr->Grid("xyz","B;");
  gr->Label('x',"B"); gr->Label('y',"C"); gr->Label('t',"A");

  gr->SubPlot(2,2,2); gr->Title("Quaternary axis 3D");
  gr->Rotate(50,60);    gr->Light(true);
  gr->Ternary(2);
  gr->Plot(x,y,z,"r2"); gr->Surf(a,"BbcyrR#");
  gr->Axis(); gr->Grid(); gr->Box();
  gr->Label('t',"A",1); gr->Label('x',"B",1);
  gr->Label('y',"C",1); gr->Label('z',"D",1);

  gr->SubPlot(2,2,3); gr->Title("Ternary axis 3D");
  gr->Rotate(50,60);    gr->Light(true);
  gr->Ternary(1);
  gr->Plot(x,y,z,"r2"); gr->Surf(a,"BbcyrR#");
  gr->Axis(); gr->Grid(); gr->Box();
  gr->Label('t',"A",1); gr->Label('x',"B",1);
  gr->Label('y',"C",1); gr->Label('z',"Z",1);
  return 0;
}

2.2.7 Text features

MathGL prints text by vector font. There are functions for manual specifying of text position (like Puts) and for its automatic selection (like Label, Legend and so on). MathGL prints text always in specified position even if it lies outside the bounding box. The default size of font is specified by functions SetFontSize* (see Font settings). However, the actual size of output string depends on subplot size (depends on functions SubPlot, InPlot). The switching of the font style (italic, bold, wire and so on) can be done for the whole string (by function parameter) or inside the string. By default MathGL parses TeX-like commands for symbols and indexes (see Font styles).

Text can be printed as usual one (from left to right), along some direction (rotated text), or along a curve. Text can be printed on several lines, divided by new line symbol ‘\n’.

Example of MathGL font drawing is:

int sample(mglGraph *gr)
{
  gr->SubPlot(2,2,0,"");
  gr->Putsw(mglPoint(0,1),L"Text can be in ASCII and in Unicode");
  gr->Puts(mglPoint(0,0.6),"It can be \\wire{wire}, \\big{big} or #r{colored}");
  gr->Puts(mglPoint(0,0.2),"One can change style in string: "
  "\\b{bold}, \\i{italic, \\b{both}}");
  gr->Puts(mglPoint(0,-0.2),"Easy to \\a{overline} or "
  "\\u{underline}");
  gr->Puts(mglPoint(0,-0.6),"Easy to change indexes ^{up} _{down} @{center}");
  gr->Puts(mglPoint(0,-1),"It parse TeX: \\int \\alpha \\cdot "
  "\\sqrt3{sin(\\pi x)^2 + \\gamma_{i_k}} dx");

  gr->SubPlot(2,2,1,"");
  gr->Puts(mglPoint(0,0.5), "\\sqrt{\\frac{\\alpha^{\\gamma^2}+\\overset 1{\\big\\infty}}{\\sqrt3{2+b}}}", "@", -4);
  gr->Puts(mglPoint(0,-0.5),"Text can be printed\non several lines");

  gr->SubPlot(2,2,2,"");
  mglData y;  mgls_prepare1d(&y);
  gr->Box();  gr->Plot(y.SubData(-1,0));
  gr->Text(y,"This is very very long string drawn along a curve",":k");
  gr->Text(y,"Another string drawn under a curve","T:r");

  gr->SubPlot(2,2,3,"");
  gr->Line(mglPoint(-1,-1),mglPoint(1,-1),"rA");
  gr->Puts(mglPoint(0,-1),mglPoint(1,-1),"Horizontal");
  gr->Line(mglPoint(-1,-1),mglPoint(1,1),"rA");
  gr->Puts(mglPoint(0,0),mglPoint(1,1),"At angle","@");
  gr->Line(mglPoint(-1,-1),mglPoint(-1,1),"rA");
  gr->Puts(mglPoint(-1,0),mglPoint(-1,1),"Vertical");
  return 0;
}

You can change font faces by loading font files by function loadfont. Note, that this is long-run procedure. Font faces can be downloaded from MathGL website or from here. The sample code is:

int sample(mglGraph *gr)
{
  double h=1.1, d=0.25;
  gr->LoadFont("STIX");     gr->Puts(mglPoint(0,h), "default font (STIX)");
  gr->LoadFont("adventor"); gr->Puts(mglPoint(0,h-d), "adventor font");
  gr->LoadFont("bonum");    gr->Puts(mglPoint(0,h-2*d), "bonum font");
  gr->LoadFont("chorus");   gr->Puts(mglPoint(0,h-3*d), "chorus font");
  gr->LoadFont("cursor");   gr->Puts(mglPoint(0,h-4*d), "cursor font");
  gr->LoadFont("heros");    gr->Puts(mglPoint(0,h-5*d), "heros font");
  gr->LoadFont("heroscn");  gr->Puts(mglPoint(0,h-6*d), "heroscn font");
  gr->LoadFont("pagella");  gr->Puts(mglPoint(0,h-7*d), "pagella font");
  gr->LoadFont("schola");   gr->Puts(mglPoint(0,h-8*d), "schola font");
  gr->LoadFont("termes");   gr->Puts(mglPoint(0,h-9*d), "termes font");
  return 0;
}

2.2.8 Legend sample

Legend is one of standard ways to show plot annotations. Basically you need to connect the plot style (line style, marker and color) with some text. In MathGL, you can do it by 2 methods: manually using addlegend function; or use ‘legend’ option (see Command options), which will use last plot style. In both cases, legend entries will be added into internal accumulator, which later used for legend drawing itself. clearlegend function allow you to remove all saved legend entries.

There are 2 features. If plot style is empty then text will be printed without indent. If you want to plot the text with indent but without plot sample then you need to use space ‘ ’ as plot style. Such style ‘ ’ will draw a plot sample (line with marker(s)) which is invisible line (i.e. nothing) and print the text with indent as usual one.

Function legend draw legend on the plot. The position of the legend can be selected automatic or manually. You can change the size and style of text labels, as well as setup the plot sample. The sample code demonstrating legend features is:

int sample(mglGraph *gr)
{
  gr->AddLegend("sin(\\pi {x^2})","b");
  gr->AddLegend("sin(\\pi x)","g*");
  gr->AddLegend("sin(\\pi \\sqrt{x})","rd");
  gr->AddLegend("just text"," ");
  gr->AddLegend("no indent for this","");

  gr->SubPlot(2,2,0,""); gr->Title("Legend (default)");
  gr->Box();  gr->Legend();

  gr->Legend(3,"A#");
  gr->Puts(mglPoint(0.75,0.65),"Absolute position","A");

  gr->SubPlot(2,2,2,"");  gr->Title("coloring");  gr->Box();
  gr->Legend(0,"r#"); gr->Legend(1,"Wb#");  gr->Legend(2,"ygr#");

  gr->SubPlot(2,2,3,"");  gr->Title("manual position"); gr->Box();
  gr->Legend(0.5,1);  gr->Puts(mglPoint(0.5,0.55),"at x=0.5, y=1","a");
  gr->Legend(1,"#-"); gr->Puts(mglPoint(0.75,0.25),"Horizontal legend","a");
  return 0;
}

2.2.9 Cutting sample

The last common thing which I want to show in this section is how one can cut off points from plot. There are 4 mechanism for that.

• You can set one of coordinate to NAN value. All points with NAN values will be omitted.
• You can enable cutting at edges by SetCut function. As result all points out of bounding box will be omitted.
• You can set cutting box by SetCutBox function. All points inside this box will be omitted.
• You can define cutting formula by SetCutOff function. All points for which the value of formula is nonzero will be omitted. Note, that this is the slowest variant.

Below I place the code which demonstrate last 3 possibilities:

int sample(mglGraph *gr)
{
  mglData a,c,v(1); mgls_prepare2d(&a); mgls_prepare3d(&c); v.a[0]=0.5;
  gr->SubPlot(2,2,0); gr->Title("Cut on (default)");
  gr->Rotate(50,60);  gr->Light(true);
  gr->Box();  gr->Surf(a,"","zrange -1 0.5");

  gr->SubPlot(2,2,1); gr->Title("Cut off");   gr->Rotate(50,60);
  gr->Box();  gr->Surf(a,"","zrange -1 0.5; cut off");

  gr->SubPlot(2,2,2); gr->Title("Cut in box");  gr->Rotate(50,60);
  gr->SetCutBox(mglPoint(0,-1,-1), mglPoint(1,0,1.1));
  gr->Alpha(true);  gr->Box();  gr->Surf3(c);
  gr->SetCutBox(mglPoint(0), mglPoint(0));  // switch it off

  gr->SubPlot(2,2,3); gr->Title("Cut by formula");  gr->Rotate(50,60);
  gr->CutOff("(z>(x+0.5*y-1)^2-1) & (z>(x-0.5*y-1)^2-1)");
  gr->Box();  gr->Surf3(c); gr->CutOff(""); // switch it off
  return 0;
}

2.3.1 Array creation

There are many ways in MathGL how data arrays can be created and filled.

One can put the data in mglData instance by several ways. Let us do it for sinus function:

• one can create external array, fill it and put to mglData variable

    double *a = new double[50];
    for(int i=0;i<50;i++)   a[i] = sin(M_PI*i/49.);
  
    mglData y;
    y.Set(a,50);
  

• another way is to create mglData instance of the desired size and then to work directly with data in this variable

    mglData y(50);
    for(int i=0;i<50;i++)   y.a[i] = sin(M_PI*i/49.);
  

• next way is to fill the data in mglData instance by textual formula with the help of Modify() function

    mglData y(50);
    y.Modify("sin(pi*x)");
  

• or one may fill the array in some interval and modify it later

    mglData y(50);
    y.Fill(0,M_PI);
    y.Modify("sin(u)");
  

• finally it can be loaded from file

    FILE *fp=fopen("sin.dat","wt");   // create file first
    for(int i=0;i<50;i++)   fprintf(fp,"%g\n",sin(M_PI*i/49.));
    fclose(fp);
  
    mglData y("sin.dat");             // load it
  

  At this you can use textual or HDF files, as well as import values from bitmap image (PNG is supported right now).

• at this one can read only part of data

    FILE *fp-fopen("sin.dat","wt");   // create large file first
    for(int i=0;i<70;i++)   fprintf(fp,"%g\n",sin(M_PI*i/49.));
    fclose(fp);
  
    mglData y;
    y.Read("sin.dat",50);             // load it
  

Creation of 2d- and 3d-arrays is mostly the same. But one should keep in mind that class mglData uses flat data representation. For example, matrix 30*40 is presented as flat (1d-) array with length 30*40=1200 (nx=30, ny=40). The element with indexes {i,j} is a[i+nx*j]. So for 2d array we have:

  mglData z(30,40);
  for(int i=0;i<30;i++)   for(int j=0;j<40;j++)
    z.a[i+30*j] = sin(M_PI*i/29.)*sin(M_PI*j/39.);

or by using Modify() function

  mglData z(30,40);
  z.Modify("sin(pi*x)*cos(pi*y)");

The only non-obvious thing here is using multidimensional arrays in C/C++, i.e. arrays defined like mreal dat[40][30];. Since, formally these elements dat[i] can address the memory in arbitrary place you should use the proper function to convert such arrays to mglData object. For C++ this is functions like mglData::Set(mreal **dat, int N1, int N2);. For C this is functions like mgl_data_set_mreal2(HMDT d, const mreal **dat, int N1, int N2);. At this, you should keep in mind that nx=N2 and ny=N1 after conversion.

2.3.2 Linking array

Sometimes the data arrays are so large, that one couldn’t’ copy its values to another array (i.e. into mglData). In this case, he can define its own class derived from mglDataA (see User defined types (mglDataA class)) or can use Link function.

In last case, MathGL just save the link to an external data array, but not copy it. You should provide the existence of this data array for whole time during which MathGL can use it. Another point is that MathGL will automatically create new array if you’ll try to modify data values by any of mglData functions. So, you should use only function with const modifier if you want still using link to the original data array.

Creating the link is rather simple – just the same as using Set function

  double *a = new double[50];
  for(int i=0;i<50;i++)   a[i] = sin(M_PI*i/49.);

  mglData y;
  y.Link(a,50);

2.3.3 Change data

MathGL has functions for data processing: differentiating, integrating, smoothing and so on (for more detail, see Data processing). Let us consider some examples. The simplest ones are integration and differentiation. The direction in which operation will be performed is specified by textual string, which may contain symbols ‘x’, ‘y’ or ‘z’. For example, the call of Diff("x") will differentiate data along ‘x’ direction; the call of Integral("xy") perform the double integration of data along ‘x’ and ‘y’ directions; the call of Diff2("xyz") will apply 3d Laplace operator to data and so on. Example of this operations on 2d array a=x*y is presented in code:

int sample(mglGraph *gr)
{
  gr->SetRanges(0,1,0,1,0,1);
  mglData a(30,40); a.Modify("x*y");
  gr->SubPlot(2,2,0); gr->Rotate(60,40);
  gr->Surf(a);    gr->Box();
  gr->Puts(mglPoint(0.7,1,1.2),"a(x,y)");
  gr->SubPlot(2,2,1); gr->Rotate(60,40);
  a.Diff("x");    gr->Surf(a);  gr->Box();
  gr->Puts(mglPoint(0.7,1,1.2),"da/dx");
  gr->SubPlot(2,2,2); gr->Rotate(60,40);
  a.Integral("xy"); gr->Surf(a);  gr->Box();
  gr->Puts(mglPoint(0.7,1,1.2),"\\int da/dx dxdy");
  gr->SubPlot(2,2,3); gr->Rotate(60,40);
  a.Diff2("y"); gr->Surf(a);  gr->Box();
  gr->Puts(mglPoint(0.7,1,1.2),"\\int {d^2}a/dxdy dx");
  return 0;
}

Data smoothing (function smooth) is more interesting and important. This function has single argument which define type of smoothing and its direction. Now 3 methods are supported: ‘3’ – linear averaging by 3 points, ‘5’ – linear averaging by 5 points, and default one – quadratic averaging by 5 points.

MathGL also have some amazing functions which is not so important for data processing as useful for data plotting. There are functions for finding envelope (useful for plotting rapidly oscillating data), for data sewing (useful to removing jumps on the phase), for data resizing (interpolation). Let me demonstrate it:

int sample(mglGraph *gr)
{
  gr->SubPlot(2,2,0,"");  gr->Title("Envelop sample");
  mglData d1(1000); gr->Fill(d1,"exp(-8*x^2)*sin(10*pi*x)");
  gr->Axis();     gr->Plot(d1, "b");
  d1.Envelop('x');  gr->Plot(d1, "r");

  gr->SubPlot(2,2,1,"");  gr->Title("Smooth sample");
  mglData y0(30),y1,y2,y3;
  gr->SetRanges(0,1,0,1);
  gr->Fill(y0, "0.4*sin(pi*x) + 0.3*cos(1.5*pi*x) - 0.4*sin(2*pi*x)+0.5*rnd");

  y1=y0;  y1.Smooth("x3");
  y2=y0;  y2.Smooth("x5");
  y3=y0;  y3.Smooth("x");

  gr->Plot(y0,"{m7}:s", "legend 'none'"); //gr->AddLegend("none","k");
  gr->Plot(y1,"r", "legend ''3' style'");
  gr->Plot(y2,"g", "legend ''5' style'");
  gr->Plot(y3,"b", "legend 'default'");
  gr->Legend();   gr->Box();

  gr->SubPlot(2,2,2);   gr->Title("Sew sample");
  mglData d2(100, 100); gr->Fill(d2, "mod((y^2-(1-x)^2)/2,0.1)");
  gr->Rotate(50, 60);   gr->Light(true);  gr->Alpha(true);
  gr->Box();            gr->Surf(d2, "b");
  d2.Sew("xy", 0.1);  gr->Surf(d2, "r");

  gr->SubPlot(2,2,3);   gr->Title("Resize sample (interpolation)");
  mglData x0(10), v0(10), x1, v1;
  gr->Fill(x0,"rnd");     gr->Fill(v0,"rnd");
  x1 = x0.Resize(100);    v1 = v0.Resize(100);
  gr->Plot(x0,v0,"b+ ");  gr->Plot(x1,v1,"r-");
  gr->Label(x0,v0,"%n");
  return 0;
}

Also one can create new data arrays on base of the existing one: extract slice, row or column of data (subdata), summarize along a direction(s) (sum), find distribution of data elements (hist) and so on.

Another interesting feature of MathGL is interpolation and root-finding. There are several functions for linear and cubic spline interpolation (see Interpolation). Also there is a function evaluate which do interpolation of data array for values of each data element of index data. It look as indirect access to the data elements.

This function have inverse function solve which find array of indexes at which data array is equal to given value (i.e. work as root finding). But solve function have the issue – usually multidimensional data (2d and 3d ones) have an infinite number of indexes which give some value. This is contour lines for 2d data, or isosurface(s) for 3d data. So, solve function will return index only in given direction, assuming that other index(es) are the same as equidistant index(es) of original data. If data have multiple roots then second (and later) branches can be found by consecutive call(s) of solve function. Let me demonstrate this on the following sample.

int sample(mglGraph *gr)
{
  gr->SetRange('z',0,1);
  mglData x(20,30), y(20,30), z(20,30), xx,yy,zz;
  gr->Fill(x,"(x+2)/3*cos(pi*y)");
  gr->Fill(y,"(x+2)/3*sin(pi*y)");
  gr->Fill(z,"exp(-6*x^2-2*sin(pi*y)^2)");

  gr->SubPlot(2,1,0); gr->Title("Cartesian space");   gr->Rotate(30,-40);
  gr->Axis("xyzU");   gr->Box();  gr->Label('x',"x"); gr->Label('y',"y");
  gr->SetOrigin(1,1); gr->Grid("xy");
  gr->Mesh(x,y,z);

  // section along 'x' direction
  mglData u = x.Solve(0.5,'x');
  mglData v(u.nx);  v.Fill(0,1);
  xx = x.Evaluate(u,v);   yy = y.Evaluate(u,v);   zz = z.Evaluate(u,v);
  gr->Plot(xx,yy,zz,"k2o");

  // 1st section along 'y' direction
  mglData u1 = x.Solve(-0.5,'y');
  mglData v1(u1.nx);  v1.Fill(0,1);
  xx = x.Evaluate(v1,u1); yy = y.Evaluate(v1,u1); zz = z.Evaluate(v1,u1);
  gr->Plot(xx,yy,zz,"b2^");

  // 2nd section along 'y' direction
  mglData u2 = x.Solve(-0.5,'y',u1);
  xx = x.Evaluate(v1,u2); yy = y.Evaluate(v1,u2); zz = z.Evaluate(v1,u2);
  gr->Plot(xx,yy,zz,"r2v");

  gr->SubPlot(2,1,1); gr->Title("Accompanied space");
  gr->SetRanges(0,1,0,1); gr->SetOrigin(0,0);
  gr->Axis(); gr->Box();  gr->Label('x',"i"); gr->Label('y',"j");
  gr->Grid(z,"h");

  gr->Plot(u,v,"k2o");    gr->Line(mglPoint(0.4,0.5),mglPoint(0.8,0.5),"kA");
  gr->Plot(v1,u1,"b2^");  gr->Line(mglPoint(0.5,0.15),mglPoint(0.5,0.3),"bA");
  gr->Plot(v1,u2,"r2v");  gr->Line(mglPoint(0.5,0.7),mglPoint(0.5,0.85),"rA");
}

2.5.1 “Compound” graphics

As I noted above, MathGL functions (except the special one, like Clf()) do not erase the previous plotting but just add the new one. It allows one to draw “compound” plots easily. For example, popular Matlab command surfc can be emulated in MathGL by 2 calls:

  Surf(a);
  Cont(a, "_");     // draw contours at bottom

Here a is 2-dimensional data for the plotting, -1 is the value of z-coordinate at which the contour should be plotted (at the bottom in this example). Analogously, one can draw density plot instead of contour lines and so on.

Another nice plot is contour lines plotted directly on the surface:

  Light(true);       // switch on light for the surface
  Surf(a, "BbcyrR"); // select 'jet' colormap for the surface
  Cont(a, "y");      // and yellow color for contours

The possible difficulties arise in black&white case, when the color of the surface can be close to the color of a contour line. In that case I may suggest the following code:

  Light(true);   // switch on light for the surface
  Surf(a, "kw"); // select 'gray' colormap for the surface
  CAxis(-1,0);   // first draw for darker surface colors
  Cont(a, "w");  // white contours
  CAxis(0,1);    // now draw for brighter surface colors
  Cont(a, "k");  // black contours
  CAxis(-1,1);   // return color range to original state

The idea is to divide the color range on 2 parts (dark and bright) and to select the contrasting color for contour lines for each of part.

Similarly, one can plot flow thread over density plot of vector field amplitude (this is another amusing plot from Matlab) and so on. The list of compound graphics can be prolonged but I hope that the general idea is clear.

Just for illustration I put here following sample code:

int sample(mglGraph *gr)
{
  mglData a,b,d;  mgls_prepare2v(&a,&b);  d = a;
  for(int i=0;i<a.nx*a.ny;i++)  d.a[i] = hypot(a.a[i],b.a[i]);
  mglData c;  mgls_prepare3d(&c);
  mglData v(10);  v.Fill(-0.5,1);

  gr->SubPlot(2,2,1,"");  gr->Title("Flow + Dens");
  gr->Flow(a,b,"br"); gr->Dens(d,"BbcyrR"); gr->Box();

  gr->SubPlot(2,2,0); gr->Title("Surf + Cont"); gr->Rotate(50,60);
  gr->Light(true);  gr->Surf(a);  gr->Cont(a,"y");  gr->Box();

  gr->SubPlot(2,2,2); gr->Title("Mesh + Cont"); gr->Rotate(50,60);
  gr->Box();  gr->Mesh(a);  gr->Cont(a,"_");

  gr->SubPlot(2,2,3); gr->Title("Surf3 + ContF3");gr->Rotate(50,60);
  gr->Box();  gr->ContF3(v,c,"z",0);  gr->ContF3(v,c,"x");  gr->ContF3(v,c);
  gr->SetCutBox(mglPoint(0,-1,-1), mglPoint(1,0,1.1));
  gr->ContF3(v,c,"z",c.nz-1); gr->Surf3(-0.5,c);
  return 0;
}

2.5.2 Transparency and lighting

Here I want to show how transparency and lighting both and separately change the look of a surface. So, there is code and picture for that:

int sample(mglGraph *gr)
{
  mglData a;  mgls_prepare2d(&a);
  gr->SubPlot(2,2,0); gr->Title("default"); gr->Rotate(50,60);
  gr->Box();  gr->Surf(a);

  gr->SubPlot(2,2,1); gr->Title("light on");  gr->Rotate(50,60);
  gr->Box();  gr->Light(true);  gr->Surf(a);

  gr->SubPlot(2,2,3); gr->Title("alpha on; light on");  gr->Rotate(50,60);
  gr->Box();  gr->Alpha(true);  gr->Surf(a);

  gr->SubPlot(2,2,2); gr->Title("alpha on");  gr->Rotate(50,60);
  gr->Box();  gr->Light(false); gr->Surf(a);
  return 0;
}

2.5.3 Types of transparency

MathGL library has advanced features for setting and handling the surface transparency. The simplest way to add transparency is the using of function alpha. As a result, all further surfaces (and isosurfaces, density plots and so on) become transparent. However, their look can be additionally improved.

The value of transparency can be different from surface to surface. To do it just use SetAlphaDef before the drawing of the surface, or use option alpha (see Command options). If its value is close to 0 then the surface becomes more and more transparent. Contrary, if its value is close to 1 then the surface becomes practically non-transparent.

Also you can change the way how the light goes through overlapped surfaces. The function SetTranspType defines it. By default the usual transparency is used (‘0’) – surfaces below is less visible than the upper ones. A “glass-like” transparency (‘1’) has a different look – each surface just decreases the background light (the surfaces are commutable in this case).

A “neon-like” transparency (‘2’) has more interesting look. In this case a surface is the light source (like a lamp on the dark background) and just adds some intensity to the color. At this, the library sets automatically the black color for the background and changes the default line color to white.

As example I shall show several plots for different types of transparency. The code is the same except the values of SetTranspType function:

int sample(mglGraph *gr)
{
  gr->Alpha(true);  gr->Light(true);
  mglData a;  mgls_prepare2d(&a);
  gr->SetTranspType(0); gr->Clf();
  gr->SubPlot(2,2,0); gr->Rotate(50,60);  gr->Surf(a);  gr->Box();
  gr->SubPlot(2,2,1); gr->Rotate(50,60);  gr->Dens(a);  gr->Box();
  gr->SubPlot(2,2,2); gr->Rotate(50,60);  gr->Cont(a);  gr->Box();
  gr->SubPlot(2,2,3); gr->Rotate(50,60);  gr->Axial(a); gr->Box();
  return 0;
}

2.5.4 Axis projection

You can easily make 3D plot and draw its x-,y-,z-projections (like in CAD) by using ternary function with arguments: 4 for Cartesian, 5 for Ternary and 6 for Quaternary coordinates. The sample code is:

int sample(mglGraph *gr)
{
  gr->SetRanges(0,1,0,1,0,1);
  mglData x(50),y(50),z(50),rx(10),ry(10), a(20,30);
  a.Modify("30*x*y*(1-x-y)^2*(x+y<1)");
  x.Modify("0.25*(1+cos(2*pi*x))");
  y.Modify("0.25*(1+sin(2*pi*x))");
  rx.Modify("rnd"); ry.Modify("(1-v)*rnd",rx);
  z.Modify("x");

  gr->Title("Projection sample");
  gr->Ternary(4);
  gr->Rotate(50,60);      gr->Light(true);
  gr->Plot(x,y,z,"r2");   gr->Surf(a,"#");
  gr->Axis(); gr->Grid(); gr->Box();
  gr->Label('x',"X",1);   gr->Label('y',"Y",1);   gr->Label('z',"Z",1);
}

2.5.5 Adding fog

MathGL can add a fog to the image. Its switching on is rather simple – just use fog function. There is the only feature – fog is applied for whole image. Not to particular subplot. The sample code is:

int sample(mglGraph *gr)
{
  mglData a;  mgls_prepare2d(&a);
  gr->Title("Fog sample");
  gr->Light(true);  gr->Rotate(50,60);  gr->Fog(1); gr->Box();
  gr->Surf(a);  gr->Cont(a,"y");
  return 0;
}

2.5.6 Lighting sample

In contrast to the most of other programs, MathGL supports several (up to 10) light sources. Moreover, the color each of them can be different: white (this is usual), yellow, red, cyan, green and so on. The use of several light sources may be interesting for the highlighting of some peculiarities of the plot or just to make an amusing picture. Note, each light source can be switched on/off individually. The sample code is:

int sample(mglGraph *gr)
{
  mglData a;  mgls_prepare2d(&a);
  gr->Title("Several light sources");
  gr->Rotate(50,60);  gr->Light(true);
  gr->AddLight(1,mglPoint(0,1,0),'c');
  gr->AddLight(2,mglPoint(1,0,0),'y');
  gr->AddLight(3,mglPoint(0,-1,0),'m');
  gr->Box();  gr->Surf(a,"h");
  return 0;
}

Additionally, you can use local light sources and set to use diffuse reflection instead of specular one (by default) or both kinds. Note, I use attachlight command to keep light settings relative to subplot.

int sample(mglGraph *gr)
{
  gr->Light(true);  gr->AttachLight(true);
  gr->SubPlot(2,2,0); gr->Title("Default"); gr->Rotate(50,60);
  gr->Line(mglPoint(-1,-0.7,1.7),mglPoint(-1,-0.7,0.7),"BA"); gr->Box();  gr->Surf(a);

  gr->SubPlot(2,2,1); gr->Title("Local");   gr->Rotate(50,60);
  gr->AddLight(0,mglPoint(1,0,1),mglPoint(-2,-1,-1));
  gr->Line(mglPoint(1,0,1),mglPoint(-1,-1,0),"BAO");  gr->Box();  gr->Surf(a);

  gr->SubPlot(2,2,2); gr->Title("no diffuse"); gr->Rotate(50,60);
  gr->SetDiffuse(0);
  gr->Line(mglPoint(1,0,1),mglPoint(-1,-1,0),"BAO");  gr->Box();  gr->Surf(a);

  gr->SubPlot(2,2,3); gr->Title("diffusive only");  gr->Rotate(50,60);
  gr->SetDiffuse(0.5);
  gr->AddLight(0,mglPoint(1,0,1),mglPoint(-2,-1,-1),'w',0);
  gr->Line(mglPoint(1,0,1),mglPoint(-1,-1,0),"BAO");  gr->Box();  gr->Surf(a);
}

2.5.7 Using primitives

MathGL provide a set of functions for drawing primitives (see Primitives). Primitives are low level object, which used by most of plotting functions. Picture below demonstrate some of commonly used primitives.

Generally, you can create arbitrary new kind of plot using primitives. For example, MathGL don’t provide any special functions for drawing molecules. However, you can do it using only one type of primitives drop. The sample code is:

int sample(mglGraph *gr)
{
  gr->Alpha(true);  gr->Light(true);

  gr->SubPlot(2,2,0,"");  gr->Title("Methane, CH_4");
  gr->StartGroup("Methane");
  gr->Rotate(60,120);
  gr->Sphere(mglPoint(0,0,0),0.25,"k");
  gr->Drop(mglPoint(0,0,0),mglPoint(0,0,1),0.35,"h",1,2);
  gr->Sphere(mglPoint(0,0,0.7),0.25,"g");
  gr->Drop(mglPoint(0,0,0),mglPoint(-0.94,0,-0.33),0.35,"h",1,2);
  gr->Sphere(mglPoint(-0.66,0,-0.23),0.25,"g");
  gr->Drop(mglPoint(0,0,0),mglPoint(0.47,0.82,-0.33),0.35,"h",1,2);
  gr->Sphere(mglPoint(0.33,0.57,-0.23),0.25,"g");
  gr->Drop(mglPoint(0,0,0),mglPoint(0.47,-0.82,-0.33),0.35,"h",1,2);
  gr->Sphere(mglPoint(0.33,-0.57,-0.23),0.25,"g");
  gr->EndGroup();

  gr->SubPlot(2,2,1,"");  gr->Title("Water, H_{2}O");
  gr->StartGroup("Water");
  gr->Rotate(60,100);
  gr->StartGroup("Water_O");
  gr->Sphere(mglPoint(0,0,0),0.25,"r");
  gr->EndGroup();
  gr->StartGroup("Water_Bond_1");
  gr->Drop(mglPoint(0,0,0),mglPoint(0.3,0.5,0),0.3,"m",1,2);
  gr->EndGroup();
  gr->StartGroup("Water_H_1");
  gr->Sphere(mglPoint(0.3,0.5,0),0.25,"g");
  gr->EndGroup();
  gr->StartGroup("Water_Bond_2");
  gr->Drop(mglPoint(0,0,0),mglPoint(0.3,-0.5,0),0.3,"m",1,2);
  gr->EndGroup();
  gr->StartGroup("Water_H_2");
  gr->Sphere(mglPoint(0.3,-0.5,0),0.25,"g");
  gr->EndGroup();
  gr->EndGroup();

  gr->SubPlot(2,2,2,"");  gr->Title("Oxygen, O_2");
  gr->StartGroup("Oxygen");
  gr->Rotate(60,120);
  gr->Drop(mglPoint(0,0.5,0),mglPoint(0,-0.3,0),0.3,"m",1,2);
  gr->Sphere(mglPoint(0,0.5,0),0.25,"r");
  gr->Drop(mglPoint(0,-0.5,0),mglPoint(0,0.3,0),0.3,"m",1,2);
  gr->Sphere(mglPoint(0,-0.5,0),0.25,"r");
  gr->EndGroup();

  gr->SubPlot(2,2,3,"");  gr->Title("Ammonia, NH_3");
  gr->StartGroup("Ammonia");
  gr->Rotate(60,120);
  gr->Sphere(mglPoint(0,0,0),0.25,"b");
  gr->Drop(mglPoint(0,0,0),mglPoint(0.33,0.57,0),0.32,"n",1,2);
  gr->Sphere(mglPoint(0.33,0.57,0),0.25,"g");
  gr->Drop(mglPoint(0,0,0),mglPoint(0.33,-0.57,0),0.32,"n",1,2);
  gr->Sphere(mglPoint(0.33,-0.57,0),0.25,"g");
  gr->Drop(mglPoint(0,0,0),mglPoint(-0.65,0,0),0.32,"n",1,2);
  gr->Sphere(mglPoint(-0.65,0,0),0.25,"g");
  gr->EndGroup();
  return 0;
}

Moreover, some of special plots can be more easily produced by primitives rather than by specialized function. For example, Venn diagram can be produced by Error plot:

int sample(mglGraph *gr)
{
  double xx[3]={-0.3,0,0.3}, yy[3]={0.3,-0.3,0.3}, ee[3]={0.7,0.7,0.7};
  mglData x(3,xx), y(3,yy), e(3,ee);
  gr->Title("Venn-like diagram"); gr->Alpha(true);
  gr->Error(x,y,e,e,"!rgb@#o");
  return 0;
}

You see that you have to specify and fill 3 data arrays. The same picture can be produced by just 3 calls of circle function:

int sample(mglGraph *gr)
{
  gr->Title("Venn-like diagram"); gr->Alpha(true);
  gr->Circle(mglPoint(-0.3,0.3),0.7,"rr@");
  gr->Circle(mglPoint(0,-0.3),0.7,"gg@");
  gr->Circle(mglPoint( 0.3,0.3),0.7,"bb@");
  return 0;
}

Of course, the first variant is more suitable if you need to plot a lot of circles. But for few ones the usage of primitives looks easy.

2.5.8 STFA sample

Short-time Fourier Analysis (stfa) is one of informative method for analyzing long rapidly oscillating 1D data arrays. It is used to determine the sinusoidal frequency and phase content of local sections of a signal as it changes over time.

MathGL can find and draw STFA result. Just to show this feature I give following sample. Initial data arrays is 1D arrays with step-like frequency. Exactly this you can see at bottom on the STFA plot. The sample code is:

int sample(mglGraph *gr)
{
  mglData a(2000), b(2000);
  gr->Fill(a,"cos(50*pi*x)*(x<-.5)+cos(100*pi*x)*(x<0)*(x>-.5)+\
  cos(200*pi*x)*(x<.5)*(x>0)+cos(400*pi*x)*(x>.5)");
  gr->SubPlot(1, 2, 0,"<_");  gr->Title("Initial signal");
  gr->Plot(a);
  gr->Axis();
  gr->Label('x', "\\i t");

  gr->SubPlot(1, 2, 1,"<_");  gr->Title("STFA plot");
  gr->STFA(a, b, 64);
  gr->Axis();
  gr->Label('x', "\\i t");
  gr->Label('y', "\\omega", 0);
  return 0;
}

2.5.9 Mapping visualization

Sometime ago I worked with mapping and have a question about its visualization. Let me remember you that mapping is some transformation rule for one set of number to another one. The 1d mapping is just an ordinary function – it takes a number and transforms it to another one. The 2d mapping (which I used) is a pair of functions which take 2 numbers and transform them to another 2 ones. Except general plots (like surfc, surfa) there is a special plot – Arnold diagram. It shows the area which is the result of mapping of some initial area (usually square).

I tried to make such plot in map. It shows the set of points or set of faces, which final position is the result of mapping. At this, the color gives information about their initial position and the height describes Jacobian value of the transformation. Unfortunately, it looks good only for the simplest mapping but for the real multivalent quasi-chaotic mapping it produces a confusion. So, use it if you like :).

The sample code for mapping visualization is:

int sample(mglGraph *gr)
{
  mglData a(50, 40), b(50, 40);
  gr->Puts(mglPoint(0, 0), "\\to", ":C", -1.4);
  gr->SetRanges(-1,1,-1,1,-2,2);

  gr->SubPlot(2, 1, 0);
  gr->Fill(a,"x");  gr->Fill(b,"y");
  gr->Puts(mglPoint(0, 1.1), "\\{x, y\\}", ":C", -2);   gr->Box();
  gr->Map(a, b, "brgk");

  gr->SubPlot(2, 1, 1);
  gr->Fill(a,"(x^3+y^3)/2");  gr->Fill(b,"(x-y)/2");
  gr->Puts(mglPoint(0, 1.1), "\\{\\frac{x^3+y^3}{2}, \\frac{x-y}{2}\\}", ":C", -2);
  gr->Box();
  gr->Map(a, b, "brgk");
  return 0;
}

2.5.10 Data interpolation

There are many functions to get interpolated values of a data array. Basically all of them can be divided by 3 categories:

1. functions which return single value at given point (see Interpolation and mglGSpline() in Global functions);
2. functions subdata and evaluate for indirect access to data elements;
3. functions refill, gspline and datagrid which fill regular (rectangular) data array by interpolated values.

The usage of first category is rather straightforward and don’t need any special comments.

There is difference in indirect access functions. Function subdata use use step-like interpolation to handle correctly single nan values in the data array. Contrary, function evaluate use local spline interpolation, which give smoother output but spread nan values. So, subdata should be used for specific data elements (for example, for given column), and evaluate should be used for distributed elements (i.e. consider data array as some field). Following sample illustrates this difference:

int sample(mglGraph *gr)
{
  gr->SubPlot(1,1,0,"");  gr->Title("SubData vs Evaluate");
  mglData in(9), arg(99), e, s;
  gr->Fill(in,"x^3/1.1"); gr->Fill(arg,"4*x+4");
  gr->Plot(in,"ko ");     gr->Box();
  e = in.Evaluate(arg,false); gr->Plot(e,"b.","legend 'Evaluate'");
  s = in.SubData(arg);    gr->Plot(s,"r.","legend 'SubData'");
  gr->Legend(2);
}

Example of datagrid usage is done in Making regular data. Here I want to show the peculiarities of refill and gspline functions. Both functions require argument(s) which provide coordinates of the data values, and return rectangular data array which equidistantly distributed in axis range. So, in opposite to evaluate function, refill and gspline can interpolate non-equidistantly distributed data. At this both functions refill and gspline provide continuity of 2nd derivatives along coordinate(s). However, refill is slower but give better (from human point of view) result than global spline gspline due to more advanced algorithm. Following sample illustrates this difference:

int sample(mglGraph *gr)
{
  mglData x(10), y(10), r(100);
  x.Modify("0.5+rnd");  x.CumSum("x");  x.Norm(-1,1);
  y.Modify("sin(pi*v)/1.5",x);
  gr->SubPlot(2,2,0,"<_");  gr->Title("Refill sample");
  gr->Axis();  gr->Box(); gr->Plot(x,y,"o ");
  gr->Refill(r,x,y);  // or you can use r.Refill(x,y,-1,1);
  gr->Plot(r,"r");  gr->FPlot("sin(pi*x)/1.5","B:");
  gr->SubPlot(2,2,1,"<_");gr->Title("Global spline");
  gr->Axis();  gr->Box(); gr->Plot(x,y,"o ");
  r.RefillGS(x,y,-1,1);   gr->Plot(r,"r");
  gr->FPlot("sin(pi*x)/1.5","B:");

  gr->Alpha(true);  gr->Light(true);
  mglData z(10,10), xx(10,10), yy(10,10), rr(100,100);
  y.Modify("0.5+rnd");  y.CumSum("x");  y.Norm(-1,1);
  for(int i=0;i<10;i++) for(int j=0;j<10;j++)
    z.a[i+10*j] = sin(M_PI*x.a[i]*y.a[j])/1.5;
  gr->SubPlot(2,2,2); gr->Title("2d regular");  gr->Rotate(40,60);
  gr->Axis();  gr->Box(); gr->Mesh(x,y,z,"k");
  gr->Refill(rr,x,y,z); gr->Surf(rr);

  gr->Fill(xx,"(x+1)/2*cos(y*pi/2-1)");
  gr->Fill(yy,"(x+1)/2*sin(y*pi/2-1)");
  for(int i=0;i<10*10;i++)
    z.a[i] = sin(M_PI*xx.a[i]*yy.a[i])/1.5;
  gr->SubPlot(2,2,3); gr->Title("2d non-regular");  gr->Rotate(40,60);
  gr->Axis();  gr->Box();  gr->Plot(xx,yy,z,"ko ");
  gr->Refill(rr,xx,yy,z);  gr->Surf(rr);
}

2.5.11 Making regular data

Sometimes, one have only unregular data, like as data on triangular grids, or experimental results and so on. Such kind of data cannot be used as simple as regular data (like matrices). Only few functions, like dots, can handle unregular data as is.

However, one can use built in triangulation functions for interpolating unregular data points to a regular data grids. There are 2 ways. First way, one can use triangulation function to obtain list of vertexes for triangles. Later this list can be used in functions like triplot or tricont. Second way consist in usage of datagrid function, which fill regular data grid by interpolated values, assuming that coordinates of the data grid is equidistantly distributed in axis range. Note, you can use options (see Command options) to change default axis range as well as in other plotting functions.

int sample(mglGraph *gr)
{
  mglData x(100), y(100), z(100);
  gr->Fill(x,"2*rnd-1"); gr->Fill(y,"2*rnd-1"); gr->Fill(z,"v^2-w^2",x,y);
  // first way - plot triangular surface for points
  mglData d = mglTriangulation(x,y);
  gr->Title("Triangulation");
  gr->Rotate(40,60);	gr->Box();	gr->Light(true);
  gr->TriPlot(d,x,y,z);	gr->TriPlot(d,x,y,z,"#k");
  // second way - make regular data and plot it
  mglData g(30,30);
  gr->DataGrid(g,x,y,z);	gr->Mesh(g,"m");
}

2.5.12 Making histogram

Using the hist function(s) for making regular distributions is one of useful fast methods to process and plot irregular data. Hist can be used to find some momentum of set of points by specifying weight function. It is possible to create not only 1D distributions but also 2D and 3D ones. Below I place the simplest sample code which demonstrate hist usage:

int sample(mglGraph *gr)
{
  mglData x(10000), y(10000), z(10000);  gr->Fill(x,"2*rnd-1");
  gr->Fill(y,"2*rnd-1"); gr->Fill(z,"exp(-6*(v^2+w^2))",x,y);
  mglData xx=gr->Hist(x,z), yy=gr->Hist(y,z);	xx.Norm(0,1);
  yy.Norm(0,1);
  gr->MultiPlot(3,3,3,2,2,"");   gr->SetRanges(-1,1,-1,1,0,1);
  gr->Box();  gr->Dots(x,y,z,"wyrRk");
  gr->MultiPlot(3,3,0,2,1,"");   gr->SetRanges(-1,1,0,1);
  gr->Box();  gr->Bars(xx);
  gr->MultiPlot(3,3,5,1,2,"");   gr->SetRanges(0,1,-1,1);
  gr->Box();  gr->Barh(yy);
  gr->SubPlot(3,3,2);
  gr->Puts(mglPoint(0.5,0.5),"Hist and\nMultiPlot\nsample","a",-6);
  return 0;
}

2.5.13 Nonlinear fitting hints

Nonlinear fitting is rather simple. All that you need is the data to fit, the approximation formula and the list of coefficients to fit (better with its initial guess values). Let me demonstrate it on the following simple example. First, let us use sin function with some random noise:

  mglData dat(100), in(100); //data to be fitted and ideal data
  gr->Fill(dat,"0.4*rnd+0.1+sin(2*pi*x)");
  gr->Fill(in,"0.3+sin(2*pi*x)");

and plot it to see that data we will fit

  gr->Title("Fitting sample");
  gr->SetRange('y',-2,2); gr->Box();  gr->Plot(dat, "k. ");
  gr->Axis(); gr->Plot(in, "b");
  gr->Puts(mglPoint(0, 2.2), "initial: y = 0.3+sin(2\\pi x)", "b");

The next step is the fitting itself. For that let me specify an initial values ini for coefficients ‘abc’ and do the fitting for approximation formula ‘a+b*sin(c*x)’

  mreal ini[3] = {1,1,3};
  mglData Ini(3,ini);
  mglData res = gr->Fit(dat, "a+b*sin(c*x)", "abc", Ini);

Now display it

  gr->Plot(res, "r");
  gr->Puts(mglPoint(-0.9, -1.3), "fitted:", "r:L");
  gr->PutsFit(mglPoint(0, -1.8), "y = ", "r");

NOTE! the fitting results may have strong dependence on initial values for coefficients due to algorithm features. The problem is that in general case there are several local "optimums" for coefficients and the program returns only first found one! There are no guaranties that it will be the best. Try for example to set ini[3] = {0, 0, 0} in the code above.

The full sample code for nonlinear fitting is:

int sample(mglGraph *gr)
{
  mglData dat(100), in(100);
  gr->Fill(dat,"0.4*rnd+0.1+sin(2*pi*x)");
  gr->Fill(in,"0.3+sin(2*pi*x)");
  mreal ini[3] = {1,1,3};
  mglData Ini(3,ini);

  mglData res = gr->Fit(dat, "a+b*sin(c*x)", "abc", Ini);

  gr->Title("Fitting sample");
  gr->SetRange('y',-2,2); gr->Box();  gr->Plot(dat, "k. ");
  gr->Axis();   gr->Plot(res, "r"); gr->Plot(in, "b");
  gr->Puts(mglPoint(-0.9, -1.3), "fitted:", "r:L");
  gr->PutsFit(mglPoint(0, -1.8), "y = ", "r");
  gr->Puts(mglPoint(0, 2.2), "initial: y = 0.3+sin(2\\pi x)", "b");
  return 0;
}

2.5.14 PDE solving hints

Solving of Partial Differential Equations (PDE, including beam tracing) and ray tracing (or finding particle trajectory) are more or less common task. So, MathGL have several functions for that. There are ray for ray tracing, pde for PDE solving, qo2d for beam tracing in 2D case (see Global functions). Note, that these functions take “Hamiltonian” or equations as string values. And I don’t plan now to allow one to use user-defined functions. There are 2 reasons: the complexity of corresponding interface; and the basic nature of used methods which are good for samples but may not good for serious scientific calculations.

The ray tracing can be done by ray function. Really ray tracing equation is Hamiltonian equation for 3D space. So, the function can be also used for finding a particle trajectory (i.e. solve Hamiltonian ODE) for 1D, 2D or 3D cases. The function have a set of arguments. First of all, it is Hamiltonian which defined the media (or the equation) you are planning to use. The Hamiltonian is defined by string which may depend on coordinates ‘x’, ‘y’, ‘z’, time ‘t’ (for particle dynamics) and momentums ‘p’=p_x, ‘q’=p_y, ‘v’=p_z. Next, you have to define the initial conditions for coordinates and momentums at ‘t’=0 and set the integrations step (default is 0.1) and its duration (default is 10). The Runge-Kutta method of 4-th order is used for integration.

  const char *ham = "p^2+q^2-x-1+i*0.5*(y+x)*(y>-x)";
  mglData r = mglRay(ham, mglPoint(-0.7, -1), mglPoint(0, 0.5), 0.02, 2);

This example calculate the reflection from linear layer (media with Hamiltonian ‘p^2+q^2-x-1’=p_x^2+p_y^2-x-1). This is parabolic curve. The resulting array have 7 columns which contain data for {x,y,z,p,q,v,t}.

The solution of PDE is a bit more complicated. As previous you have to specify the equation as pseudo-differential operator \hat H(x, \nabla) which is called sometime as “Hamiltonian” (for example, in beam tracing). As previously, it is defined by string which may depend on coordinates ‘x’, ‘y’, ‘z’ (but not time!), momentums ‘p’=(d/dx)/i k_0, ‘q’=(d/dy)/i k_0 and field amplitude ‘u’=|u|. The evolutionary coordinate is ‘z’ in all cases. So that, the equation look like du/dz = ik_0 H(x,y,\hat p, \hat q, |u|)[u]. Dependence on field amplitude ‘u’=|u| allows one to solve nonlinear problems too. For example, for nonlinear Shrodinger equation you may set ham="p^2 + q^2 - u^2". Also you may specify imaginary part for wave absorption, like ham = "p^2 + i*x*(x>0)" or ham = "p^2 + i1*x*(x>0)".

Next step is specifying the initial conditions at ‘z’ equal to minimal z-axis value. The function need 2 arrays for real and for imaginary part. Note, that coordinates x,y,z are supposed to be in specified axis range. So, the data arrays should have corresponding scales. Finally, you may set the integration step and parameter k0=k_0. Also keep in mind, that internally the 2 times large box is used (for suppressing numerical reflection from boundaries) and the equation should well defined even in this extended range.

Final comment is concerning the possible form of pseudo-differential operator H. At this moment, simplified form of operator H is supported – all “mixed” terms (like ‘x*p’->x*d/dx) are excluded. For example, in 2D case this operator is effectively H = f(p,z) + g(x,z,u). However commutable combinations (like ‘x*q’->x*d/dy) are allowed for 3D case.

So, for example let solve the equation for beam deflected from linear layer and absorbed later. The operator will have the form ‘"p^2+q^2-x-1+i*0.5*(z+x)*(z>-x)"’ that correspond to equation 1/ik_0 * du/dz + d^2 u/dx^2 + d^2 u/dy^2 + x * u + i (x+z)/2 * u = 0. This is typical equation for Electron Cyclotron (EC) absorption in magnetized plasmas. For initial conditions let me select the beam with plane phase front exp(-48*(x+0.7)^2). The corresponding code looks like this:

int sample(mglGraph *gr)
{
  mglData a,re(128),im(128);
  gr->Fill(re,"exp(-48*(x+0.7)^2)");
  a = gr->PDE("p^2+q^2-x-1+i*0.5*(z+x)*(z>-x)", re, im, 0.01, 30);
  a.Transpose("yxz");
  gr->SubPlot(1,1,0,"<_"); gr->Title("PDE solver");
  gr->SetRange('c',0,1);  gr->Dens(a,"wyrRk");
  gr->Axis(); gr->Label('x', "\\i x");  gr->Label('y', "\\i z");
  gr->FPlot("-x", "k|");
  gr->Puts(mglPoint(0, 0.85), "absorption: (x+z)/2 for x+z>0");
  gr->Puts(mglPoint(0,1.1),"Equation: ik_0\\partial_zu + \\Delta u + x\\cdot u + i \\frac{x+z}{2}\\cdot u = 0");
  return 0;
}

The next example is the beam tracing. Beam tracing equation is special kind of PDE equation written in coordinates accompanied to a ray. Generally this is the same parameters and limitation as for PDE solving but the coordinates are defined by the ray and by parameter of grid width w in direction transverse the ray. So, you don’t need to specify the range of coordinates. BUT there is limitation. The accompanied coordinates are well defined only for smooth enough rays, i.e. then the ray curvature K (which is defined as 1/K^2 = (|r''|^2 |r'|^2 - (r'', r'')^2)/|r'|^6) is much large then the grid width: K>>w. So, you may receive incorrect results if this condition will be broken.

You may use following code for obtaining the same solution as in previous example:

int sample(mglGraph *gr)
{
  mglData r, xx, yy, a, im(128), re(128);
  const char *ham = "p^2+q^2-x-1+i*0.5*(y+x)*(y>-x)";
  r = mglRay(ham, mglPoint(-0.7, -1), mglPoint(0, 0.5), 0.02, 2);
  gr->SubPlot(1,1,0,"<_"); gr->Title("Beam and ray tracing");
  gr->Plot(r.SubData(0), r.SubData(1), "k");
  gr->Axis(); gr->Label('x', "\\i x");  gr->Label('y', "\\i z");

  // now start beam tracing
  gr->Fill(re,"exp(-48*x^2)");
  a = mglQO2d(ham, re, im, r, xx, yy, 1, 30);
  gr->SetRange('c',0, 1);
  gr->Dens(xx, yy, a, "wyrRk");
  gr->FPlot("-x", "k|");
  gr->Puts(mglPoint(0, 0.85), "absorption: (x+y)/2 for x+y>0");
  gr->Puts(mglPoint(0.7, -0.05), "central ray");
  return 0;
}

Note, the pde is fast enough and suitable for many cases routine. However, there is situations then media have both together: strong spatial dispersion and spatial inhomogeneity. In this, case the pde will produce incorrect result and you need to use advanced PDE solver apde. For example, a wave beam, propagated in plasma, described by Hamiltonian exp(-x^2-p^2), will have different solution for using of simplification and advanced PDE solver:

int sample(mglGraph *gr)
{
  gr->SetRanges(-1,1,0,2,0,2);
  mglData ar(256), ai(256);	gr->Fill(ar,"exp(-2*x^2)");

  mglData res1(gr->APDE("exp(-x^2-p^2)",ar,ai,0.01));	res1.Transpose();
  gr->SubPlot(1,2,0,"_");	gr->Title("Advanced PDE solver");
  gr->SetRanges(0,2,-1,1);	gr->SetRange('c',res1);
  gr->Dens(res1);	gr->Axis();	gr->Box();
  gr->Label('x',"\\i z");	gr->Label('y',"\\i x");
  gr->Puts(mglPoint(-0.5,0.2),"i\\partial_z\\i u = exp(-\\i x^2+\\partial_x^2)[\\i u]","y");

  mglData res2(gr->PDE("exp(-x^2-p^2)",ar,ai,0.01));
  gr->SubPlot(1,2,1,"_");	gr->Title("Simplified PDE solver");
  gr->Dens(res2);	gr->Axis();	gr->Box();
  gr->Label('x',"\\i z");	gr->Label('y',"\\i x");
  gr->Puts(mglPoint(-0.5,0.2),"i\\partial_z\\i u \\approx\\ exp(-\\i x^2)\\i u+exp(\\partial_x^2)[\\i u]","y");
  return 0;
}

2.5.15 Drawing phase plain

Here I want say a few words of plotting phase plains. Phase plain is name for system of coordinates x, x', i.e. a variable and its time derivative. Plot in phase plain is very useful for qualitative analysis of an ODE, because such plot is rude (it topologically the same for a range of ODE parameters). Most often the phase plain {x, x'} is used (due to its simplicity), that allows one to analyze up to the 2nd order ODE (i.e. x''+f(x,x')=0).

The simplest way to draw phase plain in MathGL is using flow function(s), which automatically select several points and draw flow threads. If the ODE have an integral of motion (like Hamiltonian H(x,x')=const for dissipation-free case) then you can use cont function for plotting isolines (contours). In fact. isolines are the same as flow threads, but without arrows on it. Finally, you can directly solve ODE using ode function and plot its numerical solution.

Let demonstrate this for ODE equation x''-x+3*x^2=0. This is nonlinear oscillator with square nonlinearity. It has integral H=y^2+2*x^3-x^2=Const. Also it have 2 typical stationary points: saddle at {x=0, y=0} and center at {x=1/3, y=0}. Motion at vicinity of center is just simple oscillations, and is stable to small variation of parameters. In opposite, motion around saddle point is non-stable to small variation of parameters, and is very slow. So, calculation around saddle points are more difficult, but more important. Saddle points are responsible for solitons, stochasticity and so on.

So, let draw this phase plain by 3 different methods. First, draw isolines for H=y^2+2*x^3-x^2=Const – this is simplest for ODE without dissipation. Next, draw flow threads – this is straightforward way, but the automatic choice of starting points is not always optimal. Finally, use ode to check the above plots. At this we need to run ode in both direction of time (in future and in the past) to draw whole plain. Alternatively, one can put starting points far from (or at the bounding box as done in flow) the plot, but this is a more complicated. The sample code is:

int sample(mglGraph *gr)
{
  gr->SubPlot(2,2,0,"<_");  gr->Title("Cont");  gr->Box();
  gr->Axis();  gr->Label('x',"x");  gr->Label('y',"\\dot{x}");
  mglData f(100,100);   gr->Fill(f,"y^2+2*x^3-x^2-0.5");
  gr->Cont(f);
  gr->SubPlot(2,2,1,"<_");  gr->Title("Flow");  gr->Box();
  gr->Axis();  gr->Label('x',"x");  gr->Label('y',"\\dot{x}");
  mglData fx(100,100), fy(100,100);
  gr->Fill(fx,"x-3*x^2");  gr->Fill(fy,"y");
  gr->Flow(fy,fx,"v","value 7");
  gr->SubPlot(2,2,2,"<_");  gr->Title("ODE");   gr->Box();
  gr->Axis();  gr->Label('x',"x");  gr->Label('y',"\\dot{x}");
  for(double x=-1;x<1;x+=0.1)
  {
    mglData in(2), r;   in.a[0]=x;
    r = mglODE("y;x-3*x^2","xy",in);
    gr->Plot(r.SubData(0), r.SubData(1));
    r = mglODE("-y;-x+3*x^2","xy",in);
    gr->Plot(r.SubData(0), r.SubData(1));
  }
}

2.5.16 Pulse properties

There is common task in optics to determine properties of wave pulses or wave beams. MathGL provide special function pulse which return the pulse properties (maximal value, center of mass, width and so on). Its usage is rather simple. Here I just illustrate it on the example of Gaussian pulse, where all parameters are obvious.

void sample(mglGraph *gr)
{
  gr->SubPlot(1,1,0,"<_");  gr->Title("Pulse sample");
  // first prepare pulse itself
  mglData a(100); gr->Fill(a,"exp(-6*x^2)");
  // get pulse parameters
  mglData b(a.Pulse('x'));
  // positions and widths are normalized on the number of points. So, set proper axis scale.
  gr->SetRanges(0, a.nx-1, 0, 1);
  gr->Axis(); gr->Plot(a);  // draw pulse and axis
  // now visualize found pulse properties
  double m = b[0];  // maximal amplitude
  // approximate position of maximum
  gr->Line(mglPoint(b[1],0), mglPoint(b[1],m),"r=");
  // width at half-maximum (so called FWHM)
  gr->Line(mglPoint(b[1]-b[3]/2,0), mglPoint(b[1]-b[3]/2,m),"m|");
  gr->Line(mglPoint(b[1]+b[3]/2,0), mglPoint(b[1]+b[3]/2,m),"m|");
  gr->Line(mglPoint(0,m/2), mglPoint(a.nx-1,m/2),"h");
  // parabolic approximation near maximum
  char func[128];	sprintf(func,"%g*(1-((x-%g)/%g)^2)",b[0],b[1],b[2]);
  gr->FPlot(func,"g");
}

2.5.17 Using MGL parser

Sometimes you may prefer to use MGL scripts in yours code. It is simpler (especially in comparison with C/Fortran interfaces) and provide faster way to plot the data with annotations, labels and so on. Class mglParse (see mglParse class parse MGL scripts in C++. It have also the corresponding interface for C/Fortran.

The key function here is mglParse::Parse() (or mgl_parse() for C/Fortran) which execute one command per string. At this the detailed information about the possible errors or warnings is passed as function value. Or you may execute the whole script as long string with lines separated by ‘\n’. Functions mglParse::Execute() and mgl_parse_text() perform it. Also you may set the values of parameters ‘$0’...‘$9’ for the script by functions mglParse::AddParam() or mgl_add_param(), allow/disable picture resizing, check “once” status and so on. The usage is rather straight-forward.

The only non-obvious thing is data transition between script and yours program. There are 2 stages: add or find variable; and set data to variable. In C++ you may use functions mglParse::AddVar() and mglParse::FindVar() which return pointer to mglData. In C/Fortran the corresponding functions are mgl_add_var(), mgl_find_var(). This data pointer is valid until next Parse() or Execute() call. Note, you must not delete or free the data obtained from these functions!

So, some simple example at the end. Here I define a data array, create variable, put data into it and plot it. The C++ code looks like this:

int sample(mglGraph *gr)
{
  gr->Title("MGL parser sample");
  mreal a[100];   // let a_i = sin(4*pi*x), x=0...1
  for(int i=0;i<100;i++)a[i]=sin(4*M_PI*i/99);
  mglParse *parser = new mglParse;
  mglData *d = parser->AddVar("dat");
  d->Set(a,100); // set data to variable
  parser->Execute(gr, "plot dat; xrange 0 1\nbox\naxis");
  // you may break script at any line do something
  // and continue after that
  parser->Execute(gr, "xlabel 'x'\nylabel 'y'\nbox");
  // also you may use cycles or conditions in script
  parser->Execute(gr, "for $0 -1 1 0.1\nif $0<0\n"
    "line 0 0 -1 $0 'r':else:line 0 0 -1 $0 'g'\n"
    "endif\nnext");
  delete parser;
  return 0;
}

The code in C/Fortran looks practically the same:

int sample(HMGL gr)
{
  mgl_title(gr, "MGL parser sample", "", -2);
  double a[100];   // let a_i = sin(4*pi*x), x=0...1
  int i;
  for(i=0;i<100;i++)  a[i]=sin(4*M_PI*i/99);
  HMPR parser = mgl_create_parser();
  HMDT d = mgl_parser_add_var(parser, "dat");
  mgl_data_set_double(d,a,100,1,1);    // set data to variable
  mgl_parse_text(gr, parser, "plot dat; xrange 0 1\nbox\naxis");
  // you may break script at any line do something
  // and continue after that
  mgl_parse_text(gr, parser, "xlabel 'x'\nylabel 'y'");
  // also you may use cycles or conditions in script
  mgl_parse_text(gr, parser, "for $0 -1 1 0.1\nif $0<0\n"
    "line 0 0 -1 $0 'r':else:line 0 0 -1 $0 'g'\n"
    "endif\nnext");
  mgl_write_png(gr, "test.png", "");  // don't forgot to save picture
  return 0;
}

2.5.18 Using options

Command options allow the easy setup of the selected plot by changing global settings only for this plot. Often, options are used for specifying the range of automatic variables (coordinates). However, options allows easily change plot transparency, numbers of line or faces to be drawn, or add legend entries. The sample function for options usage is:

void template(mglGraph *gr)
{
  mglData a(31,41);
  gr->Fill(a,"-pi*x*exp(-(y+1)^2-4*x^2)");

  gr->SubPlot(2,2,0);	gr->Title("Options for coordinates");
  gr->Alpha(true);	gr->Light(true);
  gr->Rotate(40,60);    gr->Box();
  gr->Surf(a,"r","yrange 0 1"); gr->Surf(a,"b","yrange 0 -1");
  if(mini)	return;
  gr->SubPlot(2,2,1);   gr->Title("Option 'meshnum'");
  gr->Rotate(40,60);    gr->Box();
  gr->Mesh(a,"r","yrange 0 1"); gr->Mesh(a,"b","yrange 0 -1; meshnum 5");
  gr->SubPlot(2,2,2);   gr->Title("Option 'alpha'");
  gr->Rotate(40,60);    gr->Box();
  gr->Surf(a,"r","yrange 0 1; alpha 0.7");
  gr->Surf(a,"b","yrange 0 -1; alpha 0.3");
  gr->SubPlot(2,2,3,"<_");  gr->Title("Option 'legend'");
  gr->FPlot("x^3","r","legend 'y = x^3'");
  gr->FPlot("cos(pi*x)","b","legend 'y = cos \\pi x'");
  gr->Box();    gr->Axis(); gr->Legend(2,"");
}

2.5.19 “Templates”

As I have noted before, the change of settings will influence only for the further plotting commands. This allows one to create “template” function which will contain settings and primitive drawing for often used plots. Correspondingly one may call this template-function for drawing simplification.

For example, let one has a set of points (experimental or numerical) and wants to compare it with theoretical law (for example, with exponent law \exp(-x/2), x \in [0, 20]). The template-function for this task is:

void template(mglGraph *gr)
{
  mglData  law(100);      // create the law
  law.Modify("exp(-10*x)");
  gr->SetRanges(0,20, 0.0001,1);
  gr->SetFunc(0,"lg(y)",0);
  gr->Plot(law,"r2");
  gr->Puts(mglPoint(10,0.2),"Theoretical law: e^x","r:L");
  gr->Label('x',"x val."); gr->Label('y',"y val.");
  gr->Axis(); gr->Grid("xy","g;"); gr->Box();
}

At this, one will only write a few lines for data drawing:

  template(gr);     // apply settings and default drawing from template
  mglData dat("fname.dat"); // load the data
  // and draw it (suppose that data file have 2 columns)
  gr->Plot(dat.SubData(0),dat.SubData(1),"bx ");

A template-function can also contain settings for font, transparency, lightning, color scheme and so on.

I understand that this is obvious thing for any professional programmer, but I several times receive suggestion about “templates” ... So, I decide to point out it here.

2.5.20 Stereo image

One can easily create stereo image in MathGL. Stereo image can be produced by making two subplots with slightly different rotation angles. The corresponding code looks like this:

int sample(mglGraph *gr)
{
  mglData a;  mgls_prepare2d(&a);
  gr->Light(true);

  gr->SubPlot(2,1,0); gr->Rotate(50,60+1);
  gr->Box();  gr->Surf(a);

  gr->SubPlot(2,1,1); gr->Rotate(50,60-1);
  gr->Box();  gr->Surf(a);
  return 0;
}

2.5.21 Reduce memory usage

By default MathGL save all primitives in memory, rearrange it and only later draw them on bitmaps. Usually, this speed up drawing, but may require a lot of memory for plots which contain a lot of faces (like cloud, dew). You can use quality function for setting to use direct drawing on bitmap and bypassing keeping any primitives in memory. This function also allow you to decrease the quality of the resulting image but increase the speed of the drawing.

The code for lowest memory usage looks like this:

int sample(mglGraph *gr)
{
  gr->SetQuality(6);   // firstly, set to draw directly on bitmap
  for(i=0;i<1000;i++)
    gr->Sphere(mglPoint(mgl_rnd()*2-1,mgl_rnd()*2-1),0.05);
  return 0;
}

2.5.22 Scanning file

MathGL have possibilities to write textual information into file with variable values. In MGL script you can use save command for that. However, the usual printf(); is simple in C/C++ code. For example, lets create some textual file

FILE *fp=fopen("test.txt","w");
fprintf(fp,"This is test: 0 -> 1 q\n");
fprintf(fp,"This is test: 1 -> -1 q\n");
fprintf(fp,"This is test: 2 -> 0 q\n");
fclose(fp);

It contents look like

This is test: 0 -> 1 q
This is test: 1 -> -1 q
This is test: 2 -> 0 q

Let assume now that you want to read this values (i.e. [[0,1],[1,-1],[2,0]]) from the file. You can use scanfile for that. The desired values was written using template "This is test: %g -> %g q\n". So, just use

mglData a;
a.ScanFile("test.txt","This is test: %g -> %g");

and plot it to for assurance

gr->SetRanges(a.SubData(0), a.SubData(1));
gr->Axis();	gr->Plot(a.SubData(0),a.SubData(1),"o");

Note, I keep only the leading part of template (i.e. "This is test: %g -> %g" instead of "This is test: %g -> %g q\n"), because there is no important for us information after the second number in the line.

2.5.23 Mixing bitmap and vector output

Sometimes output plots contain surfaces with a lot of points, and some vector primitives (like axis, text, curves, etc.). Using vector output formats (like EPS or SVG) will produce huge files with possible loss of smoothed lighting. Contrary, the bitmap output may cause the roughness of text and curves. Hopefully, MathGL have a possibility to combine bitmap output for surfaces and vector one for other primitives in the same EPS file, by using rasterize command.

The idea is to prepare part of picture with surfaces or other "heavy" plots and produce the background image from them by help of rasterize command. Next, we draw everything to be saved in vector form (text, curves, axis and etc.). Note, that you need to clear primitives (use clf command) after rasterize if you want to disable duplication of surfaces in output files (like EPS). Note, that some of output formats (like 3D ones, and TeX) don’t support the background bitmap, and use clf for them will cause the loss of part of picture.

The sample code is:

// first draw everything to be in bitmap output
gr->FSurf("x^2+y^2", "#", "value 10");

gr->Rasterize();  // set above plots as bitmap background
gr->Clf();        // clear primitives, to exclude them from file

// now draw everything to be in vector output
gr->Axis(); gr->Box();

// and save file
gr->WriteFrame("fname.eps");

3.8.1 C/Fortran interface

The C interface is a base for many other interfaces. It contains the pure C functions for most of the methods of MathGL classes. In distinction to C++ classes, C functions must have an argument HMGL (for graphics) and/or HMDT (for data arrays), which specifies the object for drawing or manipulating (changing). So, firstly, the user has to create this object by the function mgl_create_*() and has to delete it after the use by function mgl_delete_*().

All C functions are described in the header file #include <mgl2/mgl_cf.h> and use variables of the following types:

• HMGL — Pointer to class mglGraph (see MathGL core).
• HCDT — Pointer to class const mglDataA (see Data processing) — constant data array.
• HMDT — Pointer to class mglData (see Data processing) — data array of real numbers.
• HADT — Pointer to class mglDataC (see Data processing) — data array of complex numbers.
• HMPR — Pointer to class mglParse (see mglParse class) — MGL script parsing.
• HMEX — Pointer to class mglExpr (see Evaluate expression) — textual formulas for real numbers.
• HMAX — Pointer to class mglExprC (see Evaluate expression) — textual formulas for complex numbers.

These variables contain identifiers for graphics drawing objects and for the data objects.

Fortran functions/subroutines have the same names as C functions. However, there is a difference. Variable of type HMGL, HMDT must be an integer with sufficient size (integer*4 in the 32-bit operating system or integer*8 in the 64-bit operating system). All C functions of type void are subroutines in Fortran, which are called by operator call. The exceptions are functions, which return variables of types HMGL or HMDT. These functions should be declared as integer in Fortran code. Also, one should keep in mind that strings in Fortran are denoted by ' symbol, not the " symbol.

3.8.2 C++/Python interface

MathGL provides the interface to a set of languages via SWIG library. Some of these languages support classes. The typical example is Python – which is named in this chapter’s title. Exactly the same classes are used for high-level C++ API. Its feature is using only inline member-functions what make high-level API to be independent on compiler even for binary build.

There are 3 main classes in:

• mglGraph – provide most plotting functions (see MathGL core).
• mglData – provide base data processing (see Data processing). It have an additional feature to access data values. You can use a construct like this: dat[i]=sth; or sth=dat[i] where flat representation of data is used (i.e., i can be in range 0...nx*nx*nz-1). You can also import NumPy arrays as input arguments in Python: mgl_dat = mglData(numpy_dat);.
• mglParse – provide functions for parsing MGL scripts (see MGL scripts).

To use Python classes just execute ‘import mathgl’. The simplest example will be:

import mathgl
a=mathgl.mglGraph()
a.Box()
a.WritePNG("test.png")

Alternatively you can import all classes from mathgl module and easily access MathGL classes like this:

from mathgl import *
a=mglGraph()
a.Box()
a.WritePNG("test.png")

This becomes useful if you create many mglData objects, for example.

4.2.1 Transparency

There are several functions and variables for setup transparency. The general function is alpha which switch on/off the transparency for overall plot. It influence only for graphics which created after alpha call (with one exception, OpenGL). Function alphadef specify the default value of alpha-channel. Finally, function transptype set the kind of transparency. See Transparency and lighting, for sample code and picture.

MGL command: alpha [val=on] ¶

Method on mglGraph: void Alpha (bool enable) ¶

C function: void mgl_set_alpha (HMGL gr, int enable) ¶

Sets the transparency on/off and returns previous value of transparency. It is recommended to call this function before any plotting command. Default value is transparency off.

MGL command: alphadef val ¶

Method on mglGraph: void SetAlphaDef (mreal val) ¶

C function: void mgl_set_alpha_default (HMGL gr, mreal alpha) ¶

Sets default value of alpha channel (transparency) for all plotting functions. Initial value is 0.5.

MGL command: transptype val ¶

Method on mglGraph: void SetTranspType (int type) ¶

C function: void mgl_set_transp_type (HMGL gr, int type) ¶

Set the type of transparency. Possible values are:

• Normal transparency (‘0’) – below things is less visible than upper ones. It does not look well in OpenGL mode (mglGraphGL) for several surfaces.
• Glass-like transparency (‘1’) – below and upper things are commutable and just decrease intensity of light by RGB channel.
• Lamp-like transparency (‘2’) – below and upper things are commutable and are the source of some additional light. I recommend to set SetAlphaDef(0.3) or less for lamp-like transparency.

See Types of transparency, for sample code and picture..

4.2.2 Lighting

There are several functions for setup lighting. The general function is light which switch on/off the lighting for overall plot. It influence only for graphics which created after light call (with one exception, OpenGL). Generally MathGL support up to 10 independent light sources. But in OpenGL mode only 8 of light sources is used due to OpenGL limitations. The position, color, brightness of each light source can be set separately. By default only one light source is active. It is source number 0 with white color, located at top of the plot. See Lighting sample, for sample code and picture.

MGL command: light [val=on] ¶

Method on mglGraph: bool Light (bool enable) ¶

C function: void mgl_set_light (HMGL gr, int enable) ¶

Sets the using of light on/off for overall plot. Function returns previous value of lighting. Default value is lightning off.

MGL command: light num val ¶

Method on mglGraph: void Light (int n, bool enable) ¶

C function: void mgl_set_light_n (HMGL gr, int n, int enable) ¶

Switch on/off n-th light source separately.

MGL command: light num xdir ydir zdir ['col'='w' br=0.5] ¶

MGL command: light num xdir ydir zdir xpos ypos zpos ['col'='w' br=0.5 ap=0] ¶

Method on mglGraph: void AddLight (int n, mglPoint d, char c='w', mreal bright=0.5, mreal ap=0) ¶

Method on mglGraph: void AddLight (int n, mglPoint r, mglPoint d, char c='w', mreal bright=0.5, mreal ap=0) ¶

C function: void mgl_add_light (HMGL gr, int n, mreal dx, mreal dy, mreal dz) ¶

C function: void mgl_add_light_ext (HMGL gr, int n, mreal dx, mreal dy, mreal dz, char c, mreal bright, mreal ap) ¶

C function: void mgl_add_light_loc (HMGL gr, int n, mreal rx, mreal ry, mreal rz, mreal dx, mreal dy, mreal dz, char c, mreal bright, mreal ap) ¶

The function adds a light source with identification n in direction d with color c and with brightness bright (which must be in range [0,1]). If position r is specified and isn’t NAN then light source is supposed to be local otherwise light source is supposed to be placed at infinity.

MGL command: diffuse val ¶

Method on mglGraph: void SetDiffuse (mreal bright) ¶

C function: void mgl_set_difbr (HMGL gr, mreal bright) ¶

Set brightness of diffusive light (only for local light sources).

MGL command: ambient val ¶

Method on mglGraph: void SetAmbient (mreal bright=0.5) ¶

C function: void mgl_set_ambbr (HMGL gr, mreal bright) ¶

Sets the brightness of ambient light. The value should be in range [0,1].

MGL command: attachlight val ¶

Method on mglGraph: void AttachLight (bool val) ¶

C function: void mgl_set_attach_light (HMGL gr, int val) ¶

Set to attach light settings to inplot/subplot. Note, OpenGL and some output formats don’t support this feature.

4.2.3 Fog

MGL command: fog val [dz=0.25] ¶

Method on mglGraph: void Fog (mreal d, mreal dz=0.25) ¶

C function: void mgl_set_fog (HMGL gr, mreal d, mreal dz) ¶

Function imitate a fog in the plot. Fog start from relative distance dz from view point and its density growths exponentially in depth. So that the fog influence is determined by law ~ 1-exp(-d*z). Here z is normalized to 1 depth of the plot. If value d=0 then the fog is absent. Note, that fog was applied at stage of image creation, not at stage of drawing. See Adding fog, for sample code and picture.

4.2.4 Default sizes

These variables control the default (initial) values for most graphics parameters including sizes of markers, arrows, line width and so on. As any other settings these ones will influence only on plots created after the settings change.

MGL command: barwidth val ¶

Method on mglGraph: void SetBarWidth ( mreal val) ¶

C function: void mgl_set_bar_width (HMGL gr, mreal val) ¶

Sets relative width of rectangles in bars, barh, boxplot, candle, ohlc. Default value is 0.7.

MGL command: marksize val ¶

Method on mglGraph: void SetMarkSize (mreal val) ¶

C function: void mgl_set_mark_size (HMGL gr, mreal val) ¶

Sets size of marks for 1D plotting. Default value is 1.

MGL command: arrowsize val ¶

Method on mglGraph: void SetArrowSize (mreal val) ¶

C function: void mgl_set_arrow_size (HMGL gr, mreal val) ¶

Sets size of arrows for 1D plotting, lines and curves (see Primitives). Default value is 1.

MGL command: meshnum val ¶

Method on mglGraph: void SetMeshNum (int val) ¶

C function: void mgl_set_meshnum (HMGL gr, int num) ¶

Sets approximate number of lines in mesh, fall, grid2, and also the number of hachures in vect, dew, and the number of cells in cloud, and the number of markers in plot, tens, step, mark, textmark. By default (=0) it draws all lines/hachures/cells/markers.

MGL command: facenum val ¶

Method on mglGraph: void SetFaceNum (int val) ¶

C function: void mgl_set_facenum (HMGL gr, int num) ¶

Sets approximate number of visible faces. Can be used for speeding up drawing by cost of lower quality. By default (=0) it draws all of them.

MGL command: plotid 'id' ¶

Method on mglGraph: void SetPlotId (const char *id) ¶

C function: void mgl_set_plotid (HMGL gr, const char *id) ¶

Sets default name id as filename for saving (in FLTK window for example).

Method on mglGraph: const char * GetPlotId () ¶

C function only: const char * mgl_get_plotid (HMGL gr) ¶

Fortran subroutine: mgl_get_plotid (long gr, char *out, int len) ¶

Gets default name id as filename for saving (in FLTK window for example).

MGL command: pendelta val ¶

Method on mglGraph: void SetPenDelta (double val) ¶

C function: void mgl_pen_delta (HMGL gr, double val) ¶

Changes the blur around lines and text (default is 1). For val>1 the text and lines are more sharped. For val<1 the text and lines are more blurred.

4.2.5 Cutting

These variables and functions set the condition when the points are excluded (cutted) from the drawing. Note, that a point with NAN value(s) of coordinate or amplitude will be automatically excluded from the drawing. See Cutting sample, for sample code and picture.

MGL command: cut val ¶

Method on mglGraph: void SetCut (bool val) ¶

C function: void mgl_set_cut (HMGL gr, int val) ¶

Flag which determines how points outside bounding box are drawn. If it is true then points are excluded from plot (it is default) otherwise the points are projected to edges of bounding box.

MGL command: cut x1 y1 z1 x2 y2 z2 ¶

Method on mglGraph: void SetCutBox (mglPoint p1, mglPoint p1) ¶

C function: void mgl_set_cut_box (HMGL gr, mreal x1, mreal y1, mreal z1, mreal x2, mreal y2, mreal z2) ¶

Lower and upper edge of the box in which never points are drawn. If both edges are the same (the variables are equal) then the cutting box is empty.

MGL command: cut 'cond' ¶

Method on mglGraph: void CutOff (const char *cond) ¶

C function: void mgl_set_cutoff (HMGL gr, const char *cond) ¶

Sets the cutting off condition by formula cond. This condition determine will point be plotted or not. If value of formula is nonzero then point is omitted, otherwise it plotted. Set argument as "" to disable cutting off condition.

4.2.6 Font settings

MGL command: font 'fnt' [val=6] ¶

Font style for text and labels (see text). Initial style is ’fnt’=’:rC’ give Roman font with centering. Parameter val sets the size of font for tick and axis labels. Default font size of axis labels is 1.4 times large than for tick labels. For more detail, see Font styles.

MGL command: rotatetext val ¶

Method on mglGraph: void SetRotatedText (bool val) ¶

C function: void mgl_set_rotated_text (HMGL gr, int val) ¶

Sets to use or not text rotation.

MGL command: scaletext val ¶

Method on mglGraph: void SetScaleText (bool val) ¶

C function: void mgl_set_scale_text (HMGL gr, int val) ¶

Sets to scale text in relative inplot (including columnplot, gridplot, stickplot, shearplot) or not.

MGL command: texparse val ¶

Method on mglGraph: void SetTeXparse (bool val) ¶

C function: void mgl_set_tex_parse (HMGL gr, int val) ¶

Enables/disables TeX-like command parsing at text output.

MGL command: loadfont ['name'=''] ¶

Method on mglGraph: void LoadFont (const char *name, const char *path="") ¶

C function: void mgl_load_font (HMGL gr, const char *name, const char *path) ¶

Load font typeface from path/name. Empty name will load default font.

Method on mglGraph: void SetFontDef (const char *fnt) ¶

C function: void mgl_set_font_def (HMGL gr, const char * val) ¶

Sets the font specification (see Text printing). Default is ‘rC’ – Roman font centering.

Method on mglGraph: void SetFontSize (mreal val) ¶

C function: void mgl_set_font_size (HMGL gr, mreal val) ¶

Sets the size of font for tick and axis labels. Default font size of axis labels is 1.4 times large than for tick labels.

Method on mglGraph: void SetFontSizePT (mreal cm, int dpi=72) ¶

Set FontSize by size in pt and picture DPI (default is 16 pt for dpi=72).

Method on mglGraph: inline void SetFontSizeCM (mreal cm, int dpi=72) ¶

Set FontSize by size in centimeters and picture DPI (default is 0.56 cm = 16 pt).

Method on mglGraph: inline void SetFontSizeIN (mreal cm, int dpi=72) ¶

Set FontSize by size in inch and picture DPI (default is 0.22 in = 16 pt).

Method on mglGraph: void CopyFont (mglGraph * from) ¶

C function: void mgl_copy_font (HMGL gr, HMGL gr_from) ¶

Copy font data from another mglGraph object.

Method on mglGraph: void RestoreFont () ¶

C function: void mgl_restore_font (HMGL gr) ¶

Restore font data to default typeface.

Method on mglGraph: void SetDefFont (const char *name, const char *path="") static ¶

C function: void mgl_def_font (const char *name, const char *path) ¶

Load default font typeface (for all newly created HMGL/mglGraph objects) from path/name.

4.2.7 Palette and colors

MGL command: palette 'colors' ¶

Method on mglGraph: void SetPalette (const char *colors) ¶

C function: void mgl_set_palette (HMGL gr, const char *colors) ¶

Sets the palette as selected colors. Default value is "Hbgrcmyhlnqeup" that corresponds to colors: dark gray ‘H’, blue ‘b’, green ‘g’, red ‘r’, cyan ‘c’, magenta ‘m’, yellow ‘y’, gray ‘h’, blue-green ‘l’, sky-blue ‘n’, orange ‘q’, yellow-green ‘e’, blue-violet ‘u’, purple ‘p’. The palette is used mostly in 1D plots (see 1D plotting) for curves which styles are not specified. Internal color counter will be nullified by any change of palette. This includes even hidden change (for example, by box or axis functions).

Method on mglGraph: void SetDefScheme (const char *sch) ¶

C function: void mgl_set_def_sch (HMGL gr, const char *sch) ¶

Sets the sch as default color scheme. Default value is "BbcyrR".

Method on mglGraph: void SetColor (char id, mreal r, mreal g, mreal b) static ¶

C function: void mgl_set_color (char id, mreal r, mreal g, mreal b) ¶

Sets RGB values for color with given id. This is global setting which influence on any later usage of symbol id.

MGL command: gray [val=on] ¶

Method on mglGraph: void Gray (bool enable) ¶

C function: void mgl_set_gray (HMGL gr, int enable) ¶

Sets the gray-scale mode on/off.

4.2.8 Masks

MGL command: mask 'id' 'hex' [angle] ¶

Команда MGL: mask 'id' hex [angle] ¶

Method on mglGraph: void SetMask (char id, const char *hex) ¶

Method on mglGraph: void SetMask (char id, uint64_t hex) ¶

C function: void mgl_set_mask (HMGL gr, const char *hex) ¶

C function: void mgl_set_mask_val (HMGL gr, uint64_t hex) ¶

Sets new bit matrix hex of size 8*8 for mask with given id. This is global setting which influence on any later usage of symbol id. The predefined masks are (see Color scheme): ‘-’ give lines (0x000000FF00000000), ‘+’ give cross-lines (080808FF08080808), ‘=’ give double lines (0000FF00FF000000), ‘;’ give dash lines (0x0000000F00000000), ‘o’ give circles (0000182424180000), ‘O’ give filled circles (0000183C3C180000), ‘s’ give squares (00003C24243C0000), ‘S’ give solid squares (00003C3C3C3C0000), ‘~’ give waves (0000060990600000), ‘<’ give left triangles (0060584658600000), ‘>’ give right triangles (00061A621A060000), ‘j’ give dash-dot lines (0000002700000000), ‘d’ give pluses (0x0008083E08080000), ‘D’ give tacks (0x0139010010931000), ‘*’ give dots (0x0000001818000000), ‘^’ give bricks (0x101010FF010101FF). Parameter angle set the rotation angle too. IMPORTANT: the rotation angle will be replaced by a multiple of 45 degrees at export to EPS.

MGL command: mask angle ¶

Method on mglGraph: void SetMaskAngle (int angle) ¶

C function: void mgl_set_mask_angle (HMGL gr, int angle) ¶

Sets the default rotation angle (in degrees) for masks. Note, you can use symbols ‘\’, ‘/’, ‘I’ in color scheme for setting rotation angles as 45, -45 and 90 degrees correspondingly. IMPORTANT: the rotation angle will be replaced by a multiple of 45 degrees at export to EPS.

4.2.9 Error handling

Normally user should set it to zero by SetWarn(0); before plotting and check if GetWarn() or Message() return non zero after plotting. Only last warning will be saved. All warnings/errors produced by MathGL is not critical – the plot just will not be drawn. By default, all warnings are printed in stderr. You can disable it by using mgl_suppress_warn(true);.

Method on mglGraph: void SetWarn (int code, const char *info="") ¶

C function: void mgl_set_warn (HMGL gr, int code, const char *info) ¶

Set warning code. Normally you should call this function only for clearing the warning state, i.e. call SetWarn(0);. Text info will be printed as is if code<0.

Method on mglGraph: const char *Message () ¶

C function only: const char *mgl_get_mess (HMGL gr) ¶

Fortran subroutine: mgl_get_mess (long gr, char *out, int len) ¶

Return messages about matters why some plot are not drawn. If returned string is empty then there are no messages.

Method on mglGraph: int GetWarn () ¶

C function: int mgl_get_warn (HMGL gr) ¶

Return the numerical ID of warning about the not drawn plot. Possible values are:

mglWarnNone=0

Everything OK

mglWarnDim

Data dimension(s) is incompatible

mglWarnLow

Data dimension(s) is too small

mglWarnNeg

Minimal data value is negative

mglWarnFile

No file or wrong data dimensions

mglWarnMem

Not enough memory

mglWarnZero

Data values are zero

mglWarnLeg

No legend entries

mglWarnSlc

Slice value is out of range

mglWarnCnt

Number of contours is zero or negative

mglWarnOpen

Couldn’t open file

mglWarnLId

Light: ID is out of range

mglWarnSize

Setsize: size(s) is zero or negative

mglWarnFmt

Format is not supported for that build

mglWarnTern

Axis ranges are incompatible

mglWarnNull

Pointer is NULL

mglWarnSpc

Not enough space for plot

mglScrArg

Wrong argument(s) of a command in MGL script

mglScrCmd

Wrong command in MGL script

mglScrLong

Too long line in MGL script

mglScrStr

Unbalanced ’ in MGL script

mglScrTemp

Change temporary data in MGL script

Method on mglGraph: void SuppressWarn (bool state) static ¶

C function: void mgl_suppress_warn (int state) ¶

Disable printing warnings to stderr if state is nonzero.

Method on mglGraph: void SetGlobalWarn (const char *info) static ¶

C function: void mgl_set_global_warn (const char *info) ¶

Set warning message info for global scope.

Method on mglGraph: const char * GlobalWarn () static ¶

C function: const char * mgl_get_global_warn () ¶

Get warning message(s) for global scope.

Method on mglGraph: void ClearGlobalWarn () static ¶

C function: void mgl_clear_global_warn () ¶

Clears global warning messages.

4.2.10 Stop drawing

Method on mglGraph: void Stop (bool stop=true) ¶

C function only: void mgl_ask_stop (HMGL gr, int stop) ¶

Ask to stop drawing if stop is non-zero, otherwise reset stop flag.

Method on mglGraph: bool NeedStop () ¶

C function only: void mgl_need_stop (HMGL gr) ¶

Return true if drawing should be terminated. Also it process all events in GUI. User should call this function from time to time inside a long calculation to allow processing events for GUI.

Method on mglGraph: bool SetEventFunc (void (*func)(void *), void *par=NULL) ¶

C function only: void mgl_set_event_func (HMGL gr, void (*func)(void *), void *par) ¶

Set callback function which will be called to process events of GUI library.

4.3.1 Ranges (bounding box)

MGL command: xrange v1 v2 [add=off] ¶

MGL command: yrange v1 v2 [add=off] ¶

MGL command: zrange v1 v2 [add=off] ¶

MGL command: crange v1 v2 [add=off] ¶

Method on mglGraph: void SetRange (char dir, mreal v1, mreal v2) ¶

Method on mglGraph: void AddRange (char dir, mreal v1, mreal v2) ¶

C function: void mgl_set_range_val (HMGL gr, char dir, mreal v1, mreal v2) ¶

C function: void mgl_add_range_val (HMGL gr, char dir, mreal v1, mreal v2) ¶

Sets or adds the range for ‘x’-,‘y’-,‘z’- coordinate or coloring (‘c’). If one of values is NAN then it is ignored. See also ranges.

MGL command: xrange dat [add=off] ¶

MGL command: yrange dat [add=off] ¶

MGL command: zrange dat [add=off] ¶

MGL command: crange dat [add=off] ¶

Method on mglGraph: void SetRange (char dir, const mglDataA &dat, bool add=false) ¶

C function: void mgl_set_range_dat (HMGL gr, char dir, const HCDT a, int add) ¶

Sets the range for ‘x’-,‘y’-,‘z’- coordinate or coloring (‘c’) as minimal and maximal values of data dat. Parameter add=on shows that the new range will be joined to existed one (not replace it).

MGL command: ranges x1 x2 y1 y2 [z1=0 z2=0] ¶

Method on mglGraph: void SetRanges (mglPoint p1, mglPoint p2) ¶

Method on mglGraph: void SetRanges (double x1, double x2, double y1, double y2, double z1=0, double z2=0) ¶

C function: void mgl_set_ranges (HMGL gr, double x1, double x2, double y1, double y2, double z1, double z2) ¶

Sets the ranges of coordinates. If minimal and maximal values of the coordinate are the same then they are ignored. Also it sets the range for coloring (analogous to crange z1 z2). This is default color range for 2d plots. Initial ranges are [-1, 1].

MGL command: ranges xx yy [zz cc=zz] ¶

Method on mglGraph: void SetRanges (const mglDataA &xx, const mglDataA &yy) ¶

Method on mglGraph: void SetRanges (const mglDataA &xx, const mglDataA &yy, const mglDataA &zz) ¶

Method on mglGraph: void SetRanges (const mglDataA &xx, const mglDataA &yy, const mglDataA &zz, const mglDataA &cc) ¶

Sets the ranges of ‘x’-,‘y’-,‘z’-,‘c’-coordinates and coloring as minimal and maximal values of data xx, yy, zz, cc correspondingly.

Method on mglGraph: void SetAutoRanges (mglPoint p1, mglPoint p2) ¶

Method on mglGraph: void SetAutoRanges (double x1, double x2, double y1, double y2, double z1=0, double z2=0, double c1=0, double c2=0) ¶

C function: void mgl_set_auto_ranges (HMGL gr, double x1, double x2, double y1, double y2, double z1, double z2, double z1, double z2) ¶

Sets the ranges for automatic coordinates. If minimal and maximal values of the coordinate are the same then they are ignored.

MGL command: origin x0 y0 [z0=nan] ¶

Method on mglGraph: void SetOrigin (mglPoint p0) ¶

Method on mglGraph: void SetOrigin (mreal x0, mreal y0, mreal z0=NAN) ¶

C function: void mgl_set_origin (HMGL gr, mreal x0, mreal y0, mreal z0) ¶

Sets center of axis cross section. If one of values is NAN then MathGL try to select optimal axis position.

MGL command: zoomaxis x1 x2 ¶

MGL command: zoomaxis x1 y1 x2 y2 ¶

MGL command: zoomaxis x1 y1 z1 x2 y2 z2 ¶

MGL command: zoomaxis x1 y1 z1 c1 x2 y2 z2 c2 ¶

Method on mglGraph: void ZoomAxis (mglPoint p1, mglPoint p2) ¶

C function: void mgl_zoom_axis (HMGL gr, mreal x1, mreal y1, mreal z1, mreal c1, mreal x2, mreal y2, mreal z2, mreal c2) ¶

Additionally extend axis range for any settings made by SetRange or SetRanges functions according the formula min += (max-min)*p1 and max += (max-min)*p1 (or min *= (max/min)^p1 and max *= (max/min)^p1 for log-axis range when inf>max/min>100 or 0<max/min<0.01). Initial ranges are [0, 1]. Attention! this settings can not be overwritten by any other functions, including DefaultPlotParam().

MGL command: fastcut val ¶

Method on mglGraph: void SetFastCut (bool val=true) ¶

Enable/disable accurate but slower primitive cutting at axis borders. In C/Fortran you can use mgl_set_flag(gr,val, MGL_FAST_PRIM);. It automatically set on for ternary axis now.

4.3.2 Curved coordinates

MGL command: axis 'fx' 'fy' 'fz' ['fa'=''] ¶

Method on mglGraph: void SetFunc (const char *EqX, const char *EqY, const char *EqZ="", const char *EqA="") ¶

C function: void mgl_set_func (HMGL gr, const char *EqX, const char *EqY, const char *EqZ, const char *EqA) ¶

Sets transformation formulas for curvilinear coordinate. Each string should contain mathematical expression for real coordinate depending on internal coordinates ‘x’, ‘y’, ‘z’ and ‘a’ or ‘c’ for colorbar. For example, the cylindrical coordinates are introduced as SetFunc("x*cos(y)", "x*sin(y)", "z");. For removing of formulas the corresponding parameter should be empty or NULL. Using transformation formulas will slightly slowing the program. Parameter EqA set the similar transformation formula for color scheme. See Textual formulas.

MGL command: axis how ¶

Method on mglGraph: void SetCoor (int how) ¶

C function: void mgl_set_coor (HMGL gr, int how) ¶

Sets one of the predefined transformation formulas for curvilinear coordinate. Parameter how define the coordinates:

mglCartesian=0

Cartesian coordinates (no transformation, {x,y,z});

mglPolar=1

Polar coordinates: {x*cos(y), x*sin(y), z};

mglSpherical=2

Sperical coordinates: {x*sin(y)*cos(z), x*sin(y)*sin(z), x*cos(y)};

mglParabolic=3

Parabolic coordinates: {x*y, (x*x-y*y)/2, z}

mglParaboloidal=4

Paraboloidal coordinates: {(x*x-y*y)*cos(z)/2, (x*x-y*y)*sin(z)/2, x*y};

mglOblate=5

Oblate coordinates: {cosh(x)*cos(y)*cos(z), cosh(x)*cos(y)*sin(z), sinh(x)*sin(y)};

mglProlate=6

Prolate coordinates: {sinh(x)*sin(y)*cos(z), sinh(x)*sin(y)*sin(z), cosh(x)*cos(y)};

mglElliptic=7

Elliptic coordinates: {cosh(x)*cos(y), sinh(x)*sin(y), z};

mglToroidal=8

Toroidal coordinates: {sinh(x)*cos(z)/(cosh(x)-cos(y)), sinh(x)*sin(z)/(cosh(x)-cos(y)), sin(y)/(cosh(x)-cos(y))};

mglBispherical=9

Bispherical coordinates: {sin(y)*cos(z)/(cosh(x)-cos(y)), sin(y)*sin(z)/(cosh(x)-cos(y)), sinh(x)/(cosh(x)-cos(y))};

mglBipolar=10

Bipolar coordinates: {sinh(x)/(cosh(x)-cos(y)), sin(y)/(cosh(x)-cos(y)), z};

mglLogLog=11

Log-log coordinates: {lg(x), lg(y), lg(z)};

mglLogX=12

Log-x coordinates: {lg(x), y, z};

mglLogY=13

Log-y coordinates: {x, lg(y), z}.

MGL command: ternary val ¶

Method on mglGraph: void Ternary (int tern) ¶

C function: void mgl_set_ternary (HMGL gr, int tern) ¶

The function sets to draws Ternary (tern=1), Quaternary (tern=2) plot or projections (tern=4,5,6).

Ternary plot is special plot for 3 dependent coordinates (components) a, b, c so that a+b+c=1. MathGL uses only 2 independent coordinates a=x and b=y since it is enough to plot everything. At this third coordinate z act as another parameter to produce contour lines, surfaces and so on.

Correspondingly, Quaternary plot is plot for 4 dependent coordinates a, b, c and d so that a+b+c+d=1. MathGL uses only 3 independent coordinates a=x, b=y and d=z since it is enough to plot everything.

Projections can be obtained by adding value 4 to tern argument. So, that tern=4 will draw projections in Cartesian coordinates, tern=5 will draw projections in Ternary coordinates, tern=6 will draw projections in Quaternary coordinates. If you add 8 instead of 4 then all text labels will not be printed on projections.

Use Ternary(0) for returning to usual axis. See Ternary axis, for sample code and picture. See Axis projection, for sample code and picture.

4.3.3 Ticks

MGL command: adjust ['dir'='xyzc'] ¶

Method on mglGraph: void Adjust (const char *dir="xyzc") ¶

C function: void mgl_adjust_ticks (HMGL gr, const char *dir) ¶

Set the ticks step, number of sub-ticks and initial ticks position to be the most human readable for the axis along direction(s) dir. Also set SetTuneTicks(true). Usually you don’t need to call this function except the case of returning to default settings.

MGL command: xtick val [sub=0 org=nan 'fact'=''] ¶

MGL command: ytick val [sub=0 org=nan 'fact'=''] ¶

MGL command: ztick val [sub=0 org=nan 'fact'=''] ¶

MGL command: xtick val sub ['fact'=''] ¶

MGL command: ytick val sub ['fact'=''] ¶

MGL command: ztick val sub ['fact'=''] ¶

MGL command: ctick val ['fact'=''] ¶

Method on mglGraph: void SetTicks (char dir, mreal d=0, int ns=0, mreal org=NAN, const char *fact="") ¶

Method on mglGraph: void SetTicks (char dir, mreal d, int ns, mreal org, const wchar_t *fact) ¶

C function: void mgl_set_ticks (HMGL gr, char dir, mreal d, int ns, mreal org) ¶

C function: void mgl_set_ticks_fact (HMGL gr, char dir, mreal d, int ns, mreal org, const char *fact) ¶

C function: void mgl_set_ticks_factw (HMGL gr, char dir, mreal d, int ns, mreal org, const wchar_t *fact) ¶

Set the ticks step d, number of sub-ticks ns (used for positive d) and initial ticks position org for the axis along direction dir (use ’c’ for colorbar ticks). Variable d set step for axis ticks (if positive) or it’s number on the axis range (if negative). Zero value set automatic ticks. If org value is NAN then axis origin is used. Parameter fact set text which will be printed after tick label (like "\pi" for d=M_PI).

MGL command: xtick val1 'lbl1' [val2 'lbl2' ...] ¶

MGL command: ytick val1 'lbl1' [val2 'lbl2' ...] ¶

MGL command: ztick val1 'lbl1' [val2 'lbl2' ...] ¶

MGL command: ctick val1 'lbl1' [val2 'lbl2' ...] ¶

MGL command: xtick vdat 'lbls' [add=off] ¶

MGL command: ytick vdat 'lbls' [add=off] ¶

MGL command: ztick vdat 'lbls' [add=off] ¶

MGL command: ctick vdat 'lbls' [add=off] ¶

Method on mglGraph: void SetTicksVal (char dir, const char *lbl, bool add=false) ¶

Method on mglGraph: void SetTicksVal (char dir, const wchar_t *lbl, bool add=false) ¶

Method on mglGraph: void SetTicksVal (char dir, const mglDataA &val, const char *lbl, bool add=false) ¶

Method on mglGraph: void SetTicksVal (char dir, const mglDataA &val, const wchar_t *lbl, bool add=false) ¶

C function: void mgl_set_ticks_str (HMGL gr, char dir, const char *lbl, bool add) ¶

C function: void mgl_set_ticks_wcs (HMGL gr, char dir, const wchar_t *lbl, bool add) ¶

C function: void mgl_set_ticks_val (HMGL gr, char dir, HCDT val, const char *lbl, bool add) ¶

C function: void mgl_set_ticks_valw (HMGL gr, char dir, HCDT val, const wchar_t *lbl, bool add) ¶

Set the manual positions val and its labels lbl for ticks along axis dir. If array val is absent then values equidistantly distributed in x-axis range are used. Labels are separated by ‘\n’ symbol. If only one value is specified in MGL command then the label will be add to the current ones. Use SetTicks() to restore automatic ticks.

Method on mglGraph: void AddTick (char dir, double val, const char *lbl) ¶

Method on mglGraph: void AddTick (char dir, double val, const wchar_t *lbl) ¶

C function: void mgl_add_tick (HMGL gr, char dir, double val, const char *lbl) ¶

C function: void mgl_set_tickw (HMGL gr, char dir, double val, const wchar_t *lbl) ¶

The same as previous but add single tick label lbl at position val to the list of existed ones.

MGL command: xtick 'templ' ¶

MGL command: ytick 'templ' ¶

MGL command: ztick 'templ' ¶

MGL command: ctick 'templ' ¶

Method on mglGraph: void SetTickTempl (char dir, const char *templ) ¶

Method on mglGraph: void SetTickTempl (char dir, const wchar_t *templ) ¶

C function: void mgl_set_tick_templ (HMGL gr, const char *templ) ¶

C function: void mgl_set_tick_templw (HMGL gr, const wchar_t *templ) ¶

Set template templ for x-,y-,z-axis ticks or colorbar ticks. It may contain TeX symbols also. If templ="" then default template is used (in simplest case it is ‘%.2g’). If template start with ‘&’ symbol then long integer value will be passed instead of default type double. Setting on template switch off automatic ticks tuning.

MGL command: ticktime 'dir' [dv=0 'tmpl'=''] ¶

Method on mglGraph: void SetTicksTime (char dir, mreal val, const char *templ) ¶

C function: void mgl_set_ticks_time (HMGL gr, mreal val, const char *templ) ¶

Sets time labels with step val and template templ for x-,y-,z-axis ticks or colorbar ticks. It may contain TeX symbols also. The format of template templ is the same as described in http://www.manpagez.com/man/3/strftime/. Most common variants are ‘%X’ for national representation of time, ‘%x’ for national representation of date, ‘%Y’ for year with century. If val=0 and/or templ="" then automatic tick step and/or template will be selected. You can use mgl_get_time() function for obtaining number of second for given date/time string. Note, that MS Visual Studio couldn’t handle date before 1970.

C function: double mgl_get_time (const char*str, const char *templ) ¶

Gets number of seconds from 1970 year to specified date/time str. The format of string is specified by templ, which is the same as described in http://www.manpagez.com/man/3/strftime/. Most common variants are ‘%X’ for national representation of time, ‘%x’ for national representation of date, ‘%Y’ for year with century. Note, that MS Visual Studio couldn’t handle date before 1970.

MGL command: tuneticks val [pos=1.15] ¶

Method on mglGraph: void SetTuneTicks (int tune, mreal pos=1.15) ¶

C function: void mgl_tune_ticks (HMGL gr, int tune, mreal pos) ¶

Switch on/off ticks enhancing by factoring common multiplier (for small, like from 0.001 to 0.002, or large, like from 1000 to 2000, coordinate values – enabled if tune&1 is nonzero) or common component (for narrow range, like from 0.999 to 1.000 – enabled if tune&2 is nonzero). Also set the position pos of common multiplier/component on the axis: =0 at minimal axis value, =1 at maximal axis value. Default value is 1.15.

MGL command: tickshift dx [dy=0 dz=0 dc=0] ¶

Method on mglGraph: void SetTickShift (mglPoint d) ¶

C function: void mgl_set_tick_shift (HMGL gr, mreal dx, mreal dy, mreal dz, mreal dc) ¶

Set value of additional shift for ticks labels.

Method on mglGraph: void SetTickRotate (bool val) ¶

C function: void mgl_set_tick_rotate (HMGL gr, bool val) ¶

Enable/disable ticks rotation if there are too many ticks or ticks labels are too long.

Method on mglGraph: void SetTickSkip (bool val) ¶

C function: void mgl_set_tick_skip (HMGL gr, bool val) ¶

Enable/disable ticks skipping if there are too many ticks or ticks labels are too long.

Method on mglGraph: void SetTimeUTC (bool val) ¶

Enable/disable using UTC time for ticks labels. In C/Fortran you can use mgl_set_flag(gr,val, MGL_USE_GMTIME);.

MGL command: origintick val ¶

Method on mglGraph: void SetOriginTick (bool val=true) ¶

Enable/disable drawing of ticks labels at axis origin. In C/Fortran you can use mgl_set_flag(gr,val, MGL_NO_ORIGIN);.

MGL command: ticklen val [stt=1] ¶

Method on mglGraph: void SetTickLen (mreal val, mreal stt=1) ¶

C function: void mgl_set_tick_len (HMGL gr, mreal val, mreal stt) ¶

The relative length of axis ticks. Default value is 0.1. Parameter stt>0 set relative length of subticks which is in sqrt(1+stt) times smaller.

MGL command: axisstl 'stl' ['tck'='' 'sub'=''] ¶

Method on mglGraph: void SetAxisStl (const char *stl="k", const char *tck=0, const char *sub=0) ¶

C function: void mgl_set_axis_stl (HMGL gr, const char *stl, const char *tck, const char *sub) ¶

The line style of axis (stl), ticks (tck) and subticks (sub). If stl is empty then default style is used (‘k’ or ‘w’ depending on transparency type). If tck or sub is empty then axis style is used (i.e. stl).