Compatibility

Incompatibilities between GMT 5 and GMT 4

As features are added and bugs are discovered, it is occasionally necessary to break the established syntax of a GMT program option, such as when the intent of the option is non-unique due to a modifier key being the same as a distance unit indicator. Other times we see a greatly improved commonality across similar options by making minor adjustments. However, we are aware that such changes may cause grief and trouble with established scripts and the habits of many GMT users. To alleviate this situation we have introduced a configuration that allows GMT to tolerate and process obsolete program syntax (to the extent possible). To activate you must make sure GMT_COMPATIBILITY is set to 4 in your gmt.conf file. When not running in compatibility mode any obsolete syntax will be considered as errors. We recommend that users with prior GMT 4 experience run GMT 5 in compatibility mode, heed the warnings about obsolete syntax, and correct their scripts or habits accordingly. When this transition has been successfully navigated it is better to turn compatibility mode off and leave the past behind. Occasionally, users will supply an ancient GMT 3 syntax which may have worked in GMT 4 but is not honored in GMT 5.

Here are a list of known incompatibilities that are correctly processed with a warning under compatibility mode:

  • GMT default names: We have organized the default parameters logically by group and renamed several to be easier to remember and to group. Old and new names can be found in Table obsolete. In addition, a few defaults are no longer recognized, such as N_COPIES, PS_COPIES, DOTS_PR_INCH, GMT_CPTDIR, PS_DPI, and PS_EPS, TRANSPARENCY. This also means the old common option -c for specifying PostScript copies is no longer available.
  • Units: The unit abbreviation for arc seconds is finally s instead of c, with the same change for upper case in some clock format statements.
  • Contour labels: The modifiers +kfontcolor and +sfontsize are obsolete, now being part of +ffont.
  • Ellipsoids: Assigning PROJ_ELLIPSOID a file name is deprecated, use comma-separated parameters a, f^{-1} instead.
  • Custom symbol macros: Circle macro symbol C is deprecated; use c instead.
  • Map scale: Used by psbasemap and others. Here, the unit m is deprecated; use M for statute miles.
  • 3-D perspective: Some programs used a combination of -E, -Z to set up a 3-D perspective view, but these options were not universal. The new 3-D perspective in GMT 5 means you instead use the common option -p to configure the 3-D projection.
  • Pixel vs. gridline registration: Some programs used to have a local -F to turn on pixel registration; now this is a common option -r.
  • Table file headers: For consistency with other common i/o options we now use -h instead of -H.
  • Segment headers: These are now automatically detected and hence there is no longer a -m (or the older -M option).
  • Front symbol: The syntax for the front symbol has changed from -Sfspacing/size[+d][+t][:offset] to -Sfspacing[/size][+r+l][+f+t+s+c+b][+ooffset].
  • Vector symbol: With the introduction of geo-vectors there are three kinds of vectors that can be drawn: Cartesian (straight) vectors with -Sv or -SV, geo-vectors (great circles) with -S=, and circular vectors with -Sm. These are all composed of a line (controlled by pen settings) and 0–2 arrow heads (control by fill and outline settings). Many modifiers common to all arrows have been introduced using the +key[arg] format. The size of a vector refers to the length of its head; all other quantities are given via modifiers (which have sensible default values). In particular, giving size as vectorwidth/headlength/headwidth is deprecated. See the psxy man page for a clear description of all modifiers.
  • blockmean: The -S and -Sz options are deprecated; use -Ss instead.
  • filter1d: The -Nncol/tcol option is deprecated; use -Ntcol instead as we automatically determine the number of columns in the file.
  • gmt2kml: The -L option no longer expects column numbers, just the column names. This allows the extra columns to contain text strings but means users have to supply the data columns in the order specified by -L.
  • gmtconvert: -F is deprecated; use common option -o instead.
  • gmtdefaults: -L is deprecated; this is now the default behavior.
  • gmtmath: -F is deprecated; use common option -o instead.
  • gmtselect: -Cf is deprecated; use common specification format -C- instead. Also, -N...o is deprecated; use -E instead.
  • grd2xyz: -E is deprecated as the ESRI ASCII exchange format is now detected automatically.
  • grdcontour: -m is deprecated as segment headers are handled automatically.
  • grdfft: -M is deprecated; use common option -fg instead.
  • grdgradient: -L is deprecated; use common option -n instead. Also, -M is deprecated; use common option -fg instead.
  • grdlandmask: -N...o is deprecated; use -E instead.
  • grdimage: -S is deprecated; use -nmode[+a][+tthreshold] instead.
  • grdmath: LDIST and PDIST now return distances in spherical degrees; while in GMT 4 it returned km; use DEG2KM for conversion, if needed.
  • grdproject: -S is deprecated; use -nmode[+a][+tthreshold] instead. Also, -N is deprecated; use -D instead.
  • grdsample: -Q is deprecated; use -nmode[+a][+tthreshold] instead. Also, -L is deprecated; use common option -n instead, and -Nnx/ny is deprecated; use -Inx+/ny+ instead.
  • grdtrack: -Q is deprecated; use -nmode[+a][+tthreshold] instead. Also, -L is deprecated; use common option -n instead, and -S is deprecated; use common option -sa instead.
  • grdvector: -E is deprecated; use the vector modifier +jc as well as the general vector specifications discussed earlier.
  • grdview: -L is deprecated; use common option -n instead.
  • nearneighbor: -L is deprecated; use common option -n instead.
  • project: -D is deprecated; use --FORMAT_GEO_OUT instead.
  • psbasemap: -G is deprecated; specify canvas color via -B modifier +gcolor.
  • pscoast: -m is deprecated and have reverted to -M for selecting data output instead of plotting.
  • pscontour: -Tindexfile is deprecated; use -Qindexfile.
  • pshistogram: -Tcol is deprecated; use common option -i instead.
  • pslegend: Paragraph text header flag > is deprecated; use P instead.
  • psmask: -D...+nmin is deprecated; use -Q instead.
  • psrose: Old vector specifications in Option -M are deprecated; see new explanations.
  • pstext: -m is deprecated; use -M to indicate paragraph mode. Also, -S is deprecated as fonts attributes are now specified via the font itself.
  • pswiggle: -D is deprecated; use common option -g to indicate data gaps. Also, -N is deprecated as all fills are set via the -G option.
  • psxy: Old vector specifications in Option -S are deprecated; see new explanations.
  • psxyz: Old vector specifications in Option -S are deprecated; see new explanations.
  • splitxyz: -G is deprecated; use common option -g to indicate data gaps. Also, -M is deprecated; use common option -fg instead.
  • triangulate: -m is deprecated; use -M to output triangle vertices.
  • xyz2grd: -E is deprecated as the ESRI ASCII exchange format is one of our recognized formats. Also, -A (no arguments) is deprecated; use -Az instead.
  • grdraster: Now in the main GMT core. The Hskip field in grdraster.info is no longer expected as we automatically determine if a raster has a GMT header. Also, to output x,y,z triplets instead of writing a grid now requires -T.
  • img2grd: -minc is deprecated; use -Iinc instead.
  • psvelo: Old vector specifications are deprecated; see new explanations.
  • mgd77convert: -4 is deprecated; use -D instead.
  • mgd77list: The unit m is deprecated; use M for statute miles.
  • mgd77manage: The unit m is deprecated; use M for statute miles. The -Q is deprecated; use -nmode[+a][+tthreshold] instead
  • mgd77path: -P is deprecated (clashes with GMT common options); use -A instead.
  • backtracker: -C is deprecated as stage vs. finite rotations are detected automatically.
  • grdrotater: -C is deprecated as stage vs. finite rotations are detected automatically. Also, -Tlon/lat/angle is now set via -elon/lat/angle.
  • grdspotter: -C is deprecated as stage vs. finite rotations are detected automatically.
  • hotspotter: -C is deprecated as stage vs. finite rotations are detected automatically.
  • originator: -C is deprecated as stage vs. finite rotations are detected automatically.
  • rotconverter: -Ff selection is deprecated, use -Ft instead.
  • x2sys_datalist: The unit m is deprecated; use M for statute miles.
