MathGL ¶

2.1.1 Использование окон MathGL ¶

“Интерактивный” способ использования MathGL состоит в создании окна с помощью классов mglQT, mglFLTK или mglGLUT (см. “Оконные” классы) и последующем рисовании в этом окне. Соответствующий код выглядит так:

#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();
}

Здесь используется callback функция sample, выполняющая собственно рисование. Функция main – точка входа в программу – создает окно (объект gr типа mglQT) и запускает цикл обработки сообщений (вызов gr.Run()). Для компиляции достаточно выполнить команду

gcc test.cpp -lmgl-qt5 -lmgl

Вы можете использовать "-lmgl-qt4" вместо "-lmgl-qt5", если установлен Qt4.

Альтернативный способ состоит в использовании класса, производного от mglDraw с переопределенной функцией Draw():

#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();
}

Или в использовании функций С:

#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. */
}

Похожий код получается и при использовании окон mglFLTK, mglGLUT (функция sample() та же):

#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 mglWindow) 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 Матрица преобразования) 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 “Оконные” классы) 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 Матрица преобразования). 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 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 Масштаб осей координат). Ticks on axis are specified by function SetTicks, SetTicksVal, SetTicksTime (see Метки осей). 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,2,0); gr->Title("Usual axis");  gr->Axis();
  gr->SubPlot(3,2,1); gr->Title("Too big/small range");
  gr->SetRanges(-1000,1000,0,0.001);  gr->Axis();
  gr->SubPlot(3,2,3); gr->Title("Too narrow range");
  gr->SetRanges(100,100.1,10,10.01);  gr->Axis();
  gr->SubPlot(3,2,4); gr->Title("Disable ticks tuning");
  gr->SetTuneTicks(0);  gr->Axis();

  gr->SubPlot(3,2,2); gr->Title("Manual ticks");  gr->SetRanges(-M_PI,M_PI, 0, 2);
  mreal 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,2,5); gr->Title("Time ticks");  gr->SetRange('x',0,3e5);
  gr->SetTicksTime('x',0);  gr->Axis();
  return 0;
}

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 Шрифты). 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 Стиль текста).

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("STIX2");     gr->Puts(mglPoint(0,h), "default font (STIX2)");
  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 Опции команд), 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 Обработка данных). 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 Интерполяция). 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 Опции команд). 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 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 Интерполяция and mglGSpline() in Глобальные функции);
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 Опции команд) 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 Глобальные функции). 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 example of 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\nline 0 0 -1 $0 'r'\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 ¶

Опции команд 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 интерфейс ¶

C интерфейс – основа для многих других интерфейсов. Он содержит функции С для всех методов MathGL. В отличие от C++ классов, C функции содержат обязательный(ые) аргумент(ы) типа HMGL (для графики) и/или HCDT/HMDT/HADT (для массивов данных), который указывают на объект для рисования или изменения. Поэтому перед использованием их необходимо создать с помощью функции mgl_create_*(), и удалить после использования (или в конце программы) с помощью функции mgl_delete_*().

Все C функции описаны в заголовочном файле #include <mgl2/mgl_cf.h> и используют переменные следующих типов:

• HMGL — Указатель на класс mglGraph (см. Ядро MathGL).
• HCDT — Указатель на класс const mglDataA (см. Обработка данных) — неизменяемые массивы данных.
• HMDT — Указатель на класс mglData (см. Обработка данных) — массивы данных с действительными числами.
• HADT — Указатель на класс mglDataC (см. Обработка данных) — массивы данных с комплексными числами.
• HMPR — Указатель на класс mglParse (см. mglParse class) — выполнение MGL скриптов.
• HMEX — Указатель на класс mglExpr (см. Вычисление выражений) — текстовые формулы для действительных чисел.
• HMAX — Указатель на класс mglExprC (см. Вычисление выражений) — текстовые формулы для комплексных чисел.

Фортрановские функции и подпрограммы имеют такие же имена как функции С. Однако есть отличие. Переменные типов HMGL, HCDT, HMDT, ... должны быть целыми с достаточной разрядностью (integer*4 для 32-битной операционной системы или integer*8 для 64-битной). Все C функции типа void — подпрограммы на Фортране и должны вызываться оператором call. Прочие функции, возвращающие тип HMGL или HMDT и т.п. должны быть объявлены в Фортране как возвращающие целое нужной разрядности. Также необходимо иметь в виду, что строки в Фортране отделяются символом ', а не ".

3.8.2 C++/Python интерфейс ¶

MathGL имеет интерфейс на основе классов (объектов с членами-функциями) с использованием библиотеки SWIG. Типичный пример – Python, имя которого использовано в заголовке раздела. В точности те же классы используются и в C++ API. Отмечу, что С++ классы содержат только inline члены-функции, что делает С++ API независимым от компилятора даже для бинарной версии.

Есть 3 основных класса:

• mglGraph – обеспечивает вывод графики (см. Ядро MathGL).
• mglData – обеспечивает обработку данных (см. Обработка данных). Класс имеет возможность прямого доступа к данным с помощью конструкции вида: dat[i]=sth; или sth=dat[i], где используется "плоское" представление данных (т.е., i может быть в диапазоне 0...nx*nx*nz-1). Также можно импортировать массивы NumPy в Python: mgl_dat = mglData(numpy_dat);.
• mglParse – обеспечивает выполнение скриптов MGL (см. Скрипты MGL).

Для использования в Python достаточно выполнить ‘import mathgl’. Простейший пример имеет вид:

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

Также можно импортировать все классы из модуля mathgl и обеспечить более легкий доступ к MathGL:

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

Это становится более полезным если, например, вы создаете много объектов данных mglData.

4.2.1 Прозрачность ¶

