Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

       mapproject - Forward and Inverse map transformation of 2-D coordinates

SYNOPSIS

       mapproject  infiles  -Jparameters  -Rwest/east/south/north[r]  [  -Ab|B|f|F[lon0/lat0] ] [
       -C[dx/dy] ] [ -Dc|i|m|p ] [ -E[datum] ] [ -F[k|m|n|i|c|p] ] [  -G[x0/y0][+|-][/unit]  ]  [
       -H[i][nrec] ] [ -I ] [ -Lline.xy[/unit][+] ] [ -Q[d|e ] [ -S ] [ -T[h]from[/to] ] [ -V ] [
       -:[i|o]   ]   [   -b[i|o][s|S|d|D[ncol]|c[var1/...]]    ]    [    -f[i|o]colinfo    ]    [
       -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] ] [ -m[i|o][flag] ]

DESCRIPTION

       mapproject  reads  (longitude,  latitude)  positions  from infiles [or standard input] and
       computes (x,y) coordinates using the specified map projection and scales.  Optionally,  it
       can  read  (x,y)  positions  and  compute  (longitude,  latitude) values doing the inverse
       transformation.  This can be used to transform linear (x,y) points obtained by  digitizing
       a map of known projection to geographical coordinates.  May also calculate distances along
       track, to a fixed point, or closest approach to a line.  Finally, can be used  to  perform
       various datum conversions.  Additional data fields are permitted after the first 2 columns
       which  must  have  (longitude,latitude)  or  (x,y).   See  option  -:  on  how   to   read
       (latitude,longitude) files.

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

       -J     Selects  the  map projection. The following character determines the projection. If
              the  character  is  upper  case  then  the  argument(s)  supplied  as  scale(s)  is
              interpreted  to  be  the map width (or axis lengths), else the scale argument(s) is
              the map scale (see its definition for each projection). 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 or width  values.   Append
              h,  +,  or  - to the given width if you instead want to set map height, the maximum
              dimension, or the minimum dimension, respectively [Default is w for width].
              In case the central meridian is an optional parameter and it is being omitted, then
              the  center  of  the  longitude  range  given by the -R option is used. The default
              standard parallel is the equator.
              The ellipsoid used  in  the  map  projections  is  user-definable  by  editing  the
              .gmtdefaults4  file  in  your  home  directory.  73  commonly  used  ellipsoids and
              spheroids are currently supported, and users may  also  specify  their  own  custum
              ellipsoid  parameters  [Default  is WGS-84].  Several GMT parameters can affect the
              projection: ELLIPSOID, INTERPOLANT, MAP_SCALE_FACTOR,  and  MEASURE_UNIT;  see  the
              gmtdefaults man page for details.
              Choose  one  of the following projections (The E or C after projection names stands
              for Equal-Area and Conformal, respectively):

              CYLINDRICAL PROJECTIONS:

              -Jclon0/lat0/scale or -JClon0/lat0/width (Cassini).
                     Give projection center lon0/lat0 and scale (1:xxxx or UNIT/degree).

              -Jcyl_stere/[lon0/[lat0/]]scale  or  -JCyl_stere/[lon0/[lat0/]]width   (Cylindrical
              Stereographic).
                     Give  central  meridian  lon0 (optional), standard parallel lat0 (optional),
                     and scale along parallel (1:xxxx or UNIT/degree).  The standard parallel  is
                     typically one of these (but can be any value):
                            66.159467 - Miller's modified Gall
                            55 - Kamenetskiy's First
                            45 - Gall's Stereographic
                            30 - Bolshoi Sovietskii Atlas Mira or Kamenetskiy's Second
                            0 - Braun's Cylindrical

              -Jj[lon0/]scale or -JJ[lon0/]width (Miller Cylindrical Projection).
                     Give the central meridian lon0 (optional) and scale (1:xxxx or UNIT/degree).

              -Jm[lon0/[lat0/]]scale or -JM[lon0/[lat0/]]width
                     Give  central  meridian  lon0 (optional), standard parallel lat0 (optional),
                     and scale along parallel (1:xxxx or UNIT/degree).

              -Joparameters (Oblique Mercator [C]).
                     Typically used with -R<...>r, otherwise region is  in  oblique  coordinates.
                     Specify one of:

                     -Jo[a]lon0/lat0/azimuth/scale or -JO[a]lon0/lat0/azimuth/width
                            Set  projection  center  lon0/lat0,  azimuth  of oblique equator, and
                            scale.

                     -Jo[b]lon0/lat0/lon1/lat1/scale or -JO[b]lon0/lat0/lon1/lat1/scale
                            Set projection center lon0/lat0, another point on the oblique equator
                            lon1/lat1, and scale.

                     -Joclon0/lat0/lonp/latp/scale or -JOclon0/lat0/lonp/latp/scale
                            Set   projection   center   lon0/lat0,  pole  of  oblique  projection
                            lonp/latp, and scale.

                     Give scale along oblique equator (1:xxxx or UNIT/degree).

              -Jq[lon0/[lat0/]]scale or -JQ[lon0/[lat0/]]width (Cylindrical Equidistant).
                     Give  the  central  meridian  lon0  (optional),   standard   parallel   lat0
                     (optional),  and  scale  (1:xxxx  or UNIT/degree).  The standard parallel is
                     typically one of these (but can be any value):
                            61.7 - Grafarend and Niermann, minimum linear distortion
                            50.5 - Ronald Miller Equirectangular
                            43.5 - Ronald Miller, minimum continental distortion
                            42 - Grafarend and Niermann
                            37.5 - Ronald Miller, minimum overall distortion
                            0 - Plate Carree, Simple Cylindrical, Plain/Plane Chart

              -Jtlon0/[lat0/]scale or -JTlon0/[lat0/]width
                     Give the central meridian lon0, central parallel lat0 (optional), and  scale
                     (1:xxxx or UNIT/degree).

              -Juzone/scale or -JUzone/width (UTM - Universal Transverse Mercator [C]).
                     Give the UTM zone (A,B,1-60[C-X],Y,Z)) and scale (1:xxxx or UNIT/degree).
                     Zones:  If  C-X  not  given,  prepend - or + to enforce southern or northern
                     hemisphere conventions [northern if south > 0].

              -Jy[lon0/[lat0/]]scale or -JY[lon0/[lat0/]]width (Cylindrical Equal-Area [E]).
                     Give  the  central  meridian  lon0  (optional),   standard   parallel   lat0
                     (optional),  and  scale  (1:xxxx  or UNIT/degree).  The standard parallel is
                     typically one of these (but can be any value):
                            50 - Balthasart
                            45 - Gall-Peters
                            37.0666 - Caster
                            37.4 - Trystan Edwards
                            37.5 - Hobo-Dyer
                            30 - Behrman
                            0 - Lambert (default)

              CONIC PROJECTIONS:

              -Jblon0/lat0/lat1/lat2/scale or -JBlon0/lat0/lat1/lat2/width (Albers [E]).
                     Give projection center lon0/lat0,  two  standard  parallels  lat1/lat2,  and
                     scale (1:xxxx or UNIT/degree).

              -Jdlon0/lat0/lat1/lat2/scale or -JDlon0/lat0/lat1/lat2/width (Conic Equidistant)
                     Give  projection  center  lon0/lat0,  two  standard parallels lat1/lat2, and
                     scale (1:xxxx or UNIT/degree).

              -Jllon0/lat0/lat1/lat2/scale or -JLlon0/lat0/lat1/lat2/width (Lambert [C])
                     Give origin lon0/lat0, two standard parallels  lat1/lat2,  and  scale  along
                     these (1:xxxx or UNIT/degree).

              -Jpoly/[lon0/[lat0/]]scale or -JPoly/[lon0/[lat0/]]width ((American) Polyconic).
                     Give   the   central  meridian  lon0  (optional),  reference  parallel  lat0
                     (optional, default = equator), and scale along central meridian  (1:xxxx  or
                     UNIT/degree).

              AZIMUTHAL PROJECTIONS:

              Except  for  polar  aspects,  -R  w/e/s/n  will  be reset to -Rg.  Use -R<...>r for
              smaller regions.

              -Jalon0/lat0[/horizon]/scale or -JAlon0/lat0[/horizon]/width (Lambert [E]).
                     lon0/lat0 specifies  the  projection  center.   horizon  specifies  the  max
                     distance  from  projection  center  (in  degrees, <= 180, default 90).  Give
                     scale as 1:xxxx or radius/lat, where radius is distance in UNIT from  origin
                     to the oblique latitude lat.

              -Jelon0/lat0[/horizon]/scale     or     -JElon0/lat0[/horizon]/width     (Azimuthal
              Equidistant).
                     lon0/lat0 specifies  the  projection  center.   horizon  specifies  the  max
                     distance  from  projection  center  (in degrees, <= 180, default 180).  Give
                     scale as 1:xxxx or radius/lat, where radius is distance in UNIT from  origin
                     to the oblique latitude lat.

              -Jflon0/lat0[/horizon]/scale or -JFlon0/lat0[/horizon]/width (Gnomonic).
                     lon0/lat0  specifies  the  projection  center.   horizon  specifies  the max
                     distance from projection center (in degrees, < 90, default 60).  Give  scale
                     as 1:xxxx or radius/lat, where radius is distance in UNIT from origin to the
                     oblique latitude lat.

              -Jglon0/lat0[/horizon]/scale or -JGlon0/lat0[/horizon]/width (Orthographic).
                     lon0/lat0 specifies  the  projection  center.   horizon  specifies  the  max
                     distance from projection center (in degrees, <= 90, default 90).  Give scale
                     as 1:xxxx or radius/lat, where radius is distance in UNIT from origin to the
                     oblique latitude lat.

              -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale                      or
              -JGlon0/lat0/altitude/azimuth/tilt/twist/Width/Height/width (General Perspective).
                     lon0/lat0 specifies the projection center.  altitude is the height  (in  km)
                     of  the  viewpoint above local sea level.  If altitude is less than 10, then
                     it is the distance from the center of the earth to the  viewpoint  in  earth
                     radii.  If  altitude has a suffix r then it is the radius from the center of
                     the earth in kilometers.  azimuth is measured to the east of north of  view.
                     tilt  is  the  upward  tilt of the plane of projection. If tilt is negative,
                     then the viewpoint  is  centered  on  the  horizon.   Further,  specify  the
                     clockwise  twist, Width, and Height of the viewpoint in degrees.  Give scale
                     as 1:xxxx or radius/lat, where radius is distance in UNIT from origin to the
                     oblique latitude lat.

              -Jslon0/lat0[/horizon]/scale or -JSlon0/lat0[/horizon]/width (General Stereographic
              [C]).
                     lon0/lat0 specifies  the  projection  center.   horizon  specifies  the  max
                     distance from projection center (in degrees, < 180, default 90).  Give scale
                     as 1:xxxx (true at pole) or lat/1:xxxx (true at standard  parallel  lat)  or
                     radius/lat  (radius  in UNIT from origin to the oblique latitude lat).  Note
                     if 1:xxxx is used then to specify horizon you must also specify the  lat  as
                     +-90 to avoid ambiguity.

              MISCELLANEOUS PROJECTIONS:

              -Jh[lon0/]scale or -JH[lon0/]width (Hammer [E]).
                     Give the central meridian lon0 (optional) and scale along equator (1:xxxx or
                     UNIT/degree).

              -Ji[lon0/]scale or -JI[lon0/]width (Sinusoidal [E]).
                     Give the central meridian lon0 (optional) and scale along equator (1:xxxx or
                     UNIT/degree).

              -Jkf[lon0/]scale or -JKf[lon0/]width (Eckert IV) [E]).
                     Give the central meridian lon0 (optional) and scale along equator (1:xxxx or
                     UNIT/degree).

              -Jk[s][lon0/]scale or -JK[s][lon0/]width (Eckert VI) [E]).
                     Give the central meridian lon0 (optional) and scale along equator (1:xxxx or
                     UNIT/degree).

              -Jn[lon0/]scale or -JN[lon0/]width (Robinson).
                     Give the central meridian lon0 (optional) and scale along equator (1:xxxx or
                     UNIT/degree).

              -Jr[lon0/]scale -JR[lon0/]width (Winkel Tripel).
                     Give the central meridian lon0 (optional) and scale along equator (1:xxxx or
                     UNIT/degree).

              -Jv[lon0/]scale or -JV[lon0/]width (Van der Grinten).
                     Give the central meridian lon0 (optional) and scale along equator (1:xxxx or
                     UNIT/degree).

              -Jw[lon0/]scale or -JW[lon0/]width (Mollweide [E]).
                     Give the central meridian lon0 (optional) and scale along equator (1:xxxx or
                     UNIT/degree).

              NON-GEOGRAPHICAL PROJECTIONS:

              -Jp[a]scale[/origin][r|z]    or    -JP[a]width[/origin][r|z]   (Polar   coordinates
              (theta,r))
                     Optionally insert a after -Jp [ or -JP] for azimuths CW from  North  instead
                     of directions CCW from East [Default].  Optionally append /origin in degrees
                     to indicate an angular offset [0]).  Finally, append r if r is elevations in
                     degrees  (requires  s  >=  0 and n <= 90) or z if you want to annotate depth
                     rather than radius [Default].  Give scale in UNIT/r-unit.

              -Jxx-scale[/y-scale] or -JXwidth[/height] (Linear, log, and power scaling)
                     Give x-scale (1:xxxx or UNIT/x-unit) and/or y-scale (1:xxxx or UNIT/y-unit);
                     or  specify  width  and/or height in UNIT.  y-scale=x-scale if not specified
                     separately and using 1:xxxx implies that x-unit and y-unit  are  in  meters.
                     Use  negative  scale(s) to reverse the direction of an axis (e.g., to have y
                     be positive down). Set height or width to 0 to have it recomputed  based  on
                     the  implied  scale  of  the  other axis.  Optionally, append to x-scale, y-
                     scale, width or height one of the following:

                     d      Data are geographical coordinates (in degrees).

                     l      Take log10 of values before scaling.

                     ppower Raise values to power before scaling.

                     t      Input coordinates are time relative to TIME_EPOCH.

                     T      Input coordinates are absolute time.

                     Default axis lengths (see  gmtdefaults)  can  be  invoked  using  -JXh  (for
                     landscape);  -JXv  (for  portrait) will swap the x- and y-axis lengths.  The
                     default unit for this installation is either cm or inch, as defined  in  the
                     file  share/gmt_setup.conf.  However,  you  may  change this by editing your
                     .gmtdefaults4 file(s).

       -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).
              Special  case  for  the  UTM projection: If -C is used and -R is not given then the
              region is set to coincide with the given UTM  zone  so  as  to  preserve  the  full
              ellipsoidal solution (See RESTRICTIONS for more information).

