Metagraf's Icon

Welcome to METAGRAF-3D

(Release 1.1.1)


METAGRAF has changed. From the first alfa released one year ago to the present version there is a big step. We, J.J.Arribas & S.Muelas, are proud of the work done and the result obtained. Nevertheless, every time we put something new in the program, we think of a lot of other things that would be convenient. So, and owing to the fact that MG's license is GPL, we will create a CVS repository in Source Forge where we hope to receive the help that, up to this moment, we haven't had.

The first consequence of this lack of help is the need to write these lines in this extremely limited English. Anyway, we will try to explain the many capabilities of MG and we hope to be, at least, understandable. Sorry about that.

This lines are not going to substitute the User's Manual, available from inside the program if wanted. They are a complement with interesting points and pretend to be easier to read than the manual. The idea is to begin by reading this page (that being a complete file, can be downloaded "on the fly" with any browser) and go thereafter to try somethings with Metagraf reading slowly the Manual.

We strongly recommend for reading this page, the use of Amaya or Opera, both of them free to download.

And now, let's go to business!

A first look

The version that we hereby present, has many new features, most of them really useful with a few that will show the impressive future possibilities of MG.

Here is a short list of the improvements already available:

And now it's time to begin with the detailed explanation of the way of using MG and how to exploit its capabilities to the maximum.

Working with Metagraf 1.1.1

The importance of grouping

It is very important to understand the preferred way of working with MG. Its capability, enormously increased in this last version, of working with groups of objects is not without reason. The point is that working with groups is a lot quicker and safer. That means that if some optimization is wanted it is recommended to group objects as soon as they are finish. On the other hand, working with groups simplifies a lot some common tasks. For example, we can create "composite objects" that, once finished will not be modified any more. For those cases I have included the button "ATTACH" on the right. Once a few objects are "attached" in a group they can not be ungrouped any more. (So be cautious.) It is possible to draw new objects and text and everything over or under the group, but this kind of group will be maintained as it is "forever and ever....", as it is, really, a new object.

Drawings in MG require one or two minutes of reflection before beginning the job. The advantage of this approach is not to under estimate. One or two minutes can save one or two hours of modifying lines, changing text and so on, as it is usual with other well known programs. The incredible simplicity for moving, cloning or resizing objects and groups in MG, makes it a child's play to finish a part of a drawing in a few minutes. Then, grouping -and viewing- are the words. (About viewing, a little later on). Once the drawing is grouped and viewed, it is safe and we can continue with the next step.

As we have given so much importance to groups in MG, let's find out which are your tools for working with them:

Those buttons work in a straightforward way. They do what they promise to do. There are some subtle differences that must be stated. For the two general buttons to work, the objects must be selected (so, in red color). With the second one, ungroup, we have to select a group and clicking the button will ungroup the objects included and let them in a selected state, so in red color. The third one works just by clicking it. All the objects on the screen, singles or groups, selected or not, will be grouped and the group selected. The fourth doesn't care about selections of any kind. It is the same to have some groups selected and others not. It will ungroup everything -with the exception noted. But, it will ungroup all the objects and let them in a NOT selected state. Finally, for attaching objects it is necessary to group them and immediately to click this button. The group will be converted to a new object (so, be careful).

One last thing to be said about groups is that their use makes easier the selection of objects. In fact, when a new group is created, it is placed over the last object created on the screen ( as, really, it is the last object). One way to change the order of objects and to make one of them the "last one" is simply to select it, to group itself alone and to ungroup it. It will be placed over all the rest on the screen. It can be convenient for the user to try this mechanism as it is useful with selection (one of the points to improve in the TO DO list of MG).

A new way of saving, viewing and recovering files

This point has been totally modified and the new way is very simple and convenient. When something is drawn on the screen and we want to see it "the real way" or to save it, both things are done just by clicking the ghost button: ghost button When this button is clicked a double action takes place: on one side the file is processed and the "ghostview" screen launched (more precisely, gv in Unix and gsview32 in Windows). It will appear on the screen the drawing done "up to the moment". But on another side, a couple of new files with the general name: and graf_num.bmg are created in the directory files, where "num" is a number beginning with 1 and increasing one unit every time the ghost button is clicked. (More about the distribution of directories in this release, later on).

