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 basemap 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 plot 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.
- convert: -F is deprecated; use common option -o instead.
- defaults: -L is deprecated; this is now the default behavior.
- math: -F is deprecated; use common option -o instead.
- select: -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+n/ny+n 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.
- basemap: -G is deprecated; specify canvas color via -B modifier +gcolor.
- coast: -m is deprecated and have reverted to -M for selecting data output instead of plotting.
- contour: -Tindexfile is deprecated; use -Qindexfile.
- histogram: -Tcol is deprecated; use common option -i instead.
- legend: Paragraph text header flag > is deprecated; use P instead.
- mask: -D…+nmin is deprecated; use -Q instead.
- rose: Old vector specifications in Option -M are deprecated; see new explanations.
- text: -m is deprecated; use -M to indicate paragraph mode. Also, -S is deprecated as fonts attributes are now specified via the font itself.
- wiggle: -D is deprecated; use common option -g to indicate data gaps. Also, -N is deprecated as all fills are set via the -G option.
- plot: Old vector specifications in Option -S are deprecated; see new explanations.
- plot3d: 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.
- velo: 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.
- originater: -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.