Эти функции и переменные настраивают тип и степень прозрачности поверхностей. Главной является функция alpha, которая включает/выключает прозрачность для всего графика. Функция alphadef устанавливает величину alpha-канала по умолчанию. Наконец, функция transptype задает тип прозрачности. См. раздел Transparency and lighting, для примеров кода и графика.

Команда MGL: alpha [val=on] ¶

Метод класса mglGraph: void Alpha (bool enable) ¶

Функция С: void mgl_set_alpha (HMGL gr, int enable) ¶

Включает/выключает прозрачность и возвращает свое предыдущее состояние. По умолчанию прозрачность выключена. Функция включает прозрачность для всего рисунка.

Команда MGL: alphadef val ¶

Метод класса mglGraph: void SetAlphaDef (mreal val) ¶

Функция С: void mgl_set_alpha_default (HMGL gr, mreal alpha) ¶

Задает значение прозрачности по умолчанию для всех графиков. Значение по умолчанию 0.5.

Команда MGL: transptype val ¶

Метод класса mglGraph: void SetTranspType (int type) ¶

Функция С: void mgl_set_transp_type (HMGL gr, int type) ¶

Задает тип прозрачности. Допустимые значения:

• Обычная прозрачность (‘0’) – "закрытые" объекты видны меньше чем закрывающие. Этот режим некорректно отображается в OpenGL (mglGraphGL) для нескольких перекрывающихся поверхностей.
• "Стеклянная" прозрачность (‘1’) – закрытые и закрывающие объекты единообразно ослабляют интенсивность света (по RGB каналам).
• "Ламповая" прозрачность (‘2’) – закрытые и закрывающие объекты являются источниками дополнительного освещения (рекомендую установить SetAlphaDef(0.3) или меньше в этом случае).

См. раздел Types of transparency, для примеров кода и графика.

4.2.2 Освещение ¶

Эти функции настраивают освещение графика. Главная функция light включает/выключает освещение графиков построенных после ее вызова (в OpenGL работает сразу для всего рисунка). MathGL поддерживает до 10 независимых источников света. Но в режиме OpenGL можно использовать только первые 8 из них. Положение, цвет, яркость каждого источника света можно задавать по отдельности. По умолчанию включен только первый (с порядковым номером 0) источник света белого цвета, расположенный сверху. См. раздел Lighting sample, для примеров кода и графика.

Команда MGL: light [val=on] ¶

Метод класса mglGraph: bool Light (bool enable) ¶

Функция С: void mgl_set_light (HMGL gr, int enable) ¶

Включает/выключает освещение графика и возвращает предыдущее состояние. По умолчанию освещение выключено.

Команда MGL: light num val ¶

Метод класса mglGraph: void Light (int n, bool enable) ¶

Функция С: void mgl_set_light_n (HMGL gr, int n, int enable) ¶

Включает/выключает n-ый источник света.

Команда MGL: light num xdir ydir zdir ['col'='w' br=0.5 ap=0] ¶

Команда MGL: light num xdir ydir zdir xpos ypos zpos ['col'='w' br=0.5] ¶

Метод класса mglGraph: void AddLight (int n, mglPoint d, char c='w', mreal bright=0.5, mreal ap=0) ¶

Метод класса mglGraph: void AddLight (int n, mglPoint r, mglPoint d, char c='w', mreal bright=0.5, mreal ap=0) ¶

Функция С: void mgl_add_light (HMGL gr, int n, mreal dx, mreal dy, mreal dz) ¶

Функция С: void mgl_add_light_ext (HMGL gr, int n, mreal dx, mreal dy, mreal dz, char c, mreal bright, mreal ap) ¶

Функция С: 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) ¶

Добавляет источник света с номером n в положение p с цветом c и яркостью bright, которая должна быть в диапазоне [0,1]. Если указано положение источника r и оно не NAN, то источник считается локальным, иначе источник полагается бесконечно удалённым (для более быстрого рисования).

Команда MGL: diffuse val ¶

Метод класса mglGraph: void SetDifLight (mreal bright) ¶

Функция С: void mgl_set_difbr (HMGL gr, mreal bright) ¶

Задает яркость диффузного освещения (только для локальных источников света).

Команда MGL: ambient val ¶

Метод класса mglGraph: void SetAmbient (mreal bright=0.5) ¶

Функция С: void mgl_set_ambbr (HMGL gr, mreal bright) ¶

Задает яркость рассеянного освещения. Значение должно быть в диапазоне [0,1].

Команда MGL: attachlight val ¶

Метод класса mglGraph: void AttachLight (bool val) ¶

Функция С: void mgl_set_attach_light (HMGL gr, int val) ¶

Задает привязку настроек освещения к inplot/subplot. Отмечу, что OpenGL и некоторые выходные форматы не поддерживают эту возможность.

4.2.3 Туман ¶

Команда MGL: fog val [dz=0.25] ¶

Метод класса mglGraph: void Fog (mreal d, mreal dz=0.25) ¶

Функция С: void mgl_set_fog (HMGL gr, mreal d, mreal dz) ¶

Имитирует туман на графике. Туман начинается на относительном расстоянии dz от точки обзора и его плотность растет экспоненциально вглубь по закону ~ 1-exp(-d*z). Здесь z – нормализованная на 1 глубина графика. Если d=0 то туман отсутствует. См. раздел Adding fog, для примеров кода и графика.

4.2.4 Базовые размеры ¶

Эти функции задают величины большинства параметров графика, включая размеры маркеров, стрелок, толщину линий и т.д. Как и любые другие настройки, они подействуют только на графики созданные после изменения настроек.

Команда MGL: barwidth val ¶

Метод класса mglGraph: void SetBarWidth ( mreal val) ¶

Функция С: void mgl_set_bar_width (HMGL gr, mreal val) ¶

Задает относительный размер прямоугольников в bars, barh, boxplot, candle. Значение по умолчанию 0.7.

Команда MGL: marksize val ¶