In this way just by viewing the drawing done, we save a copy of it. But it is necessary to say something more. If we leave MG by clicking the "bye bye" button: by by button , as must be generally done, all the files saved with the name graf_num.* in directory files will be erased. If we begin another MG session and open this directory, it will be empty of those files. So, our drawing is safe temporarily. To save it "forever and ever" we must click the save button: save button and choose a name and a directory to put it. Sometimes, it can be convenient just to give it a name and save it in the same directory files. It will not be erased as its name will not begin with "graf" (I guess...). We must mention that if MG is closed by clicking the closing button on the external window, no files will be deleted.

It is a good practice to group the drawing before saving it. Many times you will also find that once finished and saved a part of a drawing, you can delete it to have your screen cleaner and continue working in an easier way.

All the points related with "saving" are in a close relationship with those related with "recovering" or opening. Let's see how all that works now.

To recover a part of a picture already saved and deleted from screen, we have to click the open button: open button and choose the file to paste. Just by clicking open, the drawing will be pasted on the screen in the same place, and exactly as it was when we saved it. (Nevertheless, there is a bug not yet solved when recovering files with text written in TeX/LaTeX. So you must leave the titles for the end of the drawing if you don't use postscript text). If substitution of a drawing is the point, and there is no interest in pasting, the only thing to do in a different way is to press CTRL key when clicking the open button. The drawing on the screen will disappear and the saved one will take its place.

In both cases, saving and opening, it is possible (and simple) to open any directory to save or open the file.

Writing and editing text

For writing and editing simple text in drawings, a totally "new way of doing" has been developed. Now, the upper left part of MG's screen has lost the label with the name of the program and a, relatively small, text field has taken its place. Although short, the text scrolls at the end of the visible text field, so text of any length can be written.

For placing text on the drawing it is not necessary to launch the editor as before. Just click on the text field to see the cursor and write anything. Then click the "place text" button: text button and click and drag on the screen, where a red line will be visible. As before the text will have its center on the first point clicked and the length of the line drawn doesn't matter. Just a point is enough (but you will have difficulties in moving or selecting it afterwards).

After clicking the right mouse button, your text will appear, and if you continue to work, you will see the text field clean and without your written text. You can write as many texts as you want and place them on due places. If once the text in place you realize that there is some mistake in any word, and although you have written a lot more titles, at any time you can click a couple of times over the line of the text. Then you will see this text appear once more on the text field, where you can edit it and correct any mistake. Once done and before any other action, the correct button: , at right must be clicked. You will see that the text on the screen has changed to the new one.

So, to modify any written text on screen the steps are: click the text; modify it on the text field and click the correct button. The fact of using the small text field window for this action has been choose for reasons of simplicity, as it is much easier to see the clean text than be obliged to work on the screen with grids, lines of other objects, etc.

The old editor has been maintained for two reasons. First one, it is needed if we want to input some lines of written text on the drawing. As it is known, we can write direct metapost code on the editor and then place it in the file just by clicking the metapost button: metapost button and then over the screen. Second one, it allows to modify a final file by hand (some details, text .... and so on) and save it in this modified state.

Mouse cursor

Finally, we have decided to let "nature as it is" and don't change the standard cursors. After designing the "perfect cursor" for every need, we have realized that it changed with every O.S., and not only, but also with many window managers in Linux. So, back to the standard used by Java. Let's say a couple of words about them.

In Windows, the standard cursors are the cross-hair (not very small) one and the vertical hand closed but one finger extended. In Unix, the same cross-hair (smaller) and the hand is horizontal and also smaller and with a finger extended.

Anyway, when we see the cross-hair cursor it means that if we click on the screen a new object will be created. We must be careful about that. At the beginning of using MG it is not surprising that sometimes we just want to select an object to move or resize/reshape it but we have forgotten to go out from the "create objects state". Then, just at the time of clicking we realize the mistake and click quickly the right button of the mouse. The little hand with extended finger is there and clicking once more we see our object selected (red) as we wanted. The work continues; we are happy with it and at some moment we want to see/save it. We click our nice ghost button and ... nothing happens. Let's see why. Suppose that the last object created was a rectangle. We have not deactivated the "create object state" and we have done a very short click with it before correcting the mistake. But this "very short" click has been enough to create a problem. The object has been created, but with width and hight zero, so we don't see it on the screen. Nevertheless it is there, and it has been translated to MetaPost when saving the file. Then to view the drawing, the file is processed but "old, good, strict, serious" metapost doesn't like stupidities, so he refuses to process such thing....well, you see.

A norm of good practice is to return always to the "hand-state" of the cursor as soon as we have created anything. Just click the right button. Other programs use the three buttons of the mouse and you must know what to do at every moment looking to your right and trying to break the code of the small drawing. MG only asks you to click the right button every time you create an object. That's all.

Just in case you make this mistake and you realize it, the best thing to do is to try to select the point of the disturbing, unwanted, minimal object and delete it, as although a minimal point, if it is selected, is clearly seen. If you remember exactly where you have clicked and you are working in "snap-to.grid" mode, it can be possible (although difficult) to select it. Another easier possibility is to click and drag the mouse (little hand with extended finger) in a small rectangle around the zone where our short click has been done. The point will appear clearly if it is inside. Finally, if there is a mess of lines, curves, text and everything, the best thing to do is to select and group everything with the specific button and immediately ungroup with the standard button. Doing that, all the objects will be selected, so in red, and we must be able to see our point.

A button to understand

Now let's say something about the structure of directories used by the present MG's distribution. The whole can be downloaded and installed directly from the Web, including the Java virtual machine, what is recommended. Once done the installation you will find a master directory created where you have choose, with the name "metagraf". In this directory there will be one file and five directories that are the whole MG system. Moreover, there will be some other files/directories created by the installer. The core of MG is the file metagraf.jar where all the Java classes are included. The five directories that come with MG are: "images", "src", "manual", "scripts" and "files". Now we will speak of "scripts".
In this directory we have included all the scripts needed to obtain the facilities given for visualizing, writing, launching the helping applications (ghostview...) and so on. Those scripts are available to you (you can improve them) and it can be very interesting to try different possibilities. But for doing so, it is convenient to understand how they work. When the ghost button is clicked and depending on the state of other buttons and/or variables, Java gives the instruction to run some script at the same time that creates a couple of new files and put them on the directory "files".
What matters now are the scripts, and specially the pair va and go with or without ".bat" (Windows or Linux). If we look at them we will see that, basically, they accomplish one or two important tasks. In the case of "va" it simply runs metapost (mpost) on the file created at this very moment and launches ghostview (gv) to see the drawing created by metapost. On the other side, if we compare it with "go" we will realize the difference between both. This difference is the fact that the last one does the same as "va" but the file created is run trough LaTeX, then trough "dvips" and the final postscript file is viewed with ghostview as before. So, shortly said, in some cases LaTeX is used and in some others it is not.
The reason for all that is the fact that we can include text written to be processed by TeX or not. One of the strongest points of MG is it's impressive capability of using text in so many ways as will be seen. We can write mathematical formulae or curved text or use standard postscript fonts (from which we have included just a few ones), and we can scale this text in horizontal or vertical sense, or make the text slanted...etc. What we must remember is that if we use postscript fonts we can forget any special caution and that the file will be processed only trough metapost. If we want to use some kind of curved text and/or special TeX fonts, the file must go also trough LaTeX.
To let Java know which way to go, we have placed a button to simplify its job. This is the GV-PS button: and we must never forget to click it if we are using LaTeX or curved text. Otherwise, we will not be able to see our files, although the mp files created will be o.k.
If we have changed of state some times, to remember in which one we are, a small window will tell us so. If we don't need LaTeX we must see this label: and if we need to process the file trough LaTeX (math text, curved text...etc) this other is the label to see:
Finally, another point to mention is that if you use the simple "va" script, you will have your drawing in the same place as it is on MG's screen. But, if you want to process trough LaTeX, the drawing will be displaced to the top-left of the screen. (If you does not like that, you can always place a couple of minimal points in the upper corners of MG's screen.)


