Provided by: gmt_6.5.0+dfsg-3build2_amd64 bug

NAME

       gmt - The Generic Mapping Tools data processing and display software package

INTRODUCTION

       GMT  is a collection of freely available command-line tools under the GNU LGPL that allows
       you to manipulate x, y and  x,  y,  z  data  sets  (filtering,  trend  fitting,  gridding,
       projecting,  etc.)  and  produce  illustrations ranging from simple x-y plots, via contour
       maps, to artificially illuminated surfaces and 3-D perspective  views  in  black/white  or
       full  color.  Linear,  \log_{10},  and  power  scaling is supported in addition to over 30
       common map projections. The processing and display  routines  within  GMT  are  completely
       general and will handle any (x, y) or (x, y, z) data as input.

SYNOPSIS

       gmt is the main program that can start any of the modules:

       gmt module module-options
              Starts  a  given GMT module with the module-options that pertain to that particular
              module.  A few special commands are also available:

       gmt clear items
              Deletes current defaults, or the  cache,  data  or  sessions  directories.   Choose
              between  defaults  (deletes  the  current gmt.conf file used for the current modern
              session), cache (deletes the user's cache directory and all of its  content),  data
              (deletes  the  user's data download directory and all of its content), or all (does
              all of the above).

       gmt begin [session-prefix] [format] [options]
              Initializes a new GMT session under modern mode [Default  is  classic  mode].   All
              work  is  performed  in  a  temporary  work directory.  The optional session-prefix
              assigns a  name  to  the  session,  and  this  may  be  used  as  figure  name  for
              single-figure  sessions [gmtsession].  Likewise, the optional format can be used to
              override the default graphics format [PDF].

       gmt figure prefix [format(s)] [options]
              Specifies the desired name, output format(s) and any custom arguments  that  should
              be passed to psconvert when producing this figure.  All subsequent plotting will be
              directed to this current figure until another gmt figure command is issued  or  the
              session  ends.   The prefix is used to build final figure names when extensions are
              automatically appended. The format setting is a  comma-separated  list  of  desired
              extensions (e.g., pdf,png).

       gmt inset [arguments]
              Allows  users  to  place  a  map inset by temporarily changing where plotting takes
              place as well as the region and projection, then resets to previous stage.

       gmt subplot [arguments]
              Allows users to create a matrix of panels with automatic labeling and advancement.

       gmt end [show]
              Terminates a GMT modern mode session  and  automatically  converts  the  registered
              illustration(s)  to  their  specified  formats,  then eliminates the temporary work
              directory.  The figures are placed in the current directory. Appending the optional
              directive show automatically opens the illustration in the default viewer.

       For information on any module, load the module documentation in your browser via gmt docs,
       e.g.:

          gmt docs grdimage

       If no module is given then several other options are available:

       --help List and description of GMT modules.

       --new-script[=L]
              Write a GMT modern mode script template to standard output. Optionally  append  the
              desired  scripting  language  among bash, csh, or batch.  Default is the main shell
              closest to your current shell (e.g., bash for zsh, csh for tcsh).

       --new-glue=name
              Write the C code glue  needed  when  building  third-party  supplements  as  shared
              libraries.  The name is the name of the shared library. Run gmt in the directory of
              the supplement and the glue code will be written  to  standard  output.   Including
              this  C  code when building the shared library means gmt can list available modules
              via  the  --show-modules,  --help  options.   We  recommend  saving  the  code   to
              gmt_name_glue.c.

       --show-bindir
              Show directory of executables and exit.

       --show-citation
              Show the citation for the latest GMT publication.

       --show-classic
              List classic module names on standard output and exit.

       --show-classic-core
              List classic module names (core only) on standard output and exit.

       --show-cores
              Show number of available cores.

       --show-date
              Show GMT binary building date and exit.

       --show-datadir
              Show data directory/ies and exit.

       --show-dataserver
              Show URL of the remote GMT data server.

       --show-dcw
              Show the DCW data version used.

       --show-doi
              Show the DOI of the current release.

       --show-gshhg
              Show the GSHHG data version used.

       --show-modules
              List modern module names on standard output and exit.

       --show-modules-core
              List modern module names (core only) on standard output and exit.

       --show-library
              Show the path of the shared GMT library.

       --show-plugindir
              Show plugin directory and exit.

       --show-sharedir
              Show share directory and exit.

       --show-userdir
              Show full path of user's ~/.gmt dir and exit.

       --version
              Print version and exit.

       =      Check  if  that  module  exist  and  if  so the program will exit with status of 0;
              otherwise the status of exit will be non-zero.

COMMAND-LINE COMPLETION

       GMT provides basic command-line completion (tab  completion)  for  bash.   The  completion
       rules       are      either      installed      in      /etc/bash_completion.d/gmt      or
       <prefix>/share/tools/gmt_completion.bash.  Depending on the distribution,  you  may  still
       need  to  source  the  gmt completion file from ~/.bash_completion or ~/.bashrc.  For more
       information see Section Command-line completion in the Technical Reference.

GMT MODULES

       Run gmt --help to print the list of all core and supplementals modules within GMT,  and  a
       very  short  description of their purpose.  Detailed information about each program can be
       found in the separate manual pages.

CUSTOM MODULES

       The gmt program can also load custom modules from shared libraries built as  specified  in
       the  GMT API documentation.  This way your modules can benefit from the GMT infrastructure
       and extend GMT in specific ways.

THE COMMON GMT OPTIONS

       -B[p|s]parameters                       -Jparameters                       -Jz|Zparameters
       -Rwest/east/south/north[/zmin/zmax][+r][+uunit]  -U[stamp]  -V[level]  -X[a|c|f|r][xshift]
       -Y[a|c|f|r][yshift] -aflags -bbinary -crow,col|index -dnodata[+ccol] -eregexp -fflags  -g‐
       gaps  -hheaders  -iflags -jflags -lflags -nflags -oflags -pflags -qflags -rreg -sflags -t‐
       transp -x[[-]n] -:[i|o]

DESCRIPTION

       These are all the common GMT options that remain the same for all GMT  modules.  No  space
       between the option flag and the associated arguments.

   The -B option
       Syntax

       -B[p|s]parameters
              Set map boundary frame and axes attributes. (See cookbook information).

       Description

       This is potentially the most complicated option in GMT, but most examples of its usage are
       actually quite simple. We distinguish between two sets of information: Frame settings  and
       Axes  settings.   These  are set separately by their own -B invocations; hence multiple -B
       specifications may be specified. The Frame settings cover things such as which axes should
       be  plotted,  canvas fill, plot title (and subtitle), and what type of gridlines be drawn,
       whereas the Axes settings deal with annotation, tick, and gridline intervals, axes labels,
       and annotation units.

   Frame settings
       The Frame settings are specified by
          -B[axes][+b][+gfill][+i[val]][+n][+olon/lat][+ssubtitle][+ttitle][+w[pen]][+xfill][+yfill][+zfill]

       The frame setting is optional but can be  invoked  once  to  override  the  defaults.  The
       following directives and modifiers can be appended to -B to control the Frame settings:

       • axes to set which of the axes should be drawn and possibly annotated using a combination
         of the codes listed below [default is theme dependent]. Borders omitted from the set  of
         codes  will  not  be  drawn.   For  example,  WSn  denotes that the "western" (left) and
         "southern" (bottom) axes should be drawn with tick-marks and annotations by using W  and
         S;  that  the  "northern"  (top)  edge  of  the plot should be drawn with tick-marks and
         without annotations by using n; and that the "eastern" (right) axes should not be  drawn
         by not including one of E|e|r.

            • West,  East,  South,  North,  and/or (for 3-D plots) Z indicate axes that should be
              drawn with both tick-marks and annotations.

            • west, east, south, north, and/or (for 3-D plots) z indicate  axes  that  should  be
              drawn with tick-marks but without annotations.

            • l(eft),  r(ight),  b(ottom),  t(op)  and/or (for 3-D plots) u(p) indicate axes that
              should be drawn without tick-marks or annotations.

       • Z|zcode (for 3-D plots) where code is any combination of the corner ids 1, 2, 3, 4.   By
         default,  a  single vertical axes will be plotted for 3-D plots at the most suitable map
         corner. code can be  used  to  override  this,  where  1  represents  the  south-western
         (lower-left)   corner,   2   the   south-eastern   (lower-right),  3  the  north-eastern
         (upper-right), and 4 the north-western (upper-left) corner.

       • +w[pen] (for 3-D plots) to draw the outlines of the x-z and y-z planes  [default  is  no
         outlines].  Optionally,  append  pen  to  specify  different  pen attributes [default is
         MAP_GRID_PEN_PRIMARY].

       • +b (for 3-D plots) to draw the foreground lines of the 3-D cube defined by -R.

       • +gfill to paint the interior of the canvas with a color specified by fill [default is no
         fill]. This also sets fill for the two back-walls in 3-D plots.

       • +xfill to paint the yz plane with a color specified by fill [default is no fill].

       • +yfill to paint the xz plane with a color specified by fill [default is no fill].

       • +zfill to paint the xy plane with a color specified by fill [default is no fill].

       • +i[val]  to  annotate an internal meridian or parallel when the axis that normally would
         be drawn and annotated does not exist (e.g., for an azimuthal map with 360-degree  range
         that  has no latitude axis or a global Hammer map that has no longitude axis). val gives
         the meridian or parallel that should be annotated [default is 0].

       • +olon/lat to produce oblique gridlines about another pole specified by lon/lat  [default
         references  to  the  North pole]. +o is ignored if no gridlines are requested. Note: One
         cannot specify oblique gridlines for non-geographic projections as well as  the  oblique
         Mercator projection.

       • +n to have no frame and annotations at all [default is controlled by axes].

       • +ttitle  to place the string given in title centered above the plot frame [default is no
         title].

       • +ssubtitle (requires +ttitle) to place the string given in subtitle  beneath  the  title
         [default is no subtitle].

       Note: Both +ttitle and +ssubtitle may be set over multiple lines by breaking them up using
       the markers @^ or <break>.  To include LaTeX code  as  part  of  a  single-line  title  or
       subtitle,  enclose  the  expression  with @[ markers (or alternatively <math> ... </math>)
       (requires latex and dvips to be installed). See the Using LaTeX Expressions in GMT chapter
       for more details.

   Axes settings
       The Axes settings are specified by
          -B[p|s][x|y|z]intervals[+aangle|n|p][+f][+llabel][+pprefix][+uunit]

       but you may also split this into two separate invocations for clarity, i.e.,
          -B[p|s][x|y|z][+aangle|n|p][+e[l|u]][+f][+l|Llabel][+pprefix][+s|Sseclabel][+uunit]
          -B[p|s][x|y|z]intervals

       The following directives and modifiers can be appended to -B to control the Axes settings:

       • p|s  to set whether the modifiers apply to the p(rimary) or s(econdary) axes [Default is
         p].  These settings are mostly used for time axes  annotations  but  are  available  for
         geographic  axes  as  well.  Note: Primary refers to annotations closest to the axis and
         secondary  to  annotations  further  away.   Hence,  primary  annotation-,  tick-,   and
         gridline-intervals  must  be  shorter  than  their  secondary  counterparts.  The  terms
         "primary" and "secondary" do not reflect any hierarchical order of units: the  "primary"
         annotation  interval  is  usually  smaller (e.g., days) while the "secondary" annotation
         interval typically is larger (e.g., months).

       • x|y|z to set which axes the modifiers apply to [default is xy].  If  you  wish  to  give
         different annotation intervals or labels for the various axes then you must repeat the B
         option for each axis. For a 3-D plot with the -p and -Jz options used, -Bz can  be  used
         to provide settings for the vertical axis.

       • +e to give skip annotations that fall exactly at the ends of the axis.  Append l or u to
         only skip the lower or upper annotation, respectively.

       • +f (for geographic axes only) to give fancy annotations with W|E|S|N  suffixes  encoding
         the sign.

       • +l|+Llabel  (for  Cartesian  plots  only) to add a label to an axis. +l uses the default
         label orientation; +L forces a horizontal label for y-axes, which  is  useful  for  very
         short labels.

       • +s|Sseclabel  (for  Cartesian plots only) to specify an alternate label for the right or
         upper axes.  +s uses the default label orientation; +S forces  a  horizontal  label  for
         y-axes, which is useful for very short labels.

       • +pprefix  (for  Cartesian  plots  only)  to  define  a  leading text prefix for the axis
         annotation (e.g., dollar sign for plots related  to  money).  For  geographic  maps  the
         addition of degree symbols, etc. is automatic and controlled by FORMAT_GEO_MAP.

       • +uunit  (for  Cartesian  plots  only)  to  append specific units to the annotations. For
         geographic maps the addition of degree symbols, etc.  is  automatic  and  controlled  by
         FORMAT_GEO_MAP.

       • +aangle  (for Cartesian plots only) to plot slanted annotations, where angle is measured
         with respect to the horizontal and must be in the -90 <= angle <= 90 range. +an  can  be
         used  as  a  shorthand for normal (i.e., +a90) [Default for y-axis] and +ap for parallel
         (i.e., +a0) annotations  [Default  for  x-axis].  These  defaults  can  be  changed  via
         MAP_ANNOT_ORTHO.

       • intervals  to  define  the  intervals for annotations and major tick spacing, minor tick
         spacing, and/or grid line  spacing.  See  Intervals  Specification  for  the  formatting
         associated with this modifier.

       NOTE: To include LaTeX code as part of a label, enclose the expression with @[ markers (or
       alternatively <math> ... </math>). (requires latex and dvips to  be  installed).  See  the
       Using LaTeX Expressions in GMT chapter for more details.

       NOTE: If any labels, prefixes, or units contain spaces or special characters you will need
       to enclose them in quotes.

       NOTE: Text items such as title, subtitle, label and seclabel are seen by GMT as part of  a
       long  string containing everything passed to -B. Therefore, they cannot contain substrings
       that look like other modifiers. If you need to  embed  such  sequences  (e.g.,  +t"Solving
       a+b=c")  you  need  to  replace  those  + symbols with their octal equivalent \053, (e.g.,
       +t"Solving a\053b=c").

       NOTE: For non-geographical projections: Give negative scale (in -Jx) or  axis  length  (in
       -JX)  to change the direction of increasing coordinates (i.e., to make the y-axis positive
       down).
       Intervals specification
       The intervals specification is a concatenated string made up of substrings of the form

          [a|f|g][stride][phase][unit].

       The choice of a|f|g sets the axis item of  interest,  which  are  detailed  in  the  Table
       interval types. Optionally, append phase to shift the annotations by that amount (positive
       or negative with the sign being required). Optionally, append unit to specify the units of
       stride,  where  unit  is  one  of  the 18 supported unit codes. For custom annotations and
       intervals, intervals can be given as  cintfile,  where  intfile  contains  any  number  of
       records with coord type [label]. See the section Custom axes for more details.

                               ┌─────┬──────────────────────────────────┐
                               │FlagDescription                      │
                               ├─────┼──────────────────────────────────┤
                               │a    │ Annotation    and   major   tick │
                               │     │ spacing                          │
                               ├─────┼──────────────────────────────────┤
                               │f    │ Minor tick spacing               │
                               ├─────┼──────────────────────────────────┤
                               │g    │ Grid line spacing                │
                               └─────┴──────────────────────────────────┘

       NOTE: The appearance of certain time annotations (month-, week-,  and  day-names)  may  be
       affected  by  the  GMT_LANGUAGE,  FORMAT_TIME_PRIMARY_MAP,  and  FORMAT_TIME_SECONDARY_MAP
       settings.

       Automatic intervals: GMT will auto-select the spacing between the  annotations  and  major
       ticks,  minor  ticks,  and  grid  lines if stride is not provided after a|f|g. This can be
       useful for automated plots where the  region  may  not  always  be  the  same,  making  it
       difficult  to  determine the appropriate stride in advance. For example, -Bafg will select
       all three spacings automatically for both axes. In case of longitude–latitude plots,  this
       will keep the spacing the same on both axes. You can also use -Bxafg -Byafg to auto-select
       them separately. Note that given the myriad ways of specifying time-axis annotations,  the
       automatic  selections  may  need  to be overridden with manual settings to achieve exactly
       what you need. When stride is omitted after g, the grid line are spaced the  same  as  the
       minor  ticks;  unless g is used in consort with a, in which case the grid lines are spaced
       the same as the annotations.

       Stride units: The unit flag can take on one of 18 codes which are listed in  Table  Units.
       Almost  all  of these units are time-axis specific. However, the d, m, and s units will be
       interpreted as arc degrees, minutes, and arc seconds respectively when a map projection is
       in effect.

                           ┌─────┬────────────────┬──────────────────────────┐
                           │FlagUnitDescription              │
                           ├─────┼────────────────┼──────────────────────────┤
                           │Y    │ year           │ Plot using all 4 digits  │
                           ├─────┼────────────────┼──────────────────────────┤
                           │y    │ year           │ Plot using last 2 digits │
                           ├─────┼────────────────┼──────────────────────────┤
                           │O    │ month          │ Format  annotation using │
                           │     │                │ FORMAT_DATE_MAP          │
                           ├─────┼────────────────┼──────────────────────────┤
                           │o    │ month          │ Plot as 2-digit  integer │
                           │     │                │ (1–12)                   │
                           ├─────┼────────────────┼──────────────────────────┤
                           │U    │ ISO week       │ Format  annotation using │
                           │     │                │ FORMAT_DATE_MAP          │
                           ├─────┼────────────────┼──────────────────────────┤
                           │u    │ ISO week       │ Plot as 2-digit  integer │
                           │     │                │ (1–53)                   │
                           ├─────┼────────────────┼──────────────────────────┤
                           │r    │ Gregorian week │ 7-day  stride from start │
                           │     │                │ of       week       (see │
                           │     │                │ TIME_WEEK_START)         │
                           ├─────┼────────────────┼──────────────────────────┤
                           │K    │ ISO weekday    │ Plot  name of weekday in │
                           │     │                │ selected language        │
                           ├─────┼────────────────┼──────────────────────────┤
                           │k    │ weekday        │ Plot number  of  day  in │
                           │     │                │ the   week   (1–7)  (see │
                           │     │                │ TIME_WEEK_START)         │
                           ├─────┼────────────────┼──────────────────────────┤
                           │D    │ date           │ Format annotation  using │
                           │     │                │ FORMAT_DATE_MAP          │
                           └─────┴────────────────┴──────────────────────────┘

                           │d    │ day            │ Plot day of month (1–31) │
                           │     │                │ or day of  year  (1–366) │
                           │     │                │ (see FORMAT_DATE_MAP)    │
                           ├─────┼────────────────┼──────────────────────────┤
                           │R    │ day            │ Same  as  d; annotations │
                           │     │                │ aligned with  week  (see │
                           │     │                │ TIME_WEEK_START)         │
                           ├─────┼────────────────┼──────────────────────────┤
                           │H    │ hour           │ Format  annotation using │
                           │     │                │ FORMAT_CLOCK_MAP         │
                           ├─────┼────────────────┼──────────────────────────┤
                           │h    │ hour           │ Plot as 2-digit  integer │
                           │     │                │ (0–24)                   │
                           ├─────┼────────────────┼──────────────────────────┤
                           │M    │ minute         │ Format  annotation using │
                           │     │                │ FORMAT_CLOCK_MAP         │
                           ├─────┼────────────────┼──────────────────────────┤
                           │m    │ minute         │ Plot as 2-digit  integer │
                           │     │                │ (0–60)                   │
                           ├─────┼────────────────┼──────────────────────────┤
                           │S    │ seconds        │ Format  annotation using │
                           │     │                │ FORMAT_CLOCK_MAP         │
                           ├─────┼────────────────┼──────────────────────────┤
                           │s    │ seconds        │ Plot as 2-digit  integer │
                           │     │                │ (0–60)                   │
                           └─────┴────────────────┴──────────────────────────┘

       NOTE:  If  your  axis  is  in radians you can use multiples or fractions of pi to set such
       annotation intervals. The format is [s]pi[f], for an optional integer scale s and optional
       integer  fraction f. When GMT parses one of these forms we alert the labeling machinery to
       look for certain combinations of pi, limited to npi, 3/2  pi  (3pi2),  and  fractions  3/4
       (3pi4), 2/3 (2pi3), 1/2 (1pi2), 1/3 (1pi3), and 1/4 (1pi4) in the interval given to the -B
       axes settings.  When an annotated value is within roundoff-error of these combinations  we
       typeset the label using the Greek letter \pi and required multiples or fractions.

       NOTE: These GMT parameters can affect the appearance of the map boundary:
              MAP_ANNOT_MIN_ANGLE,           MAP_ANNOT_MIN_SPACING,           FONT_ANNOT_PRIMARY,
              FONT_ANNOT_SECONDARY,     MAP_ANNOT_OFFSET_PRIMARY,     MAP_ANNOT_OFFSET_SECONDARY,
              MAP_ANNOT_ORTHO,  MAP_FRAME_AXES,  MAP_DEFAULT_PEN, MAP_FRAME_TYPE, FORMAT_GEO_MAP,
              MAP_FRAME_PEN, MAP_FRAME_WIDTH, MAP_GRID_CROSS_SIZE_PRIMARY,  MAP_GRID_PEN_PRIMARY,
              MAP_GRID_CROSS_SIZE_SECONDARY,   MAP_GRID_PEN_SECONDARY,   FONT_TITLE,  FONT_LABEL,
              MAP_LINE_STEP,      MAP_ANNOT_OBLIQUE,      FORMAT_CLOCK_MAP,      FORMAT_DATE_MAP,
              FORMAT_TIME_PRIMARY_MAP,  FORMAT_TIME_SECONDARY_MAP, GMT_LANGUAGE, TIME_WEEK_START,
              MAP_TICK_LENGTH_PRIMARY, and MAP_TICK_PEN_PRIMARY; see the gmt.conf  man  page  for
              details.

   The -J option
       Syntax

       -Jparameters
              Specify the projection. (See cookbook summary) (See projections table).

       Description

       Select map projection. The first character of parameters determines the projection. If the
       character is upper case then the argument(s) supplied as scale(s) is interpreted to be the
       map  width  (or  axis  lengths),  else  the  scale  argument(s)  is the map scale (see its
       definition for each projection). The measurement unit (called UNIT below) is cm, inch,  or
       point,  depending  on the PROJ_LENGTH_UNIT setting in gmt.conf, but this can be overridden
       on the command line by appending c, i, or p to the scale or width values. Append +dh, +du,
       or  +dl  to the given width if you instead want to set the map height, the maximum (upper)
       dimension, or the minimum (lower) dimension, respectively [Default is +dw for width].   In
       case  the  central  meridian  is  an  optional parameter and it is being omitted, then the
       center of the longitude range given by  the  -R  option  is  used.  The  default  standard
       parallel  is  the  equator.   The  ellipsoid used in map projections is user-definable. 73
       commonly used ellipsoids and spheroids are currently supported, and users may also specify
       their  own  custom  ellipsoid  parameters [Default is WGS-84].  Several GMT parameters can
       affect   the   projection:   PROJ_ELLIPSOID,   GMT_INTERPOLANT,   PROJ_SCALE_FACTOR,   and
       PROJ_LENGTH_UNIT;  see  the  gmt.conf  man  page for details.  Choose one of the following
       projections and append the required parameters (The E or C after projection  names  stands
       for Equal-Area and Conformal, respectively):
          CYLINDRICAL PROJECTIONS:
          -Jc|Clon0/lat0/scale|width (Cassini).
              Give  projection  center  lon0/lat0  and  either  scale  (with  -Jc;  as  1:xxxx or
              plot-units/degree) or width (with -JC; in plot-units).
          -Jcyl_stere|Cyl_stere/[lon0/[lat0/]]scale|width (Cylindrical Stereographic)
              Give central meridian lon0  (optional),  standard  parallel  lat0  (optional),  and
              either  scale  along parallel (with -Jcyl_stere; as 1:xxxx or plot-units/degree) or
              width (with -JCyc_stere; in plot-units). The standard parallel is typically one  of
              these (but can be any value):

                 • 66.159467 - Miller's modified Gall

                 • 55 - Kamenetskiy's First

                 • 45 - Gall's Stereographic

                 • 30 - Bolshoi Sovietskii Atlas Mira or Kamenetskiy's Second

                 • 0 - Braun's Cylindrical
          -Jj|J[lon0/]scale|width (Miller Cylindrical Projection).
              Give  the central meridian lon0 (optional) and either scale (with -Jj; as 1:xxxx or
              plot-units/degree) or width (with -JJ; in plot-units).
          -Jm|M[lon0/[lat0/]]scale|width (Mercator [C])
              Give central meridian lon0  (optional),  standard  parallel  lat0  (optional),  and
              either  scale  along  parallel  (with -Jm; as 1:xxxx or plot-units/degree) or width
              (with -JM; in plot-units).
          -Joparameters[+v] (Oblique Mercator [C]).
              Typically used with -RLLx/LLy/URx/URy+r or with projected coordinates.  Specify one
              of:

              -Jo|O[a|A]lon0/lat0/azimuth/scale|width[+v]
                     Set  projection  center  lon0/lat0, azimuth of oblique equator, and scale or
                     width

              -Jo|O[b|B]lon0/lat0/lon1/lat1/scale|width[+v]
                     Set projection center  lon0/lat0,  another  point  on  the  oblique  equator
                     lon1/lat1, and scale or width

              -Jo|O[c|C]lon0/lat0/lonp/latp/scale|width[+v]
                     Set  projection  center lon0/lat0, pole of oblique projection lonp/latp, and
                     scale or width

              Give scale along oblique equator (with -Jo as 1:xxxx or plot-units/degree) or width
              (with  -JO in plot-units). Use upper-case A|B|C to remove enforcement of a northern
              hemisphere pole. Append +v to  let  the  oblique  Equator  align  with  the  y-axis
              [x-axis].   Note:  If  the  region  (-R)  is given without the +r modifier then the
              arguments are considered oblique degrees relative to the projection center and  not
              longitude/latitude bounds.
          -Jq|Q[lon0/[lat0/]]scale|width (Cylindrical Equidistant).
              Give  the  central meridian lon0 (optional), standard parallel lat0 (optional), and
              either scale (with -Jq; as 1:xxxx or plot-units/degree)  or  width  (with  -JQ;  in
              plot-units) The standard parallel is typically one of these (but can be any value):

                 • 61.7 - Grafarend and Niermann, minimum linear distortion

                 • 50.5 - Ronald Miller Equirectangular

                 • 43.5 - Ronald Miller, minimum continental distortion

                 • 42 - Grafarend and Niermann

                 • 37.5 - Ronald Miller, minimum overall distortion

                 • 0 - Plate Carree, Simple Cylindrical, Plain/Plane Chart
          -Jt|Tlon0/[lat0/]scale|width (Transverse Mercator [C])
              Give  the central meridian lon0, central parallel lat0 (optional), and either scale
              (with -Jt; as 1:xxxx or plot-units/degree) or width (with -JT; in plot-units).
          -Ju|Uzone/scale|width (UTM - Universal Transverse Mercator [C]).
              Give the UTM zone (A,B,1-60[C-X],Y,Z)) and either scale (with  -Ju;  as  1:xxxx  or
              plot-units/degree)  or  width  (with  -JU; in plot-units). Zones: If C-X not given,
              prepend - or + to enforce southern or northern hemisphere conventions  [default  is
              northern if south > 0].
          -Jy|Y[lon0/[lat0/]]scale|width (Cylindrical Equal-Area [E]).
              Give  the  central meridian lon0 (optional), standard parallel lat0 (optional), and
              either scale (with -Jy; as 1:xxxx or plot-units/degree)  or  width  (with  -JY;  in
              plot-units).  The  standard  parallel  is  typically  one  of these (but can be any
              value):

                 • 50 - Balthasart

                 • 45 - Gall

                 • 37.0666 - Caster

                 • 37.4 - Trystan Edwards

                 • 37.5 - Hobo-Dyer

                 • 30 - Behrman

                 • 0 - Lambert (default)

          CONIC PROJECTIONS:

          -Jb|Blon0/lat0/lat1/lat2/scale|width (Albers [E]).
                 Give projection center lon0/lat0, two standard parallels lat1/lat2,  and  either
                 scale  (with  -Jb;  as  1:xxxx  or  plot-units/degree)  or  width  (with -JB; in
                 plot-units).

          -Jd|Dlon0/lat0/lat1/lat2/scale|width (Conic Equidistant)
                 Give projection center lon0/lat0, two standard parallels lat1/lat2,  and  either
                 scale  (with  -Jd;  as  1:xxxx  or  plot-units/degree)  or  width  (with -JD; in
                 plot-units).

          -Jl|Llon0/lat0/lat1/lat2/scale|width (Lambert [C])
                 Give origin lon0/lat0, two standard parallels lat1/lat2, and scale  along  these
                 (with -Jl; as 1:xxxx or plot-units/degree) or width (with -JL; in plot-units).

          -Jpoly|Poly/[lon0/[lat0/]]scale|width ((American) Polyconic).
                 Give  the  central  meridian lon0 (optional), reference parallel lat0 (optional,
                 default = equator), and either scale along central  meridian  (with  -Jpoly;  as
                 1:xxxx or plot-units/degree) or width (with -JPoly; in plot-units).

          AZIMUTHAL PROJECTIONS:

          Except    for    polar    aspects,    -Rw/e/s/n    will    be   reset   to   -Rg.   Use
          -Rxlleft/ylleft/xuright/yuright+r for smaller regions.

          -Ja|Alon0/lat0[/horizon]scale|width (Lambert [E]).
                 lon0/lat0 specifies the projection center. horizon specifies  the  max  distance
                 from projection center (in degrees, <= 180, default 90). Give either scale (with
                 -Ja; as 1:xxxx or radius/lat, where radius is distance in plot-units from origin
                 to the oblique latitude lat) or width (with -JA; in plot-units).

          -Je|Elon0/lat0[/horizon]scale|width (Azimuthal Equidistant).
                 lon0/lat0  specifies  the  projection center. horizon specifies the max distance
                 from projection center (in degrees, <= 180, default 180). Give scale (with  -Je;
                 as  1:xxxx  or radius/lat, where radius is distance in plot-units from origin to
                 the oblique latitude lat) or width (with -JE; in plot-units).

          -Jf|Flon0/lat0[/horizon]scale|width (Gnomonic).
                 lon0/lat0 specifies the projection center. horizon specifies  the  max  distance
                 from  projection center (in degrees, < 90, default 60). Give scale (with -Jf; as
                 1:xxxx or radius/lat, where radius is distance in plot-units from origin to  the
                 oblique latitude lat) or width (with -JF; in plot-units).

          -Jg|Glon0/lat0[/horizon]/scale|width (Orthographic).
                 lon0/lat0  specifies  the  projection center. horizon specifies the max distance
                 from projection center (in degrees, <= 90, default 90). Give scale (with -Jg; as
                 1:xxxx  or radius/lat, where radius is distance in plot-units from origin to the
                 oblique latitude lat.

          -Jg|Glon0/lat0/scale|width[+aazimuth][+ttilt][+vvwidth/vheight][+wtwist][+zaltitude[r|R]|g]
          (General Perspective).
                     lon0/lat0  specifies  the projection center. Give scale (with -Jg; as 1:xxxx
                     or radius/lat, where radius is distance in plot-units  from  origin  to  the
                     oblique  latitude  lat) or width (with -JG; in plot-units). Several optional
                     modifiers control the perspective:

                 • +a sets azimuth measured to the east of north of view [0].

                 • +t sets the upward tilt of the plane of projection. If tilt is negative,  then
                   the viewpoint is centered on the horizon [0].

                 • +v  sets  a  restricted view: vwidth and vheight ( in degrees) limits the view
                   from the viewpoint [unrestricted].

                 • +w sets the clockwise twist of the viewpoint (in degrees) [0].

                 • +z sets the altitude of the viewer above sea level in  kilometers  [infinity].
                   Alternatively append R if giving the distance of the viewer from the center of
                   the Earth in Earth radii, or r if giving the distance from the center  of  the
                   Earth  in  kilometers.   Finally,  give  altitude  as g to compute and use the
                   altitude for a geosynchronous orbit.

          -Js|Slon0/lat0[/horizon]/scale|width (General Stereographic [C]).
                 lon0/lat0 specifies the projection center. horizon specifies  the  max  distance
                 from projection center (in degrees, < 180, default 90). Give scale (with -Js; as
                 1:xxxx (true at pole) or lat/1:xxxx (true at standard parallel lat and  requires
                 lat0  =  ±90)  or  radius/lat  (radius  in plot-units from origin to the oblique
                 latitude lat). Note if 1:xxxx is used then to  specify  horizon  you  must  also
                 specify the lat as ±90 to avoid ambiguity.) or width (with -JS; in plot-units).

          MISCELLANEOUS PROJECTIONS:

          -Jh|H[lon0/]scale|width (Hammer [E]).
                 Give  the  central meridian lon0 (optional) and either scale along equator (with
                 -Jh; as 1:xxxx or plot-units/degree) or width (with -JH; in plot-units).

          -Ji|I[lon0/]scale|width (Sinusoidal [E]).
                 Give the central meridian lon0 (optional) and either scale along  equator  (with
                 -Ji; as 1:xxxx or plot-units/degree) or width (with -JI; in plot-units).

          -Jk|Kf[lon0/]scale|width (Eckert IV [E]).
                 Give  the  central meridian lon0 (optional) and either scale along equator (with
                 -Jk; as 1:xxxx or plot-units/degree) or width (with -JK; in plot-units).

          -Jk|K[s][lon0/]scale|width (Eckert VI [E]).
                 Give the central meridian lon0 (optional) and either scale along  equator  (with
                 -Jk; as 1:xxxx or plot-units/degree) or width (with -JK; in plot-units).

          -Jn|N[lon0/]scale|width (Robinson).
                 Give  the  central meridian lon0 (optional) and either scale along equator (with
                 -Jn; as 1:xxxx or plot-units/degree) or width (with -JN; in plot-units).

          -Jr|R[lon0/]scale|width (Winkel Tripel).
                 Give the central meridian lon0 (optional) and either scale along  equator  (with
                 -Jr; as 1:xxxx or plot-units/degree) or width (with -JR; in plot-units).

          -Jv|V[lon0/]scale|width (Van der Grinten).
                 Give  the  central meridian lon0 (optional) and either scale along equator (with
                 -Jv; as 1:xxxx or plot-units/degree) or width (with -JV; in plot-units).

          -Jw|W[lon0/]scale|width (Mollweide [E]).
                 Give the central meridian lon0 (optional) and either scale along  equator  (with
                 -Jw; as 1:xxxx or plot-units/degree) or width (with -JW; in plot-units).

          NON-GEOGRAPHICAL PROJECTIONS:
          -Jp|Pscale|width[+a][+f[e|p|radius]][+kkind][+roffset][+torigin][+z[p|radius]]]  (Polar
          coordinates (theta, r))

          Give scale (with -Jp; in plot-units/r-unit) or width (with  -JP;  in  plot-units).  The
          following modifiers are supported by -Jp|P:

          • +a to indicate that theta is azimuth CW from North instead of direction CCW from East
            [Default is CCW from East].

          • +f to flip the radial direction to point inwards, and append e  to  indicate  that  r
            represents  elevations  in degrees (requires south >= 0 and north <= 90), p to select
            current planetary radius (determined by PROJ_ELLIPSOID) as maximum radius [north], or
            radius to specify a custom radius.

          • +k  sets  the  annotation  kind  to  be  longitudes  (x) or latitudes (y) [Default is
            unspecified angles].

          • +roffset to include a radial offset in measurement units [default is 0].

          • +torigin in degrees so that this angular value is aligned with  the  positive  x-axis
            (or the azimuth to be aligned with the positive y-axis if +a) [default is 0].

          • +z to annotate depth rather than radius [default is radius]. Alternatively, if your r
            data are actually depths then you can append p or radius to get radial annotations (r
            = radius - z) instead.
          -Jx|Xx-scale|width[l|ppower|T|t][/y-scale|height[l|ppower|T|t]][d|g]  (Linear, log, and
          power scaling)

          Give x-scale (with -Jx; as 1:xxxx  or  plot-units/x-unit)  and/or  y-scale  (1:xxxx  or
          plot-units/y-unit);   or  specify  width  and/or  height  (with  -JX;  in  plot-units).
          y-scale=x-scale if not specified separately and using 1:xxxx implies  that  x-unit  and
          y-unit  are in meters. Use negative scale(s) to reverse the direction of an axis (e.g.,
          to have y be positive down). Set height or width to 0 to have it  recomputed  based  on
          the  implied  scale of the other axis.  Optionally, append to x-scale y-scale, width or
          height one of the following:

          • d to indicate that data are geographical coordinates (in degrees).

          • g to indicate that data are geographical coordinates

          • l to take \log_{10} of values before scaling.

          • ppower to raise values to power before scaling.

          • t to indicate that input coordinates are time relative to TIME_EPOCH.

          • T to indicate that input coordinates are absolute time.
                For mixed axes with only one geographic axis you may need to set -f as well.

       When -J is used without any further arguments, or  just  with  the  projection  type,  the
       arguments  of  the  last  used  -J, or the last used -J with that projection type, will be
       used.

       -Jz|Zparameters
              Set z-axis scaling; same syntax as -Jx.

       -Jproj|EPSG:n
              Starting at GMT6 it is possible to use the PROJ library to do coordinate and  datum
              transforms.   This  is  achieved  via  the GDAL library. It is, however, beyond the
              scope of this manual to document the PROJ syntax (that is the syntax  of  the  proj
              and cs2cs programs) so users are referred to PROJ Applications for the details.

              The usage of PROJ follows very closely the syntax of proj and cs2cs. The projection
              parameters are encapsulated under the -J option. Because there are normally several
              parameters  defining  a referencing system separated by spaces (in PROJ or GDAL) we
              can either use double quotes as in -J"+proj=merc  +ellps=WGS84  +units=m"  or  just
              glue all parameters like in -J+proj=merc+ellps=WGS84+units=m.

              Using  EPSG  codes  is  also  possible  (but  need  the  setting  of  the GDAL_DATA
              environment variable to point  to  the  GDAL's  data  sub-directory).  For  example
              -JEPSG:4326 sets the WGS-84 system.

              For mapproject and grdproject we can go directly from the referencing system A to B
              without the intermediate step of converting to  geographic  coordinates.   That  is
              obtained    (like    in    cs2cs)    by    using    the   +to   keyword.   Example:
              -JEPSG:4326+to+proj=aeqd+ellps=WGS84+units=m. A much awaited bonus is also that  we
              now do not need to set -R to do point coordinate conversions.

              While  for  point and grid conversions done by mapproject and grdproject we can use
              all PROJ projections, the situations is, however, rather more limited  for  mapping
              purposes.   Here,  only  the subset of the PROJ projections that can be mapped into
              the GMT projections syntax is available to use. Another aspect that is not  present
              in  PROJ,  because  it's  not a mapping library, is how to set the map scale or map
              dimension. We introduced the two extensions +width=size and +scale=1:xxxx that work
              exactly  like  the  map  width  and  scale  in classical GMT. It is also allowed to
              provide the scale (but not the width) by appending the string "/1:xxx" to  the  end
              of the projection parameters.

   The -R option
       Syntax

       -Rxmin/xmax/ymin/ymax[+r][+uunit]
              Specify the region of interest. (See cookbook information).

       Description

       The  -R  option  defines the map region or data domain of interest. It may be specified in
       one of several ways (options 1 and 3 are shown in panels a) and  b)  respectively  of  the
       Figure Map region):

       1. -Rxmin/xmax/ymin/ymax.  This  is the standard way to specify Cartesian data domains and
          geographic regions when  using  map  projections  where  meridians  and  parallels  are
          rectilinear, where xmin, xmax, ymin, and ymax refer to the data limits.

       2. -Rxmin/xmax/ymin/ymax+uunit.  Append  +uunit  to  the  option  1 to specify a region in
          projected units (e.g., UTM meters) where xmin/xmax/ymin/ymax  are  Cartesian  projected
          coordinates  compatible  with  the  chosen projection and unit is an allowable distance
          unit [e]. The coordinates are relative to the standard longitude and latitude indicated
          in  the  projection  (-J).   For  projected  regions  centered on (0,0) you may use the
          short-hand -Rhalfwidth[/halfheight]+uunit, where halfheight defaults  to  halfwidth  if
          not given. This short-hand requires the +u modifier.

       3. -Rxlleft/ylleft/xuright/yuright+r.  This  form  is  useful for map projections that are
          oblique, making meridians and parallels poor  choices  for  map  boundaries.  Here,  we
          instead  specify  the  lower left corner and upper right corner geographic coordinates,
          followed by the modifier +r. This form guarantees a rectangular map even  though  lines
          of equal longitude and latitude are not straight lines.

       4. -Rg or -Rd. These forms can be used to quickly specify the global domain (0/360 for -Rg
          and -180/+180 for -Rd in longitude, with -90/+90 in latitude).

       5. -Rgridfile. This will copy the domain settings found for the grid  in  specified  file.
          Note  that  depending on the nature of the calling module, this mechanism will also set
          grid spacing and possibly the grid registration (see Grid registration: The -r option).

       6. -Rcode1,code2,...[+e|r|Rincs]. This indirectly supplies the region  by  consulting  the
          DCW  (Digital  Chart of the World) database and derives the bounding regions for one or
          more countries given by the codes. Simply append one or more comma-separated  countries
          using  either  the two-character ISO 3166-1 alpha-2 convention (e.g., -RNO) or the full
          country name (e.g., -RNorway). To select a  state  within  a  country  (if  available),
          append  .state  (e.g,  -RUS.TX).  To  specify  a  whole  continent,  spell out the full
          continent name (e.g., -RAfrica).  Finally, append any DCW collection  abbreviations  or
          full  names  for  the  extent  of  the  collection  or  named  region.  All  names  are
          case-insensitive. The following modifiers can be appended:

          • +r to adjust the region boundaries to be multiples of the  steps  indicated  by  inc,
            xinc/yinc,  or  winc/einc/sinc/ninc  [default is no adjustment]. For example, -RFR+r1
            will select the national bounding box of France rounded to  nearest  integer  degree,
            where inc can be positive to expand the region or negative to shrink the region.

          • +R  to  adjust  the  region  by  adding  the  amounts specified by inc, xinc/yinc, or
            winc/einc/sinc/ninc [default is no extension], where inc can be  positive  to  expand
            the region or negative to shrink the region.

          • +e  to  adjust  the  region boundaries to be multiples of the steps indicated by inc,
            xinc/yinc, or winc/einc/sinc/ninc, while ensuring that the bounding box  is  adjusted
            by  at  least  0.25  times the increment [default is no adjustment], where inc can be
            positive to expand the region or negative to shrink the region.

       7. -Rjustifyx0/y0/nx/ny, where justify is a 2-character combination of  L|C|R  (for  left,
          center, or right) and T|M|B (for top, middle, or bottom) (e.g., BL for lower left). The
          two character code justify indicates which point on a rectangular grid region the x0/y0
          coordinates  refer  to  and  the  grid dimensions nx and ny are used with grid spacings
          given via -I to create the corresponding region. This method can be used when  creating
          grids. For example, -RCM25/25/50/50 specifies a 50x50 grid centered on 25,25.

       8. -Rxmin/xmax/ymin/ymax/zmin/zmax. This method can be used for perspective views with the
          -Jz and the -p option, where the z-range (zmin/zmax) is appended to the first method to
          indicate  the  third  dimension.  This  is not used for -p without -Jz, in which case a
          perspective view of the place is plotted with no third dimension.

       9. -Ra[uto] or -Re[xact]. Under modern mode,  and  for  plotting  modules  only,  you  can
          automatically  determine  the  region  from the data used. You can either get the exact
          area using -Re [Default if no -R is given] or a slightly larger area  sensibly  rounded
          outwards to the next multiple of increments that depend on the data range using -Ra.
          In  case of perspective view -p, a z-range (zmin, zmax) can be appended to indicate the
          third dimension. This needs to be done only when using the -Jz option, not  when  using
          only the -p option. In the latter case a perspective view of the plane is plotted, with
          no third dimension.

   The -U option
       Syntax

       -U[label|+c][+jjustify][+odx[/dy]][+ttext]
              Draw GMT time stamp logo on plot. (See cookbook information).

       Description

       The -U option draws the GMT system time stamp on the plot. You  may  provide  on  optional
       label  text  string written to the right side of the time stamp (and must be surrounded by
       double quotes if it contains spaces).

       Several modifiers  are supported:

       • +c - Plot the current command string.

       • +j - Append the justification of the  time  stamp,  where  justify  is  a  two-character
         justification  code that is a combination of a horizontal (L(eft), C(enter), or R(ight))
         and a vertical (T(op), M(iddle), or B(ottom)) code [default is BL].

       • +o - Give dx[/dy] to offset the anchor point for the time stamp by dx and optionally  dy
         (if different than dx).

       • +t  -  Replace  the  UNIX time stamp with a custom text instead (< 64 characters). Place
         multi-word text in quotes and let +t be the last modifier used.

       The GMT parameters MAP_LOGO, MAP_LOGO_POS, FONT_LOGO and FORMAT_TIME_STAMP can affect  the
       appearance;  see  the gmt.conf man page for details. The time string will be in the locale
       set by the environment variable TZ (generally local time).

   The -V option
       Syntax

       -V[level]
              Select verbosity level [w]. (See cookbook information).

       Description

       The -V option controls the verbosity mode, which determines which  messages  are  sent  to
       standard error. Choose among 7 levels of verbosity; each level adds more messages:

       • q - Quiet, not even fatal error messages are produced.

       • e - Error messages only.

       • w - Warnings (by default, same as running without -V)

       • t - Timings (report runtimes for time-intensive algorithms).

       • i - Informational messages (same as -V only).

       • c - Compatibility warnings (if compiled with backward-compatibility).

       • d - Debugging messages.

       This  option  can  also  be  set  by  specifying  the default GMT_VERBOSE as quiet, error,
       warning, timing, compat, information, or debug, in order of increased  verbosity  [default
       is warning].

   The -X -Y options
       Syntax

       -X[a|c|f|r][xshift]
              Shift plot origin. (See cookbook information).

       -Y[a|c|f|r][yshift]
              Shift plot origin. (See cookbook information).

       Description

       The  -X  and  -Y  options  shift  the  plot  origin  relative  to  the  current  origin by
       (xshift,yshift). Optionally,  append  the  length  unit  (c,  i,  or  p).  Default  is  (‐
       MAP_ORIGIN_X,  MAP_ORIGIN_Y) for new plots, which ensures that boundary annotations fit on
       the page. Subsequent overlays will be co-registered with  the  previous  plot  unless  the
       origin  is shifted using these options. The following directives are supported [default is
       r]:

       • a - Prepend to shift the origin back to the original position after plotting.

       • c - Prepend to center the plot on the center of  the  paper  (optionally  add  a  shift)
         (classic mode only).

       • f - Prepend to shift the origin relative to the fixed lower left (classic mode only).

       • r - Prepend to move the origin relative to its current location.

       Note:  Directives  c  and  f  are  only available in classic mode.  When -X or -Y are used
       without any further arguments, the values from the last use of that option in  a  previous
       GMT  command  will  be  used.  In modern mode, -X and -Y can also access the previous plot
       bounding box dimensions w and h and construct offsets that involve them.  Thus, xshift can
       in general be [[±][f]w[/d]±]xoff, where optional signs, factor f and divisor d can be used
       to compute an offset that may be adjusted further  by  ±off.   Similarly,  yshift  can  in
       general be [[±][f]h[/d]±]yoff.  For instance, to move the origin up 2 cm beyond the height
       of the previous plot, use -Yh+2c.  To move the origin half the width  to  the  right,  use
       -Xw/2.  Note:  the previous plot bounding box refers to the last object plotted, which may
       be an image, logo, legend, colorbar, etc.

   The -a option
       Syntax

       -a[[col=]name][,...]
              Control how aspatial data are handled in GMT during input and output.

       Description

       GMT relies on external tools to translate geospatial  files  such  as  shapefiles  into  a
       format  we  can  read.  The  tool ogr2ogr in the GDAL package can do such translations and
       preserve the aspatial metadata via a new OGR/GMT format specification  (See  the  cookbook
       chapter The GMT Vector Data Format for OGR Compatibility). For this to be useful we need a
       mechanism to associate certain metadata values with  required  input  and  output  columns
       expected  by  GMT programs. The -a option allows you to supply one or more comma-separated
       associations col=name, where name is the name of an aspatial attribute field in a  OGR/GMT
       file  and  whose  value  we wish to as data input for column col. The given aspatial field
       thus replaces any other value already set. Notes: (1) col = 0 is the  first  data  column.
       (2) If no aspatial attributes are needed then the -a option is not needed – GMT will still
       process and read such data files.

   OGR/GMT input with -a option
       If you need to populate GMT data columns with  (constant)  values  specified  by  aspatial
       attributes,  use  -a  and  append any number of comma-separated col=name associations. For
       example, -a2=depth will read the spatial x, y columns from the file and add  a  third  (z)
       column  based  on  the  value  of  the aspatial field called depth. You can also associate
       aspatial fields with other settings such as labels, fill colors,  pens,  and  values  (for
       looking-up  colors)  by  letting the col value be one of D (for distance), G (for fill), I
       (for ID), L (for label), T (for  text),  W  (for  pen),  or  Z  (for  value).  This  works
       analogously  to  how  standard  multi-segment  files can pass such options via its segment
       headers (See the cookbook chapter GMT File Formats). Note: If the leading col= is omitted,
       the column value is automatically incremented starting at 2.

   OGR/GMT output with -a option
       GMT  table-writing  tools  can also output the OGR/GMT format directly. Specify if certain
       GMT data columns with  constant  values  should  be  stored  as  aspatial  metadata  using
       col=name[:type],  where  you  can  optionally specify what data type it should be from the
       options double, float, integer, char, string,  logical,  byte,  or  datetime  [default  is
       double].  As  for  input,  you can also use the special col entries of D (for distance), G
       (for fill), I (for ID), L (for label), T (for text), W (for pen), or Z (for value) to have
       values  stored  as options in segment headers be used as the source for the named aspatial
       field. The type will be set automatically for these  special  col  entries.  Finally,  for
       output  you must append +ggeometry, where geometry can be any of [M]POINT|LINE|POLY; where
       M represents the multi-versions of these three geometries. Use  upper-case  +G  to  signal
       that you want to split any line or polygon features that straddle the Dateline.

   The -bi option
       Syntax

       -birecord[+b|l]
              Select  native  binary  format for primary table input (secondary inputs are always
              ASCII).

       Description

       Select native binary record format for primary table input. The  record  is  one  or  more
       groups with format [ncols][type][w], where ncols is the number of consecutive data columns
       of given type and type must be one of:

          • c - int8_t (1-byte signed char)

          • u - uint8_t (1-byte unsigned char)

          • h - int16_t (2-byte signed int)

          • H - uint16_t (2-byte unsigned int)

          • i - int32_t (4-byte signed int)

          • I - uint32_t (4-byte unsigned int)

          • l - int64_t (8-byte signed int)

          • L - uint64_t (8-byte unsigned int)

          • f - 4-byte single-precision float

          • d - 8-byte double-precision float [Default]

          • x - use to skip ncols anywhere in the record

       Force byte-swapping of a group by appending w at the end of the group.  For  records  with
       mixed  types,  append  additional  comma-separated  groups (no space between groups).  The
       following modifiers are supported:

          • +b|l - Indicate that the entire data file should be read as  big-  or  little-endian,
            respectively.

       The  cumulative  number of ncols may exceed the columns actually needed by the program. If
       ncols is not specified we assume that type applies  to  all  columns  and  that  ncols  is
       implied  by the expectation of the program. When using native binary data the user must be
       aware of the fact that GMT has no way of determining the actual number of columns  in  the
       file.  Native  binary  files may have a header section, where the -h option can be used to
       skip the first n bytes. If the input file is  netCDF,  no  -b  is  needed;  simply  append
       ?var1/var2/...  to  the filename to specify the variables to be read (see GMT File Formats
       and Modifiers for COARDS-compliant netCDF files for more information).  Here is an example
       that writes a binary file and reads it back with the first column 4 byte float, the second
       column 8 byte int, and the third column 8 byte double.

          echo 1.5 2 2.5 | gmt convert -bo1f,1l,1d > test.bin
          gmt convert test.bin -bi1f,1l,1d

   The -bo option
       Syntax

       -borecord[+b|l]
              Select native binary format for table output.

       Description

       Select native binary format for table output. The record must be one or more  groups  with
       format  [ncols][type][w],  where  ncols is the number of consecutive data columns of given
       type and type must be one of c, u, h, H, i, I, l, L, f, or d [Default] (see -bi types  for
       descriptions).   Force  byte-swapping  of  a group by appending w at the end of the group.
       For a mixed-type output record, append additional comma-separated groups (no space between
       groups) The following modifiers are supported:

          • +b|l   to  indicate  that  the  entire  data  file  should  be  written  as  big-  or
            little-endian, respectively.

       If ncols is not specified we assume that type applies to all columns  and  that  ncols  is
       implied by the default output of the program. Note: NetCDF file output is not supported.

   The -c option
       Syntax

       -c[row,col|index]
              Advance to the selected subplot panel.

       Description

       The -c option can be used to either advance the focus of plotting to the next panel in the
       sequence (either by row or by column as set by subplot's -A option) or to specify directly
       the  row,col  or  1-D  index of the desired panel, when using subplot to assemble multiple
       individual panels in a matrix layout.  The -c option is only allowed when in subplot mode.
       If  no  -c option is given for the first subplot then we default to row=col=index=0, i.e.,
       the upper left panel.  Note: row, col, and index all start at 0.

   The -d option
       Syntax

       -di|onodata[+ccol]
              Substitute specific values with NaN.

       Description

       The -d option allows user-coded missing data values  to  be  translated  to  official  NaN
       values  in  GMT.  Within  GMT,  any  missing values are represented by the IEEE NaN value.
       However, user data may occasionally denote missing data  with  an  unlikely  value  (e.g.,
       -99999). Since GMT cannot guess this special missing data value, you can use the -d option
       to have such values replaced with NaNs. Similarly, the -d option can replace all NaNs with
       the chosen nodata value should the GMT output need to conform to such a requirement.

       For  input  only,  use  -dinodata to examine all input columns after the first two. If any
       item equals nodata, the value is interpreted as a missing data  item  and  is  substituted
       with the value NaN.

       For  output only, use -donodata to examine all output columns. If any item equals NaN, the
       NaN value is substituted with the chosen missing data value nodata.

       Use the +c modifier to override the starting column  used  for  the  examinations  [2  for
       input, 0 for output].

   The -e option
       Syntax

       -e[~]"pattern" | -e[~]/regexp/[i]
              Only accept ASCII data records that contain the specified pattern.

       Description

       The -e option offers a built-in pattern scanner that will only pass records that match the
       given pattern or regular expressions, whereas modules that read ASCII tables will normally
       process  all  the  data records that are read.  The test can also be inverted to only pass
       data records that do not match the pattern, by using -e~.  The  test  is  not  applied  to
       header  or  segment  headers.  Should your pattern happen to start with ~ you will need to
       escape this character with a backslash [Default accepts all data  records].  For  matching
       data  records  against  extended  regular  expressions,  please  enclose the expression in
       slashes. Append i for case-insensitive matching. To supply a list of such  patterns,  give
       +ffile  with  one  pattern per line.  To give a single pattern starting with +f, escape it
       with a backslash. Note: Option -e is not allowed if -b selects binary input.

   The -f option
       Syntax

       -f[i|o]colinfo
              Specify the data types of input and/or output columns (time or geographical data).

       Description

       The -f option specifies what kind of data each input or output column  contains  when  map
       projections  are  not required. Optionally, append i or o to make this apply only to input
       or output, respectively [Default applies to both]. Append a text string  with  information
       about  each  column  (or range of columns) separated by commas. Each group starts with the
       column number (0 is the first column) followed by either x (longitude),  y  (latitude),  T
       (absolute  calendar  time),  t  (relative  time  in  chosen TIME_UNIT since TIME_EPOCH), d
       (dimension) or s (trailing text). If several consecutive columns have the same format  you
       may specify a range of columns rather than a single column. Column ranges must be given in
       the format start[:inc]:stop, where inc defaults to 1 if not specified.   For  example,  if
       our  input  file  has  geographic coordinates (latitude, longitude) with absolute calendar
       coordinates in the columns 3 and 4, we would specify fi0y,1x,3:4T. All other  columns  are
       assumed  to  have  the  default  (floating point) format and need not be set individually.
       Notes: (1) You can also indicate that all items from the given column and to  the  end  of
       the  record should be considered trailing text by giving the code s (for string). Only the
       last group may set s. (2) Types T and s can only be used with ASCII data sets.

       Three shorthand options for common selections are available. The shorthand -f[i|o]g  means
       -f[i|o]0x,1y  (i.e.,  geographic  coordinates),  while  -f[i|o]c  means -f[i|o]0:1f (i.e.,
       Cartesian coordinates). A special use of -f is to select -fp[unit], which requires  -J  -R
       and  lets  you  use  projected  map  coordinates  (e.g.,  UTM meters) as data input.  Such
       coordinates are automatically inverted to longitude,  latitude  during  the  data  import.
       Optionally,  append  a length unit (see table distance units) [default is meter]. For more
       information, see Sections Input data formats and Output data formats.

   The -g option
       Syntax

       -gx|y|z|d|X|Y|Dgap[u][+a][+ccol][+n|p]
              Examine the spacing between consecutive data points in order to  impose  breaks  in
              the line.

       Description

       The  -g  option is used to detect gaps based on one or more criteria. Repeat the option to
       specify multiple criteria.  A criterion  is  specified  using  one  of  the  x|y|z|d|X|Y|D
       directives.  The upper-case directives specify that the criterion should be applied to the
       projected coordinates for modules that map data to map coordinates.

       • x|X - Define a gap when there is a large enough change in the x coordinates (upper  case
         to use projected coordinates).

       • y|Y  - Define a gap when there is a large enough change in the y coordinates (upper case
         to use projected coordinates).

       • z - Define a gap when there is a large enough change in the z data. Use +ccol to  change
         the z data column [Default col is 2 (i.e., 3rd column)].

       • d|D - Define a gap when there is a large enough distance between coordinates (upper case
         to use projected coordinates).

       A unit u may be appended to the specified gap:

       • For geographic data (x|y|d), the unit may be arc d(egree), m(inute),  and  s(econd),  or
         (m)e(ter), f(eet), k(ilometer), M(iles), or n(autical miles) [Default is (m)e(ter)].

       • For  projected  data  (X|Y|D), the unit may be i(nch), c(entimeter), or p(oint) [Default
         unit is set by PROJ_LENGTH_UNIT].

       Append modifier +a to specify that all the criteria must be met [default imposes breaks if
       any one criterion is met].

       One of the following modifiers can be appended:

       • +n  - Specify that the previous value minus the current column value must exceed gap for
         a break to be imposed.

       • +p - Specify that the current value minus the previous value must exceed gap for a break
         to be imposed.

       Default  imposes  breaks based on the absolute value of the difference between the current
       and previous value.  Notes: (1) For x|y|z with time data the unit is instead controlled by
       TIME_UNIT.  (2)  GMT  has other mechanisms that can determine line segmentation, including
       segments defined by multiple segment header records (see the  cookbook  chapter  GMT  File
       Formats)  or  segments  defined  by NaN values when IO_NAN_RECORDS is set to pass [default
       skips NaN values].

   The -h option
       Syntax

       -h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle]
              Specify that input and/or output file(s) have n header records [default is 0].

       Description

       Specify that the primary input file(s) has n  header  record(s).  The  default  number  of
       header  records  is  set  by  IO_N_HEADER_RECS [default is 0]. Use -hi if only the primary
       input data should have header records [Default will write out header records if the  input
       data  have them]. For output you may control the writing of header records using -h[o] and
       the optional modifiers:

       • +d - Remove existing header records.

       • +c - Add a header comment with column names to the output [default is no column names].

       • +m - Add a segment header segheader to the output after the header block [default is  no
         segment header].

       • +r  -  Add a remark comment to the output [default is no comment]. The remark string may
         contain \n to indicate line-breaks.

       • +t - Add a title comment to the output [default is  no  title].  The  title  string  may
         contain \n to indicate line-breaks.

       Notes:  (1)  Blank  lines  and  lines  starting  with # are always skipped. To use another
       leading character for indicating header records, set IO_HEADER_MARKER. With -h  in  effect
       the  first n records are taken verbatim as headers and not skipped even if any is starting
       with #. (2) If used with native binary data (using -b) we interpret n to instead mean  the
       number of bytes to skip on input or pad on output.

   The -i option
       Syntax

       -icols[+l][+ddivisor][+sscale|d|k][+ooffset][,...][,t[word]]
              Select specific data columns for primary input, in arbitrary order.

       Description

       The  -i  option allows you to specify which input file physical data columns to use and in
       what order. Specify individual columns or column ranges in  the  format  start[:inc]:stop,
       where  inc  defaults to 1 if not specified, separated by commas [Default reads all columns
       in order, starting with the first column (i.e., column 0)]. Columns can be  repeated.  The
       chosen  data  columns  will  be  used  as  given  and  columns not listed will be skipped.
       Optionally, append one of the following  modifiers  to  any  column  or  column  range  to
       transform the input columns:

       • +l - Take \log_{10} of the input values.

       • +d - Divide the input values by the factor divisor [default is 1].

       • +s - Multiply the input values by the factor scale [default is 1]. Alternatively, give d
         to convert km to degrees or k to convert degrees to km using PROJ_MEAN_RADIUS.

       • +o - Add the given offset to the input values [default is 0].

       Notes: (1) The order of these optional transformations are (1) take \log_{10},  (2)  scale
       or divide, and (3) add offset. Do not repeat operations: -i+d9+o8+o2+s3+d4 will be treated
       as -i+o2+d4.  To read from a given column until the end of the record, leave off stop when
       specifying  the column range. Normally, any trailing text will be read but when -i is used
       to specify specific input columns you must explicitly append the "column" t to retain  the
       trailing  text internally. To only ingest a single word from the trailing text, append the
       word number (first word is 0).  If your trailing text columns start with  a  valid  number
       and  you  want  to  ensure  the  content  from column col to the end of the record will be
       considered trailing text, use -fcols.  Finally, -in will simply read the  numerical  input
       and  skip  any  trailing text. (2) Using -i assumes there are as many numerical columns as
       implied in -i, so if you have a mix of numerical and text columns we will forge ahead  and
       read  those  text  columns  (most  likely  returned  as NaNs) and return your selection as
       numerical values.  The  default  (no  -i  provided)  will  examine  the  record  and  stop
       conversions when the record switches to trailing text.

   The -j option (spherical distance calculations)
       Syntax

       -je|f|g
              Determine  how  spherical  distances  are  calculated  in modules that support this
              [Default is -jg].

       Description

       GMT has different ways to  compute  distances  on  planetary  bodies.  Choose  from  these
       directives:

       • g  -  Perform  great  circle  distance  calculations,  with  parameters such as distance
         increments or radii compared against calculated great circle distances [Default is -jg].

       • f - Select Flat Earth mode, which gives a more approximate but faster result.

       • e - Select ellipsoidal  (or  geodesic)  mode  for  the  highest  precision  and  slowest
         calculation time.

       Note:  (1)  All  spherical  distance  calculations  depend  on  the  current  ellipsoid (‐
       PROJ_ELLIPSOID),  the  definition  of  the  mean  radius   (PROJ_MEAN_RADIUS),   and   the
       specification  of  latitude  type  (PROJ_AUX_LATITUDE).  Geodesic distance calculations is
       also controlled by method (PROJ_GEODESIC).  (2) Coordinate transformations  that  can  use
       ellipsoidal or spherical forms will first consult -j if given.

   The -l option
       Syntax

       -l[label][+Dpen][+Ggap][+Hheader][+L[code/]text][+Ncols][+Ssize[/height]][+V[pen]][+ffont][+gfill][+jjustify][+ooff][+ppen][+sscale][+wwidth]
          Add a map legend entry to the session legend information file for the current plot.

       Description

       The -l option is used to automatically build the specfile  that  is  read  by  the  legend
       module  to  create  map or plot legends. This allows detailed and complicated legends that
       mix a variety of items, such as symbols, free text, colorbars, scales, images,  and  more.
       Yet,  a  simple  legend  will suffice for the vast majority of plots displaying symbols or
       lines. Optionally, append a text label to describe the entry. The following modifiers  are
       supported  to  allow  further  changes  to  the legend that is built by legend (upper-case
       modifiers reflect legend codes described  in  legend,  which  provides  more  details  and
       customization):

       • +D  - Draw a horizontal line in the given pen before the legend entry is placed [default
         is no line].

       • +G - Add the vertical space specified by gap [default is no extra space].

       • +H - Add the specified legend header [default is no header].

       • +L - Set a line text.  Optionally,  prepend  a  horizontal  justification  code  L(eft),
         C(enter), or R(ight) for text [default is C].

       • +N  -  Change  the  number  of  columns  used  to set the following legend items to cols
         [default is 1].

       • +S - Override the size of the current symbol for the legend or set a height if  plotting
         a line or contour [default uses the same symbol as plotted].

       • +V  -  Start and +vpen to stop drawing vertical line from previous to current horizontal
         line [default is no vertical line].

       • +f - Set the font used for the legend header [default is FONT_TITLE].

       • +g - Set the fill used for the legend frame [default is white].

       • +j - Set placement of the legend using  the  two-character  justification  code  justify
         [default is TR].

       • +o - Set the offset from legend frame to anchor point [default is 0.2c].

       • +p - Set the pen used for the legend frame [default is 1p].

       • +s - Resize all symbol and length sizes in the legend by scale [default is no scaling].

       • +w - Set legend frame width [default is auto].

       Notes:  (1)  Default  pen  is given by MAP_DEFAULT_PEN. (2) +H, +g, +j, +o, +p, +w, and +s
       will only take effect if appended to the very first -l option for a plot. The +N modifier,
       if  appended  to  the  first  -l  option,  affects  the  legend width (unless set via +w);
       otherwise it just subdivides the available width among the specified columns. If legend is
       not  called  explicitly we will call it implicitly when finishing the plot via end. (3) If
       auto-coloring is used for pens or fills and -l is set then label may  contain  a  C-format
       for  integers  (e.g., %3.3d) or just # and we will use the sequence number with the format
       to build the label entries.  Alternatively, give a list of comma-separated labels, or give
       no label if your segment headers contain label settings.(4) Due to this mechanism, if your
       single label actually contains commas, you must replace these with the octal  code  for  a
       comma (\054).

   The -n option
       Syntax

       -n[b|c|l|n][+a][+bg|p|n][+c][+tthreshold]
              Select grid interpolation mode.

       Description

       The  -n  option  controls  parameters  used  for  2-D grids resampling [default is bicubic
       interpolation with antialiasing and a threshold of 0.5, using geographic (if grid is known
       to  be  geographic) or natural boundary conditions]. Append one of the following to select
       the type of spline used:

       • b - Use B-spline smoothing.

       • c - Use bicubic interpolation.

       • l - Use bilinear interpolation.

       • n - Use nearest-neighbor value (for example to plot categorical data).

       The following modifiers are supported:

       • +a - Switch off antialiasing (where supported) [default uses antialiasing].

       • +b - Override boundary conditions used, by appending g for geographic, p  for  periodic,
         or  n  for  natural  boundary  conditions.  For  the latter two you may append x or y to
         specify just one direction, otherwise both are assumed.

       • +c - Clip the interpolated grid to input z-min/z-max [default may exceed limits].

       • +t - Control how close to nodes with NaNs the interpolation will go based on  threshold.
         A threshold of 1.0 requires all (4 or 16) nodes involved in interpolation to be non-NaN.
         For example, 0.5 will interpolate about half way from a non-NaN value and  0.1  will  go
         about 90% of the way [default is 0.5].

   The -o option
       Syntax

       -ocols[+l][+ddivisor][+sscale|d|k][+ooffset][,...][,t[word]]
              Select specific data columns for primary output, in arbitrary order.

       Description

       The  -o option allows you to specify which output file physical data columns to use and in
       what order. This is especially useful when table  output  is  generated  by  modules  that
       derive  its  output from gridded data sets. Specify individual columns or column ranges in
       the format start[:inc]:stop, where inc defaults to 1 if not specified, separated by commas
       [Default  writes  all  columns in order, starting with the first column (i.e., column 0)].
       Columns can be repeated. The chosen data columns will be used as  given  and  columns  not
       listed  will  be skipped.  To write from a given column until the end of the record, leave
       off stop when specifying the column  range.   Optionally,  append  one  of  the  following
       modifiers to any column or column range to transform the output columns:

       • +l - Take \log_{10} of the output values.

       • +d - Divide the output values by the factor divisor [default is 1].

       • +s  - Multiply the output values by the factor scale [default is 1]. Alternatively, give
         d to convert km to degrees or k to convert degrees to km using PROJ_MEAN_RADIUS.

       • +o - Add the given offset to the output values [default is 0].

       Notes: (1) The order of these optional transformations are (1) take \log_{10},  (2)  scale
       or divide, and (3) add offset. Do not repeat operations: -o+d9+o8+o2+s3+d4 will be treated
       as -o+o2+d4.  To write from a given column until the end of the  record,  leave  off  stop
       when  specifying  the  column  range.  Normally, any trailing text in the internal records
       will be included in the output, but when -o is used to specify specific columns  you  must
       explicitly  append  the  extra  "column" t to include the trailing text on output. To only
       select a single word from the trailing text, append the word number (first word is 0).  If
       your  trailing  text  columns start with a valid number and you want to ensure the content
       from column col to the end of the record will be considered  trailing  text,  use  -fcols.
       Finally, -on will simply write the numerical output only and skip any trailing text, while
       -ot will only output the trailing text (or selected word). (2) Using -o assumes there  are
       as many numerical columns as implied in -o.

   The -p option
       Syntax

       -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]
              Select perspective view and set the azimuth and elevation of the viewpoint.

       Description

       All  plotting  programs  that normally produce a flat, two-dimensional illustration can be
       told to view this flat illustration from  a  particular  vantage  point,  resulting  in  a
       perspective  view.  You  can  select  perspective  view  with the -p option by setting the
       azimuth (azim) of the viewpoint [Default is 180]. The following directives are supported:

       • x|y|z to plot against the "wall" x = level (using x) or y  =  level  (using  y)  or  the
         horizontal plain (using z) [default is z].

       • /elev to set the elevation of the viewport [Default is 90].

       • /zlevel  to  indicate  the  z-level  at  which  all 2D material, like the plot frame, is
         plotted (only valid when -p is used in consort with -Jz  or  -JZ)  [Default  is  at  the
         bottom of the z-axis].

       For  frames  used  for  animation,  we fix the center of your data domain. Specify another
       center using one of the following modifiers:

       • +w - Project lon0/lat0 (and z0 if applicable) to the center of the page size.

       • +v - Specify the coordinates of the projected 2-D view point as x0/y0.

       When -p is used without any further arguments, the values from the last use  of  -p  in  a
       previous  GMT  command will be used (in modern mode this also supplies the previous -Jz or
       -JZ if doing a 3-D region). Alternatively, you can perform a  simple  rotation  about  the
       z-axis  by just giving the rotation angle. Optionally, use +v or +w to select another axis
       location than the plot origin.

   The -q option
       Syntax

       -q[i|o][~]rows|limits[+ccol][+a|t|s]
              Select specific data rows to be read and/or written.

       Description

       The -q option is used to select specific data rows to be read (using -q or -qi) or written
       (using  -qo)  [Default  is  all rows]. Specify individual rows or row ranges in the format
       start[:inc]:stop, where inc defaults to 1 if not specified, separated by  commas  [Default
       reads  and  writes  all rows in order, starting with the first row (i.e., row 0)]. To read
       (or write) from a given row until the end of the data, leave off stop. To select  all  the
       rows not specified by the given ranges, prepend the selected rows with a leading ~. Append
       one of the following modifiers to control how the rows are counted [Default is +a]:

       • +a - Count all rows in the data set.

       • +t - Reset the count at the start of each table.

       • +s - Reset the count at the start of each segment.

       Alternatively, use +ccol to indicate that the arguments instead are  min/max  data  limits
       for  the  values  in column col. With +ccol, only rows whose data for the given column col
       are within the range(s) given by the min/max limits are read (with -qi) or  written  (with
       -qo).  Note: Because arguments may contain colons or be negative, you must specify min/max
       instead of start[:inc]:stop. If min or max is not given we  default  to  -infinity  and  +
       infinity,  respectively  (e.g.,  -qo50/+c2  will only write records whose z-values (in 3rd
       column) is ≥ 50 while -qo/50+c2 will only write records whose z-values is ≤ 50).

       Note: Header records do not increase the row counters; only data records do.

   The -r option (grid registration)
       Syntax

       -r[g|p]
              Select gridline or pixel node registration.

       Description

       All 2-D grids in GMT have their nodes organized in one of two ways, known as gridline  and
       pixel  registration.  The  GMT default is gridline registration (-rg); programs that allow
       for the creation of grids can use the -r option (or  -rp)  to  select  pixel  registration
       instead.

       Most  observed  data tend to be in gridline registration while processed data sometime may
       be distributed in pixel registration.  While you may convert between the two registrations
       this conversion looses the Nyquist frequency and dampens the other high frequencies. It is
       best to avoid any registration conversion if you  can  help  it.  Planning  ahead  may  be
       important.  (Node registrations are defined in Section Grid registration: The -r option of
       the GMT Technical Reference.)

   The -s option
       Syntax

       -s[cols][+a][+r]
              Suppress output of data records whose z-value(s) equal NaN.

       Description

       The -s option can be used to suppress output for records whose z-value equals NaN [default
       outputs  all records].  Optionally, supply a comma-separated list of all output columns or
       column ranges to consider for this NaN test [default only considers the third output  data
       column  (i.e.,  cols  =  2)].  Column ranges must be given in the format start[:inc]:stop,
       where inc defaults to 1 if not specified. The following modifiers are supported:

       • +r - Reverse the suppression, i.e., only output the records whose z-value equals NaN.

       • +a - Suppress the output of the record if just one or more  of  the  columns  equal  NaN
         [default skips record only if values in all specified cols equal NaN]

   The -t option
       Syntax

       -ttransp[/transp2][+f|s]
              Set transparency level(s) for an overlay.

       Description

       The  -t  option  allows  you  to  change the transparency level for the current overlay by
       appending the transp percentage  in  the  0-100  range  [default  is  0  (i.e.,  opaque)].
       Normally,  transp  applies  to both fill and stroke, but you can limit the transparency to
       one of them by appending +f or +s for fill or stroke, respectively. Alternatively,  append
       /transp2 to set separate transparencies for fills and strokes.

       Transparency  may  also  be controlled on a feature by feature basis when setting color or
       fill (see the cookbook section Specifying area fill attributes). Notes:  (1)  The  modules
       plot,  plot3d,  and  text can all change transparency on a record-by-record basis if -t is
       given without argument and the input file supplies variable  transparencies  as  the  last
       numerical  column value(s). (2) The transparency is only visible when PDF or raster format
       output is selected because the PostScript language does not support transparency. Only the
       PNG format selection adds a transparency layer in the image (for further processing).

   The -w option
       Syntax

       -wy|a|w|d|h|m|s|cperiod[/phase][+ccol]
              Convert input records to a cyclical coordinate.

       Description

       The  -w  option  converts  the input x-coordinate to a cyclical coordinate, or a different
       input column if selected via the +c modifier. Temporal data (i.e.,  regular  time  series)
       can  be analyzed for periods via standard spectral analysis, such as offered by spectrum1d
       and grdfft.  However, it is often of interest to examine aspects of such periodicities  in
       the  time domain.  To enable such analyses we need to convert our monotonically increasing
       time coordinates to periodic or cyclic coordinates so that data from many  cycles  can  be
       stacked,  binned,  displayed  in  histograms,  etc.  The  conversion from input x, y, or z
       coordinates to wrapped, periodic coordinates follows the simple equation

                                  t' = (t - \tau) \;\mathrm{mod}\; T,

       where t is the input coordinate, \tau is a phase-shift [Default is zero],  and  T  is  the
       desired  period  for the modulus operator, yielding cyclic coordinates t'. GMT offers many
       standard time cycles in prescribed units plus a custom cycle for other types of  Cartesian
       coordinates.  The  table  below  shows  the  values  for  units, phase and period that are
       prescribed and  only  requires  the  user  to  specify  the  corresponding  wrapping  code
       (y|a|w|d|h|m|s|cperiod[/phase]):

                          ┌─────┬──────────────────┬──────────┬───────┬───────┐
                          │CodePurpose (unit)   │ PeriodPhaseRange │
                          ├─────┼──────────────────┼──────────┼───────┼───────┤
                          │y    │ Yearly     cycle │ 1 year   │ 0     │ 0–1   │
                          │     │ (normalized)     │          │       │       │
                          ├─────┼──────────────────┼──────────┼───────┼───────┤
                          │a    │ Annual     cycle │ 1 year   │ 0     │ 0–12  │
                          │     │ (month)          │          │       │       │
                          ├─────┼──────────────────┼──────────┼───────┼───────┤
                          │w    │ Weekly     cycle │ 1 week   │ 0     │ 0–7   │
                          │     │ (day)            │          │       │       │
                          ├─────┼──────────────────┼──────────┼───────┼───────┤
                          │d    │ Daily      cycle │ 1 day    │ 0     │ 0–24  │
                          │     │ (hour)           │          │       │       │
                          ├─────┼──────────────────┼──────────┼───────┼───────┤
                          │h    │ Hourly     cycle │ 1 hour   │ 0     │ 0–60  │
                          │     │ (minute)         │          │       │       │
                          ├─────┼──────────────────┼──────────┼───────┼───────┤
                          │m    │ Minute     cycle │ 1 minute │ 0     │ 0–60  │
                          │     │ (second)         │          │       │       │
                          ├─────┼──────────────────┼──────────┼───────┼───────┤
                          │s    │ Second     cycle │ 1 second │ 0     │ 0–1   │
                          │     │ (second)         │          │       │       │
                          ├─────┼──────────────────┼──────────┼───────┼───────┤
                          │c    │ Custom     cycle │ T        │ \tau  │ 0–1   │
                          │     │ (normalized)     │          │       │       │
                          └─────┴──────────────────┴──────────┴───────┴───────┘

       Optionally,  append  +ccol  to select the input column with the coordinates to be wrapped,
       [default col is 0, i.e., the first column]. If the custom cycle c is chosen then you  must
       also  supply  the period and optionally any phase [default is 0] in the same units of your
       data (i.e., no units should be appended to -w).

       Notes: (1) Coordinates for w in the range 0-1 correspond to the  first  day  of  the  week
       [Monday] but can be changed via TIME_WEEK_START. (2) If a temporal cycle is indicated then
       we implicitly set -f to indicate absolute time (unless already set  separately).  See  the
       cookbook section Examining data cycles: The -w option for examples.

   The -x option
       Syntax

       -x[[-]n]
              Specify  the number of active cores to be used in any OpenMP-enabled multi-threaded
              algorithms.

       Description

       The -x option limits the number of cores to  be  used  in  any  multi-threaded  algorithms
       [default  is  to  use  all available cores]. Append n to only use n cores (if too large it
       will be truncated to the maximum cores available).  Finally, give a negative n  to  select
       (all  -  n)  cores (or at least 1 if n equals or exceeds all). Note: The -x option is only
       available to GMT modules compiled with OpenMP or Glib threads support, with the  exception
       of movie and batch which handle their own parallel execution separately.

   The -: option
       Syntax

       -:[i|o]
              Swap 1st and 2nd column on input and/or output.

       Description  The -: option swaps the 1st and 2nd column on input and output [default is no
       swapping]. Append i to select input only or o  to  select  output  only  [default  affects
       both]. This option is typically used to handle (latitude, longitude) files; see also Input
       columns selection: The  -i  option.  Note  that  command  line  arguments  that  may  take
       geographic   coordinates  (e.g.,  -R)  always  expect  longitude  before  latitude.  Also,
       geographical grids are expected to have the longitude as first (minor) dimension.

   Module help and configuration
       -^ or just -
              Print a short message about the syntax of the command, then exit (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 exit.

       -? or no arguments
              Print a complete usage (help) message, including the explanation  of  all  options,
              then exit.

       --PAR=value
              Temporarily   override   a  GMT  default  setting;  repeatable.  See  gmt.conf  for
              parameters.

   Specifying Color
       color  The color of lines, areas and patterns can be specified by a valid color name, by a
              gray shade (in the range 0-255), by a decimal color triplet RGB (r/g/b, each in the
              range 0–255), by hue-saturation-value HSV (h-s-v, with ranges of 0-360, 0-1,  0-1),
              by  cyan/magenta/yellow/black  CMYK  (c/m/y/k,  each  in  the  range  0-1), or by a
              hexadecimal color code (#rrggbb, as used  in  HTML).  For  a  transparency  effect,
              append  @transparency  in  the  0–100  percent  range [Default is 0 (opaque)] Note:
              Transparency effects are only visible when PDF  or  a  raster  graphics  format  is
              selected.   See  Explanation  of color codes in GMT for more information and a full
              list of color names.

   Specifying Fill
       fill   The attribute fill specifies the solid shade or solid color (see  Specifying  Color
              above)  or  the  pattern  used  for  filling  polygons.   Patterns are specified as
              ppattern, where pattern set the number of the built-in pattern (1-90) or  the  name
              of  a raster image file. The optional +rdpi sets the resolution of the image [300].
              For 1-bit rasters: use upper case P  for inverse video, or  append  +fcolor  and/or
              +bcolor to specify fore- and background colors (no color given means transparency).
              See Predefined Bit and Hachure  Patterns  in  GMT  for  information  on  individual
              built-in patterns.

   Specifying Fonts
       font   The  attributes of text fonts as defined by font is a comma delimited list of size,
              fonttype and fill, each of which is optional. size is the  font  size  (usually  in
              points) but c or i can be added to indicate other units. fonttype is the name (case
              sensitive!) of the font or its equivalent numerical ID (e.g., Helvetica-Bold or 1).
              fill  specifies  the  gray shade, color or pattern of the text (see Specifying Fill
              above). Optionally, you may append =pen to the fill value in order to draw  a  text
              outline.  If you want to avoid that the outline partially obscures the text, append
              =~pen instead; in that case only half the linewidth is plotted on  the  outside  of
              the  font  only.  If an outline is requested, you may optionally skip the text fill
              by setting it to -, in which case the full pen width is always used. If any of  the
              font attributes is omitted their default or previous setting will be retained.

              The 35 available fonts (plus 4 optional Japanese fonts) are:

              0.   Helvetica

              1.   Helvetica-Bold

              2.   Helvetica-Oblique

              3.   Helvetica-BoldOblique

              4.   Times-Roman

              5.   Times-Bold

              6.   Times-Italic

              7.   Times-BoldItalic

              8.   Courier

              9.   Courier-Bold

              10.  Courier-Oblique

              11.  Courier-BoldOblique

              12.  Symbol

              13.  AvantGarde-Book

              14.  AvantGarde-BookOblique

              15.  AvantGarde-Demi

              16.  AvantGarde-DemiOblique

              17.  Bookman-Demi

              18.  Bookman-DemiItalic

              19.  Bookman-Light

              20.  Bookman-LightItalic

              21.  Helvetica-Narrow

              22.  Helvetica-Narrow-Bold

              23.  Helvetica-Narrow-Oblique

              24.  Helvetica-Narrow-BoldOblique

              25.  NewCenturySchlbk-Roman

              26.  NewCenturySchlbk-Italic

              27.  NewCenturySchlbk-Bold

              28.  NewCenturySchlbk-BoldItalic

              29.  Palatino-Roman

              30.  Palatino-Italic

              31.  Palatino-Bold

              32.  Palatino-BoldItalic

              33.  ZapfChancery-MediumItalic

              34.  ZapfDingbats

              35.  Ryumin-Light-EUC-H

              36.  Ryumin-Light-EUC-V

              37.  GothicBBB-Medium-EUC-H

              38.  GothicBBB-Medium-EUC-V

   Specifying Pens
       pen    The  attributes of lines and symbol outlines as defined by pen is a comma-delimited
              list of width, color and style, each of which is optional. width can  be  indicated
              as a measure (in points (this is the default), centimeters, or inches) or as faint,
              default, thin[ner|nest], thick[er|est], fat[ter|test], or wide. color  specifies  a
              gray  shade  or  color  (see  Specifying Color above). style can be any of 'solid',
              'dashed' 'dotted', 'dashdot', or 'dotdash', or a custom combination of  dashes  '-'
              and dots '.'. If any of the attributes is omitted their default or previous setting
              will be retained. See GMT Technical Reference Specifying pen  attributes  for  more
              information.

ASCII FORMAT PRECISION

       The  ASCII  output formats of numerical data are controlled by parameters in your gmt.conf
       file. Longitude and latitude are formatted according to FORMAT_GEO_OUT, absolute  time  is
       under  the control of FORMAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point
       values are formatted according to FORMAT_FLOAT_OUT. Be aware that the format in effect can
       lead  to loss of precision in ASCII output, which can lead to various problems downstream.
       If you find the output is not written with enough precision, consider switching to  binary
       output (-bo if available) or specify more decimals using the FORMAT_FLOAT_OUT setting.

GRID FILE FORMATS

       By  default  GMT  writes out grids as single precision floats in a COARDS-complaint netCDF
       file format. However, GMT is able to produce and read grid files in  many  other  commonly
       used  grid  file  formats  and  also facilitates so called "packing" of grids, writing out
       floating point data as 1- or 2-byte integers. To specify the precision, scale and  offset,
       the user should add the suffix [=ID][+ddivisor][+ninvalid][+ooffset][+sscale], where ID is
       a two-letter identifier of the grid type and precision, and the scale (or divisor), offset
       and  invalid  are  the  arguments  of optional modifiers to be applied to all grid values,
       Here, invalid is the value used to indicate missing data. In case the ID is not  provided,
       as  in  +sscale,  then  a  ID=nf  is  assumed. When reading grids, the format is generally
       automatically recognized from almost all of those  formats  that  GMT  and  GDAL  combined
       offer. If not, the same suffix can be added to input grid file names.  If reading an image
       as a grid you can select the band via +b.  See grdconvert and  Section  Grid  file  format
       specifications  of  the  GMT  Technical  Reference  for  more  information  regarding GDAL
       settings.

       When reading a netCDF file that contains multiple grids, GMT will read,  by  default,  the
       first  2-dimensional  grid that it can find in that file. To coax GMT into reading another
       multi-dimensional variable in the grid file, append  ?varname  to  the  file  name,  where
       varname  is the name of the variable. Note that you may need to escape the special meaning
       of ? in your shell program by putting a backslash in  front  of  it,  or  by  placing  the
       filename  and suffix between quotes or double quotes. The ?varname suffix can also be used
       for output grids to  specify  a  variable  name  different  from  the  default:  "z".  See
       grdconvert  and  Sections Modifiers for COARDS-compliant netCDF files and Grid file format
       specifications of the GMT Technical Reference for more information, particularly on how to
       read slices of 3-, 4-, or 5-dimensional grids.

       When  writing  a netCDF file, the grid is stored by default with the variable name "z". To
       specify another variable name varname, append ?varname to the file name. Note that you may
       need  to  escape  the special meaning of ? in your shell program by putting a backslash in
       front of it, or by placing the filename and suffix between quotes or double quotes.

CLASSIC MODE OPTIONS

       These options are only used in classic mode and are listed here just for reference.

       -K     More PostScript code will be appended later [Default terminates the  plot  system].
              Required for all but the last plot command when building multi-layer plots.

       -O     Selects  Overlay  plot  mode [Default initializes a new plot system].  Required for
              all but the first plot command when building multi-layer plots.

       -P     Select "Portrait" plot orientation [Default is "Landscape"; see gmt.conf or  gmtset
              to      change      the      PS_PAGE_ORIENTATION      parameter,      or     supply
              --PS_PAGE_ORIENTATION=orientation on the command line].

MORE INFORMATION SOURCES

       Look up the individual man pages for more details and full syntax. Run gmt --help to  list
       all  GMT  programs  and  to  show  all installation directories. For an explanation of the
       various GMT settings in this man page (like FORMAT_FLOAT_OUT), see the man page of the GMT
       configuration  file  gmt.conf. Information is also available on the GMT documentation site
       https://docs.generic-mapping-tools.org/

DEPRECATIONS

       • 6.3.0: Update -g syntax. #5617

       • 6.3.0: Update -JG syntax to use modifiers. #5780

SEE ALSO

       docs

COPYRIGHT

       2024, The GMT Team