begin
Initiate a new GMT modern mode session
Synopsis
gmt begin [prefix] [formats] [options] [ -C ] [ -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 mode 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 (see also GMT Modern Mode One-line Commands). However, if you want to create multiple illustrations within this session, you will instead use figure to name 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 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 (without their leading hyphens) that will override the default settings provided via PS_CONVERT [A]. The only other available options control the verbosity.
Optional Arguments
- prefix
Name-stem used to construct the single final figure name [gmtsession]. The extension is appended automatically from your formats selection(s). If your script only performs calculations or needs to make several figures then you will not use this argument. While not recommended, if your prefix has spaces in it then you must enclose your prefix in single or double quotes. You may also include a relative or absolute output path.
- formats
Give one or more comma-separated graphics extensions from the list of allowable graphics formats (default format is configurable via setting GMT_GRAPHICS_FORMAT [pdf]). Optionally, append +m for monochrome image (BMP, JPEG, PNG, and TIFF only) and +qquality in 0-100 range to change JPEG quality [90]. If you specify one or more formats, you should also supply a prefix.
- options
Sets one or more comma-separated options (and possibly arguments) that can be passed to psconvert when preparing a session figure [A]. The valid subset of options are A[args],Cargs,Ddir,Edpi,Hfactor,Iargs,Margs,Nargs,Qargs,S. Note that the leading hyphens should not be given. See the psconvert documentation for details on these options.
- -C
Start this session with a clean slate: Any gmt.conf files in the usual search path directories are ignored [Default starts session with the prevailing user settings].
- -V[level]
Select verbosity level [w]. (See full description) (See technical reference).
- -^ 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.
Supported Graphic Formats
Format |
Explanation |
|---|---|
bmp |
Microsoft Bit Map |
eps |
Encapsulated PostScript |
jpg |
Joint Photographic Experts Group Format |
Portable Document Format [Default] |
|
png |
Portable Network Graphics |
PNG |
Portable Network Graphics (with transparency layer) |
ppm |
Portable Pixel Map |
ps |
Plain PostScript |
tif |
Tagged Image Format File |
view |
Use format set by GMT_GRAPHICS_FORMAT |
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 start our script thus:
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, and strictly using the GMT default settings, we would run:
gmt begin 'My Figure4' jpg A,I+m0.5c -C
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 a tight 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. Note that any other graphics formats specified with ps will also not be cropped. Otherwise, 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 gmt_session.##### then you can add this command to the top of your script to make the issue go away (in Bourne shell):
export GMT_SESSION_NAME=$$
or in C shell:
setenv GMT_SESSION_NAME $$
This setting is prescribed if you create a new script with gmt --new-script, as is the -e option
that will stop the script if any command returns an error.
Because of this mode of communication you can also not run two separate modern mode scripts from the same terminal at the same time (e.g., job_1.sh &; job_2.sh &) since they would share the same GMT_SESSION_NAME (unless you reassigned it explicitly in the scripts). Finally, if you Ctrl-C a modern mode command it will first try to remove the hidden gmt_session.###### directory. Should you try to terminate a script with a mix of GMT and UNIX commands then whatever process is running when you hit Ctrl-C will be the one that stops, and if that is not a GMT command then the hidden directory will be left behind. You can clean this up via:
gmt clear sessions