Copying (cloning) and moving objects and/or groups are the simplest things to do with MG. For cloning, there is the copy button: . Everytime you click over it, an exact copy with all the attributes of the objects/groups selected is made, and the original remains selected so if you click a second time another copy is done, and so on. Let's see how you can use this capability.
Suposse that you want to draw an image like this one: surcharge. One way of doing is to draw a right line; to put an arrow at the extrem; to change color to blue and to click 15 times the copy button. Then, placing the extrem of the extended finger of the cursor over the line and clicking and dragging the mouse we can place every arrowline in place. When we put the arrow and change the color the line remains selected so we don't need to select and unselect never. Anyway, this is not the right way of doing as it is a lot quicker to make a first copy of the arrowline, move it to its place, click the "group and select everything" button and once more the copy button. Moving the group is easier than movin a single arrowline. After putting the second group in place we repeat the operation. So, finally we need only four operations instead of 15.
Let's see another example with the same arrows. Now the figure to create will be this one:
The way of doing could be to begin doing the same as before and then rotate the figure and the lines ..etc. That would be involved and probably the result not very good. But if we rotate the first arrowline the angle needed (in this case 30 degrees) and then make the copies by groups and finally rotate the whole group, it will take a couple of minutes and the quality of the final drawing wil be outstanding, as can be seen in the picture bellow, that is just a x8 zoom of the beginning of the other one.

