manpagez: man pages & more
man mapproject(1)
Home | html | info | man
mapproject(1)                         GMT                        mapproject(1)




NAME

       mapproject  - Do forward and inverse map transformations, datum conver-
       sions and geodesy


SYNOPSIS

       mapproject [ tables ]  -Jparameters
        -Rregion [  -Ab|B|f|F|o|O[lon0/lat0][+v] ] [  -C[dx/dy] ] [  -Dc|i|p ]
       [   -E[datum] ] [  -F[unit] ] [  -G[lon0/lat0][+a][+i][+u[+|-]unit][+v]
       ] [  -I ] [  -Lline.xy[+u[+|-]unit][+p] ] [  -N[a|c|g|m] ] [  -Q[d|e  ]
       [    -S   ]  [   -T[h]from[/to]  ]  [   -V[level]  ]  [   -W[w|h]  ]  [
       -Z[speed][+a][+i][+f][+tepoch] ] [ -bbinary ] [ -dnodata ] [ -eregexp ]
       [  -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -oflags ] [ -pflags
       ] [ -sflags ] [ -:[i|o] ]

       Note: No space is allowed between the option flag  and  the  associated
       arguments.


DESCRIPTION

       mapproject  reads (longitude, latitude) positions from tables [or stan-
       dard input] and computes (x,y) coordinates using the specified map pro-
       jection 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.
       Alternatively, can be used to perform various datum conversions.  Addi-
       tional  data  fields are permitted after the first 2 columns which must
       have (longitude,latitude) or (x,y). See option -: on how to read (lati-
       tude,longitude)  files.   Finally,  mapproject can compute a variety of
       auxiliary output data from input coordinates  that  make  up  a  track.
       Items   like   azimuth,   distances,  distances  to  other  lines,  and
       travel-times along lines can all be computed by using one  or  more  of
       the options -A, -G, -L, and -Z.


REQUIRED ARGUMENTS

       -Jparameters (more a|)
              Select map projection.

       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more a|)
              Specify the region of interest. Special case for the UTM projec-
              tion: 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).


