1.. _changelog: 2 3========= 4Changelog 5========= 6 7New Features in GMT 6.3 8======================= 9 10GMT 6.3 includes a new module, many new features, general code and documentation improvements, and numerous 11bug fixes! Here are the general updates included in 6.3: 12 13* Add new -B axis modifier +e to skip annotation(s) at end of an axis (`#5873 <https://github.com/GenericMappingTools/gmt/pull/5873>`_) 14* Allow for a fixed label offset (`#5320 <https://github.com/GenericMappingTools/gmt/pull/5320>`_) 15* Implement auto resolution for remote grids for plotting modules (`#5753 <https://github.com/GenericMappingTools/gmt/pull/5753>`_) 16* Simplify conversions between km and degrees (`#5824 <https://github.com/GenericMappingTools/gmt/pull/5824>`_) 17 18New Modules in GMT 6.3 19---------------------- 20 21* :doc:`grdselect`: Make selections or determine common regions from 2-D grids, images or 3-D cubes (`#5929 <https://github.com/GenericMappingTools/gmt/pull/5929>`_) 22 23New Core Module Features in GMT 6.3 24----------------------------------- 25 26* :doc:`begin`, :doc:`figure`, and :doc:`psconvert`: JPEG quality and recognition of modifiers (`#5574 <https://github.com/GenericMappingTools/gmt/pull/5574>`_) 27* :doc:`coast`: Enable country-based clipping in -E (`#5334 <https://github.com/GenericMappingTools/gmt/pull/5334>`_) 28* :doc:`coast`: Allow -Ecode+L to list for specific country (`#5744 <https://github.com/GenericMappingTools/gmt/pull/5744>`_) 29* :doc:`colorbar`: Add modifier +r to reverse direction of scalebar (`#5230 <https://github.com/GenericMappingTools/gmt/pull/5230>`_) 30* :doc:`colorbar`: Allow colorbar length and/or width to be given in percentages (`#5775 <https://github.com/GenericMappingTools/gmt/pull/5775>`_) 31* :doc:`colorbar`: Handle CPTs with transparency (`#5328 <https://github.com/GenericMappingTools/gmt/pull/5328>`_) 32* :doc:`events`: Support temporal color changes (`#5695 <https://github.com/GenericMappingTools/gmt/pull/5695>`_) 33* :doc:`gmtmath`: Improve -Q behavior (`#5362 <https://github.com/GenericMappingTools/gmt/pull/5362>`_) 34* :doc:`grd2cpt` and :doc:`makecpt`: Add suitable shorthands for creating month and day labels (`#5201 <https://github.com/GenericMappingTools/gmt/pull/5201>`_) 35* :doc:`grd2cpt`: Let -L have ability to only set one limit (`#5317 <https://github.com/GenericMappingTools/gmt/pull/5317>`_) 36* :doc:`grd2xyz`: Add option -L to limit output to a single vector (`#5705 <https://github.com/GenericMappingTools/gmt/pull/5705>`_) 37* :doc:`grd2xyz`: Let option -T write STL output file (`#5955 <https://github.com/GenericMappingTools/gmt/pull/5955>`_) 38* :doc:`grdclip`: Handle polar resampling via -Ar|t (`#5264 <https://github.com/GenericMappingTools/gmt/pull/5264>`_) 39* :doc:`grdgradient`: Add +f modifier to -Q to specify file (`#5866 <https://github.com/GenericMappingTools/gmt/pull/5866>`_) 40* :doc:`grdimage`: Resample 2nd grid used for intensities (`#5363 <https://github.com/GenericMappingTools/gmt/pull/5363>`_) 41* :doc:`grdinfo`: Add ability to specify the two tails separately in -T+a (`#5924 <https://github.com/GenericMappingTools/gmt/pull/5924>`_) 42* :doc:`grdmath`: Add CUMSUM operator (`#5239 <https://github.com/GenericMappingTools/gmt/pull/5239>`_) 43* :doc:`grdtrack`: Let -C also accept a fixed azimuth for all profiles (`#5849 <https://github.com/GenericMappingTools/gmt/pull/5849>`_) 44* :doc:`grdtrend`: Fit model along xx or yy only. (`#5496 <https://github.com/GenericMappingTools/gmt/pull/5496>`_) 45* :doc:`inset`: Let begin optionally take -R -J to determine inset size instead of via -D (`#5903 <https://github.com/GenericMappingTools/gmt/pull/5903>`_) 46* :doc:`plot`:Add inverted triangle to front symbol choices (`#5983 <https://github.com/GenericMappingTools/gmt/pull/5983>`_) 47* :doc:`plot`: For error bars, allow asymmetrical bounds as well (`#5844 <https://github.com/GenericMappingTools/gmt/pull/5844>`_) 48* :doc:`plot`, :doc:`plot3d`, and :doc:`clip`: Add polar resampling via -Ar|t (`#5263 <https://github.com/GenericMappingTools/gmt/pull/5263>`_) 49* :doc:`project`: Let -G accept increment unit and +n modifier (`#5984 <https://github.com/GenericMappingTools/gmt/pull/5984>`_) 50* :doc:`mapproject`: Report rectangular region that covers an obliquely defined region (`#5782 <https://github.com/GenericMappingTools/gmt/pull/5782>`_) 51* :doc:`movie`: Let master frame accept a different dpu than the movie frames (`#5198 <https://github.com/GenericMappingTools/gmt/pull/5198>`_) 52* :doc:`subplot`: Allow drop-down shade modifier in tag option (`#5333 <https://github.com/GenericMappingTools/gmt/pull/5333>`_) 53* :doc:`text`: Implement smart justify -Dj for -M (`#5995 <https://github.com/GenericMappingTools/gmt/pull/5995>`_) 54 55Supplement updates in GMT 6.3 56----------------------------- 57 58* :doc:`/supplements/seis/coupe` and :doc:`/supplements/seis/meca`: Add linear moment scaling (`#5649 <https://github.com/GenericMappingTools/gmt/pull/5649>`_) 59* :doc:`/supplements/potential/grdflexure`: Let input list of grids and load times optionally also have load density (`#5249 <https://github.com/GenericMappingTools/gmt/pull/5249>`_) 60* :doc:`greenspline` and :doc:`/supplements/geodesy/gpsgridder`: Improve histories, update and add animations (`#5734 <https://github.com/GenericMappingTools/gmt/pull/5734>`_) 61 62Enhancements in GMT 6.3 63----------------------- 64 65* Add v (vector) to custom symbol kit, plus handle azimuth vs angle (`#5606 <https://github.com/GenericMappingTools/gmt/pull/5606>`_) 66* Allow trailing comments in custom symbol files (`#5610 <https://github.com/GenericMappingTools/gmt/pull/5610>`_) 67* Let -d set starting column via modifier (`#5966 <https://github.com/GenericMappingTools/gmt/pull/5966>`_) 68* Let -f\ *col* explicity set start of input trailing text (`#5370 <https://github.com/GenericMappingTools/gmt/pull/5370>`_) 69* Let multi-layer geotiff files be cut via gdal_translate (`#5819 <https://github.com/GenericMappingTools/gmt/pull/5819>`_) 70 71Documentation updates in GMT 6.3 72-------------------------------- 73 74* Add a GMT team page and update contributor recognition model (`#5589 <https://github.com/GenericMappingTools/gmt/pull/5589>`_) 75* Add deprecations section to ReST documentation (`#5847 <https://github.com/GenericMappingTools/gmt/pull/5847>`_) 76* Migrate remote dataset documentation to external site (`#6021 <https://github.com/GenericMappingTools/gmt/pull/6021>`_) 77* New gallery example 53 showing subplots and shading (`#5336 <https://github.com/GenericMappingTools/gmt/pull/5336>`_) 78* Improved animations in the gallery 79* Update formatting of usage messages across all modules 80 81Deprecations in GMT 6.3 82----------------------- 83 84* Clean up aspects of SVD function usage in GMT (`#5725 <https://github.com/GenericMappingTools/gmt/pull/5725>`_) 85* Complete -D parsing update (`#5827 <https://github.com/GenericMappingTools/gmt/pull/5827>`_) 86* Consolidate -A into -F for a more unified option (`#5613 <https://github.com/GenericMappingTools/gmt/pull/5613>`_) 87* Deprecate the ugly perspective -JG syntax and introduce a modern form (`#5780 <https://github.com/GenericMappingTools/gmt/pull/5780>`_) 88* :doc:`greenspline`: Update -C for writing intermediate grids (`#5714 <https://github.com/GenericMappingTools/gmt/pull/5714>`_) 89* Let gmt end better handle -A args (`#5583 <https://github.com/GenericMappingTools/gmt/pull/5583>`_) 90* Update -g synopsis, syntax, usage and docs (`#5617 <https://github.com/GenericMappingTools/gmt/pull/5617>`_) 91 92New Features in GMT 6.2 93======================= 94 95GMT 6.2 includes a new module, new common option, general code and documentation improvements, and numerous 96bug fixes! Here are the general updates included in 6.2: 97 98#. Addition of :doc:`theme-settings` (sets of GMT defaults), with a default modern theme for modern mode, and 99 :ref:`auto scaling options <cookbook/features:Automatic GMT settings>` for many GMT defaults. 100#. New :doc:`animation 13 <animations/anim13>` of seismic waveforms. 101#. New :doc:`animation 14 <animations/anim14>` of earthquake focal mechanisms. 102#. Support for **+a**\ *angle* for y-axis as well as x-axis with the :ref:`-B axes settings <gmt:Axes settings>`. 103#. General improvements to the automatic determination of frame attributes. 104#. New **+d**\ *divisor* modifier to the :ref:`-i option <gmt:The **-i** option>` to simplify scaling of input values. 105#. Allow parsing of **-Jz**\ *1:zzzzzz* for vertical scale. 106#. New GMT configuration parameters :term:`MAP_FRAME_PERCENT`, :term:`COLOR_SET`, and :term:`COLOR_CPT`. 107#. Add support for reading variable in NetCDF-4 groups. 108#. Allow specifying the reciprocal increment for generating 1d arrays. 109#. Allow LaTeX expressions in single-line titles and Cartesian axes labels, add support for multi-line plot titles, and 110 add support for subtitles. 111#. Many general documentation improvements. 112#. Various improvements to the API in support of developments taking place in the external wrappers (Python, Julia, Matlab). 113 114New Common Options in GMT 6.2: 115------------------------------ 116 117#. :ref:`-w <gmt:The **-w** option>`: Convert selected coordinate to repeating cycles. 118 119New Modules in GMT 6.2: 120----------------------- 121 122#. :doc:`gmtbinstats`: Bin spatial data and determine statistics per bin, with support for both hexagonal and rectangular tiling. 123 124New Core Module Features in GMT 6.2: 125------------------------------------ 126 127#. :doc:`colorbar`: New **+x** and **+y** modifiers to the **-S** option for setting axis label and unit; Support 128 slanted annotations with **-S**. 129#. :doc:`events`: New **-Z** option to animate geodesy and seismology symbols; New **-H** option to enable text label 130 boxes; Support plotting lines as series of closely spaced circles. 131#. :doc:`gmtmath`: New **VPDF** operator. 132#. :doc:`gmtsplit`: New name for previous module splitxyz. 133#. :doc:`grd2xyz`: New modifier for the **-W** option to set the length unit used. 134#. :doc:`grdcut`: New **-F** option to clip a grid based on a polygon. 135#. :doc:`grdfft`: New **-Q** option for no wavenumber operations. 136#. :doc:`grdmath`: New **FISHER** and **VPDF** operators. 137#. :doc:`greenspline`, :doc:`grdinterpolate`: Enable writing of 3-D netCDF data cubes. 138#. :doc:`histogram`: New **-E** option for custom bar widths and optional shift; New **+b** modifier to **-C** to set 139 color based on the bin value. 140#. :doc:`legend`: New **-M** option to handle both hidden and given information. 141#. :doc:`makecpt`, :doc:`grd2cpt`: Simplify the addition of category labels to CPT files with **-F**. 142#. :doc:`movie`: New modifiers to **-L** and **-P** to enable drop-shadow and rounded rectangular boxes. 143#. :doc:`plot`, :doc:`plot3d`: New **-H** option to scale the symbol size as well as the symbol pen outline attributes; 144 Support sequential auto-colors for polygon fills or line pens. 145#. :doc:`rose`: New **-N** option to draw the equivalent circular normal distribution. 146#. :doc:`subplot`: New **-D** option to accept previous default plot settings. 147#. :doc:`ternary`: Add support for drawing lines and polygons. 148#. :doc:`text`: New **-S** option to cast shade beneath a text box. 149 150Supplement updates in GMT 6.2: 151------------------------------ 152 153#. :doc:`coupe </supplements/seis/coupe>`: Updated syntax for the **-A** option. 154#. :doc:`coupe </supplements/seis/coupe>`, :doc:`meca </supplements/seis/meca>`, 155 :doc:`velo </supplements/geodesy/velo>`: New scaling option **-H**; allow variable transparency; allow adjusting 156 symbol color via intensity; allow setting symbol color using colormaps. 157#. :doc:`gmtgravmag3d </supplements/potential/gmtgravmag3d>`: Add option to create geometric bodies (spheres, prisms, 158 ellipsoids, etc.) and compute their effect. 159#. :doc:`grdseamount </supplements/potential/grdseamount>`: Add polynomial seamount shape. 160 161Release of GMT 6.1.1 162==================== 163 164The GMT 6.1.1 release adds no new features but fixes a number of bugs that have been reported 165since the release of 6.1. As such, it is a stable and recommended upgrade for all 6.1 users. 166For new features in 6.1.x in general, please read the following sections. 167 168New Features in GMT 6.1 169======================= 170 171GMT 6.1 may be a minor revision to 6.0 but packs quite a punch. For general 172changes, we mention 173 174 #. Updated remote global data sets: Earth reliefs, crustal ages, land/ocean masks, and day/night imagery. 175 The larger grid files (5x5 arc minutes and smaller resolutions) are now tiled and faster to download. 176 #. Let *gmt.history*, *gmt.conf*, and *gmt.cpt* be hierarchical and maintained 177 separately for figures, subplot panels, and insets in modern mode. 178 #. Use a list of keywords (*separate,anywhere,lon_horizontal,lat_horizontal, 179 tick_extend,tick_normal,lat_parallel*) instead of bit-sum for **MAP_ANNOT_OBLIQUE**. 180 #. Let the macOS bundle be built with OpenMP support to accelerate some computational modules. 181 #. Let GMT recognize MATLAB headers/comments via multiple **IO_HEADER_MARKER** characters. 182 #. Let an explicitly signed grid cross size in **GMTCASE_MAP_GRID_CROSS_SIZE_PRIMARY** or 183 **MAP_GRID_CROSS_SIZE_SECONDARY** mean centered (if positive) or asymmetrical (if negative) grid ticks. 184 #. Add modifier **+v** for a *vertical* oblique Equator in -JO [horizontal]. 185 #. New **-B** modifier **+i** for placing internal frame annotations 186 #. New **-B** modifier **+f** to turn on fancy geographic annotations. 187 #. New polar projection (**-JP**) modifiers (**+f**\|\ **r**\|\ **t**\|\ **z**) adds new 188 capabilities for annotating azimuths, depths or radii. 189 #. Revise verbosity default levels and their names and abbreviations. 190 #. Add Web-Mercator as new sphere that can be selected. 191 #. Explore adding long-format GMT options (e.g., **--region**\ =\ *w/e/s/n*). 192 #. Allow both **-i** and **-o** to specify an open-ended list of columns to end of record. 193 #. API improvements to support the GMT/MEX, PyGMT, and GMT.jl environments. 194 195New Common Options in GMT 6.1: 196------------------------------ 197 #. **-l**: Add automatic legend entries from the modules :doc:`plot`, :doc:`plot3d`, 198 :doc:`grdcontour` and :doc:`pscontour` in modern mode. 199 #. **-q**\[**i**\|\ **o**\ ]: Select specific data rows to complement selection of data columns (via **-i**, **-o**). 200 201New Modules in GMT 6.1: 202----------------------- 203 204#. :doc:`batch`: Automate batch job processing by replicating a master script with job-specific parameters. 205#. :doc:`grdmix`: Blending and transforming grids and images, including manipulating transparency. 206#. :doc:`grdinterpolate`: Interpolate new 2-D grids or 1-D data series from a 3-D data cube. 207#. :doc:`grdgdal`: Execute GDAL raster programs (such as info, dem, grid, translate, rasterize or warp), from GMT. 208 209New Core Module Features in GMT 6.1: 210------------------------------------ 211 212#. :doc:`begin`: Ignore the user's *gmt.conf* files normally included by using **-C**. 213#. :doc:`colorbar`: Option **-S** has been enhanced to handle bar appearance when **-B** is not used. 214#. :doc:`gmtget`: Options **-D**, **-I**, **-N**, and **-Q** handle download and query of remote data sets. 215#. :doc:`gmtmath`: New operators **RGB2HSV** and **HSV2RGB** for color manipulation. 216#. :doc:`gmtregress`: Let **-A** also be used to limit angles considered for LMS regressions. 217#. :doc:`gmtspatial`: New directive **-Sb** computes buffers around lines (via the optional GEOS library). 218#. :doc:`gmtvector`: Add vector operator **-Tt** that translates points by given distance in given direction. 219#. :doc:`grd2kml`: New option **-W** for adding contour overlays. Also rebuilt for global grids as well as 220 to write PNG or JPG directly (depending on transparency) without going via *PostScript* conversion (only 221 required if **-W** is used). 222#. :doc:`grdcontour`: Better handling of contour file that can now have unique angles and pens per contour. 223#. :doc:`grdconvert`: Enable scaling/translation services on output with **-Z**. 224#. :doc:`grdfill`: Implement minimum-curvature spline infill with **-As**. 225#. :doc:`grdfilter`: Let filter width optionally be a grid with variable widths. 226#. :doc:`grdgradient`: Add support for ambient light in **-N**, as in **-E**, and therefore via **-I** 227 in :doc:`grdimage` and :doc:`grdview`. 228#. :doc:`grdimage`: Now **-I** may take a filename in addition to requests to derive intensities from it. 229#. :doc:`grdinfo`: Now **-C** also appends registration and grid type as last two output columns 230 (0 = gridline, 1 = pixel registration; 0 = Cartesian, 1 = geographic). 231#. :doc:`grdmath`: New operators **DAYNIGHT** (for day/night terminator), **BLEND** (blend two grids using the weights 232 from a third), **DOT** (dot product), and **RGB2HSV**, and **HSV2RGB** for color manipulations. 233#. :doc:`grdtrack`: Determine central peak in all crossections with **-F** (requires **-C**); let **-E+c** continue 234 a track if next line is a direct continuation of previous line. 235#. :doc:`grdview`: Now **-I** may take a filename in addition to requests to derive intensities from it. 236#. :doc:`pscontour`: Better handling of contour file that can now have unique angles and pens per contour. 237#. :doc:`movie`: Add **-E** for an optional title sequence (with or without fading in/out), **-K** for fade in and 238 fade out for main animation sequence, **-Sb** and **-Sf** can now take a PostScript layer instead of a script, 239 and **-P** for adding one of six progress indicators. 240#. :doc:`nearneighbor`: Let **-Nn** call GDAL's nearest neighbor algorithm. 241#. :doc:`sample1d`: Adds a smoothing cubic spline via **-Fs**\ *p* (for a fit parameter *p*), with optional weights (**-W**). 242#. :doc:`surface`: Let **-D** take a modifier **+z**\ *value* to set a constant breakline level. 243 244Supplement updates in GMT 6.1: 245------------------------------ 246#. *seis*: Update all module syntax to GMT 6 standards and make their i/o more robust. 247#. *potential*: :doc:`grdflexure </supplements/potential/grdflexure>` adds new transfer functions now documented with equations. 248 249New Features in GMT 6.0 250======================= 251 252GMT 6.0 is a major revision of GMT and its eco-system. At the top level, 253there are numerous changes: 254 255#. An entirely new and permanent address with a brand new website layout and 256 organization: http://www.generic-mapping-tools.org. 257#. A new discussion forum at http://forum.generic-mapping-tools.org. 258#. A data server in Hawaii (oceania.generic-mapping-tools.org) with plans 259 for new mirror servers around the world. This is where the remote files 260 that start with @ come from. 261#. A new way to use GMT (*modern* mode) that eliminates many of the 262 aspects of classic GMT that perplexes users. In modern mode, PostSCript 263 is no longer the default graphics output format and most modules that 264 had names starting with **ps** have had that prefix removed. In addition, 265 a few modules have entirely different names in modern mode (*psxy* is *plot*, 266 *psxyz* is *plot3d*, and *psscale* is *colorbar*). 267#. The default mode remains *classic*, the only mode previously available. All 268 existing classic mode GMT 4 and 5 scripts will run as before. 269 270Modern mode modules in GMT 6.0 271------------------------------ 272 273GMT modern mode is supported by five new commands: 274 275#. :doc:`begin` starts a new GMT modern mode session. 276#. :doc:`figure` names a new GMT figure in the current session 277#. :doc:`subplot` starts, manages, and ends subplots in a figure. 278#. :doc:`inset` starts, manages and ends an inset in a figure or subplot. 279#. :doc:`end` ends a GMT modern mode session. 280 281Here, **gmt begin** and **gmt end** begins and ends a modern mode session, hence 282it is not possible to get entangled in modern mode if you prefer to run classic 283mode scripts. There are three additional commands that are associated with modern 284mode; the first two also work in classic mode since they are typically not useful in scripts: 285 286#. :doc:`docs` gives browser access to any GMT module documentation. 287#. :doc:`clear` removes various session files or cached data files. 288#. :doc:`movie` simplifies the construction of animated sequences. 289 290The entire cookbook, tutorial and gallery examples all use modern mode. In modern mode, 291the default graphics format is PDF and scripts can open up the plots in the default 292viewer automatically. 293 294New modules in GMT 6.0 295---------------------- 296 297Apart from modern mode we have added a few modules that are accessible to all users: 298 299#. :doc:`events` makes a snapshot of all time-dependent events. 300#. :doc:`/supplements/geodesy/earthtide` (supplement) computes the solid Earth tides. 301 302General improvements in GMT 6.0 303------------------------------- 304 305While our focus has been almost exclusively on GMT modern mode, there is a 306range of new capabilities have been added to all of GMT; here is a 307summary of these changes: 308 309* The :doc:`gmt` driver has several new options to display the latest GMT citation, DOI, 310 the current data server, and the ability to create a blank modern mode shell script or 311 DOS batch template. 312 313* A new common option **-l** lets some modules (currently, only :doc:`plot` and :doc:`plot3d`) 314 build an automatic legend. Most legends are now perfectly dimensions and aligned using 315 the PostScript language. 316 317* We now consider untouched pixels when rendering PostScript to be opaque, hence automatic 318 cropping to tightest bounding box will recognize areas painted white as different from opaque. 319 320* We have a much improved scheme for distinguishing between minus-signs and hyphens when typesetting 321 text since these are different glyphs in various character sets. 322 323* Modern mode can produce any of several graphics :ref:`formats <tbl-formats>`. While the default 324 is PDF, this can be changed via a new GMT defaults :term:`GMT_GRAPHICS_FORMAT`. 325 The conversion from PostScript to the desired format can be modified via another new GMT defaults 326 setting :term:`PS_CONVERT`. 327 328* We have relaxed the *style* syntax for pens so that the :*phase* part is optional, with a default of 0. 329 330* We have rearranged our supplements a bit: We have split meca to seis and geodesy and moved new module 331 :doc:`/supplements/geodesy/earthtide` and existing module :doc:`/supplements/geodesy/gpsgridder` to 332 the geodesy supplement. Also, :doc:`dimfilter` has moved to the core and we have remove the empty misc supplement. 333 334* In most modules that need to set up an equidistant 1-D array we now use the same machinery to parse 335 options and created the arrays through a redesigned **-T** option. For details on array creation, 336 see `Generate 1D Array`. 337 338* We have a new GMT common option **-j** that clarifies how to select flat Earth, great circle, 339 and geodesic calculations and thus eliminates awkward, sign-based increments. 340 341* The GMT common option **-r** used to always set pixel-registration for grids but it can now 342 take the optional directives **g** or **p** to specify the desired registration. 343 344* We now offer slanted annotations via the **-B** option, using the modifier **+a**\ *angle*. 345 We have added auto-computed annotation and tick intervals for time-axes. There is also the 346 frame specifications **lrbtu** that just draw the corresponding frames without ticking. 347 348* We offer a wide range of new color tables, including the scientific color maps from Fabio Crameri, 349 and we now use Google's *turbo* as the default GMT color table, and *geo* for topographic DEMs. 350 351* Modules that read data tables can now be given an ESRI shapefile directly. 352 353* GMT common options **-X** and **-Y** may now be specified using fractions of current plot's 354 dimensions. 355 356* When specifying master CPTs one can add the modifier **+i**\ *dz* to ensure any automatically computed 357 range is rounded into multiples of *dz*. 358 359* Let common option **-a** with no arguments place add all aspatial items to the input record. 360 361* We have added *dashdot* as a new shorthand style name. 362 363* Map regions can now be specified via **-R**\ *ISOcode* using the 2-char ISO country codes, with modifiers 364 to round the resulting exact regions into multiples of given increments. Under modern mode, new shorthand 365 options **-Re** and **-Ra** will examine the data files given and determine the exact or approximate region, 366 respectively. 367 368Module enhancements in GMT 6.0 369------------------------------ 370 371Several modules have obtained new options to extend their capabilities: 372 373* :doc:`grdfilter` now accepts the **-r** option to set grid node registration. 374 375* :doc:`clip` has a new option **-W**\ *pen* to draw the clip path as well as 376 setting up clipping. 377 378* :doc:`plot` takes a new modifier **+s** to **-Sr** to specify a rectangle via opposite 379 diagonal corners. Users can now also specify a color indirectly via a CPT (i.e., **-C**) 380 and a new **-Z**\ *value* option (instead of directly via **-G**). The wedge symbol (**-Sw**) has been greatly upgraded to 381 offer windshield and spider-graph symbols. There is now also a new QR code symbol 382 that will redirect to the GMT homepage. We also added a **+h** modifier for quoted lines 383 when the user wants to hide the line. Finally, symbols **-SE-**, **-SJ-** and **-SW** can 384 now all handle geographic units. 385 386* :doc:`plot3d` also allows users to specify a color indirectly via a CPT (i.e., **-C**) 387 and a new **-Z**\ *value* option. The wedge symbol (**-Sw**) has been greatly upgraded to 388 offer windshield symbols and spider-graph symbols. There is now also a new QR code symbol 389 that will redirect to the GMT homepage. 390 391* :doc:`text` can now handle lack of input files when **-F+c+t** is used to give both a string and 392 its placement. 393 394* In modern mode, both :doc:`makecpt` and :doc:`grd2cpt` require a new option **-H** to actually 395 write the resulting CPT to standard output (by default they write a hidden CPT that modern mode 396 modules know where to find automatically). **makecpt** also has a new option **-S** to create a 397 symmetric color table given the range in a data file given via **-T**. 398 399* :doc:`gmtmath` has a new operator **PHI** that computes the 400 golden ratio. We now allow **-Cx** and **-Cy** to represent **-C**\ 0 and **-C** \1. 401 402* :doc:`grdmath` also has a new operator **PHI** that computes the 403 golden ratio, as well as **NODE** and **NODEP** operators, and added more 404 OpenMP support for operators **LDISTG**, **PSI**, **TCRIT**, **PLM**, and **PLMg**. 405 406* :doc:`rose` can now take **-JX** instead of **-S** so all plot modules take **-J**. 407 408* :doc:`grdedit` can now take **-J** and add meta-data to the grid header. 409 410* :doc:`gmt2kml` takes new option **-E** to extract altitudes stored in the Extended data property. 411 412* :doc:`/supplements/seis/polar` and :doc:`/supplements/seis/meca` can let beachball size scale 413 with magnitude. These and other plotting tools in seis can now accept the 3-D projection setting via **-p**. 414 415* Both :doc:`grdcontour` and :doc:`contour` can now accept a list of comma-separated contours instead 416 of always creating equidistant lists. Also, if no contours are specified we auto-compute a reasonable 417 selection of 10 to 20 contours. We also added **-Ln**\|\ **N**\|\ **p**\|\ **P** for selecting 418 just negative or positive contours. Finally, we added modifier **+z** to **-Q** to exclude the zero-contour 419 entirely. 420 421* :doc:`mapproject` has an enhanced option **-W** that can return reference point coordinates. 422 Also, either **-J+**\ *proj* or **-J**\ *EPSG*:n can now be given. 423 424* :doc:`grdproject` also takes **-J**\ +*proj* or **-J**\ *EPSG*:n. 425 426* :doc:`project` has a new option **-Z** for generating the path of a specified ellipse. 427 428* :doc:`dimfilter` now writes an error analysis template to standard output via the **-L** option. 429 430* :doc:`surface` can now apply a data mask computed from the data distribution directly rather than 431 having to make separate calls to :doc:`grdmask` and :doc:`grdmath`. Also, the **-A** option now 432 has a directive **m** to select Flat Earth scaling via the mean latitude. 433 434* The block-modules :doc:`blockmean`, :doc:`blockmedian`, and :doc:`blockmode` have new options 435 **-A** and **-G** which allow them to write one or more grids directly. 436 437* :doc:`gmtinfo` has a new option **-a** which allows it to report aspatial column names, and 438 **-Ib** to output the boundary polygon for the data. 439 440* :doc:`/supplements/spotter/backtracker` can now do reconstruction given individual hotspot 441 drift histories. We also added **-M** for fractional stage rotations. 442 443* :doc:`/supplements/spotter/grdrotater` has an option **-A** to override region of output grid. 444 445* :doc:`/supplements/spotter/polespotter` has a new option **-Cx**\ *file*. 446 447* :doc:`psconvert` has a new option **-H** for automatic sub-pixel rendering and scaling. Under 448 modern mode we also have option **-M** for sandwiching a PostScript plot between two other plots. 449 450* We added modifiers **+a** and **+i** to option **-Z** in :doc:`gmtselect`. 451 452* :doc:`grdcut` has new option **-ZN** to strip off outside rows and cols that are all NaN. 453 454* :doc:`grdinfo` now accepts **-o** when **-Cn** is in effect. 455 456* Enable :doc:`basemap` **-L** to do Cartesian projection scales, even vertical. 457 458* Improve the vertical scale bar for :doc:`wiggle` as well. 459 460* :doc:`gmtconvert` has new option **-W** that attempts to convert trailing text to numbers, if possible. 461 Append modifier **+n** to suppress NaN columns. We also added **-N**\ *column*\ [**+a**\|\ **d**] to 462 sort a table based on specified *column*. Finally, **-EM**\ *stride* is similar to **-Em** but it will 463 always include the last point. 464 465* :doc:`grdlandmask` **-E** will trace nodes being positioned exactly on polygon border. 466 467* :doc:`histogram` can now run in reverse cumulative mode via **-Qr**. 468 469New Features in GMT 5.4 470======================= 471 472Between 5.3 and 5.4 we continued to work on the underlying API 473needed to support the modules and especially the external interfaces 474we are building toward MATLAB, Julia and Python. We have introduced the use of 475static analyzers to fix any code irregularities and we continue to submit 476our builds to Coverity for similar reasons. We have also made an effort 477to standardize GMT non-common option usage across the suite. 478Nevertheless, there have been many user-level enhancements as well. 479Here is a summary of these changes in three key areas: 480 481New modules in GMT 5.4 482---------------------- 483 484We have added a new module to the GMT core called 485:doc:`ternary`. 486This module allows for the construction of ternary diagram, currently 487restricted to symbols (i.e., a plot-like experience but for ternary data). 488The *mgd77* supplement has gained a new tool :doc:`mgd77header <supplements/mgd77/mgd77header>` 489for creating a valid MGD77-format header from basic metadata and information 490determined from the header-less data file. 491 492General improvements in GMT 5.4 493------------------------------- 494 495A range of new capabilities have been added to all of GMT; here is a 496summary of these changes: 497 498* We have added a new lower-case GMT common option. Programs that read 499 ASCII data can use **-e** to only select data records that match a 500 specified pattern or regular expression. 501 502* All modules can now read data via external URL addresses. This works 503 by using libcurl to access an external file and save it to the users' 504 GMT cache directory. This directory can be specified via a new GMT 505 defaults called :term:`DIR_CACHE` (and defaults to 506 the sub-directory cache under the **$GMT_USERDIR** directory [~/.gmt]). 507 Subsequent use of the same URL will be read from the cache (except 508 if explicitly removed by the user). An exception is CGI Get Commands 509 which will be executed anew each time. Both the user directory and 510 the cache directory will be created if they do not exist. 511 512* Any reference to Earth topographic/bathymetric relief files called 513 **@earth_relief_**\ *res*\ **.grd** will automatically obtain the grid 514 from the GMT data server. The resolution *res* allows a choice among 515 13 command grid spacings: 60m, 30m, 20m, 15m, 10m, 06m, 05m, 04m, 03m, 02m, 516 01m, 30s, and 15s (with file sizes 111 kb, 376 kb, 782 kb, 1.3 Mb, 2.8 Mb, 517 7.5 Mb, 11 Mb, 16 Mb, 27 Mb, 58 Mb, 214 Mb, 778 Mb, and 2.6 Gb respectively). 518 Once one of these have been downloaded any future reference will simply 519 obtain the file from **$GMT_USERDIR** (except if explicitly 520 removed by the user). 521 522* We are laying the groundwork for more dynamic documentation. At present, 523 the examples on the man pages (with the exception of *basemap* and *coast*) 524 cannot be run by cut and paste since they reference imaginary data sets. 525 These will soon appear with filenames starting in @ (e.g., @hotspots.txt), 526 and when such files are found on the command line it is interpreted to be 527 a shorthand notation for the full URL to the GMT cache data server. 528 529* We have added four new color tables inspired by matplotlib to the collection. 530 These CPTs are called plasma, magma, inferno, and viridis. 531 532* We have updated the online documentation of user-contributed custom symbols and 533 restored the beautiful biological symbols for whales and dolphins created by 534 Pablo Valdés during the GMT4 era. These are now complemented by new custom 535 symbols for structural geology designed by José A. Álvarez-Gómez. 536 537* The :doc:`PSL </devdocs/postscriptlight>` library no longer needs run-time files to configure the 538 list of standard fonts and character encodings, reducing the number of configure 539 files required. 540 541* The :doc:`gmt.conf` files produced by gmt set will only write parameters that differ 542 from the GMT SI Standard settings. This means most gmt.conf files will just 543 be a few lines. 544 545* We have deprecated the **-c**\ *copies* option whose purpose was to modify the 546 number of copies a printer would issue give a PostScript file. This is better 547 controlled by your printer driver and most users now work with PDF files. 548 549* The **-p** option can now do a simple rotation about the z-axis (i.e., not a 550 perspective view) for more advanced plotting. 551 552* The placement of color scales around a map can now be near-automatic, as 553 the **-DJ** setting now has many default values (such as for bar length, 554 width, offsets and orientation) based on which side you specified. If you 555 use this option in concert with **-B** to turn off frame annotation on the 556 side you place the scale bar then justification works exactly. 557 558* The **-i** option to select input columns can now handle repeat entries, 559 e.g., -i0,2,2,4, which is useful when a column is needed as a coordinate 560 *and* for symbol color or size. 561 562* The vector specifications now take one more modifier: **+h**\ *shape* 563 allows vectors to quickly set the head shape normally specified via 564 :term:`MAP_VECTOR_SHAPE`. This is particularly useful 565 when the symbol types are given via the input file. 566 567* The custom symbol macro language has been strengthened and now allows all 568 angular quantities to be variables (i.e., provided from your data file as 569 extra columns), the pen thickness can be specified as relative (and thus 570 scale with the symbol size at run-time), and a symbol can internally switch 571 colors between the pen and fill colors given on the command line. 572 573* We have reintroduced the old GMT4 polygon-vector for those who fell so hard 574 in love with that symbol. By giving old-style vector specifications you 575 will now get the old-style symbol. The new and superior vector symbols 576 will require the use of the new (and standard) syntax. 577 578Module enhancements in GMT 5.4 579------------------------------ 580 581Several modules have obtained new options to extend their capabilities: 582 583* :doc:`gmt` has new session management option that lets you clear various 584 files and cache directories via the new commands 585 **gmt clear** *all*\|\ *history*\|\ *conf*\|\ *cache*. 586 587* :doc:`gmt2kml` adds option **-Fw** for drawing wiggles along track. 588 589* :doc:`gmtinfo` adds option **-F** for reporting the number of tables, 590 segments, records, headers, etc. 591 592* :doc:`gmtmath` will convert all plot dimensions given on the command line 593 to the prevailing length unit set via :term:`PROJ_LENGTH_UNIT`. 594 This allows you to combine measurements like 12c, 4i, and 72p. The module 595 also has a new **SORT** operator for sorting columns and **RMSW** for weighted 596 root-mean-square. 597 598* :doc:`gmtwhich` **-G** will download a file from the internet (as discussed 599 above) before reporting the path to the file (which will then be in the 600 user's cache directory). 601 602* :doc:`grd2xyz` can now write weights equal to the area each node represents 603 via the **-Wa** option. 604 605* :doc:`grdgradient` can now take a grid of azimuths via the **-A** option. 606 607* :doc:`grdimage` and :doc:`grdview` can now auto-compute the intensities 608 directly from the required input grid via **-I**, and this option now 609 supports modifiers **+a** and **+n** for changing the options of the 610 grdgradient call within the module. 611 612* :doc:`grdinfo` adds option **-D** to determine the regions of all the 613 smaller-size grid tiles required to cover the larger area. It also take 614 a new argument **-Ii** for reporting the exact region of an img grid. 615 Finally, we now report area-weighted statistics for geographic grids, 616 added **-Lp** for mode (maximum-likelihood) estimate of location and scale, 617 and **-La** for requesting all of the statistical estimates. 618 619* :doc:`grdmath` has new operators **TRIM**, which will set all grid values 620 that fall in the specified tails of the data distribution to NaN, **NODE**, 621 which will create a grid with node indices 0 to (nx*ny)-1, and **RMSW**, 622 which will compute the weighted root-mean-square. 623 624* :doc:`makecpt` and :doc:`grd2cpt` add option **-Ws** for producing 625 wrapped (cyclic) CPT tables that repeat endlessly. New CPT keyword 626 **CYCLIC** controls if the CPT is cyclic. 627 628* :doc:`mapproject` adds a new **-Z** option for temporal calculations based 629 on distances and speeds, and has been redesigned to allow several outputs 630 by combining the options **-A**, **-G**, **-L**, and **-Z**. 631 632* :doc:`basemap` has a new map-inset (**-D**) modifier **+t** that will 633 translate the plot origin after determining the lower-left corner of the 634 map inset. 635 636* :doc:`histogram` has a new **-Z** modifier **+w** that will 637 accumulate weights provided in the 2nd input column instead of pure counts. 638 639* :doc:`rose` adds option **-Q** for setting the confidence level used 640 for a Rayleigh test for uniformity of direction. The **-C** option also 641 takes a new modifier **+w**\ *modfile* for storing mode direction to file. 642 643* :doc:`gmt_shell_functions.sh` adds numerous new functions to simplify the 644 building of animation scripts, animated GIF and MP4 videos, launching 645 groups of jobs across many cores, packaging KMLs into a single KMZ archive, 646 and more. 647 648API changes in GMT 5.4 649---------------------- 650 651We have introduced one change that breaks backwards compatibility for users of 652the API functions. We don't do this lightly but given the API is still considered 653beta it was the best solution. Function GMT_Create_Data now requires the mode to 654be **GMT_IS_OUTPUT** (an new constant) if a dummy (empty) container should be 655created to hold the output of a module. We also added two new API functions 656GMT_Duplicate_Options and GMT_Free_Option to manage option lists, and added 657the new constants **GMT_GRID_IS_CARTESIAN** and **GMT_GRID_IS_GEO** so that 658external tools can communicate the nature of grid written in situations where there 659are no projections involved (hence GMT does not know a grid is geographic). 660Passing this constant will be required in MB-System. 661 662Backwards-compatible syntax changes 663----------------------------------- 664 665We strive to keep the GMT user interface consistent. The common options help 666with that, but the module-specific options have often used very different 667forms to achieve similar goals. We have revised the syntax of numerous options 668across the modules to use the common *modifier* method. However, as no GMT 669users would be happy that their 670scripts no longer run, these changes are backwards compatible. Only the new 671syntax will be documented but old syntax will be accepted. Some options are 672used across GMT and will get a special mention first: 673 674* Many modules use **-G** to specify the fill (solid color or pattern). 675 The pattern specification has now changed to be 676 **-Gp**\|\ **P**\ *pattern*\ [**+b**\ *color*][**+f**\ *color*][**+r**\ *dpi*] 677 678* When specifying grids one can always add information such as grid type, scaling, 679 offset, etc. This is now done using a cleaner syntax for grids: 680 gridfile[=\ *ID*\ [**+s**\ *scale*][**+o**\ *offset*][**+n**\ *invalid*]]. 681 682Here is a list of modules with revised options: 683 684* :doc:`grdcontour` now expects **-Z**\ [**+**\ *scale*][**+o**\ *offset*][**+p**]. 685 686* In :doc:`grdedit` and :doc:`xyz2grd`, the mechanism to change a grid's 687 metadata is now done via modifiers to the **-D** option, such as 688 **+x**\ *xname*, **+t**\ *title*, etc. 689 690* :doc:`grdfft` has changed to **-E**\ [**+w**\ [**k**]][**+n**]. 691 692* :doc:`grdgradient` modifies the syntax of **-E** and **-N** by introducing modifiers, 693 i.e., **-E**\ [**m**\|\ **s**\|\ **p**]\ *azim/elev*\ [**+a**\ *ambient*][**+d**\ *diffuse*][**+p**\ *specular*][**+s**\ *shine*] and 694 **-N**\ [**e**\|\ **t**][*amp*][**+s**\ *sigma*][**+o**\ *offset*]. 695 696* :doc:`grdtrend` follows :doc:`trend1d` and now wants **-N**\ *model*\ [**+r**]. 697 698* :doc:`mapproject` introduces new and consistent syntax for **-G** and **-L** as 699 **-G**\ [*lon0*/*lat0*][**+a**][**+i**][**+u**\ [**+**\|\ **-**]\ *unit*][**+v**] and 700 **-L**\ *line.xy*\ [**+u**\ [**+**\|\ **-**]\ *unit*][**+p**]. 701 702* :doc:`project` expects **-G**\ *inc*\ [/*lat*][**+h**]. 703 704* :doc:`rose` now wants **-L**\ [*wlabel*\ ,\ *elabel*\ ,\ *slabel*\ ,\ *nlabel*] to 705 match the other labeling options. 706 707* :doc:`text` now expects **-D**\ [**j**\|\ **J**]\ *dx*\ [/*dy*][**+v**\ [*pen*]]. 708 709* :doc:`plot` expects **-E**\ [**x**\|\ **y**\|\ **X**\|\ **Y**][**+a**][**+cl**\|\ **f**][**+n**][**+w**\ *cap*][**+p**\ *pen*]. 710 711* :doc:`trend2d` follows :doc:`trend1d` and now wants **-N**\ *model*\ [**+r**]. 712 713 714New Features in GMT 5.3 715======================= 716 717Between 5.2 and 5.3 we spent much time working on the underlying API 718needed to support the modules and especially the external interfaces 719we are building toward MATLAB and Python. Nevertheless, there have 720been many user-level enhancements as well. 721Here is a summary of these changes in three key areas: 722 723New modules in GMT 5.3 724---------------------- 725 726We have added a new module to the GMT core called 727:doc:`solar`. 728This module plots various day-light terminators and other sunlight parameters. 729 730Two new modules have been added to the *spotter* supplement: 731The first is :doc:`gmtpmodeler<supplements/spotter/gmtpmodeler>`. 732Like :doc:`grdpmodeler<supplements/spotter/grdpmodeler>` it evaluates plate 733tectonic model predictions but at given point locations locations instead of 734on a grid. The second is :doc:`rotsmoother<supplements/spotter/rotsmoother>` 735which smooths estimated rotations using quaternions. 736 737Also, the *meca* supplement has gained a new tool :doc:`sac <supplements/seis/sac>` 738for the plotting of seismograms in SAC format. 739 740Finally, we have added :doc:`gpsgridder<supplements/geodesy/gpsgridder>` 741to the *potential* supplement. This tool is a Green's function gridding module 742that grids vector data assumed to be coupled via an elastic model. The prime 743usage is for gridding GPS velocity components. 744 745General improvements in GMT 5.3 746------------------------------- 747 748There are many changes to GMT, mostly under the hood, but also changes that 749affect users directly. We have added four new examples and one new animation 750to highlight recently added capabilities. There have been many bug fixes 751as well. For specific enhancements, we have: 752 753* All GMT-distributed color palette tables (CPTs, now a total of 44) are 754 *dynamic* and many have a *hinge* and a default *range*. What this means 755 is that the range of all CPTs have been normalized to 0-1, expect that 756 those with a hinge are normalized to ±1, with 0 being the normalized 757 hinge location. CPTs with a hinge are interpolated separately on either 758 side of the hinge, since a hinge typically signifies a dramatic color 759 change (e.g., at sea-level) and we do not want that color change to be 760 shifted to some other *z*-value when an asymmetrical range is being 761 requested. In situations where no range is specified then some CPTs 762 will have a default range and that will be substituted instead. The 763 tools :doc:`makecpt` and :doc:`grd2cpt` now displays more meta-data 764 about the various CPTs, including values for hinge, range, and the 765 color-model used. 766 767* We have consolidated how map embellishments are specified. This group 768 includes map scales, color bars, legends, map roses, map insets, 769 image overlays, the GMT logo, and a background panel. A new section in the Cookbook is 770 dedicated to these items and how they are specified. Common to all is 771 the concept of a *reference point* relative to which the item is 772 *justified* and *offset*. 773 774* We continue to extend support for OpenMP in GMT. New modules that are 775 OpenMP-enabled are :doc:`grdgradient`, :doc:`grdlandmask`, and :doc:`sph2grd`. 776 777* :doc:`blockmean`, :doc:`blockmedian` and :doc:`blockmode` have a new 778 modifier **+s** to the **-W** option. When used we expect 1-sigma 779 uncertainties instead of weights and compute weight = 1/sigma. 780 781* :doc:`filter1d`: can now compute high-pass filtered output via a new 782 **+h** modifier to the filter settings, similar to existing capability 783 in :doc:`grdfilter`. 784 785* :doc:`gmtconvert` has a new option (**-F**) for line segmentation and 786 network configuration. Also, the **-D** option has a new modifier **+o** 787 that sets the origin used for the numbering of tables and segments. 788 789* :doc:`gmtinfo` has a new option **-L** for finding the common bounds 790 across multiple files or segments. Also, the **-T** option has been 791 modified (while still being backwards compatible) to allow *dz* to be 792 optional, with modifiers **+s** forcing a symmetric range and **+a** 793 offering *alpha*-trimming of the tails before estimating the range. 794 795* :doc:`gmtmath` has gained new operators **VAR**, 796 **RMS**, **DENAN**, as well as the weighted statistical operators 797 **LMSSCLW**, **MADW**, **MEANW**, **MEDIANW**, **MODEW**, **PQUANTW**, 798 **STDW**, and **VARW**. Finally, we added a **SORT** operator that lets 799 you sort an entire table in ascending or descending order based on the 800 values in a selected column. 801 802* :doc:`gmtselect` has a new option **-G** for selecting based on a mask grid. 803 Points falling in bins whose grid nodes are non-zero are selected (or not if **-Ig**) 804 805* :doc:`gmtspatial` has two new modifiers for the **-Q** option that allow 806 output segments to be limited based on the segment length (or area for 807 polygons) as well as sorting the output in ascending or descending order. 808 809* :doc:`grd2cpt` existing **-F** option now takes a new modifier **+c** 810 for writing a discrete palette using the categorical format. 811 812* :doc:`grdedit` can now reset text items in the header via **-D** by 813 specifying '-'. Also, new **-C** option can be used to reset the 814 command history in the header. 815 816* :doc:`grdfft` has a new modifier to the **-E** option that allows for more 817 control of the power normalization for radial spectra. 818 819* :doc:`grdmath` also has the new operators **VAR**, 820 **RMS**, **DENAN**, as well as the weighted statistical operators 821 **LMSSCLW**, **MADW**, **MEANW**, **MEDIANW**, **MODEW**, **PQUANTW**, 822 **STDW**, and **VARW**. In addition it gains a new 823 **AREA** operator which computes the gridcell area (in km\ :sup:`2` if the 824 grid is geographic). Finally, operators **MEAN**, **MEDIAN**, etc., 825 when working on a geographic grid, will weight the result using the 826 **AREA** function for proper spherical statistics. 827 828* :doc:`grdvolume` can now accept **-Cr**\ *cval* which will evaluate 829 the volume between *cval* and the grid's minimum value. 830 831* :doc:`greenspline` now offers a new **-E** option that evaluates the 832 model fit at the input data locations and optionally saves the model 833 misfits to a secondary output file. 834 835* :doc:`makecpt` can also let you build either a discrete or continuous custom 836 color palette table from a comma-separated list of colors and 837 *z*-values provided via a file, an equidistant setup, or comma-separated list. 838 The **-F** option now takes a new modifier **+c** for writing a discrete 839 palette using the categorical format. 840 841* :doc:`text` has new modifiers to its **-F** option that allows users 842 to generate automatic labels such as record numbers of formatting of a 843 third data column into a textual representation. We also allow any 844 baseline angles to be interpreted as *orientations*, i.e., they will be 845 modified to fall in the -90/+90 range when **-F**\ ...\ **+A** is set. 846 847* :doc:`rose` can now control the attributes of vectors in a windrose 848 diagram via **-M**. 849 850* :doc:`plot` have seen numerous enhancements. New features include 851 *decorated* lines, which are similar to quoted lines except we place 852 symbols rather than text along the line. Users also gain new controls 853 over the plotting of lines, including the ability to add vector heads 854 to the line endings, to trim back lines by specified amounts, and to 855 request a Bezier spline interpolation in PostScript (see enhanced 856 **-W** option). A new option (**-F**) for line segmentation and networks 857 have also been added. Various geographic symbols (such as ellipses; **-SE**, 858 rotatable rectangles **-SJ**; and geo-vectors **-S=**) can now take size in geographic 859 dimensions, including a new geo-wedge symbol. We also offer one more 860 type of fault-slip symbol, using curved arrow heads. Also the arrow 861 head selections now include inward-pointing arrows. Custom symbols 862 may now simply be a preexisting EPS figure. Many of these enhancements 863 are also available in :doc:`plot3d`. 864 865* The spotter supplement now comes with the latest rotation files from 866 EarthByte, U. of Sydney. 867 868 869The API 870------- 871 872We have spend most of our time strengthening the API, in particular in support 873of the GMT/MATLAB toolbox. A few new API functions have been added since the 874initial release, including GMT_Get_Pixel, GMT_Set_Index, GMT_Open_VirtualFile, 875GMT_Close_VirtualFile, GMT_Read_VirtualFile, GMT_Read_Group, and GMT_Convert_Data; 876see the API :ref:`api` for details. 877 878 879New Features in GMT 5.2 880======================= 881 882While the GMT 5.1-series has seen bug-fixes since its release, new features were 883only added to the 5.2-series. All in all, almost 200 new features (a combination 884of new programs, new options, and enhancements) have been implemented. 885Here is a summary of these changes in six key areas: 886 887New modules in GMT 5.2 888---------------------- 889 890There are two new modules in the core system: 891 892:doc:`gmtlogo` is modeled after the shell script with the same 893name but is now a regular C module that can be used to add the 894GMT logo to maps and posters. 895 896:doc:`gmtregress` determines linear regressions for data sets using 897a variety of misfit norms and regression modes. 898 899Four new modules have also been added to the *potential* supplement: 900 901:doc:`gmtflexure <supplements/potential/gmtflexure>`: 902 Compute the elastic flexural response to a 2-D (line) load. 903 904:doc:`grdflexure <supplements/potential/grdflexure>`: 905 Compute the flexural response to a 3-D (grid) load, using a variety 906 or rheological models (elastic, viscoelastic, firmoviscous). 907 908:doc:`talwani2d <supplements/potential/talwani2d>`: 909 Compute a profile of the free-air gravity, geoid or vertical gravity gradient anomaly 910 over a 2-D body given as cross-sectional polygons. 911 912:doc:`talwani3d <supplements/potential/talwani3d>`: 913 Compute a grid or profile of the free-air gravity, geoid or vertical gravity gradient anomaly 914 over a 3-D body given as horizontal polygonal slices. 915 916In addition, two established modules have been given more suitable names 917(however, the old names are still recognized): 918 919:doc:`grdconvert` 920 Converts between different grid formats. 921 Previously known as grdreformat (this name is recognized 922 when GMT is running in compatibility mode). 923 924:doc:`psconvert` 925 Converts from PostScript to PDF, SVG, or various raster image formats. 926 Previously known as ps2raster (this name is recognized 927 when GMT is running in compatibility mode). 928 929Finally, we have renamed our PostScript Light (PSL) library from psl 930to PostScriptLight to avoid package name conflicts. This library will eventually 931become decoupled from GMT and end up as a required prerequisite. 932 933New common options in GMT 5.2 934----------------------------- 935 936We have added two new lower-case GMT common options: 937 938* Programs that need to specify which values should represent "no data" 939 can now use **-d**\ [**i**\|\ **o**]\ *nodata*. For instance, this 940 option replaces the old **-N** in :doc:`grd2xyz` and :doc:`xyz2grd` 941 (but is backwards compatible). 942 943* Some modules are now using OpenMP to spread computations over all 944 available cores (only available if compiled with OpenMP support). 945 Those modules will offer the new option **-x**\ [[-]\ *n*] to reduce 946 how many cores to assign to the task. The modules that currently 947 have this option are :doc:`greenspline`, :doc:`grdmask`, :doc:`grdmath`, 948 :doc:`grdfilter`, :doc:`grdsample`, :doc:`sph2grd`, the potential supplement's 949 :doc:`grdgravmag3d <supplements/potential/grdgravmag3d>`, 950 :doc:`talwani2d <supplements/potential/talwani2d>` and 951 :doc:`talwani3d <supplements/potential/talwani3d>`, and the x2sys 952 supplement's :doc:`x2sys_solve <supplements/x2sys/x2sys_solve>`. 953 This list will grow longer with time. 954 955New default parameters in GMT 5.2 956--------------------------------- 957 958There have been a few changes to the GMT Defaults parameters. All changes 959are backwards compatible: 960 961* :term:`FORMAT_FLOAT_MAP` now allows the use %'g to get comma-separated groupings 962 when integer values are plotted. 963 964* :term:`FORMAT_FLOAT_OUT` can now accept a space-separated list of formats 965 as shorthand for first few columns. On output it will show the formats 966 in effect for multiple columns. 967 968* :term:`GMT_LANGUAGE` has replaced the old parameter **TIME_LANGUAGE**. 969 Related to this, the files share/time/\*.d have been moved and renamed to 970 share/localization/\*.txt and now include a new section 971 or cardinal points letter codes. 972 973* :term:`IO_SEGMENT_BINARY` is a new parameter that controls how binary records 974 with just NaNs should or should not be interpreted as segment headers. 975 976* :term:`PROJ_GEODESIC` was added to control which geodesic calculation should be 977 used. Choose among Vincenty [Default], Andoyer (fast approximate geodesics), 978 and Rudoe (from GMT4). 979 980* :term:`TIME_REPORT` now has defaults for absolute or elapsed time stamps. 981 982Updated common options in GMT 5.2 983--------------------------------- 984 985Two of the established GMT common options have seen minor improvements: 986 987* Implemented modifier **-B+n** to *not* draw the frame at all. 988 989* Allow oblique Mercator projections to select projection poles in the 990 southern hemisphere by using upper-case selectors **A**\|\ **B**\|\ **C**. 991 992* Added a forth way to specify the region for a new grid via the new 993 **-R**\ [**L**\|\ **C**\|\ **R**][**T**\|\ **M**\|\ **B**]\ *x0*/*y0*/*nx*/*ny* 994 syntax where you specify an reference point and number of points in the two 995 dimensions (requires **-I** to use the increments). The optional justification 996 keys specify how the reference point relate to the grid region. 997 998General improvements in GMT 5.2 999------------------------------- 1000 1001Several changes have affects across GMT; these are: 1002 1003* Added optional multi-threading capabilities to several modules, such as 1004 :doc:`greenspline`, :doc:`grdfilter`, :doc:`grdmask`, :doc:`grdsample`, 1005 the potential supplement's :doc:`grdgravmag3d <supplements/potential/grdgravmag3d>`, 1006 :doc:`talwani2d <supplements/potential/talwani2d>` and 1007 :doc:`talwani3d <supplements/potential/talwani2d>` and x2sys's :doc:`x2sys_solve <supplements/x2sys/x2sys_solve>`. 1008 1009* Optional prerequisite LAPACK means SVD decomposition in :doc:`greenspline` is 1010 now very fast, as is true for the regular Gauss-Jordan solution via a 1011 new multi-processor enabled algorithm. 1012 1013* Allow comma-separated colors instead of CPTs in options that are 1014 used to pass a CPT (typically this means the **-C** option). 1015 1016* Faster netCDF reading for COARDS table data (i.e., not grids). 1017 1018* When importing grids via GDAL the projection info is preserved and stored as netCDF metadata. 1019 This will allow third party programs like GDAL and QGIS to recognize the projection info of 1020 GMT created grids. Same thing happens when creating grids with :doc:`grdproject`. 1021 1022* Tools using GSHHG can now access information for both Antarctica data 1023 sets (ice-front and grounding line). 1024 1025* Tools that specify pens may now explicitly choose "solid" as an attribute, 1026 and we added "dashed" and "dotted" as alternatives to the shorthands "-" and ".". 1027 1028* Added three alternative vector head choices (terminal, square and circle) in addition 1029 to the default "arrow" style. We have also added the option for trimming the 1030 beginning and/or end point location of a vector, and you may now place the 1031 vector head at the mid-point of the vector instead at the ends. 1032 1033* All eight map embellishment features (map scale, color bar, direction rose, magnetic 1034 rose, GMT logo, raster images, map insets, and map legends) now use a uniform 1035 mechanism for specifying placement, justification, and attributes and is supported 1036 by a new section in the documentation. 1037 1038* Typesetting simultaneous sub- and super-scripts has improved (i.e., when a symbol 1039 should have both a subscript and and a superscript). 1040 1041* The custom symbol macro codes now allow for an unspecified symbol code (**?**), which 1042 means the desired code will be given as last item on each data record. Such custom 1043 symbols must be specified with uppercase **-SK**. 1044 1045Program-specific improvements in GMT 5.2 1046---------------------------------------- 1047 1048Finally, here is a list of enhancements to individual modules. Any 1049changes to existing syntax will be backwards compatible: 1050 1051* :doc:`fitcircle` now has a new option **-F** that allows output to be in the 1052 form of coordinates only (no text report) and you may choose which items to 1053 return by appending suitable flags. 1054 1055* :doc:`gmt` now has a --show-cores option that reports the available cores. 1056 1057* :doc:`gmtconvert` adds a **-C** option that can be used to eliminate 1058 segments on output based on the number of records it contains. We also 1059 added a **-F** option to create line segments from an input data sets using 1060 a variety of connectivity modes. 1061 1062* :doc:`gmtmath` adds a long list of new operators. We have the operator **BPDF** for binomial probability distribution and 1063 **BCDF** for the cumulative binomial distribution function. Due to confusion with 1064 other probability distributions we have introduced a series of new operator names 1065 (but honor backwards compatibility). Listing the pdf and cdf for each distribution, 1066 these are **TPDF** and **TCDF** for the Student t-distribution, 1067 **FPDF** and **FCDF** for the F-distribution, 1068 **CHI2PDF** and **CHI2CDF** for the Chi-squared distribution, 1069 **EPDF** and **ECDF** for the exponential distribution (as well as **ECRIT**), 1070 **PPDF** and **PCDF** for the Poisson distribution, 1071 **LPDF** and **LCDF** for the Laplace distribution (as well as **LCRIT**), 1072 **RPDF** and **RCDF** for the Rayleigh distribution (as well as **RCRIT**), 1073 **WPDF** and **WCDF** for the Weibull distribution (as well as **WCRIT**), and 1074 **ZPDF** and **ZCDF** for the Normal distribution. We added **ROLL** for cyclic shifts of the stack, 1075 and **DENAN** as a more intuitive operator for removing NaNs, as 1076 well as new constants **TRANGE**, **TROW**, **F_EPS** and **D_EPS**, and we have renamed the 1077 normalized coordinates from **Tn** to **TNORM** (but this is backwards compatible). We added 1078 operator **POINT** which reads a data table and places the mean x and mean y on the stack. 1079 Finally, we added new hyperbolic and inverse hyperbolic functions **COTH** and **ACOTH**, 1080 **SECH** and **ASECH**, and **CSCH** and **ACSCH**. 1081 1082* :doc:`gmtspatial` now lets you specify Flat Earth or Geodesic distance calculations 1083 for line lengths via **-Q**. 1084 1085* :doc:`grdblend` relaxes the **-W** restriction on only one output grid 1086 and adds the new mode **-Wz** to write the weight*zsum grid. 1087 1088* :doc:`grdedit` enhances the **-E** option to allow for 90-degree rotations 1089 or flips of grid, as well as a new **-G** to enable writing of the result 1090 to a new output file [Default updates the existing file]. The **-J** option 1091 saves the georeferencing info as metadata in netCDF grids. 1092 1093* :doc:`grdfilter` now includes histogram mode filtering to complement mode 1094 (LMS) filtering. 1095 1096* :doc:`grdgradient` adds **-Da** to compute the aspect (down-slope) direction [up-slope]. 1097 1098* :doc:`grdinfo` reports the projection info of netCDF grids when that is stored in 1099 a grid's metadata in WKT format. 1100 1101* :doc:`grdmath` adds numerous new operators, such as **ARC** and **WRAP** for 1102 angular operators, **BPDF** for binomial probability distribution and 1103 **BCDF** for the cumulative binomial distribution function. Due to confusion with 1104 other probability distributions we have introduced a series of new operator names 1105 (but accept backwards compatibility). Listing the pdf and cdf for each distribution, 1106 these are **TPDF** and **TCDF** for the Student t-distribution, 1107 **FPDF** and **FCDF** for the F-distribution, 1108 **CHI2PDF** and **CHI2CDF** for the Chi-squared distribution, 1109 **EPDF** and **ECDF** for the exponential distribution (as well as **ECRIT**), 1110 **PPDF** and **PCDF** for the Poisson distribution, 1111 **LPDF** and **LCDF** for the Laplace distribution (as well as **LCRIT**), 1112 **RPDF** and **RCDF** for the Rayleigh distribution (as well as **RCRIT**), 1113 **WPDF** and **WCDF** for the Weibull distribution (as well as **WCRIT**), and 1114 **ZPDF** and **ZCDF** for the Normal distribution. We added **LDISTG** (for distances 1115 to GSHHG), **CDIST2** and **SDIST2** 1116 (to complement **LDIST2** and **PDIST2**), and **ROLL** for cyclic shifts of the stack, 1117 and **DENAN** as a more intuitive operator for removing NaNs, 1118 while **LDIST1** has been renamed 1119 to **LDISTC**. We also add new constants **XRANGE**, **YRANGE**, **XCOL**, 1120 **YROW** and **F_EPS**, and we have renamed the normalized coordinates from **Xn** to **XNORM** 1121 and **Yn** to **YNORM** (but this is backwards compatible). 1122 Finally, we added new hyperbolic and inverse hyperbolic functions **COTH** and **ACOTH**, 1123 **SECH** and **ASECH**, and **CSCH** and **ACSCH**. 1124 1125* :doc:`grdtrack` add the modifier **-G+l**\ *list* to pass a list of grids. 1126 1127* :doc:`grdview` implements the Waterfall plot mode via **-Qmx**\|\ **y**. 1128 1129* :doc:`kml2gmt` acquires a **-F** option to control which geometry to output. 1130 1131* :doc:`makecpt` takes **-E** to determine range from an input data table. 1132 1133* :doc:`mapproject` can be used in conjunction with the 3-D projection options to 1134 compute 3-D projected coordinates. We also added **-W** to simply output the 1135 projected dimensions of the plot without reading input data. 1136 1137* :doc:`basemap` now takes **-A** to save the plot domain polygon in geographical coordinates. 1138 The **-L** option for map scale and **-T** for map roses have been revised (backwards compatible) and a 1139 new uniform **-F** option to specify background panel and its many settings was added. 1140 1141* :doc:`coast` can accept multiple **-E** settings to color several features independently. 1142 We also have the modifiers **+AS** to *only* plot Antarctica, **+ag** to use 1143 shelf ice grounding line for Antarctica coastline, and **+ai** to use ice/water 1144 front for Antarctica coastline [Default]. As above, the **-L** option for map scale 1145 and **-T** option for map roses have been revised (backwards compatible) and a new uniform **-F** option to specify 1146 background panel and its many settings was added. 1147 1148* :doc:`psconvert` (apart from the name change) has several new features, such as 1149 reporting dimensions of the plot when **-A** and **-V** are used, 1150 scaling the output plots via **-A+s**\ [**m**]\ *width*\ [/*height*], 1151 paint and outline the bounding box via **-A** modifiers **g**\ *fill* and **+p**\ *pen*, 1152 and **-Z** for removing the PostScript file on exit. In addition, we have 1153 added SVG as a new output vector graphics format and now handle transparency even if 1154 non-PDF output formats are requested. 1155 1156* :doc:`contour` adds a **-Q**\ *cut* option like :doc:`grdcontour` and consolidates the 1157 old **-T**, **-Q** options for an index file to a new **-E** option. 1158 1159* :doc:`histogram` added modifiers **-W**\ *width*\ [**+l**\|\ **h**\|\ **b**] 1160 to allow for more control on what happens to points falling in the tails. 1161 1162* :doc:`image` added a new uniform **-D** option to specify location of the image and new uniform 1163 **-F** option to specify background panel and its many settings. 1164 1165* :doc:`legend` has many enhancements for specifying varying cell widths and color, as 1166 well as a new uniform **-D** option to specify location of legend and new uniform 1167 **-F** option to specify background panel and its many settings. 1168 1169* :doc:`colorbar` new uniform **-D** option to specify location of the scale. We have 1170 retired the **-T** option in favor of the new uniform 1171 **-F** option to specify background panel and its many settings. 1172 1173* :doc:`plot` has seen considerable enhancements. We added two new quoted 1174 line (**-Sq**) modifiers: **S**\|\ **s** for treating input as consecutive 1175 two-point line segments that should be individually quoted, 1176 and **+x**\ [*first*\ ,\ *last*] for automating cross-section labeling. 1177 We added a new symbol (**-S~**) for *decorated lines*. These are very similar 1178 to quoted lines but instead place specified symbols along lines. 1179 We expanded **-N** to handle periodic, repeating symbols near the boundary, 1180 added a new modifier **+** to **-E** for asymmetrical error bars, and provided the 1181 shorthand **-SE-**\ *diameter* for degenerated ellipses (i.e., circles). 1182 The **-L** option has been enhanced to create envelope polygons around y(x), 1183 say for confidence envelopes (modifiers **+b**\|\ **d**\|\ **D**), and to complete a closed 1184 polygon by adding selected corners (modifiers **+xl**\|\ **r**\|\ *x0* or **+yb**\|\ **t**\|\ *y0*). 1185 The **-A**\-option now has new modifiers **x**\|\ **y** for creating stair-case curves. 1186 The slip-vector symbol can now optionally accept a vector-head angle [30]. 1187 The custom symbols definition tests can now compare two input variables. 1188 We also added a **-F** option to draw line segments from an input data sets using 1189 a variety of connectivity modes. Finally, for drawing lines there are new line 1190 attribute modifiers available via the pen setting **-W** such as drawing with a 1191 Bezier spline (**+s**), trimming the segments from the ends before plotting (**+o**\ *offset*), 1192 or adding vector heads at the ends of the lines (**+v**). 1193 1194* :doc:`plot3d` also has the new **-SE-**\ *diameter* shorthand as well as the **-N** 1195 modifiers for handling periodic plot symbols. Like, plot it gets the same improvements 1196 to quoted lines and adds decorated lines as a new symbol. Likewise, 1197 the **-L** option has been enhanced to create envelope polygons around y(x), 1198 say for confidence envelopes (modifiers **+b**\|\ **d**\|\ **D**), and to complete a closed 1199 polygon by adding selected corners (modifiers **+xl**\|\ **r**\|\ *x0* or **+yb**\|\ **t**\|\ *y0*). 1200 The slip-vector symbol can now optionally accept a vector-head angle [30]. 1201 Finally, to match :doc:`plot` we have added the option **-T** for specifying no data input. 1202 1203* :doc:`sample1d` spline selection option **-F** can now accept the optional 1204 modifiers **+1** or **+2** which will compute 1205 the first or second derivatives of the spline, respectively. 1206 1207* :doc:`spectrum1d` can now turn off single-output data to stdout via **-T** 1208 or turn off multi-file output via **-N**. 1209 1210* :doc:`sphdistance` can now also perform a nearest-neighbor gridding where 1211 all grid nodes inside a Voronoi polygon is set to the same value as the 1212 Voronoi node value, via **-Ez**. 1213 1214* :doc:`trend1d` can now fit mixed polynomial and Fourier series models, 1215 as well as allowing models with just some terms in a polynomial or a 1216 Fourier series, including plain cosine or sine series terms. Modifiers 1217 have been added to specify data origin and fundamental period instead of 1218 defaulting to the data mid-point and data range, respectively. 1219 1220A few supplement modules have new features as well: 1221 1222* :doc:`mgd77track <supplements/mgd77/mgd77track>` adds the **-Gn**\ *gap* option to 1223 decimate the trackline coordinates by only plotting every *gap* point. 1224 1225* :doc:`gravfft <supplements/potential/gravfft>` adds **-W**\ *wd* to change 1226 observation level. 1227 1228* :doc:`grdgravmag3d <supplements/potential/grdgravmag3d>` adds **-H** to compute magnetic anomaly. 1229 1230* :doc:`grdpmodeler <supplements/spotter/grdpmodeler>` can now output more than one model 1231 prediction into several grids or as a record written to stdout. Also gains the **-N** option 1232 used by other spotter tools to extend the model duration. 1233 1234 1235New Features in GMT 5 1236===================== 1237 1238GMT 5 represents a new branch of GMT development that mostly preserves the 1239capabilities of the previous versions while adding over 200 new features 1240to an already extensive bag of tricks. Our PostScript library 1241:doc:`PSL </devdocs/postscriptlight>` has seen a complete rewrite as well 1242and produce shorter and more compact PostScript. However, the big news 1243is aimed for developers who wish to leverage GMT in their own applications. 1244We have completely revamped the code base so that high-level 1245GMT functionality is now accessible via GMT "modules". These are 1246high-level functions named after their corresponding programs (e.g., 1247``GMT_grdimage``) that contains all of the functionality of that program 1248within the function. While currently callable from C/C++ only (with some 1249support for F77), we are making progress on the Matlab interface as well 1250and there are plans to start on the Python version. Developers should 1251consult the :ref:`GMT API <api>` documentation for more details. 1252 1253We recommend that users of GMT 4 consider learning the new rules and defaults 1254since eventually (in some years) GMT 4 will be obsolete. 1255To ease the transition to GMT 5 you may run it in compatibility mode, 1256thus allowing the use of many obsolete default names and command 1257switches (you will receive a warning instead). This is discussed below. 1258 1259Below are six key areas of improvements in GMT 5. 1260 1261New programs in GMT 5 1262--------------------- 1263 1264First, a few new programs have been added and some have been 1265promoted (and possibly renamed) from earlier supplements: 1266 1267:doc:`gmt` 1268 This is the **only** program executable that is distributed with GMT 5. To avoid 1269 problems with namespace conflicts (e.g., there are other, non-GMT programs 1270 with generic names like triangulate, surface, etc.) all GMT 5 modules are 1271 launched from the gmt executable via "gmt module" calls (e.g, gmt coast). 1272 For backwards compatibility (see below) we also offer symbolic links with 1273 the old executable names that simply point to the gmt program, which then 1274 can start the correct module. Any module whose name starts with "gmt" can 1275 be abbreviated, e.g., "gmt gmtconvert" may be called as "gmt convert". 1276 1277:doc:`gmt2kml` 1278 A :doc:`plot` -like tool to produce KML overlays for Google Earth. Previously 1279 found in the misc supplement. 1280 1281:doc:`gmtconnect` 1282 Connect individual lines whose end points match within given tolerance. 1283 Previously known as gmtstitch in the misc supplement (this name is recognized 1284 when GMT is running in compatibility mode). 1285 1286:doc:`gmtget` 1287 Return the values of the specified GMT defaults. Previously only 1288 implemented as a shell script and thus not available on all platforms. 1289 1290:doc:`gmtinfo` 1291 Report information about data tables. Previously known by the name minmax 1292 (this name is still recognized when GMT is running in compatibility mode). 1293 1294:doc:`gmtsimplify` 1295 A line-reduction tool for coastlines and similar lines. Previously found 1296 in the misc supplement under the name gmtdp (this name is recognized when 1297 GMT is running in compatibility mode). 1298 1299:doc:`gmtspatial` 1300 Perform various geospatial operations on lines and polygons. 1301 1302:doc:`gmtvector` 1303 Perform basic vector manipulation in 2-D and 3-D. 1304 1305:doc:`gmtwhich` 1306 Return the full path to specified data files. 1307 1308grdraster 1309 Extracts subsets from large global grids. Previously 1310 found in the dbase supplement. 1311 1312:doc:`kml2gmt` 1313 Extract GMT data tables from Google Earth KML files. Previously 1314 found in the misc supplement. 1315 1316:doc:`sph2grd` 1317 Compute grid from list of spherical harmonic coefficients [We will add its 1318 natural complement grd2sph at a later date]. 1319 1320:doc:`sphdistance` 1321 Make grid of distances to nearest points on a sphere. Previously 1322 found in the sph supplement. 1323 1324:doc:`sphinterpolate` 1325 Spherical gridding in tension of data on a sphere. Previously 1326 found in the sph supplement. 1327 1328:doc:`sphtriangulate` 1329 Delaunay or Voronoi construction of spherical lon,lat data. Previously 1330 found in the sph supplement. 1331 1332We have also added a new supplement called potential that contains these five modules: 1333 1334:doc:`gmtgravmag3d <supplements/potential/gmtgravmag3d>`: 1335 Compute the gravity/magnetic anomaly of a body by the method of Okabe. 1336 1337:doc:`gmtflexure <supplements/potential/gmtflexure>`: 1338 Compute the flexure of a 2-D load using variable plate thickness and restoring force. 1339 1340:doc:`gravfft <supplements/potential/gravfft>`: 1341 Compute gravitational attraction of 3-D surfaces and a little more by the method of Parker. 1342 1343:doc:`grdgravmag3d <supplements/potential/grdgravmag3d>`: 1344 Computes the gravity effect of one (or two) grids by the method of Okabe. 1345 1346:doc:`grdredpol <supplements/potential/grdredpol>`: 1347 Compute the Continuous Reduction To the Pole, also known as differential RTP. 1348 1349:doc:`grdseamount <supplements/potential/grdseamount>`: 1350 Compute synthetic seamount (Gaussian or cone, circular or elliptical) bathymetry. 1351 1352Finally, the spotter supplement has added one new module: 1353 1354:doc:`grdpmodeler <supplements/spotter/grdpmodeler>`: 1355 Evaluate a plate model on a geographic grid. 1356 1357New common options in GMT 5 1358--------------------------- 1359 1360First we discuss changes that have been 1361implemented by a series of new lower-case GMT common options: 1362 1363* Programs that read data tables can now process the aspatial metadata 1364 in OGR/GMT files with the new **-a** option. These can be produced by 1365 **ogr2ogr** (a GDAL tool) when selecting the -f "GMT" output 1366 format. See Chapter :ref:`OGR_compat` for an explanation of the OGR/GMT file format. 1367 Because all GIS information is encoded via GMT comment lines these 1368 files can also be used in GMT 4 (the GIS metadata is simply 1369 skipped). 1370 1371* Programs that read or write data tables can specify a custom binary format 1372 using the enhanced **-b** option. 1373 1374* Programs that read data tables can control which columns to read and 1375 in what order (and optionally supply scaling relations) with the new **-i** option 1376 1377* Programs that read grids can use new common option **-n** to control 1378 grid interpolation settings and boundary conditions. 1379 1380* Programs that write data tables can control which columns to write 1381 and in what order (and optionally supply scaling relations) with the new **-o** option. 1382 1383* All plot programs can take a new **-p** option for perspective view 1384 from infinity. In GMT 4, only some programs could do this (e.g., 1385 :doc:`coast`) and it took a 1386 program-specific option, typically **-E** and sometimes an option 1387 **-Z** would be needed as well. This information is now all passed 1388 via **-p** and applies across all GMT plotting programs. 1389 1390* Programs that read data tables can control how records with NaNs are 1391 handled with the new **-s** option. 1392 1393* All plot programs can take a new **-t** option to modify the PDF 1394 transparency level for that layer. However, as PostScript has no provision for 1395 transparency you can only see the effect if you convert it to PDF. 1396 1397Updated common options in GMT 5 1398------------------------------- 1399 1400Some of the established GMT common options have seen significant 1401improvements; these include: 1402 1403* The completely revised **-B** option can now handle irregular and custom annotations 1404 (see Section :ref:`custom_axes`). It also has a new automatic mode which 1405 will select optimal intervals given data range and plot size. The 3-D base maps can now have 1406 horizontal gridlines on xz and yz back walls. 1407 1408* The **-R** option may now accept a leading unit which implies the 1409 given coordinates are projected map coordinates and should be 1410 replaced with the corresponding geographic coordinates given the 1411 specified map projection. For linear projections such units imply a 1412 simple unit conversion for the given coordinates (e.g., km to meter). 1413 1414* Introduced **-fp** which allows data input to be in 1415 projected values, e.g., UTM coordinates while **-Ju** is given. 1416 1417While just giving - (the hyphen) as argument presents just the synopsis of the command 1418line arguments, we now also support giving + which in addition will list 1419the explanations for all options that are not among the GMT common set. 1420 1421New default parameters in GMT 5 1422------------------------------- 1423 1424Most of the GMT default parameters have changed names in order to 1425group parameters into logical groups and to use more consistent naming. 1426However, under compatibility mode (see below) the old names are still recognized. 1427New capabilities have been implemented by introducing new GMT default settings: 1428 1429* :term:`DIR_DCW` specifies where to look for the optional 1430 Digital Charts of the World database (for country coloring or selections). 1431 1432* :term:`DIR_GSHHG` specifies where to look for the required 1433 Global Self-consistent Hierarchical High-resolution Geography database. 1434 1435* :term:`GMT_COMPATIBILITY` can be set to 4 to allow 1436 backwards compatibility with GMT 4 command-line syntax or 5 to impose 1437 strict GMT5 syntax checking. 1438 1439* :term:`IO_NC4_CHUNK_SIZE` is used to set the default 1440 chunk size for the **lat** and **lon** dimension of the **z** variable of 1441 netCDF version 4 files. 1442 1443* :term:`IO_NC4_DEFLATION_LEVEL` is used to set 1444 the compression level for netCDF4 files upon output. 1445 1446* :term:`IO_SEGMENT_MARKER` can be used to change the 1447 character that GMT uses to identify new segment header records [>]. 1448 1449* :term:`MAP_ANNOT_ORTHO` controls whether axes annotations 1450 for Cartesian plots are horizontal or orthogonal to the individual axes. 1451 1452* :term:`GMT_FFT` controls which algorithms to use for Fourier 1453 transforms. 1454 1455* :term:`GMT_TRIANGULATE` controls which algorithm to use 1456 for Delaunay triangulation. 1457 1458* Great circle distance approximations can now be fine-tuned via new GMT default parameters 1459 :term:`PROJ_MEAN_RADIUS` and :term:`PROJ_AUX_LATITUDE`. 1460 Geodesics are now even more accurate by using the Vincenty [1975] algorithm instead of 1461 Rudoe's method. 1462 1463* :term:`GMT_EXTRAPOLATE_VAL` controls what splines should do if 1464 requested to extrapolate beyond the given data domain. 1465 1466* :term:`PS_TRANSPARENCY` allows users to modify how transparency will be 1467 processed when converted to PDF [Normal]. 1468 1469A few parameters have been introduced in GMT 5 in the past and have been removed again. 1470Among these are: 1471 1472* *DIR_USER*: was supposed to set the directory in which the user configuration files, or data are stored, but 1473 this creates problems, because it needs to be known already before it is potentially set in *DIR_USER*/gmt.conf. 1474 The environment variable **$GMT_USERDIR** is used for this instead. 1475 1476* *DIR_TMP*: was supposed to indicate the directory in which to store temporary files. But needs to be known without 1477 gmt.conf file as well. So the environment variable **$GMT_TMPDIR** is used instead. 1478 1479General improvements in GMT 5 1480----------------------------- 1481 1482Other wide-ranging changes have been implemented in different 1483ways, such as 1484 1485* All programs now use consistent, standardized choices for plot 1486 dimension units (**c**\ m, **i**\ nch, or **p**\ oint; we no longer 1487 consider **m**\ eter a plot length unit), and actual distances 1488 (choose spherical arc lengths in **d**\ egree, **m**\ inute, and 1489 **s**\ econd [was **c**], or distances in m\ **e**\ ter [Default], 1490 **f**\ oot [new], **k**\ m, **M**\ ile [was sometimes **i** or 1491 **m**], **n**\ autical mile, and s\ **u**\ rvey foot [new]). 1492 1493* Programs that read data tables can now process multi-segment tables 1494 automatically. This means programs that did not have this capability 1495 (e.g., :doc:`filter1d`) can now all operate on the 1496 segments separately; consequently, there is no longer a **-m** 1497 option. 1498 1499* While we support the scaling of z-values in grids via the filename convention 1500 name[=\ *ID*\ [**+s**\ *scale*][**+o**\ *offset*][**+n**\ *nan*] mechanism, there are times 1501 when we wish to scale the x,y domain as well. Users can now 1502 append **+u**\ *unit* to their gridfile names, where *unit* is one of non-arc units listed 1503 in Table :ref:`distunits <tbl-distunits>`. This will convert your Cartesian 1504 x and y coordinates *from* the given unit *to* meters. We also support the inverse 1505 option **+U**\ *unit*, which can be used to convert your grid 1506 coordinates *from* meters *to* the specified unit. 1507 1508* CPTs also support the **+u**\|\ **U**\ *unit* mechanism. Here, the scaling 1509 applies to the z values. By appending these modifiers to your CPT names you 1510 can avoid having two CPTs (one for meter and one for km) since only one is needed. 1511 1512* Programs that read grids can now directly handle Arc/Info float binary 1513 files (GRIDFLOAT) and ESRI .hdr formats. 1514 1515* Programs that read grids now set boundary conditions to aid further 1516 processing. If a subset then the boundary conditions are taken from 1517 the surrounding grid values. 1518 1519* All text can now optionally be filled with patterns and/or drawn with 1520 outline pens. In the past, only :doc:`text` could plot outline fonts via 1521 **-S**\ *pen*. Now, any text can be an outline text by manipulating 1522 the corresponding FONT defaults (e.g., :term:`FONT_TITLE`). 1523 1524* All color or fill specifications may append @\ *transparency* to 1525 change the PDF transparency level for that item. See **-t** for 1526 limitations on how to visualize this transparency. 1527 1528* GMT now ships with 36 standard color palette tables (CPT), up from 24. 1529 1530Program-specific improvements in GMT 5 1531-------------------------------------- 1532 1533Finally, here is a list of numerous enhancements to individual programs: 1534 1535* :doc:`blockmean` added **-Ep** for error propagation and 1536 **-Sn** to report the number of data points per block. 1537 1538* :doc:`blockmedian` added **-Er**\ [-] 1539 to return as last column the record number that gave the median 1540 value. For ties, we return the record number of the higher data value 1541 unless **-Er**- is given (return lower). Added **-Es** to read and 1542 output source id for median value. 1543 1544* :doc:`blockmode` added **-Er**\ [-] but 1545 for modal value. Added **-Es** to read and output source id for modal 1546 value. 1547 1548* :doc:`gmtconvert` now has optional PCRE (regular expression) support, 1549 as well as a new option to select a subset of segments specified by 1550 segment running numbers (**-Q**) and improved options to extract a 1551 subset of records (**-E**) and support for a list of search strings 1552 via **-S+f**\ *patternfile*. 1553 1554* :doc:`gmtinfo` has new option **-A** to 1555 select what group to report on (all input, per file, or per segment). 1556 Also, use **-If** to report an extended region optimized for fastest results in FFTs. 1557 and **-Is** to report an extended region optimized for fastest results in :doc:`surface`. 1558 Finally, new option **-D**\ [*inc*] to align regions found via **-I** with the center 1559 of the data. 1560 1561* :doc:`gmtmath` with **-N**\ *ncol* and input 1562 files will add extra blank columns, if needed. A new option **-E** 1563 sets the minimum eigenvalue used by operators LSQFIT and SVDFIT. 1564 Option **-L** applies operators on a per-segment basis instead of 1565 accumulating operations across the entire file. Many new 1566 operators have been added (BITAND, BITLEFT, BITNOT, BITOR, BITRIGHT, 1567 BITTEST, BITXOR, DIFF, IFELSE, ISFINITE, SVDFIT, TAPER). Finally, 1568 we have implemented user macros for long or commonly used expressions, 1569 as well as ability to store and recall using named variables. 1570 1571* :doc:`gmtselect` Takes **-E** to indicate if points exactly on a polygon 1572 boundary are inside or outside, and **-Z** can now be extended to apply 1573 to other columns than the third. 1574 1575* :doc:`grd2cpt` takes **-F** to specify output color model and **-G** to 1576 truncate incoming CPT to be limited to a given range. 1577 1578* :doc:`grd2xyz` takes **-C** to write row, col instead of x,y. Append **f** 1579 to start at 1, else start at 0. Alternatively, use **-Ci** to write just 1580 the two columns *index* and *z*, where *index* 1581 is the 1-D indexing that GMT uses when referring to grid nodes. 1582 1583* :doc:`grdblend` can now take list of grids on 1584 the command line and blend, and now has more blend choices (see **-C**). Grids no 1585 longer have to have same registration or spacing. 1586 1587* :doc:`grdclip` has new option **-Si** to set all data >= low and <= high 1588 to the *between* value, and **-Sr** to set all data == old to the *new* value. 1589 1590* :doc:`grdcontour` can specify a single contour with **-C+**\ *contour* and 1591 **-A+**\ *contour*. 1592 1593* :doc:`grdcut` can use **-S** to specify an origin and radius and cut the 1594 corresponding rectangular area, and **-N** to extend the region if the new 1595 **-R** domain exceeds existing boundaries. 1596 1597* :doc:`grdfft` can now accept two grids and let **-E** compute the cross-spectra. 1598 The **-N** option allows for many new and special settings, including ability 1599 to control data mirroring, detrending, tapering, and output of intermediate 1600 results. 1601 1602* :doc:`grdfilter` can now do spherical 1603 filtering (with wrap around longitudes and over poles) for non-global 1604 grids. We have also begun implementing Open MP threads to speed up 1605 calculations on multi-core machines. We have added rectangular 1606 filtering and automatic resampling to input resolution for high-pass 1607 filters. There is also **-Ff**\ *weightgrd* which reads the gridfile 1608 *weightgrd* for a custom Cartesian grid convolution. The *weightgrd* 1609 must have odd dimensions. Similarly added **-Fo**\ *opgrd* for 1610 operators (via coefficients in the grdfile *opgrd*) whose weight sum 1611 is zero (hence we do not sum and divide the convolution by the weight 1612 sum). 1613 1614* :doc:`grdgradient` now has **-Em** that gives results close to ESRI's 1615 "hillshade"'" (but faster). 1616 1617* :doc:`grdinfo` now has modifier 1618 **-Ts**\ *dz* which returns a symmetrical range about zero. Also, 1619 if **-Ib** is given then the grid's bounding box polygon is written. 1620 1621* :doc:`grdimage` with GDAL support can write a raster image directly to 1622 a raster file (**-A**) and may plot raster images as well (**-Dr**). 1623 It also automatically assigns a color table if none is given and can use 1624 any of the 36 GMT color tables and scale them to fit the grid range. 1625 1626* :doc:`grdmask` has new option 1627 **-Ni**\|\ I\|\ p\|\ P to set inside of 1628 polygons to the polygon IDs. These may come from OGR aspatial values, 1629 segment head **-L**\ ID, or a running number, starting at a specified 1630 origin [0]. Now correctly handles polygons with perimeters and holes. 1631 Added z as possible radius value in **-S** which means read radii 1632 from 3rd input column. 1633 1634* :doc:`grdmath` added many new operators such as BITAND, BITLEFT, BITNOT, BITOR, BITRIGHT, 1635 BITTEST, BITXOR, DEG2KM, IFELSE, ISFINITE, KM2DEG, and TAPER. Finally, 1636 we have implemented user macros for long or commonly used expressions, 1637 as well as ability to store and recall using named variables. 1638 1639* :doc:`grdtrack` has many new options. The **-A** option controls how the 1640 input track is resampled when **-C** is selected, the new **-C**, **-D** 1641 options automatically create an equidistant set of cross-sectional 1642 profiles given input line segments; one or more grids can then be 1643 sampled at these locations. The **-E** option allows users to quickly specify 1644 tracks for sampling without needed input tracks. Also added **-S** which stack 1645 cross-profiles generated with **-C**. The **-N** will not skip 1646 points that are outside the grid domain but return NaN as sampled 1647 value. Finally, **-T** will return the nearest non-NaN node if the initial 1648 location only finds a NaN value. 1649 1650* :doc:`grdvector` can now take **-Si**\ *scale* to give the reciprocal scale, 1651 i.e., cm/ unit or km/unit. Also, the vector heads in GMT have completely been overhauled 1652 and includes geo-vector heads that follow great or small circles. 1653 1654* :doc:`grdview` will automatically assigns a color table if none is given and can use 1655 any of the 36 GMT color tables and scale them to fit the grid range. 1656 1657* :doc:`grdvolume` can let **-S** accept more distance units than just km. It also 1658 has a modified **-T**\ [**c**\|\ **h**] for ORS estimates based on max 1659 curvature or height. **-Cr** to compute the *outside* volume between two contours 1660 (for instances, the volume of water from a bathymetry grid). 1661 1662* :doc:`greenspline` has an improved **-C** option to control how many eigenvalues are used 1663 in the fitting, and **-Sl** adds a linear (or bilinear) spline. 1664 1665* :doc:`makecpt` has a new **-F** option to 1666 specify output color representation, e.g., to output the CPT in 1667 h-s-v format despite originally being given in r/g/b, and **-G** to 1668 truncate incoming CPT to be limited to a given range. It also adds **Di** 1669 to match the bottom/top values in the input CPT. 1670 1671* :doc:`mapproject` has a new **-N** 1672 option to do geodetic/geocentric conversions; it combines with **-I** 1673 for inverse conversions. Also, we have extended **-A** to accept 1674 **-A**\ **o**\| \ **O** to compute line orientations (-90/90). 1675 In **-G**, prepend - to the unit for (fast) flat Earth or + for (slow) geodesic calculations. 1676 1677* :doc:`project` has added **-G**...[+] so 1678 if + is appended we get a segment header with information about the 1679 pole for the circle. Optionally, append /*colat* in **-G** for a small circle path. 1680 1681* :doc:`psconvert` has added a **-TF** option to create multi-page PDF files. There is 1682 also modification to **-A** to add user-specified margins, and it automatically detects 1683 if transparent elements have been included (and a detour via PDF might be needed). 1684 1685* :doc:`basemap` has added a **-D** option to place a map-inset box. 1686 1687* :doc:`clip` has added an extended **-C** option to close different types of clip paths. 1688 1689* :doc:`coast` has added a new option **-E** which lets users specify one or more countries 1690 to paint, fill, extract, or use as plot domain (requires DCW to be installed). 1691 1692* :doc:`contour` is now similar to :doc:`grdcontour` in the options it 1693 takes, e.g., **-C** in particular. In GMT 4, the program could only 1694 read a CPT and not take a specific contour interval. 1695 1696* :doc:`histogram` now takes **-D** to place histogram count labels on top of each bar 1697 and **-N** to draw the equivalent normal distributions. 1698 1699* :doc:`legend` no longer uses system calls to do the plotting. The modified **-D** 1700 allows for minor offsets, while **-F** offers more control over the frame and fill. 1701 1702* :doc:`rose` has added **-Wv**\ *pen* to 1703 specify pen for vector (specified in **-C**). Added **-Zu** to set all radii to 1704 unity (i.e., for analysis of angles only). 1705 1706* :doc:`colorbar` has a new option **-T** that paints a rectangle behind the color bar. 1707 The **+n** modifier to **-E** draws a rectangle with NaN color and adds a label. 1708 The **-G** option will truncate incoming CPT to be limited to the specified z-range. 1709 Modification **-Np** indicates a preference to use polygons to draw the color bar. 1710 1711* :doc:`text` can take simplified input 1712 via new option **-F** to set fixed font (including size), angle, and 1713 justification. If these parameters are fixed for all the text strings 1714 then the input can simply be *x y text*. It also has enhanced **-DJ** option 1715 to shorten diagonal offsets by :math:`\sqrt{2}` to maintain the same 1716 radial distance from point to annotation. Change all text to upper or 1717 lower case with **-Q**. 1718 1719* :doc:`plot` and :doc:`plot3d` both support the revised custom symbol macro 1720 language which has been expanded considerably to allow for complicated, 1721 multi-parameter symbols; see Chapter :ref:`App-custom_symbols` 1722 for details. Finally, we allow the base for bars and columns optionally to be 1723 read from data file by not specifying the base value. 1724 1725* :doc:`sample1d` offers **-A** to control resampling of spatial curves (with **-I**). 1726 1727* :doc:`spectrum1d` has added **-L** to control removal of trend, mean value or mid value. 1728 1729* :doc:`surface` has added **-r** to create pixel-registered grids and knows about 1730 periodicity in longitude (given **-fg**). There is also **-D** to supply a "sort" break line. 1731 1732* :doc:`triangulate` now offers **-S** 1733 to write triangle polygons and can handle 2-column input if **-Z** is given. 1734 Can also write triangle edges as line with **-M**. 1735 1736* :doc:`xyz2grd` now also offers **-Af** (first value encountered), 1737 **-Am** (mean, the default), **-Ar** (rms), and **-As** (last value encountered). 1738 1739Several supplements have new features as well: 1740 1741* :doc:`img2grd <supplements/img/img2grd>` 1742 used to be a shell script but is now a C program and can be used on all platforms. 1743 1744* :doc:`mgd77convert <supplements/mgd77/mgd77convert>` 1745 added **-C** option to assemble \*.mgd77 files from \*.h77/\*.a77 pairs. 1746 1747* The spotter programs can now read GPlates rotation files directly as well 1748 as write this format. Also, 1749 :doc:`rotconverter <supplements/spotter/rotconverter>` can extract plate 1750 circuit rotations on-the-fly from the GPlates rotation file. 1751 1752**Note**: GMT 5 only produces PostScript and no longer has a setting for 1753Encapsulated PostScript (EPS). We made this decision since (a) our EPS determination 1754was always very approximate (no consideration of font metrics, etc.) and quite often wrong, 1755and (b) :doc:`psconvert` handles it exactly. Hence, users who need EPS plots should 1756simply process their PostScript files via :doc:`psconvert`. 1757