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

mapprojectinfiles-Jparameters-Rwest/east/south/north[r] [-Ab|B|f|Flon0/lat0] [-C[dx/dy] ] [-Dc|i|m|p] [-E[datum] ] [-F[k|m|n|i|c|p] ] [-G[x0/y0][/unit] ] [-H[nrec] ] [-I] [-Lline.xy[/unit]][-M[flag]][-Q[d|e][-S][-T[h]from[/to]][-V][-:][-bi[s][n]][-bo[s][n]][-f[i|o]colinfo]

mapprojectreads (longitude, latitude) positions frominfiles[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 com- pute (longitude, latitude) values doing the inverse transformation. This can be used to transform linear (x,y) points obtained by digitiz- ing 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. No space between the option flag and the associated arguments. Use upper case for the option flags and lower case for modifiers.infilesData file(s) to be transformed. If not given, standard input is read.-JSelects the map projection. The following character determines the projection. If the character is upper case then the argu- ment(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 appendingc,i, ormto the scale/width values. Appendh,+, or-to the givenwidthif you instead want to set map height, the maximum dimen- sion, or the minimum dimension, respectively [Default iswfor width]. Choose one of the following projections (TheEorCafter projection names stands for Equal-Area and Conformal, respectively):CYLINDRICALPROJECTIONS:-Jclon0/lat0/scaleor-JClon0/lat0/width(Cassini). Give projection center and scale (1:xxxx or UNIT/degree).-Jjlon0/scaleor-JJlon0/width(Miller Cylindrical Projection). Give the central meridian and scale (1:xxxx or UNIT/degree).-Jmparameters(Mercator[C]). Specify one of:-Jmscaleor-JMwidthGive scale along equator (1:xxxx or UNIT/degree).-Jmlon0/lat0/scaleor-JMlon0/lat0/widthGive central meridian, standard latitude and scale along parallel (1:xxxx or UNIT/degree).-Joparameters(Oblique Mercator[C]). Specify one of:-Joalon0/lat0/azimuth/scaleor-JOalon0/lat0/azimuth/widthSet projection center, azimuth of oblique equator, and scale.-Joblon0/lat0/lon1/lat1/scaleor-JOblon0/lat0/lon1/lat1/scaleSet projection center, another point on the oblique equator, and scale.-Joclon0/lat0/lonp/latp/scaleor-JOclon0/lat0/lonp/latp/scaleSet projection center, pole of oblique projec- tion, and scale. Give scale along oblique equator (1:xxxx or UNIT/degree).-Jqlon0/scaleor-JQlon0/width(Equidistant Cylindrical Projec- tion (Plate Carree)). Give the central meridian and scale (1:xxxx or UNIT/degree).-Jtparameters(Transverse Mercator[C]). Specify one of:-Jtlon0/scaleor-JTlon0/widthGive the central meridian and scale (1:xxxx or UNIT/degree).-Jtlon0/lat0/scaleor-JTlon0/lat0/widthGive projection center and scale (1:xxxx or UNIT/degree).-Juzone/scaleor-JUzone/width(UTM - Universal Transverse Mer- cator[C]). Give the zone number (1-60) and scale (1:xxxx or UNIT/degree). zones: prepend - or + to enforce southern or northern hemisphere conventions [northern if south > 0].-Jylon0/lats/scaleor-JYlon0/lats/width(Basic Cylindrical Pro- jections[E]). Give the central meridian, standard parallel, and scale (1:xxxx or UNIT/degree). The standard parallel is typically one of these (but can be any value): 45 - The Peters projection 37.4 - The Trystan Edwards projection 30 - The Behrman projection 0 - The Lambert projectionAZIMUTHALPROJECTIONS:[Except for polar aspects, -Rw/e/s/n will be reset to -Rg. Use -R<...>r for smaller regions]-Jalon0/lat0/scaleor-JAlon0/lat0/width(Lambert[E]).lon0/lat0specifies the projection center. Give scale as 1:xxxx orradius/lat, whereradiusis dis- tance in UNIT from origin to the oblique latitudelat.-Jelon0/lat0/scaleor-JElon0/lat0/width(Equidistant).lon0/lat0specifies the projection center. Give scale as 1:xxxx orradius/lat, whereradiusis dis- tance in UNIT from origin to the oblique latitudelat.-Jflon0/lat0/horizon/scaleor-JFlon0/lat0/horizon/width(Gnomonic).lon0/lat0specifies the projection center.horizonspecifies the max distance from projection cen- ter (in degrees, < 90). Give scale as 1:xxxx orradius/lat, whereradiusis dis- tance in UNIT from origin to the oblique latitudelat.-Jglon0/lat0/scaleor-JGlon0/lat0/width(Orthographic).lon0/lat0specifies the projection center. Give scale as 1:xxxx orradius/lat, whereradiusis dis- tance in UNIT from origin to the oblique latitudelat.-Jslon0/lat0/scaleor-JSlon0/lat0/width(General Stereographic[C]).lon0/lat0specifies the projection center. Give scale as 1:xxxx (true at pole) orslat/1:xxxx (true at standard parallelslat) orradius/lat(radiusin UNIT from origin to the oblique latitudelat).CONICPROJECTIONS:-Jblon0/lat0/lat1/lat2/scaleor-JBlon0/lat0/lat1/lat2/width(Albers[E]). Give projection center, two standard parallels, and scale (1:xxxx or UNIT/degree).-Jdlon0/lat0/lat1/lat2/scaleor-JDlon0/lat0/lat1/lat2/width(Equidistant) Give projection center, two standard parallels, and scale (1:xxxx or UNIT/degree).-Jllon0/lat0/lat1/lat2/scaleor-JLlon0/lat0/lat1/lat2/width(Lambert[C]) Give origin, 2 standard parallels, and scale along these (1:xxxx or UNIT/degree).MISCELLANEOUSPROJECTIONS:-Jhlon0/scaleor-JHlon0/width(Hammer[E]). Give the central meridian and scale along equator (1:xxxx or UNIT/degree).-Jilon0/scaleor-JIlon0/width(Sinusoidal[E]). Give the central meridian and scale along equator (1:xxxx or UNIT/degree).-Jk[f|s]lon0/scaleor-JK[f|s]lon0/width(Eckert IV (f) and VI (s)[E]). Give the central meridian and scale along equator (1:xxxx or UNIT/degree).-Jnlon0/scaleor-JNlon0/width(Robinson). Give the central meridian and scale along equator (1:xxxx or UNIT/degree).-Jrlon0/scale-JRlon0/width(Winkel Tripel). Give the central meridian and scale along equator (1:xxxx or UNIT/degree).-Jvlon0/scaleor-JVlon0/width(Van der Grinten). Give the central meridian and scale along equator (1:xxxx or UNIT/degree).-Jwlon0/scaleor-JWlon0/width(Mollweide[E]). Give the central meridian and scale along equator (1:xxxx or UNIT/degree).NON-GEOGRAPHICALPROJECTIONS:-Jp[a]scale[/origin] or-JP[a]width[/origin] (Linear projection for polar (theta,r) coordinates, optionally insertaafter-Jp[ or-JP] for azimuths CW from North instead of directions CCW from East [default], optionally append /originin degrees to indicate an angular offset [0]). Give scale in UNIT/r-unit.-Jxx-scale[/y-scale] or-JXwidth[/height]scale[orwidth] can be any of the following 3 types:-Jxscale- Regular linear scaling.-Jxscalel- Take log10 of values before scaling.-Jxscaleppower- Raise values topowerbefore scaling.-JxscaleT|t- Time axis.Tindicates input coordinates are absolute time whiletmeans they are time relative toTIME_EPOCH. Givex-scalein UNIT/x-unit andy-scalein UNIT/y-unit. (y-scale=x-scaleif not specified separately). Use negative scale(s) to reverse the direction of an axis (e.g., to have y be positive down). Append a singledif data are geographical coordinates in degrees. Default axis lengths (see gmtdefaults) can be invoked using-JXh(for landscape);-JXv(for portrait) will swap the x- and y-axis lengths. TheGMTdefault unit for this installation is UNIT. However, you may change this by editing your .gmtde- faults4 file(s) (run gmtdefaults to create one if you don’t have it).’ The ellipsoid used in the map projections is user-defin- able by editing the .gmtdefaults4 file in your home directory. 63 commonly used ellipsoids and a spheroid are currently sup- ported, and users may also specify their own ellipsoid parame- ters (see man gmtdefaults for more details).GMTdefault is WGS-84. Several GMT parameters can affect the projection: ELLIP- SOID, INTERPOLANT, MAP_SCALE_FACTOR, and MEASURE_UNIT; see thegmtdefaultsman page for details.-Rxmin,xmax,ymin,andymaxspecify the Region of interest. For geographic regions, these limits correspond towest,east,south,andnorthand you may specify them in decimal degrees or in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Appendrif lower left and upper right map coordinates are given instead of wesn. The two shorthands-Rg-Rdstand for global domain (0/360 or -180/+180 in longitude respectively, with -90/+90 in latitude). For calendar time coordinates you may either give relative time (relative to the selected TIME_EPOCH and in the selected TIME_UNIT; appendtto-JX|x), or absolute time of the form [date]T[clock] (appendTto-JX|x). At least one ofdateandclockmust be present; theTis always required. Thedatestring must be of the form [-]yyyy[-mm[-dd]] (Gregorian calendar) or yyyy[-Www[-d]] (ISO week calendar), while theclockstring must be of the form hh:mm:ss[.xxx]. The use of delimiters and their type and positions must be as indicated (however, input/output and plotting formats are flexible).

infile(s)input file(s) with 2 or more columns. If no file(s) is given,mapprojectwill read the standard input.-A-Afcalculates the (forward) azimuth from fixed pointlon/latto each data point. Use-Abto get backazimuth from data points to fixed point. Upper caseForBwill convert from geodetic to geocentric latitudes and estimate azimuth of geodesics (assuming the current ellipsoid is not a sphere).-CSet 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-Iis 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_UNTI) unless-Fis used, in which case the offsets are in meters.-DTemporarily override MEASURE_UNIT and usec(cm),i(inch),m(meter), orp(points) instead. Cannot be used with-F.-EConvert from geodetic (lon, lat, height) to Earth Centered Earth Fixed (ECEF) (x,y,z) coordinates (add-Ifor the inverse conver- sion). Append datum ID (see-Qd) or giveellipsoid:dx,dy,dzwhereellipsoidmay be an ellipsoid ID (see-Qe) or given asa,1/f. Ifdatumis - or not given we assume WGS-84.-FForce 1:1 scaling, i.e., output (or input, see-I) data are in actual projected meters. To specify other units, appendk(km),m(mile),n(nautical mile),i(inch),c(cm), orp(points). Without-F, the output (or input, see-I) are in the units spec- ified by MEASURE_UNIT (but see-D).-GCalculate distances along track OR to the optional point set with-Gx0/y0. Append the distance unit; choose amonge(m),k(km),m(mile),n(nautical mile),d(spherical degree),c(Cartesian distance using input coordinates) orC(Cartesian distance using projected coordinates). The last unit requires-Rand-Jto be set. Upper caseE,K,M,N, orDwill use exact methods for geodesic distances (Rudoe’s method for distances in length units and emplying geocentric latitudes in degree calcu- lations, assuming the current ellipsoid is not a sphere).-HInput file(s) has Header record(s). Number of header records can be changed by editing your .gmtdefaults4 file. If used,GMTdefault is 1 header record. Use-Hiif only input data should have header records [Default will write out header records if the input data have them].-IDo the Inverse transformation, i.e. get (longitude,latitude) from (x,y) data.-LDetermine the shortest distance from the input data points to the line(s) given in the ASCII multi-segment fileline.xy. Append the distance unit; choose amonge(m),k(km),m(mile),n(nautical mile),d(spherical degree),c(Cartesian distance using input coordinates) orC(Cartesian distance using pro- jected coordinates). The last unit requires-Rand-Jto be set. A spherical approximation is used for geographic data.-MMultiple segment file(s). Segments are separated by a special record. For ASCII files the first character must beflag[Default is ’>’]. For binary files all fields must be NaN and-bo[s]nmust set the number of output columns explicitly.-QList all projection parameters. To only list datums, use-Qd. To only list ellipsoids, use-Qe.-SSuppress points that fall outside the region.-TCoordinate conversions between datumsfromandto. Use-Thif 3rd input column has height above ellipsoid [Default assumes height = 0, i.e., on the ellipsoid]. Specify datums using the ID (see-Qd) or giveellipsoid:dx,dy,dz, whereellipsoidmay be an ellipsoid ID (see-Qe) or given asa,1/f. Ifdatumis - or not given we use WGS-84.-Tmay be used in conjunction with-R-Jto change the datum before coordinate projection (add-Ito apply the datum conversion after the inverse projection). Make sure that theELLIPSOIDsetting is correct for your case.-VSelects 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)]. Appendito select input only oroto select output only. [Default affects both].-biSelects binary input. Appendsfor single precision [Default is double]. Appendnfor the number of columns in the binary file(s). [Default is 2 input columns].-boSelects binary output. Appendsfor single precision [Default is double]. Appendnfor the number of columns in the binary file(s).-fSpecial formatting of input and output columns (time or geo- graphical data) Specifyi(nput) oro(utput) [Default is both input and output]. Give one or more columns (or column ranges) separated by commas. AppendT(Absolute calendar time),t(time relative to chosen TIME_EPOCH),x(longitude),y(latitude),g(geographic coordinate), orf(floating point) to each column or column range item.

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, runmapprojectlonlatfile-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, runmapprojecttracks.*-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, runmapprojectold.dat-Th131 > new.dat To compute the closest distance (in km) between each point in the input file quakes.dat and the line seg- ments given in the multi-segment ASCII file coastline.xy, runmapprojectquakes.dat-Lcoastline.xy/k > quake_dist.dat

The rectangular input region set with-Rwill in general be mapped into a non-rectangular grid. Unless-Cis 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 throughmapprojectusing 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, useawkto scale and shift the (x,y) values before transforming.

GMTwill use ellipsoidal formulae if they are implemented and the user have selected an ellipsoid as the reference shape (seegmtdefaults). The user needs to be aware of a few potential pitfalls: (1) For some projections, such as Transverse Mercator, Albers, and Lamberts 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 thatGMTgives 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 whatGMTuses), 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.

gmtdefaults(l),gmt(l),project(l)

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. GMT4.0 1 Oct 2004 MAPPROJECT(l)

Man(1) output converted with man2html