Метод класса mglGraph: void SetMarkSize (mreal val) ¶

Функция С: void mgl_set_mark_size (HMGL gr, mreal val) ¶

Задает размер маркеров для 1D графики. Значение по умолчанию 1.

Команда MGL: arrowsize val ¶

Метод класса mglGraph: void SetArrowSize (mreal val) ¶

Функция С: void mgl_set_arrow_size (HMGL gr, mreal val) ¶

Задает размер стрелок для 1D графики, линий и кривых (см. Рисование примитивов). Значение по умолчанию 1.

Команда MGL: meshnum val ¶

Метод класса mglGraph: void SetMeshNum (int val) ¶

Функция С: void mgl_set_meshnum (HMGL gr, int num) ¶

Задает ориентировочное число линий в mesh, fall, и число стрелок (штрихов) в vect, dew, и число ячеек в cloud, и число маркеров в plot, tens, step, mark, textmark. По умолчанию (=0) рисуются все линии, стрелки, ячейки и т.д.

Команда MGL: facenum val ¶

Метод класса mglGraph: void SetFaceNum (int val) ¶

Функция С: void mgl_set_facenum (HMGL gr, int num) ¶

Задает ориентировочное число видимых граней. Может быть использована для ускорения рисования за счет более грубого рисунка. По умолчанию (=0) рисуются все грани.

Команда MGL: plotid 'id' ¶

Метод класса mglGraph: void SetPlotId (const char *id) ¶

Функция С: void mgl_set_plotid (HMGL gr, const char *id) ¶

Задает имя графика для сохранения в файл (например, в окне FLTK).

Метод класса mglGraph: const char * GetPlotId () ¶

Функция С: const char * mgl_get_plotid (HMGL gr) ¶

Fortran процедура: mgl_get_plotid (long gr, char *out, int len) ¶

Возвращает имя графика для сохранения в файл (например, в окне FLTK).

Команда MGL: pendelta val ¶

Метод класса mglGraph: void SetPenDelta (double val) ¶

Функция С: void mgl_pen_delta (HMGL gr, double val) ¶

Изменяет размытие около линий и текста (по умолчанию 1). Для val>1 текст и линии более резкие. Для val<1 текст и линии более размытые.

4.2.5 Обрезание ¶

Эти функции задают условия когда точка будет исключена (вырезана) из рисования. Замечу, что все точки со значением(-ями) NAN по одной из координат или амплитуде автоматически исключаются из рисования. См. раздел Cutting sample, для примеров кода и графика.

Команда MGL: cut val ¶

Метод класса mglGraph: void SetCut (bool val) ¶

Функция С: void mgl_set_cut (HMGL gr, int val) ¶

Задает обрезание точек за пределами осей координат. Если true то такие точки исключаются из рисования (это по умолчанию) иначе они проецируются на ограничивающий прямоугольник.

Команда MGL: cut x1 y1 z1 x2 y2 z2 ¶

Метод класса mglGraph: void SetCutBox (mglPoint p1, mglPoint p1) ¶

Функция С: void mgl_set_cut_box (HMGL gr, mreal x1, mreal y1, mreal z1, mreal x2, mreal y2, mreal z2) ¶

Задает границы параллелепипеда внутри которого точки не рисуются. Если границы одинаковы (переменные равны), то параллелепипеда считается пустым.

Команда MGL: cut 'cond' ¶

Метод класса mglGraph: void CutOff (const char *cond) ¶

Функция С: void mgl_set_cutoff (HMGL gr, const char *cond) ¶

Задает условие обрезания по формуле cond. Это условие исключает точки из рисования если результат вычисления формулы не равен нулю. Установите аргумент "" для выключения условия обрезания.

4.2.6 Шрифты ¶

Команда MGL: font 'fnt' [val=6] ¶

Задает стиль и размер шрифта. Вначале используется ‘:rC’ – прямой шрифт с выравниванием по центру. По умолчанию размер подписей оси координат в 1.4 раза больше. См. также см. Стиль текста.

Команда MGL: rotatetext val ¶

Метод класса mglGraph: void SetRotatedText (bool val) ¶

Функция С: void mgl_set_rotated_text (HMGL gr, int val) ¶

Включает/выключает вращение меток и подписей осей координат вдоль оси.

Команда MGL: scaletext val ¶

Метод класса mglGraph: void SetScaleText (bool val) ¶

Функция С: void mgl_set_scale_text (HMGL gr, int val) ¶

Включает/выключает масштабирование текста в относительных inplot-ах (в том числе columnplot, gridplot, stickplot, shearplot).

Команда MGL: texparse val ¶

Метод класса mglGraph: void SetTeXparse (bool val) ¶

Функция С: void mgl_set_tex_parse (HMGL gr, int val) ¶

Включает/выключает распознавание TeX-подобных команд при печати текста.

Команда MGL: loadfont ['name'=''] ¶

Метод класса mglGraph: void LoadFont (const char *name, const char *path="") ¶

Функция С: void mgl_load_font (HMGL gr, const char *name, const char *path) ¶

Загружает начертание шрифта из файла path/name. Пустая строка загрузит шрифт по умолчанию.

Метод класса mglGraph: void SetFontDef (const char *fnt) ¶

Функция С: void mgl_set_font_def (HMGL gr, const char * val) ¶

Задает стиль шрифта (см. Вывод текста). По умолчанию используется ‘rC’ – прямой шрифт с выравниванием по центру.

Метод класса mglGraph: void SetFontSize (mreal val) ¶

Функция С: void mgl_set_font_size (HMGL gr, mreal val) ¶

Задает базовый размер шрифта. По умолчанию размер подписей оси координат в 1.4 раза больше.

Метод класса mglGraph: void SetFontSizePT (mreal cm, int dpi=72) ¶

Задает размер шрифта в пунктах для заданного DPI (по умолчанию 16 pt для dpi=72).

