NAME

       gmtdigitize - Digitizing and Inverse map transformation of map x/y coordinates

SYNOPSIS

       gmtdigitize -Jparameters -Rwest/east/south/north[r] [ -A ] [ -Cdevice ] [ -Dlimit ] [ -F ]
       [  -H[i][nrec]  ]  [  -Llpi  ]  [  -Nnamestem  ]  [  -S  ]  [   -V   ]   [   -Zk|v   ]   [
       -bo[s|S|d|D[ncol]|c[var1/...]] ] [ -m[flag] ] [ > output.d ]

DESCRIPTION

       gmtdigitize  digitizes  points  from a digitizer via a serial line connection and computes
       map coordinates using the specified map projection.  The program is interactive  and  will
       take  you  through the setup procedure and how you will digitize points.  The program will
       determine the actual map scale as well as rotation of the  paper  that  is  taped  to  the
       digitizer table.  By default the output will go to stdout.
            No  space  between  the option flag and the associated arguments.  Use upper case for
       the option flags and lower case for modifiers.

       -J     Selects the map projection. Scale is UNIT/degree, 1:xxxxx, or width in UNIT  (upper
              case  modifier).   UNIT is cm, inch, or m, depending on the MEASURE_UNIT setting in
              .gmtdefaults4, but this can be overridden on the command line by appending c, i, or
              m  to  the scale/width value.  When central meridian is optional, default is center
              of longitude range on -R option.  Default standard parallel is  the  equator.   For
              map  height,  max  dimension,  or  min  dimension,  append h, +, or - to the width,
              respectively.
              More details can be found in the psbasemap man pages.

              CYLINDRICAL PROJECTIONS:

              -Jclon0/lat0/scale (Cassini)
              -Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
              -Jj[lon0/]scale (Miller)
              -Jm[lon0/[lat0/]]scale (Mercator)
              -Jmlon0/lat0/scale (Mercator - Give meridian and standard parallel)
              -Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and azimuth)
              -Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
              -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and pole)
              -Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
              -Jtlon0/[lat0/]scale (TM - Transverse Mercator)
              -Juzone/scale (UTM - Universal Transverse Mercator)
              -Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)

              CONIC PROJECTIONS:

              -Jblon0/lat0/lat1/lat2/scale (Albers)
              -Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
              -Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
              -Jpoly/[lon0/[lat0/]]scale ((American) Polyconic)

              AZIMUTHAL PROJECTIONS:

              -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
              -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
              -Jflon0/lat0[/horizon]/scale (Gnomonic)
              -Jglon0/lat0[/horizon]/scale (Orthographic)
              -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale (General Perspective).
              -Jslon0/lat0[/horizon]/scale (General Stereographic)

              MISCELLANEOUS PROJECTIONS:

              -Jh[lon0/]scale (Hammer)
              -Ji[lon0/]scale (Sinusoidal)
              -Jkf[lon0/]scale (Eckert IV)
              -Jk[s][lon0/]scale (Eckert VI)
              -Jn[lon0/]scale (Robinson)
              -Jr[lon0/]scale (Winkel Tripel)
              -Jv[lon0/]scale (Van der Grinten)
              -Jw[lon0/]scale (Mollweide)

              NON-GEOGRAPHICAL PROJECTIONS:

              -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
              -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log, and power scaling)
              For geographic projections you can give 1 as the scale will be solved for anyway.

       -R     xmin, xmax, ymin, and ymax specify the Region of interest.  For geographic regions,
              these limits correspond to west, east, south, and north and you may specify them in
              decimal degrees or in [+-]dd:mm[:ss.xxx][W|E|S|N] format.  Append r if  lower  left
              and  upper  right map coordinates are given instead of w/e/s/n.  The two shorthands
              -Rg and -Rd stand for global domain (0/360 and -180/+180 in longitude respectively,
              with  -90/+90  in  latitude).   Alternatively, specify the name of an existing grid
              file and the -R settings (and grid spacing, if  applicable)  are  copied  from  the
              grid.   For  calendar  time  coordinates  you  may  either  give  (a) relative time
              (relative to the selected TIME_EPOCH and in the selected  TIME_UNIT;  append  t  to
              -JX|x),  or  (b)  absolute time of the form [date]T[clock] (append T to -JX|x).  At
              least one of date and clock must be present; the T is always  required.   The  date
              string must be of the form [-]yyyy[-mm[-dd]] (Gregorian calendar) or yyyy[-Www[-d]]
              (ISO week calendar), while the clock string must be  of  the  form  hh:mm:ss[.xxx].
              The  use  of  delimiters  and their type and positions must be exactly as indicated
              (however, input, output and plot formats are customizable; see gmtdefaults).

