Provided by: gmt_4.5.11-1build1_amd64 bug


       backtracker - Reconstruct points, flowlines and hotspot tracks


       backtracker [infile(s)] -Erotations.txt | -elon/lat/angle [ -A[young/old] ] [ -C ] [ -Df|b
       ] [ -Fdrift.txt ] [ -H[i][nrec] ] [  -Lf|bstep  ]  [  -Nupper_age  ]  [  -Qfixed_age  ]  [
       -Sfilestem    ]    [   -Tzero_age   ]   [   -V   ]   [   -W[a|t]   ]   [   -:[i|o]   ]   [
       -b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ -m[i|o][flag] ]


       backtracker reads (longitude, latitude, age) positions from infiles  [or  standard  input]
       and  computes rotated (x,y,t) coordinates using the specified rotation parameters.  It can
       either calculate final positions [Default] or create a sampled track (flowline or  hotspot
       track)  between  the  initial and final positions.  The former mode allows additional data
       fields after the first 3 columns which must have (longitude,latitude,age).  See option  -:
       on how to read (latitude,longitude,age) files.
            No  space  between  the option flag and the associated arguments.  Use upper case for
       the option flags and lower case for modifiers.

              Data file(s) to be projected.  If not given, standard input is read.

       -E     Give file with rotation parameters.  This file must contain  one  record  for  each
              rotation; each record must be of the following format:

                   lon lat tstart [tstop] angle [ khat a b c d e f g df ]

              where  tstart  and  tstop  are in Myr and lon lat angle are in degrees.  tstart and
              tstop are the ages of the old and young ends of a stage.  If -C is set then a total
              reconstruction rotation is expected and tstop is implicitly set to 0 and should not
              be specified in the file.  If a covariance matrix C for the rotation  is  available
              it  must be specified in a format using the nine optional terms listed in brackets.
              Here, C = (g/khat)*[ a b d; b c e; d e f ] which shows  C  made  up  of  three  row
              vectors.   If the degrees of freedom (df) in fitting the rotation is 0 or not given
              it is set to 10000.  Blank lines and records whose first column contains # will  be

       -e     Alternatively,  specify  the longitude, latitude, and opening angle (all in degrees
              and separated by /) for a single  total  reconstruction  rotation  that  should  be
              applied to all input points.


       -A     Used  in  conjunction  with -Lb|f to limit the track output to those sections whose
              predicted ages lie between the specified young and old limits.  If  -LB|F  is  used
              instead then the limits apply to the stage ids (id 1 is the youngest stage).  If no
              limits are specified then individual limits for each record are expected in columns
              4 and 5 of the input file.

       -C     Expect   Total   Reconstruction  Rotations  rather  than  Forward  Stage  Rotations
              [Default].  File format is similar to the stage pole format except that the  tstart
              column is not present (assumed to be 0 Ma).  Requires -E.

       -D     Set  the  direction  to  go:  -Df  will  go backward in time (from younger to older
              positions), while -Db will go forward in time (from  older  to  younger  positions)
              [Default].  Note: For -Db you are specifying the age at the given location, whereas
              for -Df you are not; instead you specify the age at the reconstructed point.

       -F     Supply a file with lon, lat, age records  that  contains  the  history  of  hotspot
              motion  for  the  current hotspot.  If given, the reconstructions will only use the
              3rd data input column (i.e., the age) to obtain the location of the hotspot at that
              time,  via  an interpolation of the hotspot motion history.  This adjusted location
              is then used to reconstruct the point or path [No drift].

       -H     Input file(s) has header record(s).  If used, the default number of header  records
              is  N_HEADER_RECS.   Use -Hi if only input data should have header records [Default
              will write out header records if the input data have them]. Blank lines  and  lines
              starting with # are always skipped.

       -L     Specify  a  sampled path between initial and final position: -Lf will draw particle
              flowlines, while -Lb will draw backtrack (hotspot track)  paths.   Append  sampling
              interval  in  km.  If step < 0 then only the rotation times will be returned.  When
              -LF or -LB is used, the third output  column  will  contain  the  stage  id  (1  is
              youngest)  [Default  is along-track predicted ages].  You can control the direction
              of the paths by using -D.

       -N     Set the maximum age to extend the oldest stage rotation back in time [Default is no

       -Q     Assign  a  fixed  age  to  all positions.  Only lon, lat input is expected [Default
              expects longitude, latitude, age].  Useful  when  the  input  are  points  defining

       -S     When  -L  is set, the tracks are normally written to stdout as a multisegment file.
              Specify a filestem to have each track written to filestem.#, where # is  the  track
              number.  The track number is also copied to the 4th output column.

       -T     Set the current time [Default is 0 Ma].

       -V     Selects  verbose  mode,  which  will  send progress reports to stderr [Default runs

       -W     Rotates the given input (lon,lat,t) and calculates the confidence ellipse  for  the
              projected  point.  The input point must have a time coordinate that exactly matches
              a particular finite rotation time, otherwise the point will be skipped.   Append  t
              or  a  to  output time or angle, respectively, after the projected lon, lat.  After
              these 2-3 items, we write azimuth, major, minor (in  km)  for  the  95%  confidence
              ellipse.  See -D for the direction of rotation.

       -:     Toggles  between (longitude,latitude) and (latitude,longitude) input and/or output.
              [Default is (longitude,latitude)].  Append i to select input only or  o  to  select
              output only.  [Default affects both].

       -bi    Selects  binary  input.   Append  s  for  single precision [Default is d (double)].
              Uppercase S or D will force byte-swapping.  Optionally, append ncol, the number  of
              columns  in your binary input file if it exceeds the columns needed by the program.
              Or append c if the input  file  is  netCDF.  Optionally,  append  var1/var2/...  to
              specify the variables to be read.  [Default is 3 input columns].

       -bo    Selects  binary  output.   Append  s  for single precision [Default is d (double)].
              Uppercase S or D will force byte-swapping.  Optionally, append ncol, the number  of
              desired columns in your binary output file.  [Default depends on settings].

       -m     Multiple  segment  file(s).  Segments are separated by a special record.  For ASCII
              files the first character must be flag [Default is  '>'].   For  binary  files  all
              fields  must  be  NaN  and -b must set the number of output columns explicitly.  By
              default the -m setting applies to both input and output.  Use -mi and -mo  to  give
              separate settings to input and output.


       To  backtrack  the  (x,y,t) points in the file seamounts.d to their origin (presumably the
       hotspot), using the DC85.d Euler poles, run

       backtracker seamounts.d -Db -E DC85.d > newpos.d

       To project flowlines forward from the (x,y,t) points stored in several  3-column,  binary,
       double precision files, run

       backtracker points.* -Df -E DC85.d -Lf 25 -bo -bi3 > lines.b

       This file can then be plotted with psxy -M.

       To  compute  the  predicted  Hawaiian  hotspot  track  from 0 to 80 Ma every 1 Ma, given a
       history of hotspot motion file (HIdrift.txt) and a set of total  reconstruction  rotations
       for the plate (PAC_APM.d), try

       echo 204 19 80 | backtracker -Df -C -E PAC_APM.d -Lb 1 > path.d


       Data  coordinates  are  assumed  to  be  geodetic  and  will automatically be converted to
       geocentric before  spherical  rotations  are  performed.   We  convert  back  to  geodetic
       coordinates  for  output.   Note:  If  your data already are geocentric, you can avoid the
       conversion by using --ELLIPSOID=sphere.


       GMT(1),   project(1),   grdrotater(1),   grdspotter(1),   mapproject(1),    hotspotter(1),


       Wessel, P., 1999, "Hotspotting" tools released, EOS Trans. AGU, 80 (29), p. 319.