Метод класса mglGraph: inline void SetFontSizeCM (mreal cm, int dpi=72) ¶

Задает размер шрифта в сантиметрах для заданного DPI (по умолчанию 0.56 см = 16 pt).

Метод класса mglGraph: inline void SetFontSizeIN (mreal cm, int dpi=72) ¶

Задает размер шрифта в дюймах для заданного DPI (по умолчанию 0.22 in = 16 pt).

Метод класса mglGraph: void CopyFont (mglGraph &from) ¶

Функция С: void mgl_copy_font (HMGL gr, HMGL gr_from) ¶

Копирует начертание шрифта из другого объекта mglGraph.

Метод класса mglGraph: void RestoreFont () ¶

Функция С: void mgl_restore_font (HMGL gr) ¶

Восстанавливает начертание шрифта по умолчанию.

Метод класса mglGraph: void SetDefFont (const char *name, const char *path="") static ¶

Функция С: void mgl_def_font (const char *name, const char *path) ¶

Загружает начертание шрифта по умолчанию (для всех вновь создаваемых HMGL/mglGraph объектов) из файла path/name.

4.2.7 Палитра и цвета ¶

Команда MGL: palette 'colors' ¶

Метод класса mglGraph: void SetPalette (const char *colors) ¶

Функция С: void mgl_set_palette (HMGL gr, const char *colors) ¶

Задает палитру как последовательность цветов. Значение по умолчанию "Hbgrcmyhlnqeup", что соответствует цветам: темно серый ‘H’, синий ‘b’, зелёный ‘g’, красный ‘r’, голубой ‘c’, малиновый ‘m’, жёлтый ‘y’, серый ‘h’, сине-зелёный ‘l’, небесно-голубой ‘n’, оранжевый ‘q’, желто-зелёный ‘e’, сине-фиолетовый ‘u’, фиолетовый ‘p’. Палитра в основном используется в 1D графиках (см. 1D графики) для кривых с неопределённым стилем линии. Внутренний счетчик цвета будет сброшен при любом изменении палитры, включая скрытые (например, функциями box или axis).

Метод класса mglGraph: void SetDefScheme (const char *sch) ¶

Функция С: void mgl_set_def_sch (HMGL gr, const char *sch) ¶

Устанавливает sch в качестве цветовой схемы по умолчанию. Начальное значение "BbcyrR".

Метод класса mglGraph: void SetColor (char id, mreal r, mreal g, mreal b) static ¶

Функция С: void mgl_set_color (char id, mreal r, mreal g, mreal b) ¶

Задает RGB значения для цвета с заданным id. Изменения действуют глобально для всех последующих использований данного id.

Команда MGL: gray [val=on] ¶

Метод класса mglGraph: void Gray (bool enable) ¶

Функция С: void mgl_set_gray (HMGL gr, int enable) ¶

Включает/выключает вывод графика в оттенках серого.

4.2.8 Маски ¶

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

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

Метод класса mglGraph: void SetMask (char id, const char *hex) ¶

Метод класса mglGraph: void SetMask (char id, uint64_t hex) ¶

Функция С: void mgl_set_mask (HMGL gr, const char *hex) ¶

Функция С: void mgl_set_mask_val (HMGL gr, uint64_t hex) ¶

Задает новую матрицу hex размером 8*8 для маски с заданным id. Изменения действуют глобально для всех последующих использований данного id. Значения по умолчанию (см. Цветовая схема): ‘-’ – 000000FF00000000, ‘+’ – 080808FF08080808, ‘=’ – 0000FF00FF000000, ‘;’ – 0000007700000000, ‘o’ – 0000182424180000, ‘O’ – 0000183C3C180000, ‘s’ – 00003C24243C0000, ‘S’ – 00003C3C3C3C0000, ‘~’ – 0000060990600000, ‘<’ – 0060584658600000, ‘>’ – 00061A621A060000, ‘j’ – 0000005F00000000, ‘d’ – 0008142214080000, ‘D’ – 00081C3E1C080000, ‘*’ – 8142241818244281, ‘^’ – 0000001824420000. Параметр angle позволяет сразу задать и угол поворота маски. ВАЖНО: при экспорте в EPS угол поворота будет приведен к ближайшему кратному 45 градусам.

Задает новую матрицу hex размером 8*8 для маски с заданным id. Изменения действуют глобально для всех последующих использований данного id. Значения по умолчанию (см. Цветовая схема): ‘-’ – линии (0x000000FF00000000), ‘+’ – клетки (080808FF08080808), ‘=’ – двойные линии (0000FF00FF000000), ‘;’ – пунктир (0x0000000F00000000), ‘o’ – окружкости (0000182424180000), ‘O’ – круги (0000183C3C180000), ‘s’ – квадраты (00003C24243C0000), ‘S’ – закрашенные квадраты (00003C3C3C3C0000), ‘~’ – волны (0000060990600000), ‘<’ – треугольники влево (0060584658600000), ‘>’ – треугольники вправо (00061A621A060000), ‘j’ пунктир с точками (0000002700000000), ‘d’ плюсы (0x0008083E08080000), ‘D’ – стежки (0x0139010010931000), ‘*’ – точки (0x0000001818000000), ‘^’ – кирпичи (0x101010FF010101FF). Параметр angle позволяет сразу задать и угол поворота маски. ВАЖНО: при экспорте в EPS угол поворота будет приведен к ближайшему кратному 45 градусам.

Команда MGL: mask angle ¶

Метод класса mglGraph: void SetMaskAngle (int angle) ¶

Функция С: void mgl_set_mask_angle (HMGL gr, int angle) ¶

Задает угол поворота маски в градусах. Отмечу, что символы ‘\’, ‘/’, ‘I’ в цветовой схеме задают угол поворота в 45, -45 и 90 градусов соответственно. ВАЖНО: при экспорте в EPS угол поворота будет приведен к ближайшему кратному 45 градусам.

