Initiate a new GMT modern mode session


gmt begin [prefix] [formats] [ -V[level] ]

Note: No space is allowed between the option flag and the associated arguments.


The begin module instructs GMT to begin a new modern session. If your script only makes a single plot then this is the most opportune time to specify the name and format(s) of your plot. However, if you want to create multiple illustrations within this session or need more control over the conversion from the internal PostScript to the output format, you will instead use figure for the figure(s) you wish to make. The session keeps track of all default and history settings and isolates them from any other session that may run concurrently. Thus unlike in classic mode you can run multiple modern sessions simultaneously without having destructive interference in updating the history of common options.

Optional Arguments

Name-stem used to construct the single final figure name. The extension is appended automatically from your formats selection(s) [gmtsession]. If your script only performs calculations or needs to make several figures then you will not use this argument.
Give one or more comma-separated graphics extensions from the list of allowable graphics formats formats [pdf].
-V[level] (more …)
Select verbosity level [c].
-^ or just -
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use -).
-+ or just +
Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exits.
-? or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.
Format Explanation
bmp Microsoft Bit Map
eps Encapsulated PostScript
jpg Joint Photographic Experts Group Format
pdf Portable Document Format [Default]
png Portable Network Graphics (opaque)
PNG Portable Network Graphics (transparent)
ppm Portable Pixel Map
ps Plain PostScript
tif Tagged Image Format File


To initiate a new modern session that will produce a single map called Figure_2 saved as both a PDF vector graphics file and an opaque PNG raster image, we would run

gmt begin Figure_2 pdf,png

If the modern session is only used for computations and no illustrations are produced then we do not need to give any further arguments:

gmt begin

Should we give such a command and still produce a plot then it will automatically be called gmtsession.pdf.

Note on PostScript

If the user selects ps as one of the formats, then please be aware that it is recommended you first set the desired paper size. With ps, GMT needs to work with a fixed paper size since, unlike the eps format, there will be no cropping to BoundingBox. If no paper size is specified via PS_MEDIA then GMT will default to A4 and issue a warning; GMT is unable to determine if that size is adequate for your plot but if the canvas width exceeds A4 paper width we will switch page orientation to landscape. For all other formats the final dimension will be determined automatically.