{smcl}
{* *! version 1.0.0  31jan2017}{...}
{cmd:help geo2xy_mercator}
{hline}

{title:Title}

{phang}
{cmd:geo2xy} {hline 2} Convert latitude and longitude to cartesian (x,y) coordinates


{title:Map projection}

{phang}
Mercator projection - ellipsoid model


{title:Syntax}

{p 8 16 2}
{cmd:geo2xy}
{it:lat_var lon_var} 
{ifin} 
{cmd:,}
{c -(}{opt gen:erate(y_lat x_lon)}{c |}{opt replace}{c )-}
[ 
{opt proj:ection}{cmd:(}{opt mercator}
[,{help geo2xy##proj_name:proj_opts}]{cmd:)}
{opt ti:ssot} ]


{synoptset 42 tabbed}{...}
{synopthdr}
{synoptline}
{p2coldent :* {opt gen:erate(y_lat x_lon)}}New variable names for the projected coordinates (note the order!){p_end}
{p2coldent :* {opt replace}}Replace the values in {it:lat_var lon_var} with the projected coordinates{p_end}
{synopt :{opt proj:ection(mercator [,proj_opts])}}Specifies the projection and, optionally, projection parameters{p_end}
{synopt :{opt ti:ssot}}Append Tissot's indicatrices (grid of circles){p_end}
{synoptline}
{pstd}* Either {opt gen:erate(y_lat x_lon)} or {opt replace} is required.
{p2colreset}


{synoptset 15 tabbed}{...}
{synopthdr :proj_opts}
{synoptline}
{synopt :{it:a}}semi-major axis of reference ellipsoid (default is 6378137){p_end}
{synopt :{it:f}}inverse flattening of reference ellipsoid (default is 298.257223563){p_end}
{synopt :{it:lon0}}projection's origin - longitude (default is mid-longitude){p_end}
{synoptline}
{p2colreset}

{pstd}
Projection parameters are optional. To specify some, 
all parameters must be specified and appear in the following order

{p 8 16 2}
{opt proj:ection}{hi:(mercator} {it:, a f lon0})


{pstd}
{ul:{hi:Description}}

{pstd}
The Mercator projection represents lines of constant bearing as straight 
lines on the map, making it particularly useful for navigation.
Longitudes and latitudes are projected as straight lines,
perpendicular to each other. To compensate for the fact that
longitudes are not parallel and converge at the poles, latitudes are stretched
to match the local stretch in longitude.
As longitudes converge towards the poles, the amount of stretch needed for
latitudes to maintain proportions becomes infinite. 

{pstd}
With a Mercator projection, circles retain their shapes over small areas but
their size increases towards the pole.


{pstd}
{ul:{hi:Spheroid and (x,y) coordinates units}}

{pstd}
This projection assumes that the geographic latitude and longitude
describe locations on an ellipsoid. If parameters are not
specified, {bf:geo2xy} uses the reference ellipsoid of the WGS 84 datum,
the same that is used in GPS devices.
The projected coordinates reflect the distance in meters from the
projection's origin.
With a Mercator projection, distances are accurate only on the equator.


{pstd}
{ul:{hi:Examples}}

{pstd}
These examples require {cmd:geo2xy}'s ancillary datasets
in the current directory. Click 
{stata `"net get geo2xy, from("http://fmwww.bc.edu/repec/bocode/g")"':here}
to download them.

{pstd}
The following example creates a map of the 48 conterminous states.
The shapefile's {cmd:_ID} for Alaska, Puerto Rico, Hawaii are 14, 39, 42 respectively.

{space 8}{hline 27} {it:example do-file content} {hline 27}
{cmd}{...}
{* example_start - mercator_us}{...}
	use "geo2xy_us_coor.dta", clear
	drop if inlist(_ID, 14, 39, 42) // Alaska, Puerto Rico, Hawaii

	geo2xy _Y _X, gen(ylat xlon) project(mercator)
	
	// show the projection details and compute the plot's height
	return list
	local yheight = 6 * `r(aspect)'
	
	line ylat xlon, lwidth(vthin) lcolor(gray) cmissing(n) ///
		xsize(6) ysize(`yheight') ///
		ylabel(minmax, nogrid) yscale(off) ///
		xlabel(minmax, nogrid) xscale(off) ///
		plotregion(margin(small)) graphregion(margin(small)) ///
		legend(off) name(mercator_us, replace)
			
	summarize
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run mercator_us using geo2xy_mercator.hlp, requires("geo2xy_us_coor.dta") preserve:click to run})}

{pstd}
Use the {opt tissot} option to illustrate the distortions created by
this projection. 
The {opt tissot} polygons generated by {cmd:geo2xy} do not have a feature
identifier (e.g. {cmd:_ID} is missing).

{space 8}{hline 27} {it:example do-file content} {hline 27}
{cmd}{...}
{* example_start - mercator_tissot}{...}
	use "geo2xy_us_coor.dta", clear
	drop if inlist(_ID, 14, 39, 42) // Alaska, Puerto Rico, Hawaii

	geo2xy _Y _X, gen(ylat xlon) project(mercator) tissot
	
	// show the projection details and compute the plot's height
	return list
	local yheight = 6 * `r(aspect)'
	
	line ylat xlon if !mi(_ID), lwidth(vthin) lcolor(gray) cmissing(n) ///
	|| ///
	line ylat xlon if mi(_ID), lwidth(vthin) lcolor(eltblue) cmissing(n) ///
		xsize(6) ysize(`yheight') ///
		ylabel(minmax, nogrid) yscale(off) ///
		xlabel(minmax, nogrid) xscale(off) ///
		plotregion(margin(small)) graphregion(margin(small)) ///
		legend(off) name(mercator_tissot, replace)
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run mercator_tissot using geo2xy_mercator.hlp, requires("geo2xy_us_coor.dta") preserve:click to run})}


{pstd}
{ul:{hi:Certification}}

{pstd}
The equations for this projection are from page 44 of Snyder (1987).
The numerical example at pp. 267 is used to certify {bf:geo2xy}'s
implementation:

{space 8}{hline 27} {it:example do-file content} {hline 27}
{cmd}{...}
{* example_start - certify}{...}
	clear
	input double(_Y _X)
	35 -75
	end
	
	// compute the inverse flattening from e = .0822719, see Snyder p. 13
	local f = 1 / (1 - (1-.0822719^2)^.5)

	geo2xy _Y _X, gen(y x) proj(mercator, 6378206.4 `f' -180)
	return list
	list
	
	assert string(x,"%10.1f") ==  "11688673.7"
	assert string(y,"%10.1f") ==  "4139145.6"
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run certify using geo2xy_mercator.hlp, preserve:click to run})}


{title:References and further reading}

{pstd}
National Imagery and Mapping Agency,
{it}
Department of Defense World Geodetic System 1984 - 
Its Definition and Relationships with Local Geodetic Systems{sf},
NIMA Technical Report 8350.2, Third Edition, 2000.
[{it:{browse "http://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf":download}}]

{pstd}
Snyder, John P., 
{it:Map projections: A working manual}.
U.S. Geological Survey Professional Paper 1395, 1987.
[{it:{browse "http://pubs.er.usgs.gov/publication/pp1395":download}}].

{pstd}
Wikipedia, {it:{browse "https://en.wikipedia.org/wiki/Mercator_projection":Mercator projection}}.
Web page, reviewed 1/31/2017.

{pstd}
Wikipedia, {it:{browse "http://en.wikipedia.org/wiki/Web_Mercator":Web Mercator}}.
Web page, reviewed 1/31/2017.


{title:Author}

{pstd}Robert Picard{p_end}
{pstd}picard@netbox.com{p_end}