4.2.9 Обработка ошибок ¶

Обычно вы должны сбросить признак ошибки с помощью SetWarn(0); перед построением и проверить GetWarnCode() или Message() на наличие ошибок после построения. Только последнее предупреждение сохраняется. Замечу, что все предупреждения/ошибки в MathGL не являются критичными – в худшем из вариантов соответствующий график просто не будет построен. По умолчанию, все предупреждения выводятся в stderr. Этот вывод можно выключить вызовом mgl_suppress_warn(true);.

Метод класса mglGraph: void SetWarn (int code, const char *info="") ¶

Функция С: void mgl_set_warn (HMGL gr, int code, const char *info) ¶

Задает код предупреждения. Обычно вызывается только для очистки предупреждений (SetWarn(0);) или внутри библиотеки. Текст info будет добавлен к предупреждениям как есть при code<0.

Метод класса mglGraph: const char *Message () ¶

Функция С: const char *mgl_get_mess (HMGL gr) ¶

Fortran процедура: mgl_get_mess (long gr, char *out, int len) ¶

Возвращает текст предупреждений о причине отсутствия графика. Если возвращаемая строка пустая, то сообщений нет.

Метод класса mglGraph: int GetWarn () ¶

Функция С: int mgl_get_warn (HMGL gr) ¶

Возвращает код сообщения о причине отсутствия графика. Возможные значения:

mglWarnNone=0

Предупреждений нет

mglWarnDim

Неправильные или несовместимые размеры данных

mglWarnLow

Размеры данных слишком малы

mglWarnNeg

Минимальное значение отрицательно

mglWarnFile

Файл не найден или указаны неправильные размерности

mglWarnMem

Не достаточно памяти

mglWarnZero

Значение данных равно нулю

mglWarnLeg

Нет записей в легенде

mglWarnSlc

Индекс среза вне данных

mglWarnCnt

Число линий уровня меньше или равно нулю

mglWarnOpen

Не могу открыть файл

mglWarnLId

Light: ID вне допустимых значений

mglWarnSize

Setsize: размер(ы) равны нулю или отрицательны

mglWarnFmt

Формат не поддерживается

mglWarnTern

Диапазоны осей несовместимые

mglWarnNull

Указатель равен NULL

mglWarnSpc

Не хватает места для графика

mglScrArg

Неправильные аргументы команды скрипта MGL

mglScrCmd

Неправильная команда в скрипте MGL

mglScrLong

Слишком длинная строка в скрипте MGL

mglScrStr

Одиночная ’ в скрипте MGL

mglScrTemp

Изменяется временная переменная в MGL скрипте

Метод класса mglGraph: void SuppressWarn (bool state) static ¶

Функция С: void mgl_suppress_warn (int state) ¶

Выключает вывод предупреждений в stderr если state не ноль.

Метод класса mglGraph: void SetGlobalWarn (const char *info) static ¶

Функция С: void mgl_set_global_warn (const char *info) ¶

Задает предупреждение info, не привязанное к конкретному объекту рисования.

Метод класса mglGraph: const char * GlobalWarn () static ¶

Функция С: const char * mgl_get_global_warn () ¶

Возвращает предупреждения, не привязанные к конкретному объекту рисования.

Метод класса mglGraph: void ClearGlobalWarn () static ¶

Функция С: void mgl_clear_global_warn () ¶

Удаляет общие предупреждения.

4.2.10 Остановка рисования ¶

Метод класса mglGraph: void Stop (bool stop=true) ¶

Функция С only: void mgl_ask_stop (HMGL gr, int stop) ¶

Просит остановить рисование если stop не ноль, иначе сбрасывает флаг остановки.

Метод класса mglGraph: bool NeedStop () ¶

Функция С only: void mgl_need_stop (HMGL gr) ¶

Возвращает true если рисование должно быть остановлено. Также запускает обработку всех отложенных событий в GUI. Пользователь должен вызывать эту функцию время от времени внутри долгих вычислений для плавности отклика GUI.

Метод класса mglGraph: bool SetEventFunc (void (*func)(void *), void *par=NULL) ¶

Функция С only: void mgl_set_event_func (HMGL gr, void (*func)(void *), void *par) ¶

Задает функцию, которая будет вызвана для обработки событий в GUI библиотеке.

4.3.1 Масштаб осей координат ¶

Команда MGL: xrange v1 v2 [add=off] ¶

Команда MGL: yrange v1 v2 [add=off] ¶

Команда MGL: zrange v1 v2 [add=off] ¶

Команда MGL: crange v1 v2 [add=off] ¶

Метод класса mglGraph: void SetRange (char dir, mreal v1, mreal v2) ¶

Метод класса mglGraph: void AddRange (char dir, mreal v1, mreal v2) ¶

Функция С: void mgl_set_range_val (HMGL gr, char dir, mreal v1, mreal v2) ¶

Функция С: void mgl_add_range_val (HMGL gr, char dir, mreal v1, mreal v2) ¶

Задает диапазон изменения ‘x’-,‘y’-,‘z’-,‘c’-координат. Если одно из значений равно NAN, то оно игнорируется. Параметр add=on указывает добавлять новый диапазон к существующему (не заменять его). См. также ranges.

Команда MGL: xrange dat [add=off] ¶

Команда MGL: yrange dat [add=off] ¶

Команда MGL: zrange dat [add=off] ¶

Команда MGL: crange dat [add=off] ¶

Метод класса mglGraph: void SetRange (char dir, const mglDataA &dat, bool add=false) ¶

Функция С: void mgl_set_range_dat (HMGL gr, char dir, const HCDT a, int add) ¶

Задает диапазон изменения ‘x’-,‘y’-,‘z’-,‘c’-координат как минимальное и максимальное значение массива dat. Параметр add=on указывает добавлять новый диапазон к существующему (не заменять его).

