gmt-fork/doc/GMT_Chapter_1.tex

%------------------------------------------
%	$Id$
%
%	The GMT Documentation Project
%	Copyright (c) 2000-2012.
%	P. Wessel, W. H. F. Smith, R. Scharroo, and J. Luis
%------------------------------------------
%
\chapter{Preface} 
\label{ch:1}
\thispagestyle{headings}

While \GMT\ has served the map-making and data processing needs of scientists since 1988\footnote{Version
1.0 was then informally released at the Lamont-Doherty Earth Observatory.}, the current global use was
heralded by the first official release in \emph{EOS Trans. AGU} in the fall of 1991.  Since then,
\GMT\ has grown to become a standard tool for many users, particularly in the Earth and Ocean Sciences.
Development has at times been rapid, and numerous releases have seen the light of day since the early
versions.  For a detailed history of the changes from release to release, see file \filename{ChangeLog}
in the main \GMT\ directory.  For a nightly snapshot of ongoing activity, see the online
\htmladdnormallink{ChangeLog}{http://\GMTSITE/gmt/gmt_changelog.php} page.

The success of \GMT\ is to a large degree due to the input of the user community. In fact, most of the
capabilities and options in \GMT\ programs originated as user requests.
We would like to hear from you should you have any suggestions for future enhancements and modification.
Please send your comments to the
\htmladdnormallink{GMT help list}{mailto:gmt-help@lists.hawaii.edu}.

\section{What is new in \gmt\ 5.x?}

\GMT\ 5 represents a new branch of \GMT\ development that preserves the capabilities of the previous
versions while adding new tricks to many of the tools.  Furthermore, we have added system-wide
capabilities for handling PDF transparency, dealing with GIS aspatial data, and eliminated the need
for the \Opt{m} option.  Our \PS\ library \GMTprog{PSL} has seen a complete rewrite as well and produce
shorter and more compact \PS.
However, the big news is for developers who wish to leverage \GMT\ in their
own applications.  We have completely revamped the code base so that high-level \GMT\ functionality
is now accessible via \GMT\ ``modules''.  These are high-level functions named after their corresponding
programs (.e.g., \GMTfunc{GMT\_grdimage}) that contains all of the functionality of that program within
the function.  While currently callable from C/C++ only, we have built several of the Matlab interface
modules as well and will soon start on the Python version.  Developers should consult the GMT API Documentation for more details.

Most of the \GMT\ default parameters have changed named in order to group parameters into logical groups
and to use more consistent naming.  A new default parameter has been added as well:
\textbf{MAP\_ANNOT\_ORTHO}, which controls whether axes annotations for Cartesian plots are horizontal or
orthogonal to the individual axes.

Because of the default name changes and other command-line changes (such as making \Opt{m} obsolete), we
recommend that users of \GMT\ 4 consider learning the new rules and defaults.  However, to ease the
transition to \GMT\ 5 you may use the \-\-enable-compat switch when running configure , thus allowing the use
of many obsolete default names and command switches (you will receive a warning instead).

\subsection{Overview of \gmt\ 5.0.0b [Aug-25, 2011]}

This version shares the same bug fixes applied to \GMT\ 4.5.7, released July 15, 2011.
Several new programs have been added; some have been promoted from earlier supplements:

\begin{description}
	\item [\GMTprog{gmt2kml}]: A \GMTprog{psxy}-like tool to produce KML overlays for Google Earth.
	\item [\GMTprog{gmtdp}]: A line-reduction tool for coastlines and similar lines.
	\item [\GMTprog{gmtstitch}]: Join individual lines whose end points match within given tolerance.
	\item [\GMTprog{gmtwhich}]: Return the full path to specified data files.
	\item [\GMTprog{kml2gmt}]: Extract GMT data tables from Google Earth KML files.
	\item [\GMTprog{gmtspatial}]: Perform geospatial operations on lines and polygons.
	\item [\GMTprog{gmtvector}]: Perform basic vector manipulation in 2-D and 3-D.
\end{description}

Here is a list of the recent enhancement to various programs to date; we expect more to be added
before \GMT\ 5 becomes the official version and \GMT\ 4 will be retired:

\begin{enumerate}
	\item All programs now use consistent, standardized choices for plot dimension units (\textbf{c}m, \textbf{i}nch, or
	\textbf{p}oint;
		we no longer consider \textbf{m}eter a plot length unit), and projected distances (choose spherical arc lengths in \textbf{d}egree,
		\textbf{m}inute, and \textbf{s}econd [was \textbf{c}], or distances in m\textbf{e}ter [Default], \textbf{f}eet [new], 
		\textbf{k}m, \textbf{M}iles [was sometimes \textbf{i} or \textbf{m}], or \textbf{n}autical miles).
	\item All program that reads data tables can now process multi-segment tables automatically.  This means
		programs that did not have this capability (e.g., \GMTprog{filter1}) now can filter segments
		separately; consequently, there is no longer a \Opt{m} option.
	\item All program that reads data tables can now process the aspatial metadata in OGR/GMT files with the new \Opt{a} option.
		These are produced by \progname{ogr2ogr} (a GDAL tool) when selecting the -f ``GMT'' output format.  See Appendix Q
		for an explanation of the OGR/GMT file format.  Because all GIS information is encoded via \GMT\ comment lines
		these files can also be used in \GMT\ 4 (the GIS metadata is simply skipped).
	\item All program that read data tables can control which columns to read and in what order with the new \Opt{i} option.
	\item All program that write data tables can control which columns to write and in what order with the new \Opt{o} option.
	\item All program that write data tables can specify a custom binary format using the enhanced \Opt{b} option.
	\item All program that read data tables can control how records with NaNs are handled with the new \Opt{s} option.
	\item All program that read grids can use new common option \Opt{n} to control grid interpolation settings and boundary conditions.
	\item All program that read grids can now handle Arc/Info float binary files (GRIDFLOAT) and ESRI .hdr formats.
	\item All program that read grids now set boundary conditions to aid further processing.  If a subset then the
		boundary conditions are taken from the surrounding grid values.
	\item There is now defaults parameters that control which algorithms to use for Fourier transforms and triangulation.
	\item \GMT\ 5 only produces \PS\ and no longer has a setting for EPS.  We made this decision since a) our EPS effort was always
		very approximate (no consideration of font metrics. etc.) and often wrong, and b) \GMTprog{ps2raster} handles it exactly.
	\item The \Opt{B} option can now handle irregular and custom annotations (see Section \ref{sec:custaxes}).
		It also has an automatic mode which will select optimal intervals.
	\item All plot programs can take a new \Opt{p} option for perspective view from infinity.  In \GMT\ 4, only some
		programs could do this (e.g., \GMTprog{pscoast}) and it took a program-specific option, typically \Opt{E} and
		sometimes an option \Opt{Z} would be needed as well.  This information is now all passed via \Opt{p} and
		applies across all \GMT\ plotting programs.
	\item All plot programs can take a new \Opt{t} option to modify the PDF transparency level.  However, as \PS\ has
		no provision for transparency you can only see the effect if you convert it to PDF.
	\item All text can now optionally be filled with patterns and/or drawn with outline pens.  In the past, only
		\GMTprog{pstext} could plot outline fonts via \Opt{S}\emph{pen}.  Now, any text can be an outline text
		by manipulating the corresponding FONT defaults (e.g., \textbf{FONT\_TITLE}).
	\item All color or fill specifications may append @\emph{transparency} to change the PDF transparency level for that item.
		See \Opt{t} for limitations on how to visualize this transparency.
	\item \GMTprog{gmtconvert} now has optional PCRE (regular expression) support; Thanks to Florian Wobbe.
	\item \GMTprog{grdblend} can take list of grids on the command line and blend, and now has more blend choices.  Grids no
		longer have to have same registration or spacing.
	\item \GMTprog{grdfilter} can now do spherical filtering (with wrap around longitudes and over poles) for non-global grids.
		We have also begun implementing Open MP threads to speed up calculations on multi-core machines.  Finally, we have
		added rectangular filtering and automatic resampling to input resolution for high-pass filters.
	\item \GMTprog{grdmask} has new option \Opt{Ni}$|$I$|$p$|$P to set inside of polygons to the polygon IDs.
		These may come from OGR aspatial values, segment head \Opt{L}ID,
		or a running number, starting at a specified origin [0].
		Now correctly handles polygons with perimeters and holes.
	\item \GMTprog{grdtrack} has a new \Opt{C}, \Opt{D} options to automatically create an equidistant set of cross-sectional
		profiles given input line segments; one or more grids can then be sampled at these locations.  Finally, \Opt{N}
		will not skip points that are outside the grid domain but return NaN as sampled value.
	\item \GMTprog{mapproject} has a new \Opt{N} option to do geodetic/geocentric conversions; it combines with \Opt{I}
		for inverse conversions.  Also, we have extended \Opt{A} to accept \Opt{A}\textbf{o}$|$\textbf{O} to compute line orientations (-90/90).
	\item \GMTprog{makecpt} and \GMTprog{grd2cpt} has a new \Opt{F} option to specify output color representation, e.g.,
		to output the CPT table in h-s-v format despite originally being given in r/g/b.
	\item \GMTprog{minmax} has new option \Opt{A} to select what group to report on (all input, per file, or per segment).
	\item \GMTprog{gmtconvert} has new option \Opt{Q} to select a particular segment number.
	\item \GMTprog{gmtmath} and \GMTprog{grdmath} now support simple replacement macros via user files
		\filename{.grdmath} and \filename{.gmtmath}.  This mechanism works by replacing the macro name
		with the equivalent arguments in the program argument lists.
	\item \GMTprog{grdvolume} has enhanced \Opt{T}, now \Opt{T}[\textbf{c}$|$\textbf{h}] for ORS estimates based on max curvature or height.
	\item \GMTprog{ps2raster} has added a \Opt{TF} option to create multi-page PDF files.
	\item \GMTprog{pscontour} now similar to \GMTprog{grdcontour} in the options it takes, e.g., \Opt{C} in particular.
		In \GMT\ 4, the program could only read a CPT file and not take a specific contour interval.
	\item \GMTprog{psscale} has a new option \Opt{T} that paints a rectangle behind the color bar.
	\item \GMTprog{psxy.c} and \GMTprog{psxyz.c} can take symbol modifier \textbf{+s}\emph{scale}[\emph{unit}][/\emph{origin}][{ \bf l}]
		in \Opt{S} to adjust scales read from files.  This is used when you have data in the third column that should be
		used for symbol size but they need to be offset (by \emph{origin}) and scaled by (\emph{scale}) first; \textbf{l} means
		take the logarithm of the data column first.  Also, the custom symbol macro languages has been expanded considerably
		to allow for complicated, multi-parameter symbols; see Appendix N for details.
	\item \GMTprog{pstext.c} can take simplified input via new option \Opt{F} to set fixed font (including size), angle, and justification.  If
		these parameters are fixed for all the text strings then the input can simply be \emph{x y text}.
	
\end{enumerate}

Several supplements have new feature as well:

\begin{enumerate}
	\item The spotter programs can now read Gplates rotations directly as well as write this format.
		Now, \GMTprog{rotconverter} can extract plate circuit rotations on-the-fly from the Gplates rotation file.
\end{enumerate}