OPTIONS

       No space between the option flag and the associated arguments.

       infile(s)
              input  file(s) with 2 or more columns. If no file(s) is given, mapproject will read
              the standard input.

       -A[f|b]
              -A calculates the (forward) azimuth from fixed point lon/lat to  each  data  point.
              Use  -Ab  to  get  back-azimuth from data points to fixed point.  Upper case F or B
              will convert  from  geodetic  to  geocentric  latitudes  and  estimate  azimuth  of
              geodesics  (assuming  the current ellipsoid is not a sphere).  If no fixed point is
              given then we compute the azimuth (or back-azimuth) from the previous point.

       -C     Set center of projected coordinates to be at  map  projection  center  [Default  is
              lower left corner].  Optionally, add offsets in the projected units to be added (or
              subtracted when -I is set) to (from)  the  projected  coordinates,  such  as  false
              eastings  and  northings  for particular projection zones [0/0].  The unit used for
              the offsets is the plot distance unit in effect (see  MEASURE_UNIT)  unless  -F  is
              used, in which case the offsets are always in meters.

       -D     Temporarily  override  MEASURE_UNIT  and  use  c  (cm),  i  (inch), m (meter), or p
              (points) instead.  Cannot be used with -F.

       -E     Convert from geodetic (lon, lat, height)  to  Earth  Centered  Earth  Fixed  (ECEF)
              (x,y,z) coordinates (add -I for the inverse conversion).  Append datum ID (see -Qd)
              or give ellipsoid:dx,dy,dz where ellipsoid may be an  ellipsoid  ID  (see  -Qe)  or
              given  as  a[,inv_f],  where  a  is  the  semi-major  axis and inv_f is the inverse
              flattening (0 if omitted).  If datum is - or not given we assume WGS-84.

       -F     Force 1:1 scaling, i.e., output (or input, see -I) data  are  in  actual  projected
              meters.   To  specify  other  units,  append k (km), m (mile), n (nautical mile), i
              (inch), c (cm), or p (points).  Without -F, the output (or input, see  -I)  are  in
              the units specified by MEASURE_UNIT (but see -D).

       -G     Calculate  distances along track OR to the optional point set with -Gx0/y0.  Append
              IT(unit), the distance unit; choose among e (m), k  (km),  m  (mile),  n  (nautical
              mile),  d  (spherical  degree), c (Cartesian distance using input coordinates) or C
              (Cartesian distance using projected coordinates).  The last unit requires -R and -J
              to  be  set.   Upper  case   E,  K,  M, N, or D will use exact methods for geodesic
              distances (Rudoe's method for distances in length units  and  employing  geocentric
              latitudes in degree calculations, assuming the current ellipsoid is not spherical).
              With no fixed  point  we  calculate  cumulate  distances  along  track.  To  obtain
              incremental  distance between successive points, use -G-.  To specify the 2nd point
              via two extra columns in the input file, choose -G+.

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

       -I     Do the Inverse transformation, i.e., get (longitude,latitude) from (x,y) data.

       -L     Determine  the shortest distance from the input data points to the line(s) given in
              the ASCII multi-segment file line.xy.  The distance  and  the  coordinates  of  the
              nearest  point  will  be  appended  to the output as three new columns.  Append the
              distance unit; choose among  e  (m),  k  (km),  m  (mile),  n  (nautical  mile),  d
              (spherical  degree), c (Cartesian distance using input coordinates) or C (Cartesian
              distance using projected coordinates).  The last unit requires -R and -J to be set.
              A spherical approximation is used for geographic data.  Finally, append + to report
              the line segment id and the fractional point  number  instead  of  lon/lat  of  the
              nearest point.

       -Q     List  all  projection  parameters.   To  only  list  datums, use -Qd.  To only list
              ellipsoids, use -Qe.

       -S     Suppress points that fall outside the region.

       -T     Coordinate conversions between datums from and to  using  the  standard  Molodensky
              transformation.   Use  -Th  if 3rd input column has height above ellipsoid [Default
              assumes height = 0, i.e., on the ellipsoid].  Specify datums  using  the  datum  ID
              (see  -Qd)  or  give ellipsoid:dx,dy,dz where ellipsoid may be an ellipsoid ID (see
              -Qe) or given as a[,inv_f], where a is the semi-major axis and inv_f is the inverse
              flattening (0 if omitted).  If datum is - or not given we assume WGS-84.  -T may be
              used in conjunction with -R -J to change the  datum  before  coordinate  projection
              (add  -I  to  apply  the datum conversion after the inverse projection).  Make sure
              that the ELLIPSOID setting is correct for your case.

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

       -:     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 2 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 is same as input].

       -f     Special  formatting  of  input  and/or  output columns (time or geographical data).
              Specify i or o to make this apply only to  input  or  output  [Default  applies  to
              both].   Give one or more columns (or column ranges) separated by commas.  Append T
              (absolute calendar time), t (relative time in chosen TIME_UNIT since TIME_EPOCH), x
              (longitude),  y  (latitude),  or  f (floating point) to each column or column range
              item.  Shorthand -f[i|o]g means -f[i|o]0x,1y (geographic coordinates).

       -g     Examine the spacing between consecutive data points in order to  impose  breaks  in
              the line.  Append x|X or y|Y to define a gap when there is a large enough change in
              the x or y coordinates, respectively, or d|D for distance gaps; use upper  case  to
              calculate  gaps  from  projected coordinates.  For gap-testing on other columns use
              [col]z; if col is not prepended the it defaults to 2 (i.e.,  3rd  column).   Append
              [+|-]gap  and  optionally  a  unit u.  Regarding optional signs: -ve means previous
              minus current column value must exceed |gap to be a gap, +ve  means  current  minus
              previous  column value must exceed gap, and no sign means the absolute value of the
              difference must exceed gap.  For geographic data (x|y|d), the unit u may  be  meter
              [Default], kilometer, miles, or nautical miles.  For projected data (X|Y|D), choose
              from inch, centimeter, meter, or points [Default unit set by MEASURE_UNIT].   Note:
              For  x|y|z  with time data the unit is instead controlled by TIME_UNIT.  Repeat the
              option to specify multiple criteria, of which any can be  met  to  produce  a  line
              break.  Issue an additional -ga to indicate that all criteria must be met instead.

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