Команда MGL: ranges x1 x2 y1 y2 [z1=0 z2=0] ¶

Метод класса mglGraph: void SetRanges (mglPoint p1, mglPoint p2) ¶

Метод класса mglGraph: void SetRanges (mreal x1, mreal x2, mreal y1, mreal y2, mreal z1=0, mreal z2=0) ¶

Функция С: void mgl_set_ranges (HMGL gr, mreal x1, mreal x2, mreal y1, mreal y2, mreal z1, mreal z2) ¶

Задает диапазон изменения координат. Если минимальное и максимальное значение координаты равны, то они игнорируются по данному направлению. Также устанавливает размер цветовой шкалы, аналогично команде crange z1 z2. Начальные диапазоны равны [-1, 1].

Команда MGL: ranges xx yy [zz cc=zz] ¶

Метод класса mglGraph: void SetRanges (const mglDataA &xx, const mglDataA &yy) ¶

Метод класса mglGraph: void SetRanges (const mglDataA &xx, const mglDataA &yy, const mglDataA &zz) ¶

Метод класса mglGraph: void SetRanges (const mglDataA &xx, const mglDataA &yy, const mglDataA &zz, const mglDataA &cc) ¶

Задает диапазон изменения ‘x’-,‘y’-,‘z’-,‘c’-координат как минимальное и максимальное значение массивов xx, yy, zz, cc соответственно.

Метод класса mglGraph: void SetAutoRanges (mglPoint p1, mglPoint p2) ¶

Метод класса mglGraph: void SetAutoRanges (double x1, double x2, double y1, double y2, double z1=0, double z2=0, double c1=0, double c2=0) ¶

Функция С: void mgl_set_auto_ranges (HMGL gr, double x1, double x2, double y1, double y2, double z1, double z2, double z1, double z2) ¶

Задает диапазон изменения координат для автоматических переменных. Если минимальное и максимальное значение координаты равны, то они игнорируются по данному направлению.

Команда MGL: origin x0 y0 [z0=nan] ¶

Метод класса mglGraph: void SetOrigin (mglPoint p0) ¶

Метод класса mglGraph: void SetOrigin (mreal x0, mreal y0, mreal z0=NAN) ¶

Функция С: void mgl_set_origin (HMGL gr, mreal x0, mreal y0, mreal z0) ¶

Задает центр пересечения осей координат. Если одно из значений равно NAN, то MathGL попытается выбрать оптимальное положение осей координат по этому направлению.

Команда MGL: zoomaxis x1 x2 ¶

Команда MGL: zoomaxis x1 y1 x2 y2 ¶

Команда MGL: zoomaxis x1 y1 z1 x2 y2 z2 ¶

Команда MGL: zoomaxis x1 y1 z1 c1 x2 y2 z2 c2 ¶

Метод класса mglGraph: void ZoomAxis (mglPoint p1, mglPoint p2) ¶

Функция С: void mgl_zoom_axis (HMGL gr, mreal x1, mreal y1, mreal z1, mreal c1, mreal x2, mreal y2, mreal z2, mreal c2) ¶

Дополнительно расширяет диапазон осей координат, задаваемый функциями SetRange или SetRanges, в соответствии с формулами min += (max-min)*p1 и max += (max-min)*p1 (или min *= (max/min)^p1 и max *= (max/min)^p1 для "логарифмических" диапазонов, когда inf>max/min>100 или 0<max/min<0.01). Начальные значения [0, 1]. Внимание! эти настройки не могут быть переписаны никакими другими функциями, включая DefaultPlotParam().

Команда MGL: fastcut val ¶

Метод класса mglGraph: void SetFastCut (bool val=true) ¶

Разрешает/запрещает аккуратное и более медленное обрезание примитивов на границах осей координат. В C/Fortran следует использовать mgl_set_flag(gr,val, MGL_FAST_PRIM);. Включено автоматически для ternary системы координат.

4.3.2 Криволинейные координаты ¶

Команда MGL: axis 'fx' 'fy' 'fz' ['fa'=''] ¶

Метод класса mglGraph: void SetFunc (const char *EqX, const char *EqY, const char *EqZ="", const char *EqA="") ¶

Функция С: void mgl_set_func (HMGL gr, const char *EqX, const char *EqY, const char *EqZ, const char *EqA) ¶

Задает формулы перехода к криволинейным координатам. Каждая строка является математическим выражением, зависящим от старых координат ‘x’, ‘y’, ‘z’ и ‘a’ или ‘c’ для цветовой шкалы. Например, для цилиндрических координат будет SetFunc("x*cos(y)", "x*sin(y)", "z");. Для удаления формул соответствующий параметр должен быть пустым или NULL. Использование формул преобразования слегка замедляет программу. Параметр EqA задает аналогичную формулу для цветовой шкалы. See Текстовые формулы.

Команда MGL: axis how ¶

Метод класса mglGraph: void SetCoor (int how) ¶

Функция С: void mgl_set_coor (HMGL gr, int how) ¶

Устанавливает одну из предопределенных систем криволинейных координат в зависимости от параметра how:

mglCartesian=0

декартова система (нет преобразования координат, {x,y,z});

mglPolar=1

полярные координаты: {x*cos(y),x*sin(y), z};

mglSpherical=2

сферические координаты: {x*sin(y)*cos(z), x*sin(y)*sin(z), x*cos(y)};

mglParabolic=3