Old Name New Name
ANNOT_FONT_PRIMARY FONT_ANNOT_PRIMARY
ANNOT_FONT_SECONDARY FONT_ANNOT_SECONDARY
ANNOT_FONT_SIZE_PRIMARY FONT_ANNOT_PRIMARY
ANNOT_FONT_SIZE_SECONDARY FONT_ANNOT_SECONDARY
ANNOT_MIN_ANGLE MAP_ANNOT_MIN_SPACING
ANNOT_OFFSET_PRIMARY MAP_ANNOT_OFFSET_PRIMARY
ANNOT_OFFSET_SECONDARY MAP_ANNOT_OFFSET_SECONDARY
BASEMAP_AXES MAP_FRAME_AXES
BASEMAP_FRAME_RGB MAP_DEFAULT_PEN
BASEMAP_TYPE MAP_FRAME_TYPE
CHAR_ENCODING PS_CHAR_ENCODING
D_FORMAT FORMAT_FLOAT_OUT
DEGREE_SYMBOL MAP_DEGREE_SYMBOL
ELLIPSOID PROJ_ELLIPSOID
FIELD_DELIMITER IO_COL_SEPARATOR
FRAME_PEN MAP_FRAME_PEN
FRAME_WIDTH MAP_FRAME_WIDTH
GLOBAL_X_SCALE PS_SCALE_X
GLOBAL_Y_SCALE PS_SCALE_Y
GRID_CROSS_SIZE_PRIMARY MAP_GRID_CROSS_SIZE_PRIMARY
GRID_CROSS_SIZE_SECONDARY MAP_GRID_CROSS_SIZE_SECONDARY
GRID_PEN_PRIMARY MAP_GRID_PEN_PRIMARY
GRID_PEN_SECONDARY MAP_GRID_PEN_SECONDARY
GRIDFILE_FORMAT IO_GRIDFILE_FORMAT
GRIDFILE_SHORTHAND IO_GRIDFILE_SHORTHAND
HEADER_FONT_SIZE FONT_TITLE
HEADER_FONT FONT_TITLE
HEADER_OFFSET MAP_TITLE_OFFSET
HISTORY GMT_HISTORY
HSV_MAX_SATURATION COLOR_HSV_MAX_S
HSV_MAX_VALUE COLOR_HSV_MAX_V
HSV_MIN_SATURATION COLOR_HSV_MIN_S
HSV_MIN_VALUE COLOR_HSV_MIN_V
INPUT_CLOCK_FORMAT FORMAT_CLOCK_IN
INPUT_DATE_FORMAT FORMAT_DATE_IN
INTERPOLANT GMT_INTERPOLANT
LABEL_FONT FONT_LABEL
LABEL_OFFSET MAP_LABEL_OFFSET
LINE_STEP MAP_LINE_STEP
MAP_SCALE_FACTOR PROJ_SCALE_FACTOR
MEASURE_UNIT PROJ_LENGTH_UNIT
NAN_RECORDS IO_NAN_RECORDS
OBLIQUE_ANNOTATION MAP_ANNOT_OBLIQUE
OUTPUT_CLOCK_FORMAT FORMAT_CLOCK_OUT
OUTPUT_DATE_FORMAT FORMAT_DATE_OUT
OUTPUT_DEGREE_FORMAT FORMAT_GEO_OUT
PAGE_COLOR PS_PAGE_COLOR
PAGE_ORIENTATION PS_PAGE_ORIENTATION
PAPER_MEDIA PS_MEDIA
PLOT_CLOCK_FORMAT FORMAT_CLOCK_MAP
PLOT_DATE_FORMAT FORMAT_DATE_MAP
PLOT_DEGREE_FORMAT FORMAT_GEO_MAP
POLAR_CAP MAP_POLAR_CAP
PS_COLOR COLOR_HSV_MAX_V
TICK_LENGTH MAP_TICK_LENGTH_PRIMARY|SECONDARY
TICK_PEN MAP_TICK_PEN_PRIMARY|SECONDARY
TIME_FORMAT_PRIMARY FORMAT_TIME_PRIMARY_MAP
TIME_FORMAT_SECONDARY FORMAT_TIME_SECONDARY_MAP
UNIX_TIME_FORMAT FORMAT_TIME_STAMP
UNIX_TIME_POS MAP_LOGO_POS
UNIX_TIME MAP_LOGO
VECTOR_SHAPE MAP_VECTOR_SHAPE
VERBOSE GMT_VERBOSE
WANT_LEAP_SECONDS TIME_LEAP_SECONDS
X_ORIGIN MAP_ORIGIN_X
XY_TOGGLE IO_LONLAT_TOGGLE
Y_AXIS_TYPE MAP_ANNOT_ORTHO
Y_ORIGIN MAP_ORIGIN_Y
Y2K_OFFSET_YEAR TIME_Y2K_OFFSET_YEAR

Note: While TIME_LEAP_SECONDS is a recognized keyword it is currently not implemented and has no effect. We reserve the right to enable this feature in the future.