OPTIONAL ARGUMENTS

       table  One or more ASCII (or binary, see -bi[ncols][type])  data  table
              file(s) holding a number of data columns. If no tables are given
              then we read from standard input.

       -Ab|B|f|F|o|O[lon0/lat0][+v]
              Calculate azimuth along track or to the optional fixed point set
              with  lon0/lat0.   -Af  calculates the (forward) azimuth to each
              data point. Use -Ab to get  back-azimuth  from  data  points  to
              fixed  point.  Use  -Ao to get orientations (-90/90) rather than
              azimuths (0/360). Upper case F, B or O will convert from geodet-
              ic  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.  Alternatively, append +v to  obtain  a
              variable  2nd  point  (lon0/lat0)  via  columns 3-4 in the input
              file.

       -C[dx/dy]
              Set center of projected coordinates to be at map projection cen-
              ter  [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
              PROJ_LENGTH_UNIT) unless -F is used, in which case  the  offsets
              are in meters.

       -Dc|i|p
              Temporarily  override PROJ_LENGTH_UNIT and use c (cm), i (inch),
              or p (points) instead. Cannot be used with -F.

       -E[datum]
              Convert from geodetic (lon, lat, height) to Earth Centered Earth
              Fixed (ECEF) (x,y,z) coordinates (add -I for the inverse conver-
              sion). 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[unit]
              Force 1:1 scaling, i.e., output (or input, see -I) data  are  in
              actual  projected  meters.  To  specify  other units, append the
              desired unit (see UNITS). Without -F, the output (or input,  see
              -I) are in the units specified by PROJ_LENGTH_UNIT (but see -D).

       -G[lon0/lat0][+a][+i][+u[+|-]unit][+v]
              Calculate distances along track or to the optional  fixed  point
              set  with  -Glon0/lat0.  Append  the  distance unit with +u (see
              UNITS for available  units  and  how  distances  are  computed),
              including  c  (Cartesian  distance using input coordinates) or C
              (Cartesian distance using projected  coordinates).  The  C  unit
              requires  -R  and  -J to be set. When no fixed point is given we
              calculate accumulative distances [or by  adding  +a]  along  the
              track defined by the input points. Append +i to obtain incremen-
              tal distances between successive points, or  append  both  modi-
              fiers  to  get both distance measurements. Alternatively, append
              +v to obtain a variable 2nd point (lon0/lat0) via columns 3-4 in
              the input file.

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

       -Lline.xy[+u[+|-]unit][+p]
              Determine the shortest distance from the input  data  points  to
              the  line(s)  given  in the ASCII multisegment 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 (see UNITS for available units and how distances  are  com-
              puted), including c (Cartesian distance using input coordinates)
              or C (Cartesian distance using  projected  coordinates).  The  C
              unit  requires -R and -J to be set. Finally, append +p to report
              the line segment id and the fractional point number  instead  of
              lon/lat of the nearest point.

       -N[a|c|g|m]
              Convert  from  geodetic  latitudes (using the current ellipsoid;
              see PROJ_ELLIPSOID) to one of four different auxiliary latitudes
              (longitudes  are  unaffected).  Choose from authalic, conformal,
              geocentric, and meridional latitudes  [geocentric].  Use  -I  to
              convert from auxiliary latitudes to geodetic latitudes.

       -Q[d|e 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[h]from[/to]
              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 PROJ_ELLIPSOID setting is  correct  for  your
              case.

       -V[level] (more a|)
              Select verbosity level [c].

       -W[w|h]
              Prints  map width and height on standard output.  No input files
              are read.  To only output the width or the height, append  w  or
              h, respectively.  The units of the dimensions may be changed via
              -D.

       -Z[speed][+a][+i][+f][+tepoch]
              Calculate travel times along track as specified with -G.  Append
              a  constant  speed unit; if missing we expect to read a variable
              speed from column 3.  The speed is expected to be  in  the  dis-
              tance  units  set  via  -G per time unit controlled by TIME_UNIT
              [m/s].  Append +i to output  incremental  travel  times  between
              successive  points,  +a  to  obtain accumulated travel times, or
              both to get both kinds of time information.  Use  +f  to  format
              the  accumulated (elapsed) travel time according to the ISO 8601
              convention.  As for the number of  decimals  used  to  represent
              seconds we consult the FORMAT_CLOCK_OUT setting. Finally, append
              +tepoch to report absolute times (ETA) for successive points.

       -bi[ncols][t] (more a|)
              Select native binary input. [Default is 2 input columns].

       -bo[ncols][type] (more a|)
              Select native binary output. [Default is same as input].

       -d[i|o]nodata (more a|)
              Replace input columns that equal nodata  with  NaN  and  do  the
              reverse on output.

       -e[~]^<i>apattern^<i>a | -e[~]/regexp/[i] (more a|)
              Only accept data records that match the given pattern.

       -f[i|o]colinfo (more a|)
              Specify data types of input and/or output columns.

       -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more a|)
              Determine data gaps and line breaks.

       -h[i|o][n][+c][+d][+rremark][+rtitle] (more a|)
              Skip or produce header record(s).

       -icols[+l][+sscale][+ooffset][,^<i>a|] (more a|)
              Select input columns and transformations (0 is first column).

       -ocols[,a|] (more a|)
              Select output columns (0 is first column).

       -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more a|)
              Select perspective view.

       -s[cols][a|r] (more a|)
              Set handling of NaN records.

       -:[i|o] (more a|)
              Swap 1st and 2nd column on input and/or output.

       -^ or just -
              Print  a  short  message  about  the syntax of the command, then
              exits (NOTE: on Windows just use -).

       -+ or just +
              Print an extensive usage (help) message, including the  explana-
              tion  of  any  module-specific  option  (but  not the GMT common
              options), then exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation
              of all options, then exits.


