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

{title:Title}

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


{title:Map projection}

{phang}
Mercator projection - Spherical 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_sphere}
[,{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_sphere [,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:lon0}}projection's origin - longitude (default is mid-longitude){p_end}
{synoptline}
{p2colreset}

{title: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}
This is exactly the same projection as the default
{help geo2xy_proj##web_mercator:Web Mercator} projection
but with no truncation of y-coordinates near the poles,
no Google tiles, a different projection origin, and a
different scaling of the (x,y) coordinates.

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


{title:Spheroid and (x,y) coordinates units}

{pstd}
This projection assumes that the geographic latitude and longitude
describe locations on a sphere.
The computations are performed on a unit sphere (radius of 1)
and projected coordinates are returned without further scaling.
If you want the units to reflect distances on Earth, you need to
multiply the coordinates by an appropriate radius 
(e.g. 6371 km, 3958.76 miles, 20,902,231 feet, etc.).
With a Mercator projection, distances are accurate only on the equator.


{title: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_sphere_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_sphere)
	
	// 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_sphere_us, replace)
			
	summarize
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run mercator_sphere_us using geo2xy_mercator_sphere.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_sphere_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_sphere) 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_sphere_tissot, replace)
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run mercator_sphere_tissot using geo2xy_mercator_sphere.hlp, requires("geo2xy_us_coor.dta") preserve:click to run})}


{title:Certification}

{pstd}
The equations for this projection are from page 41 of Snyder (1987).
The numerical example at pp. 266-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

	geo2xy _Y _X, gen(y x) proj(mercator_sphere, -180)
	return list
	list
	
	assert string(x,"%10.7f") ==  "1.8325957"
	assert string(y,"%10.7f") ==  "0.6528366"
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run certify using geo2xy_mercator_sphere.hlp, preserve:click to run})}


{title:References and further reading}

{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}