OPTIONS

       -A     Give an audible signal each time the digitizer mouse/puck is  clicked  [Default  is
              silent].

       -C     Specify the device (port) to read from [Default is /dev/ttyS0].

       -D     Only  output  a  point  if  it is further than limit units from the previous point.
              Append c, i, m, p for cm, inch,  meter,  or  point,  respectively  [Default  is  no
              limit].

       -F     Force  the program to ask for 4 arbitrary calibration points [Default is to use the
              4 corners of the map, if possible].

       -H     This option allows you to write out any number of header records to  the  beginning
              of  the  output  file.   Each record will automatically start with a #-character to
              indicate comment.  Headers are not written if multiple output  files  are  selected
              with -N -m.

       -L     Set the digitizer table resolution in lines per inch [2540].

       -N     Set  name  for  output file(s).  If a regular filename is given, then all digitized
              data will be written to that file.  If the file contains a C-format for an  integer
              (i.e.,  %d)  then the file is used as a format statement to create unique filenames
              based on the current segment number (e.g., line_%d.d  will  yield  files  line_0.d,
              line_1.d,  etc).   By  default,  all output is written to stdout.  Multiple segment
              files requires specifying the -m option.

       -S     Suppress points that fall outside the specified map  region  [Default  outputs  all
              points].

       -V     Selects  verbose  mode,  which  will  send progress reports to stderr [Default runs
              "silently"].  The program will also duplicate data output to stderr for monitoring.

       -Z     Append v to prompt for a z-value and output it as a third data column.  Append k to
              output the button key as the final data column.  Both -Zk and -Zv can be specified.
              [Default is just 2 column x,y output].

       -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.

       -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.

EXAMPLES

       To digitize lines from a mercator map made for a given region, and save each line  segment
       in individual files called segment_000.xy, segment_001.xy etc, try

       gmtdigitize -R 20/50/12/25 -Jm 1:1 -m -N segment_%3.3d.xy

       To  digitize  seismically  defined  interfaces  from  a multichannel seismic section, with
       horizontal distances from 130 to 970, and vertical times from 0 to 10 seconds,  write  out
       the button code, and save all line segment to a single multisegment file, and beep at each
       click, try

       gmtdigitize -R 130/970/0/10 -Jx 1/-1 -m -A -Z > interfaces.d

SYSTEM SETUP

       This applies to the Calcomp DrawingBoard III hooked up to a RedHat Linux workstation.   We
       use  /dev/ttyS0  as the serial port and change permissions so that it is world read/write-
       able.  Then, stty -F /dev/ttyS0 evenp will set the terminal settings, which can be checked
       with  stty  -F  /dev/ttyS0 -a.  Setup of digitizer: We use the CalComp 2000 ASCII (Save 3)
       setup, which has:
       Mode: Point
       Baud Rate: 9600
       Data Bits: 7
       Parity: Even
       Data Rate: 125 pps
       Resolution: 200 lpi
       Output Format: Format 0
       Emulation: CalComp 2000 ASCII
       (A)We need to make a slight modification to the Preset No 3 settings: (1) 2450 LPI instead
       of  200, and (2) None instead of yes for added CR.  These modifications can be changed and
       saved to Preset 3 on the digitizer but a power outage may reset in  back  to  the  factory
       defaults,  necessitating  a manual reset of those two settings.  (B) Setup tty port.  stty
       -F /dev/ttyS0 evenp (C) Run gmtdigitize.  Map scale does not matter; it is  computed  from
       the region and plot size.

SEE ALSO

       gmtdefaults(l), GMT(l), gmtstitch(l), mapproject(l), project(l)