UNITS

       For  map distance unit, append unit d for arc degree, m for arc minute,
       and s for arc second, or e for meter [Default], f for foot, k for km, M
       for  statute  mile,  n  for nautical mile, and u for US survey foot. By
       default we compute such distances using a spherical approximation  with
       great  circles.  Prepend - to a distance (or the unit is no distance is
       given) to perform aFlat Eartha calculations (quicker but less accurate)
       or  prepend  +  to perform exact geodesic calculations (slower but more
       accurate).


ASCII FORMAT PRECISION

       The ASCII output formats of numerical data are controlled by parameters
       in  your  gmt.conf file. Longitude and latitude are formatted according
       to  FORMAT_GEO_OUT,  absolute  time  is  under  the  control  of   FOR-
       MAT_DATE_OUT  and FORMAT_CLOCK_OUT, whereas general floating point val-
       ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for-
       mat  in effect can lead to loss of precision in ASCII 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 FORMAT_FLOAT_OUT  set-
       ting.


EXAMPLES

       To  convert  UTM coordinates in meters to geographic locations, given a
       file utm.txt and knowing the UTM zone (and zone or hemisphere), try

              gmt mapproject utm.txt -Ju+11/1:1 -C -I -F

       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

              gmt mapproject lonlatfile -R20/50/12/25 -Jm0.5c > xyfile

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

              gmt mapproject tracks.* -R-80/-70/20/40 -Jt-75/1:500000 -: -S -Di -bo -bi2 > 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

              gmt mapproject old.dat -Th131 > 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 multisegment ASCII
       file coastline.xy, run

              gmt mapproject quakes.dat -Lcoastline.xy+uk > quake_dist.dat

       Given a file with longitude and latitude, compute both incremental  and
       accumulated  distance along track, and estimate travel times assuming a
       fixed speed of 12 knots.  We do this with

              gmt mapproject track.txt -Gn+a+i -Z12+a --TIME_UNIT=h > elapsed_time.txt

       where TIME_UNIT is set to hour so that the speed is measured in nm (set
       by  -G) per hour (set by TIME_UNIT).  Elapsed times will be reported in
       hours (unless +f is added to -Z for ISO elapsed time).


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)  val-
       ues they are mapped onto. Use these values when setting up for digitiz-
       ing 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 projection, 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 Con-
       formal 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 PROJ_ELLIPSOID).
       The  user  needs  to be aware of a few potential pitfalls: (1) For some
       projections, such as Transverse Mercator, Albers, and Lambertas confor-
       mal  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 for-
       mulae are used as follows: (a) Transverse Mercator: When all points are
       within  10 degrees of central meridian, (b) Conic projections when lon-
       gitudinal 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, Snyderas  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 mis-
       matches of tens to hundreds of  meters.  (3)  Finally,  be  aware  that
       PROJ_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.


OUTPUT ORDER

       The  production order for the geodetic and temporal columns produced by
       the options -A, -G, -L, and -Z is fixed and  follows  the  alphabetical
       order  of  the  options.   Hence, the order these options appear on the
       command line is irrelevant.  The actual output order can of  course  be
       modulated via -o.


SEE ALSO

       gmt(1), gmt.conf(5), gmtvector(1), project(1)


REFERENCES

       Bomford, G., 1952, Geodesy, Oxford U. Press.

       Snyder,  J. P., 1987, Map Projections - A Working Manual, U.S. Geologi-
       cal Survey Prof. Paper 1395.

       Vanicek, P. and Krakiwsky, E, 1982, Geodesy - The Concepts,  North-Hol-
       land Publ., ISBN: 0 444 86149 1.


COPYRIGHT

       2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe



5.4.2                            Jun 24, 2017                    mapproject(1)

gmt5 5.4.2 - Generated Thu Jun 29 14:05:35 CDT 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.