параболические координаты: {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

эллиптические координаты: {cosh(x)*cos(y), sinh(x)*sin(y), z};

mglToroidal=8

тороидальные координаты: {sinh(x)*cos(z)/(cosh(x)-cos(y)), sinh(x)*sin(z)/(cosh(x)-cos(y)), sin(y)/(cosh(x)-cos(y))};

mglBispherical=9

бисферические координаты: {sin(y)*cos(z)/(cosh(x)-cos(y)), sin(y)*sin(z)/(cosh(x)-cos(y)), sinh(x)/(cosh(x)-cos(y))};

mglBipolar=10

биполярные координаты: {sinh(x)/(cosh(x)-cos(y)), sin(y)/(cosh(x)-cos(y)), z};

mglLogLog=11

Log-log координаты: {lg(x), lg(y), lg(z)};

mglLogX=12

Log-x координаты: {lg(x), y, z};

mglLogY=13

Log-y координаты: {x, lg(y), z}.

Команда MGL: ternary val ¶

Метод класса mglGraph: void Ternary (int tern) ¶

Функция С: void mgl_set_ternary (HMGL gr, int tern) ¶

Задает рисование треугольных (Ternary, tern=1), пирамидальных (Quaternary, tern=2) осей координат и проекций осей координат (tern=4,5,6).

Ternary – специальный тип графика для 3 зависимых координат (компонент) a, b, c таких, что a+b+c=1. MathGL использует только 2 независимые координаты a=x и b=y поскольку их достаточно для построения всех графиков. При этом третья координата z является независимым параметром для построения линий уровня, поверхностей и т.д.

Соответственно Quaternary координаты – 4 зависимые координаты a, b, c и d, такие что a+b+c+d=1. MathGL использует только 2 независимые координаты a=x, b=y и d=z поскольку их достаточно для построения всех графиков.

Проекции строятся если к переменной tern добавить число 4. Так что tern=4 нарисует проекции в декартовых координатах, tern=5 нарисует проекции в треугольных координатах, tern=6 нарисует проекции в пирамидальных координатах. Если добавить 8 вместо 4, то текст не будет выводиться на проекциях.

Используйте Ternary(0) для возвращения к привычным координатам. См. раздел Ternary axis, для примеров кода и графика. См. раздел Axis projection, для примеров кода и графика.

4.3.3 Метки осей ¶

Команда MGL: adjust ['dir'='xyzc'] ¶

Метод класса mglGraph: void Adjust (const char *dir="xyzc") ¶

Функция С: void mgl_adjust_ticks (HMGL gr, const char *dir) ¶

Автоматически задает шаг меток осей, число подметок и начальное положение меток для осей координат dir в виде наиболее удобном для человека. Также задает SetTuneTicks(true). Обычно не требуется вызывать эту функцию кроме случая возвращения настроек по умолчанию.

Команда MGL: xtick val [sub=0 org=nan 'fact'=''] ¶

Команда MGL: ytick val [sub=0 org=nan 'fact'=''] ¶

Команда MGL: ztick val [sub=0 org=nan 'fact'=''] ¶

Команда MGL: xtick val sub ['fact'=''] ¶

Команда MGL: ytick val sub ['fact'=''] ¶

Команда MGL: ztick val sub ['fact'=''] ¶

Команда MGL: ctick val ['fact'=''] ¶

Метод класса mglGraph: void SetTicks (char dir, mreal d=0, int ns=0, mreal org=NAN, const char *fact="") ¶

Метод класса mglGraph: void SetTicks (char dir, mreal d=0, int ns=0, mreal org=NAN, const wchar_t *fact) ¶

Функция С: void mgl_set_ticks (HMGL gr, char dir, mreal d, int ns, mreal org) ¶

Функция С: void mgl_set_ticks_fact (HMGL gr, char dir, mreal d, int ns, mreal org, const char *fact) ¶

Функция С: void mgl_set_ticks_factw (HMGL gr, char dir, mreal d, int ns, mreal org, const wchar_t * fact) ¶

Задает шаг меток осей d, число подметок ns и начальное положение меток org для оси вдоль направления dir (используйте ’c’ для меток colorbar). Переменная d задает шаг меток (если положительна) или их число на оси (если отрицательна). Нулевое значение задает автоматическую расстановку меток. Если org=NAN, то используется значение из переменной Org. Параметр fact задает текст, которые будет напечатан после метки оси (например, "\pi" для d=M_PI).

Команда MGL: xtick val1 'lbl1' [val2 'lbl2' ...] ¶

Команда MGL: ytick val1 'lbl1' [val2 'lbl2' ...] ¶

Команда MGL: ztick val1 'lbl1' [val2 'lbl2' ...] ¶

Команда MGL: ctick val1 'lbl1' [val2 'lbl2' ...] ¶

Команда MGL: xtick vdat 'lbls' [add=off] ¶

Команда MGL: ytick vdat 'lbls' [add=off] ¶

Команда MGL: ztick vdat 'lbls' [add=off] ¶

Команда MGL: ctick vdat 'lbls' [add=off] ¶

Метод класса mglGraph: void SetTicksVal (char dir, const char *lbl, bool add=false) ¶

Метод класса mglGraph: void SetTicksVal (char dir, const wchar_t *lbl, bool add=false) ¶

Метод класса mglGraph: void SetTicksVal (char dir, const mglDataA &val, const char *lbl, bool add=false) ¶

Метод класса mglGraph: void SetTicksVal (char dir, const mglDataA &val, const wchar_t *lbl, bool add=false) ¶

Функция С: void mgl_set_ticks_str (HMGL gr, char dir, const char *lbl, bool add) ¶

Функция С: void mgl_set_ticks_wcs (HMGL gr, char dir, const wchar_t *lbl, bool add) ¶

Функция С: void mgl_set_ticks_val (HMGL gr, char dir, HCDT val, const char *lbl, bool add) ¶

Функция С: void mgl_set_ticks_valw (HMGL gr, char dir, HCDT val, const wchar_t *lbl, bool add) ¶

Задает явное положение val и подписи lbl для меток вдоль оси dir. Если массив val не указан, то используются значения равно распределённые в диапазоне осей координат. Метки разделяются символом ‘\n’. Если в команде MGL задано только одно значение, то метка будет добавлена к существующим меткам. Используйте SetTicks() для восстановления автоматических меток.

Метод класса mglGraph: void AddTick (char dir, double val, const char *lbl) ¶

Метод класса mglGraph: void AddTick (char dir, double val, const wchar_t *lbl) ¶

Функция С: void mgl_add_tick (HMGL gr, char dir, double val, const char *lbl) ¶

Функция С: void mgl_set_tickw (HMGL gr, char dir, double val, const wchar_t *lbl) ¶

Аналогично предыдущему, но добавляет одну метку оси к списку существующих меток.

Команда MGL: xtick 'templ' ¶

Команда MGL: ytick 'templ' ¶

Команда MGL: ztick 'templ' ¶

Команда MGL: ctick 'templ' ¶

Метод класса mglGraph: void SetTickTempl (char dir, const char *templ) ¶

Метод класса mglGraph: void SetTickTempl (char dir, const wchar_t *templ) ¶

Функция С: void mgl_set_tick_templ (HMGL gr, const char *templ) ¶

Функция С: void mgl_set_tick_templw (HMGL gr, const wchar_t *templ) ¶

Задает шаблон templ для меток вдоль x-,y-,z-оси или colorbar. Шаблон может содержать и символы TeX. Если templ="", то используется шаблон по умолчанию (в простейшем случае ‘%.2g’). Если шаблон начинается с символа ‘&’, то будет использовано целое long вместо типа double. Установка шаблона выключает автоматическое улучшение вида меток.

Команда MGL: ticktime 'dir' [dv=0 'tmpl'=''] ¶

Метод класса mglGraph: void SetTicksTime (char dir, mreal val, const char *templ) ¶

Функция С: void mgl_set_ticks_time (HMGL gr, mreal val, const char *templ) ¶

Задает метки времени с шагом val и шаблоном templ для меток вдоль x-,y-,z-оси или colorbar. Шаблон может содержать и символы TeX. Формат шаблона templ такой же как http://www.manpagez.com/man/3/strftime/. Наиболее употребительные варианты: ‘%X’ для национального представления времени, ‘%x’ для национального представления даты, ‘%Y’ для года с цифрами столетия. Если val=0 и/или templ="", то используется автоматическая расстановка меток и/или выбор шаблона. Вы можете использовать функцию mgl_get_time() для получения числа секунд с 1970 года до указанной даты/времени. Отмечу, что MS Visual Studio не может обрабатывать даты до 1970.

Функция С: double mgl_get_time (const char*str, const char *templ) ¶

Возвращает число секунд с 1970 года до даты/времени, указанной в строке str. Формат строки задается templ, такой же как http://www.manpagez.com/man/3/strftime/. Наиболее употребительные варианты: ‘%X’ для национального представления времени, ‘%x’ для национального представления даты, ‘%Y’ для года с цифрами столетия. Отмечу, что MS Visual Studio не может обрабатывать даты до 1970.

Команда MGL: tuneticks val [pos=1.15] ¶

Метод класса mglGraph: void SetTuneTicks (int tune, mreal pos=1.15) ¶

Функция С: void mgl_tune_ticks (HMGL gr, int tune, mreal pos) ¶

Включает/выключает улучшение вида меток осей путем вынесения общего множителя (для маленьких, типа 0.001...0.002, или больших, типа 1000...2000, значений координат) или общей компоненты (для узкого диапазона, типа 0.999...1.000). Также задает положение pos общего множителя на оси: =0 около минимального значения, =1 около максимального значения.

Команда MGL: tickshift dx [dy=0 dz=0 dc=0] ¶

Метод класса mglGraph: void SetTickShift (mglPoint d) ¶

Функция С: void mgl_set_tick_shift (HMGL gr, mreal dx, mreal dy, mreal dz, mreal dc) ¶

Задает значение дополнительного сдвига меток осей координат.

Метод класса mglGraph: void SetTickRotate (bool val) ¶

Функция С: void mgl_set_tick_rotate (HMGL gr, bool val) ¶

Включает/выключает поворот меток если их число или длина меток слишком велики.

Метод класса mglGraph: void SetTickSkip (bool val) ¶

Функция С: void mgl_set_tick_skip (HMGL gr, bool val) ¶

Включает/выключает пропуск меток если их число или длина меток слишком велики.

Метод класса mglGraph: void SetTimeUTC (bool val) ¶

Разрешает/запрещает использование UTC времени в метках осей координат. В C/Fortran следует использовать mgl_set_flag(gr,val, MGL_USE_GMTIME);.

Команда MGL: origintick val ¶

Метод класса mglGraph: void SetOriginTick (bool val=true) ¶

Разрешает/запрещает рисование меток в точке пересечения осей координат. В C/Fortran следует использовать mgl_set_flag(gr,val, MGL_NO_ORIGIN);.

Команда MGL: ticklen val [stt=1] ¶

Метод класса mglGraph: void SetTickLen (mreal val, mreal stt=1) ¶

Функция С: void mgl_set_tick_len (HMGL gr, mreal val, mreal stt) ¶

Задает относительную длину меток осей координат. Значение по умолчанию 0.1. Параметр stt>0 задает относительную длину подметок, которые в sqrt(1+stt) раз меньше.

Команда MGL: axisstl 'stl' ['tck'='' 'sub'=''] ¶

Метод класса mglGraph: void SetAxisStl (const char *stl="k", const char *tck=0, const char *sub=0) ¶

Функция С: void mgl_set_axis_stl (HMGL gr, const char *stl, const char *tck, const char *sub) ¶

Задает стиль осей (stl), меток (tck) и подметок (sub) осей координат. Если stl пустая или ноль, то используется стиль по умолчанию (‘k’ или ‘w’ в зависимости от типа прозрачности). Если tck, sub пустая или ноль, то используется стиль осей (т.е. stl).