Graphics and media/Tutorials/Graphical programming with MetaPost and MetaFun

Unofficial ConTeXt Wiki mirror

Last modified: 2025-01-26

Introduction

MetaPost is a graphical programming language, based on Donald Knuth's MetaFont.

MetaPost is ConTeXt's native graphics language. MetaFun is a MetaPost module by Hans Hagen that adds a lot of extra features; it is enabled by default, so one could say that MetaFun is ConTeXt's default dialect of MetaPost.

Using MetaPost in ConTeXt

MetaPost can be directly inserted anywhere with \startMPcode.

With \startuseMPgraphic you can also you define a piece of graphics code that is processed anew every time the graphic is placed with \useMPgraphic.

Commonly used commands

reusableMPgraphic
For graphics that are the same every time, it is better to use \startreusableMPgraphic : the graphic is compiled only once , and the one resulting picture can be placed at various points with \reuseMPgraphic .
uniqueMPgraphic 
dynamic graphics that are recompiled when parameters change (width, height, depth, background color, line color) ( \startuniqueMPgraphic , \uniqueMPgraphic ).
staticMPfigure
The \startuseMPgraphic series of commands were designed for using MetaPost for drawing fancy frames and backgrounds and not for using stand-alone graphics for a document. \startstaticMPfigure creates a separate pdf file containing the graphic. This pdf can be included in the document using \usestaticMPfigure . ConTeXt is clever enough to recompile the resulting MetaPost file only if something inside the \startstaticMPfigure has changed.
MPinclusions
Inside, one can specify MetaPost files to input , and also define MetaPost functions ( \startMPinclusions )
MPinstance
used to set up MetaPost invocations with particular features. One use case could be to select a sans serif font for all MetaPost labels ( \defineMPinstance , \setupMPinstance ).
MPpage
produces a page a containing MetaPost graphic. The page is just large enough to contain the graphic. The resulting pdf is self-contained (it has all the fonts embedded). This is useful if you want to send the figure to a coauthor or a journal ( \startMPpage ).

Testing plain MetaPost or mtxrun

To test whether MetaPost is installed on your system, create a file called test.mp: 

beginfig(1)
fill fullcircle scaled 3cm withcolor red ;
endfig ;
end ;

apply MetaPost on the test file

mpost test.mp

That should create a postscript file test.1. Open test.1 with a postscript viewer like Ghostview, Okular, … You should see a red disk. To generate a pdf named test.1:

mptopdf test.mp

With a working ConTeXt distribution you should be able to get a pdf with mtxrun --script metapost test.mp

Text in MetaPost

Text that is typeset using textext or btex … etex adapts to the body font. However, when label("Foo", pair) or "Foo" infont defaultfont is used, which is not the recommended way, the text is typeset using the font MetafunDefault, which can be changed if desired. Example:

The recommended way to typeset text is to use the textext macro and change the font using \defineMPinstance or \setupMPinstance (<-- see for example).

Color

Color in MetaPost describes how to get color mixtures, TeX colors, and transparent effects in MetaPost graphics.

Overlays

Sooner or later you will want to play with \framed \startuseMPgraphic (and MP family's commands) and \defineoverlay.

Let's start with an quick one.

But then, we can have fun with MetaPost

Multipage text and nofmultipars

The basic :

Then, you can play with it:

Intermediate parts can be identified with (multilocs[i] == 3:). Actually, with LMTX it's even clearer using multikind equal to "single" or "first" or "middle" or "last":

Example of section headline with underlining touching the outer edge of the page

Remark the use of:

If you forget to setup the bounding box of the MetaPost figure with setbounds:

Example for page background

Remark the use of:

MetaPost documentation

Official

Introductions and guides

ConTeXt meetings

Older content