figure

Set attributes for the current modern mode session figure

Synopsis

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

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

Description

A GMT modern session can make any number of illustrations (including none). In situations when multiple illustrations will be made during a single session , the figure module is used to specify the name and format(s) to use for the next plot. It must be issued before you start plotting to the intended figure, and each new figure call changes plotting focus to the next figure. You may go back and forth between different figures but the optional arguments (formats and options) can only be given the first time you specify a new figure. 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 the verbosity. Each figure maintains its own history and settings, so memory of region and projection settings only apply on a per figure basis.

Required Arguments

prefix

Name stem used to construct the figure name. The extension(s) are appended automatically from your formats selection(s). While not recommended, if your prefix has spaces in it then you must enclose your prefix in single quotes.

Optional Arguments

formats

Give one or more comma-separated graphics extensions from the list of allowable graphics formats (default is configurable via setting GMT_GRAPHICS_FORMAT [pdf]).

options

Sets one or more comma-separated options (and possibly arguments) that can be passed to psconvert when preparing this figure [A]. The valid subset of options are A[args],Cargs,Ddir,Edpi,Hfactor,Margs,Qargs,S. See the psconvert documentation for details on these options.

-V[level]

Select verbosity level [w]. (See full description) (See cookbook information).

-^ 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.

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.

Examples

To start a new figure in your current modern mode session by the name Regional and request we make both a PDF and an EPS file, try:

gmt begin
gmt figure Regional pdf,eps
gmt ...
gmt end show

To start a new figure GlobalMap that should be returned as a JPEG file with a 1 cm padding around the image, try:

gmt begin
gmt figure GlobalMap jpg A+m1c
gmt ...
gmt end show

If the same figure were to be called Global Map.jpg you would need quotes:

gmt begin
gmt figure 'Global Map' jpg A+m1c
gmt ...
gmt end show

To make two figures in one session and go back and forth between different figures:

gmt begin

# Activate figure Fig1
gmt figure Fig1 pdf
gmt ...

# Activate figure Fig1
gmt figure Fig2 pdf
gmt ...

# Go back to figure Fig1
gmt figure Fig1
gmt ...

# Go back to figure Fig2
gmt figure Fig2
gmt ...

gmt end show

Technical Note

If you are calling figure from an external environment and you do not want the plot to be converted automatically when the session ends, perhaps because you wish to do this yourself, you can specify the file name or figure format as - (i.e., just a hyphen).

See Also

begin, clear, docs, end, inset, subplot, gmt