NAME¶

begin - Initiate a new GMT modern mode session

SYNOPSIS¶

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

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

DESCRIPTION¶

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, 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. In addition to prefix and formats, you can supply a comma-separated series of psconvert options that will override the default settings provided via PS_CONVERT [A]. The only other available options control verbosity and default parameter settings.

OPTIONAL ARGUMENTS¶

EXAMPLES¶

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 (assuming GMT_GRAPHICS_FORMAT is pdf).

To set up proceedings for a jpg figure with 0.5c white margin, we would run

gmt begin 'My Figure4' pdf,png A+m1c

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.

NOTE ON UNIX SHELLS¶

Modern mode works by communicating across gmt modules via the shell script's (or terminal's) process ID, which is the common parent process ID (PPID) for each module. This number is used to create the unique session directories where gmt keeps its book-keeping records. However, inconsistencies across various UNIX shells and other differences in their implementations may occasionally lead to problems for gmt to properly determine the unique PPID. The most common situation is related to a shell spawning sub-shells when you are linking two or more processes via UNIX pipes. Each sub-shell will then have its own process ID and gmt modules started by the sub-shell will then have that ID as PPID and it will differ from the one determined by gmt begin. If you are using pipes in your modern mode script and you get strange errors about not finding gmt6.##### then you can add this command to the top of your script to make the issue go away (in Bourne shell):

or in cshell:

SEE ALSO¶

clear, docs, end, figure, inset, subplot, gmt

COPYRIGHT¶

2019, The GMT Team