ASCII FORMAT PRECISION

       The  ASCII  output  formats  of  numerical  data  are  controlled  by  parameters  in your
       .gmtdefaults4   file.    Longitude   and   latitude    are    formatted    according    to
       OUTPUT_DEGREE_FORMAT,  whereas other values are formatted according to D_FORMAT.  Be aware
       that the format in effect can lead to loss of precision in the output, which can  lead  to
       various problems downstream.  If you find the output is not written with enough precision,
       consider switching to binary output (-bo if available) or specify more decimals using  the
       D_FORMAT setting.

EXAMPLES

       To  transform  a  file  with (longitude,latitude) into (x,y) positions in cm on a Mercator
       grid for a given scale of 0.5 cm per degree, run

       mapproject lonlatfile -R 20/50/12/25 -Jm 0.5c > xyfile

       To transform several 2-column, binary, double precision  files  with  (latitude,longitude)
       into  (x,y)  positions  in  inch on a Transverse Mercator grid (central longitude 75W) for
       scale = 1:500000 and suppress those points that would fall outside the map area, run

       mapproject tracks.* -R-80/-70/20/40 -Jt-75/1:500000 -: -S -Di -bo -bi 2 > tmfile.b

       To convert the geodetic coordinates (lon, lat, height) in the file old.dat from the  NAD27
       CONUS datum (Datum ID 131 which uses the Clarke-1866 ellipsoid) to WGS 84, run

       mapproject old.dat -Th 131 > new.dat

       To  compute  the  closest distance (in km) between each point in the input file quakes.dat
       and the line segments given in the multi-segment ASCII file coastline.xy, run

       mapproject quakes.dat -L coastline.xy/k > quake_dist.dat