Important details

Just a short lines to keep the atention on a couple of features that being very important are not always clear for the user.
  1. When an object is selected an you want to select one or some more, the way to do it is to press the SHIFT key and click with the mouse on the others objects to select.
  2. If you want to move very precisely an object the best thing to do is to select the object and to hit the arrow keys on the keyboard. Each hit moves the object one pixel.
  3. To limit the number of buttons in the toolbox, some buttons react in a different way if the CTRL key is pressed at the time of clicking the mouse. We know already the difference for openning and pasting or not a file. Another button that can be used with or without this method is the polyline button: If the CTRL key is pressed, clicking this button will let us create simple, two points, lines. For every line drawn, the key must be pressed when clicking the mouse on the screen and released afterwards. If the key is not pressed any more, the mouse will be prepared for drawing polylines. Try this feature. It is very simple of using but difficult to explain.
  4. Most of the buttons in the toolbox, so at left, can be clicked with the mouse but also have a letter associated that can be used from the keyboard. The key can be seen when putting the mouse over the button and looking at the tooltip that will appear. This is quite useful, for example, when there are many objects on the screen and we want to select one of them. Instead of clicking many times the change layer button: it can be easier to hit a few times the "Q" key.
  5. For putting arrow-heads over any line, usually it is necessary to click the arrow button: TWICE. The first time to launch the small arrow-panel and the second for "transferring" the type selected to the line, that will have a blue point at the extrem with the arrow-head. Having many lines selected and putting an arrow-head, will work over the totallity of the objects selected, clicking just once.
  6. Sometimes and depending on the O.S. the click over the button seems to do nothing and it is needed to click once more. The last buttons included in the toolbox are, all of them, "transparent". So, if the click works o.k., the button will have a darker color at the time of clicking. Moreover, some important buttons will "beep" when clicked o.k. This is the case for the arrow button, for the save button, for the copy button, and some others.

Beautiful things

A few lines to speak about pictures or images and to show some examples. It can be nice at this moment to change a little bit the "density" of our words. To begin with, let's look at a couple of nice, simple pictures (done a few moments ago) to interest you more on MG. We have used our "linuxed" friend, TUX. Here they are:

The only interest of the last one is that I have done it in Windows with no help from nothing else than MG distribution. All the pictures have been opened with Gimp and saved as JPEG with it. The same would be with Photoshop or any other program of the same kind. The pictures are obtained as postscript files produced by MetaPost and can be included directly in any LaTeX document if wanted.
Now, let's see how to do to use JPEG or GIF images to include in our MG's screen and output the correponding metapost file.
First of all, we strongly recommend to read the User's Manual included in the Web page dedicated to MpFot, that can be found at, taking the link to MetaPost. In this page, it is explained how to use the different buttons and sliders used. Although quite different in external aspect, in MG identical concepts are used. When the image button: is clicked the image-panel will appear:

Clicking the open button an image-chooser will appear trough which we can select the picture to try. Choosing the file and clicking the OPEN button in the chooser will launch the image choose in another panel. Then, we can modify the image in the way explained in MpFot's page. Just try it.
The important steps to remember come now. Once the picture in the state of size, colors ... etc., wanted is ready, we must click the button with the green title "Place" (see picture above). Immediatly, the panel with the image will desappear. Then you must clik the paste image button: . Doing so, the cursor of the mouse must be transformed to the crosshair type (In some cases you will need to click twice this button. This depend on the O.S. or the Window Manager), the image-panel will desappear and clicking at any place on the screen, the picture will appear having as the left-top corner the point clicked. After clicking the mouse right button, you can move the image in exactly the same way as any other object. When the picture is selected a red rectangle will countour it.
We will continue with important details on images, later on.

Text over curves

