.. index:: ! figure

.. only:: not man

    Set attributes for the current modern mode session figure

Synopsis
--------

.. include:: common_SYN_OPTs.rst_

**gmt figure** *prefix* [*formats*] [*options*]
[ |SYN_OPT-V| ]
[ |SYN_OPT--| ]

|No-spaces|

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 or when you need
specific control over the conversion from PostScript to the output format,
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
:doc:`psconvert` *options* that will override the default settings provided via
:ref:`PS_CONVERT <PS_CONVERT>` [**A**]. The only other available options control verbosity
and default parameter settings.

Required Arguments
------------------

*prefix*
    Name stem used to construct the figure name.  The extension(s) are appended
    automatically from your *formats* selection(s).

Optional Arguments
------------------

.. _figure-formats:

*formats*
    Give one or more comma-separated graphics extensions from the list of allowable graphics
    :ref:`formats <tbl-formats>` [pdf].

.. _figure-options:

*options*
    Sets one or more comma-separated options (and possibly arguments) that
    can be passed to :doc:`psconvert` when preparing this figure [**A**].
    The valid subset of options are
    **A**\ [*args*],\ **C**\ *args*,\ **D**\ *dir*,\ **E**\ *dpi*,\ **H**\ *factor*,\ **M**\ *args*,\ **Q**\ *args*,\ **S**.
    See the :doc:`psconvert` documentation for details on these options.

.. _figure-V:

.. |Add_-V| unicode:: 0x20 .. just an invisible code
.. include:: explain_-V.rst_

.. include:: explain_help.rst_

.. include:: explain_postscript.rst_

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 figure Regional pdf,eps

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

   ::

    gmt figure GlobalMap jpg A1c

See Also
--------

:doc:`begin`,
:doc:`clear`,
:doc:`docs`,
:doc:`end`,
:doc:`subplot`,
:doc:`gmt`