RESTRICTIONS

       The rectangular input region set with -R will in general be mapped into a  non-rectangular
       grid.   Unless  -C  is  set,  the  leftmost  point  on this grid has xvalue = 0.0, and the
       lowermost point will have yvalue = 0.0. Thus, before you digitize a map, run  the  extreme
       map  coordinates through mapproject using the appropriate scale and see what  (x,y) values
       they are mapped onto.  Use these values when setting up for digitizing in  order  to  have
       the  inverse  transformation  work correctly, or alternatively, use awk to scale and shift
       the (x,y) values before transforming.
       For some projections, a spherical solution may be used despite the user having selected an
       ellipsoid.  This occurs when the users -R setting implies a region that exceeds the domain
       in which the ellipsoidal series expansions are  valid.   These  are  the  conditions:  (1)
       Lambert  Conformal Conic (-JL) and Albers Equal-Area (-JB) will use the spherical solution
       when the map scale exceeds 1.0E7.  (2) Transverse Mercator (-JT) and UTM (-JU)  will  will
       use  the spherical solution when either the west or east boundary given in -R is more than
       10 degrees from the central meridian, and (3) same for Cassini (-JC) but with a  limit  of
       only 4 degrees.

ELLIPSOIDS AND SPHEROIDS

       GMT  will  use  ellipsoidal formulae if they are implemented and the user have selected an
       ellipsoid as the reference shape (see ELLIPSOID in gmtdefaults).  The  user  needs  to  be
       aware of a few potential pitfalls: (1)  For some projections, such as Transverse Mercator,
       Albers, and Lamberts conformal conic we use the ellipsoidal  expressions  when  the  areas
       mapped  are  small,  and  switch  to  the  spherical  expressions  (and  substituting  the
       appropriate auxiliary latitudes) for larger maps.  The ellipsoidal formulae  are  used  as
       follows:  (a)  Transverse  Mercator:  When  all  points  are  within 10 degrees of central
       meridian, (b) Conic projections when longitudinal range  is  less  than  90  degrees,  (c)
       Cassini  projection when all points are within 4 degrees of central meridian. (2) When you
       are trying to match some historical  data  (e.g.,  coordinates  obtained  with  a  certain
       projection and a certain reference ellipsoid) you may find that GMT gives results that are
       slightly different.  One likely source of this mismatch is that older  calculations  often
       used  less  significant digits.  For instance, Snyder's examples often use the Clarke 1866
       ellipsoid (defined by him as having a flattening  f  =  1/294.98).   From  f  we  get  the
       eccentricity  squared to be 0.00676862818 (this is what GMT uses), while Snyder rounds off
       and uses 0.00676866.  This difference can give discrepancies of several tens  of  cm.   If
       you need to reproduce coordinates projected with this slightly different eccentricity, you
       should specify your own ellipsoid with the same parameters as Clarke 1866, but  with  f  =
       1/294.97861076.  Also, be aware that older data may be referenced to different datums, and
       unless you know which datum was used and convert all  data  to  a  common  datum  you  may
       experience  mismatches  of  tens  to  hundreds  of  meters.  (3)  Finally,  be  aware that
       MAP_SCALE_FACTOR have certain default values for some  projections  so  you  may  have  to
       override the setting in order to match results produced with other settings.

SEE ALSO

       gmtdefaults(1), GMT(1), project(1)

REFERENCES

       Bomford, G., 1952, Geodesy, Oxford U. Press.
       Snyder,  J.  P.,  1987,  Map  Projections - A Working Manual, U.S. Geological Survey Prof.
       Paper 1395.
       Vanicek, P. and Krakiwsky, E, 1982, Geodesy - The Concepts, North-Holland Publ.,  ISBN:  0
       444 86149 1.