Let's now make some comments on the very interesting issue of writing text on the path. This has been a much discussed matter in metapost's lists. Really, the possibilities given by MG almost finish this matter transforming it in a totally conventional issue. Nevertheless, some points must been known to use this feature with ease and simplicity.
Usually, the written text is placed over a curve, but the curve is not shown. The way to procced is as follows:
At any moment when doing a drawing, let's suposse that we want to place curved text. The first thing to do is to write the paragraph or title or letters wanted. We do it in the usual way already explained. The only special point in this case is that the place where we put the text has no importance at all. Someone can like to put it in the upper middle part (as me), someothers would prefer to put it at the bottom of the page. No difference. When the text is placed and the right button already clicked, the line of the text must be selected and the font choose. For doing that, the "choose postscript font" button: must be used and from the small panel shown, the font selected and accepted. Then, maintaining the text selected (line in red), the text-on-the-path button: must be clicked. Under the button there is a small window where we can read: "false" until clicked. Then it will change to "true". There is nothing more to do with the text. Immediately, we must draw a line, perhaps a curved bezier line, or an oval or a circle...Once the line drawn and selected as usual, we must click once more the "text-on-the-path" button and immediately the "text parameters" button: . A quite small panel will appear trough which we can choose almost everything related with our text. If we put the cursor over the radio-buttons a tooltip will help us to understand what for is every button. Now we will explain it.

txpar screen

Radio buttons "XS" and "YS" control the x-scale and y-scale of the fonts. Remember that in this case x-scale means "scale along the tangent to the curve in the point", and y-scale refers to the perpendicular to the curve.

Radio button "SL" (from "slanted") means the shear in the glyphs. "PS" represents the scale for the curve. "HL" controls the position of the glyphs in a line perpendicular to the curve. If this value is apprx. "-3" the letters will be placed in the middle of the curve, which is the standard setting.

Radio button "SB" controls the position of the string of text related with the origin of the curve. If the standard null value is accepted, the text will begin at the origin of the curve. "SG" controls the separation between the glyphs.

"CL" controls the color of the curve if this one is drawn and "TH" the thickness. If this last value is null, the standard, no curve will be drawn. Any other reasonable value will make appear the curve.

The way to proceed is to write a value (number 2, for example) on the text field and click the button choose, for example "XS". If doing so, a new value appears on the text field and we agree with it for another button, we can click immediately this other button. Usually, the best thing is to delete this new value and write the desired one. In normal, not extremly sophisticated conditions, only buttons "XS", "YS" and "SG" are clicked, accepting the default values for the others.

Once given the values we must click once more on the text parameter button what makes the Parameter Adjuster Panel to desappear. Our work is finished and if we want to see the result, the way of doing is having the small window under the GV-PS button with the value "gv-tex", click on our ghost button what will launch ghostview and our text on the path. If we want to readjust some value, it is enough to select the curve, click once more to see the Parameter Adjuster and modify any value. It is not necessary to repeat clicks on buttons that we don't want to modify.

Postscript recovering

This is a feature added in the very last minute and not much tested. I will explain just the way of doing and hope to receive some feedback from the users.

In the "scripts" directory there is a file with the name "ps2mg". You can move this file to any place on your path or to let it where it is. It is an executable file in Linux. A modification of the well known "pstoedit" from Wolfgang Glunz, in a really alpha stage. (I have not sent anything yet to Wolfgang as it seems not terribly serious as it is :-)

If you have a postscript file that is a drawing with lines curved or not, you can run "ps2mg" over it and try to paste the result on MG's screen. Having "ps2mg" on your path or on the directory where you are working, just write:

ps2mg -f mgraf

and press ENTER. If the file is created without error messages on the console, go to MG and click the "paste postscript" button: postscrip paste you will see appear (hopefully) a new object on MG's screen. From this moment on, this object is a bezier curve or a polyline of MG and works in the same way.

A first test to see the nice precission of this approach is to draw any figure in MG and viewing (and saving) it. Then, without closing MG, use "ps2mg" on the "graf_1.1" created and expanding MG recover "". Compare the pasted image with the original as it will be placed in exactly the same place.


This file will be continued with new adendas in the future to permit to include clarifications to points that can be difficult to understand. For doing so, I need some feedback from the users telling me, simply, what is not clear or what does not work in their computers. As I have said at the begining, shortly will be created a CVS repository in SOURCE FORGE where everyone can collaborate. Thanks for your patience.


Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee or royalty is hereby granted, in the terms of the GPL license.