1[comment {-*- tcl -*- doctools manpage}]
2[manpage_begin mapproj n 0.1]
3[keywords geodesy]
4[keywords map]
5[keywords projection]
6[copyright {2007 Kevin B. Kenny <kennykb@acm.org>}]
7[moddesc {Tcl Library}]
8[titledesc {Map projection routines}]
9[require Tcl [opt 8.4]]
10[require math::interpolate [opt 1.0]]
11[require math::special [opt 0.2.1]]
12[require mapproj [opt 1.0]]
13[description]
14The [package mapproj] package provides a set of procedures for
15converting between world co-ordinates (latitude and longitude) and map
16co-ordinates on a number of different map projections.
17
18[section Commands]
19
20The following commands convert between world co-ordinates and
21map co-ordinates:
22
23[list_begin definitions]
24
25[call [cmd ::mapproj::toPlateCarree] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
26Converts to the [emph "plate carr\u00e9e"] (cylindrical equidistant)
27projection.
28[call [cmd ::mapproj::fromPlateCarree] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
29Converts from the [emph "plate carr\u00e9e"] (cylindrical equidistant)
30projection.
31[call [cmd ::mapproj::toCylindricalEqualArea] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
32Converts to the cylindrical equal-area projection.
33[call [cmd ::mapproj::fromCylindricalEqualArea] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
34Converts from the cylindrical equal-area projection.
35[call [cmd ::mapproj::toMercator] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
36Converts to the Mercator (cylindrical conformal) projection.
37[call [cmd ::mapproj::fromMercator] [arg lambda_0] [arg phi_0]  [arg x] [arg y]]
38Converts from the Mercator (cylindrical conformal) projection.
39[call [cmd ::mapproj::toMillerCylindrical] [arg lambda_0] [arg lambda] [arg phi]]
40Converts to the Miller Cylindrical projection.
41[call [cmd ::mapproj::fromMillerCylindrical] [arg lambda_0] [arg x] [arg y]]
42Converts from the Miller Cylindrical projection.
43[call [cmd ::mapproj::toSinusoidal] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
44Converts to the sinusoidal (Sanson-Flamsteed) projection.
45projection.
46[call [cmd ::mapproj::fromSinusoidal] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
47Converts from the sinusoidal (Sanson-Flamsteed) projection.
48projection.
49[call [cmd ::mapproj::toMollweide] [arg lambda_0] [arg lambda] [arg phi]]
50Converts to the Mollweide projection.
51[call [cmd ::mapproj::fromMollweide] [arg lambda_0] [arg x] [arg y]]
52Converts from the Mollweide projection.
53[call [cmd ::mapproj::toEckertIV] [arg lambda_0] [arg lambda] [arg phi]]
54Converts to the Eckert IV projection.
55[call [cmd ::mapproj::fromEckertIV] [arg lambda_0] [arg x] [arg y]]
56Converts from the Eckert IV projection.
57[call [cmd ::mapproj::toEckertVI] [arg lambda_0] [arg lambda] [arg phi]]
58Converts to the Eckert VI projection.
59[call [cmd ::mapproj::fromEckertVI] [arg lambda_0] [arg x] [arg y]]
60Converts from the Eckert VI projection.
61[call [cmd ::mapproj::toRobinson] [arg lambda_0] [arg lambda] [arg phi]]
62Converts to the Robinson projection.
63[call [cmd ::mapproj::fromRobinson] [arg lambda_0] [arg x] [arg y]]
64Converts from the Robinson projection.
65[call [cmd ::mapproj::toCassini] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
66Converts to the Cassini (transverse cylindrical equidistant)
67projection.
68[call [cmd ::mapproj::fromCassini] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
69Converts from the Cassini (transverse cylindrical equidistant)
70projection.
71[call [cmd ::mapproj::toPeirceQuincuncial] [arg lambda_0] [arg lambda] [arg phi]]
72Converts to the Peirce Quincuncial Projection.
73[call [cmd ::mapproj::fromPeirceQuincuncial] [arg lambda_0] [arg x] [arg y]]
74Converts from the Peirce Quincuncial Projection.
75[call [cmd ::mapproj::toOrthographic] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
76Converts to the orthographic projection.
77[call [cmd ::mapproj::fromOrthographic] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
78Converts from the orthographic projection.
79[call [cmd ::mapproj::toStereographic] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
80Converts to the stereographic (azimuthal conformal) projection.
81[call [cmd ::mapproj::fromStereographic] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
82Converts from the stereographic (azimuthal conformal) projection.
83[call [cmd ::mapproj::toGnomonic] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
84Converts to the gnomonic projection.
85[call [cmd ::mapproj::fromGnomonic] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
86Converts from the gnomonic projection.
87[call [cmd ::mapproj::toAzimuthalEquidistant] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
88Converts to the azimuthal equidistant projection.
89[call [cmd ::mapproj::fromAzimuthalEquidistant] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
90Converts from the azimuthal equidistant projection.
91[call [cmd ::mapproj::toLambertAzimuthalEqualArea] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
92Converts to the Lambert azimuthal equal-area projection.
93[call [cmd ::mapproj::fromLambertAzimuthalEqualArea] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
94Converts from the Lambert azimuthal equal-area projection.
95[call [cmd ::mapproj::toHammer] [arg lambda_0] [arg lambda] [arg phi]]
96Converts to the Hammer projection.
97[call [cmd ::mapproj::fromHammer] [arg lambda_0] [arg x] [arg y]]
98Converts from the Hammer projection.
99[call [cmd ::mapproj::toConicEquidistant] [arg lambda_0] [arg phi_0] [arg phi_1] [arg phi_2] [arg lambda] [arg phi]]
100Converts to the conic equidistant projection.
101[call [cmd ::mapproj::fromConicEquidistant] [arg lambda_0] [arg phi_0] [arg phi_1] [arg phi_2] [arg x] [arg y]]
102Converts from the conic equidistant projection.
103[call [cmd ::mapproj::toAlbersEqualAreaConic] [arg lambda_0] [arg phi_0] [arg phi_1] [arg phi_2] [arg lambda] [arg phi]]
104Converts to the Albers equal-area conic projection.
105[call [cmd ::mapproj::fromAlbersEqualAreaConic] [arg lambda_0] [arg phi_0] [arg phi_1] [arg phi_2] [arg x] [arg y]]
106Converts from the Albers equal-area conic projection.
107[call [cmd ::mapproj::toLambertConformalConic] [arg lambda_0] [arg phi_0] [arg phi_1] [arg phi_2] [arg lambda] [arg phi]]
108Converts to the Lambert conformal conic projection.
109[call [cmd ::mapproj::fromLambertConformalConic] [arg lambda_0] [arg phi_0] [arg phi_1] [arg phi_2] [arg x] [arg y]]
110Converts from the Lambert conformal conic projection.
111
112[list_end]
113
114Among the cylindrical equal-area projections, there are a number of
115choices of standard parallels that have names:
116
117[list_begin definitions]
118[call [cmd ::mapproj::toLambertCylindricalEqualArea] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
119Converts to the Lambert cylindrical equal area projection. (standard parallel
120is the Equator.)
121[call [cmd ::mapproj::fromLambertCylindricalEqualArea] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
122Converts from the Lambert cylindrical equal area projection. (standard parallel
123is the Equator.)
124[call [cmd ::mapproj::toBehrmann] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
125Converts to the Behrmann cylindrical equal area projection. (standard parallels
126are 30 degrees North and South)
127[call [cmd ::mapproj::fromBehrmann] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
128Converts from the Behrmann cylindrical equal area projection. (standard parallels
129are 30 degrees North and South.)
130[call [cmd ::mapproj::toTrystanEdwards] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
131Converts to the Trystan Edwards cylindrical equal area projection. (standard parallels
132are 37.4 degrees North and South)
133[call [cmd ::mapproj::fromTrystanEdwards] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
134Converts from the Trystan Edwards cylindrical equal area projection. (standard parallels
135are 37.4 degrees North and South.)
136[call [cmd ::mapproj::toHoboDyer] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
137Converts to the Hobo-Dyer cylindrical equal area projection. (standard parallels
138are 37.5 degrees North and South)
139[call [cmd ::mapproj::fromHoboDyer] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
140Converts from the Hobo-Dyer cylindrical equal area projection. (standard parallels
141are 37.5 degrees North and South.)
142[call [cmd ::mapproj::toGallPeters] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
143Converts to the Gall-Peters cylindrical equal area projection. (standard parallels
144are 45 degrees North and South)
145[call [cmd ::mapproj::fromGallPeters] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
146Converts from the Gall-Peters cylindrical equal area projection. (standard parallels
147are 45 degrees North and South.)
148[call [cmd ::mapproj::toBalthasart] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]]
149Converts to the Balthasart cylindrical equal area projection. (standard parallels
150are 50 degrees North and South)
151[call [cmd ::mapproj::fromBalthasart] [arg lambda_0] [arg phi_0] [arg x] [arg y]]
152Converts from the Balthasart cylindrical equal area projection. (standard parallels
153are 50 degrees North and South.)
154
155[list_end]
156
157[section Arguments]
158
159The following arguments are accepted by the projection commands:
160
161[list_begin definitions]
162
163[def [arg lambda]]
164
165Longitude of the point to be projected, in degrees.
166
167[def [arg phi]]
168
169Latitude of the point to be projected, in degrees.
170
171[def [arg lambda_0]]
172
173Longitude of the center of the sheet, in degrees.  For many projections,
174this figure is also the reference meridian of the projection.
175
176[def [arg phi_0]]
177
178Latitude of the center of the sheet, in degrees.  For the azimuthal
179projections, this figure is also the latitude of the center of the projection.
180
181[def [arg phi_1]]
182
183Latitude of the first reference parallel, for projections that use reference
184parallels.
185
186[def [arg phi_2]]
187
188Latitude of the second reference parallel, for projections that use reference
189parallels.
190
191[def [arg x]]
192
193X co-ordinate of a point on the map, in units of Earth radii.
194
195[def [arg y]]
196
197Y co-ordinate of a point on the map, in units of Earth radii.
198
199[list_end]
200
201[section Results]
202
203For all of the procedures whose names begin with 'to', the return value
204is a list comprising an [emph x] co-ordinate and a [emph y] co-ordinate.
205The co-ordinates are relative to the center of the map sheet to be drawn,
206measured in Earth radii at the reference location on the map.
207
208For all of the functions whose names begin with 'from', the return value
209is a list comprising the longitude and latitude, in degrees.
210
211[section {Choosing a projection}]
212
213This package offers a great many projections, because no single projection
214is appropriate to all maps.  This section attempts to provide guidance
215on how to choose a projection.
216[para]
217First, consider the type of data that you intend to display on the map.
218If the data are [emph directional] ([emph e.g.,] winds, ocean currents, or
219magnetic fields) then you need to use a projection that preserves
220angles; these are known as [emph conformal] projections.  Conformal
221projections include the Mercator, the Albers azimuthal equal-area,
222the stereographic, and the Peirce Quincuncial projection.  If the
223data are [emph thematic], describing properties of land or water, such
224as temperature, population density, land use, or demographics; then
225you need a projection that will show these data with the areas on the map
226proportional to the areas in real life.  These so-called [emph {equal area}]
227projections include the various cylindrical equal area projections,
228the sinusoidal projection, the Lambert azimuthal equal-area projection,
229the Albers equal-area conic projection, and several of the world-map
230projections (Miller Cylindrical, Mollweide, Eckert IV, Eckert VI, Robinson,
231and Hammer). If the significant factor in your data is distance from a
232central point or line (such as air routes), then you will do best with
233an [emph equidistant] projection such as [emph "plate carr\u00e9e"],
234Cassini, azimuthal equidistant, or conic equidistant.  If direction from
235a central point is a critical factor in your data (for instance,
236air routes, radio antenna pointing), then you will almost surely want to
237use one of the azimuthal projections. Appropriate choices are azimuthal
238equidistant, azimuthal equal-area, stereographic, and perhaps orthographic.
239[para]
240Next, consider how much of the Earth your map will cover, and the general
241shape of the area of interest.  For maps of the entire Earth,
242the cylindrical equal area, Eckert IV and VI, Mollweide, Robinson, and Hammer
243projections are good overall choices.  The Mercator projection is traditional,
244but the extreme distortions of area at high latitudes make it
245a poor choice unless a conformal projection is required. The Peirce
246projection is a better choice of conformal projection, having less distortion
247of landforms.  The Miller Cylindrical is a compromise designed to give
248shapes similar to the traditional Mercator, but with less polar stretching.
249The Peirce Quincuncial projection shows all the continents with acceptable
250distortion if a reference meridian close to +20 degrees is chosen.
251The Robinson projection yields attractive maps for things like political
252divisions, but should be avoided in presenting scientific data, since other
253projections have moe useful geometric properties.
254[para]
255If the map will cover a hemisphere, then choose stereographic,
256azimuthal-equidistant, Hammer, or Mollweide projections; these all project
257the hemisphere into a circle.
258[para]
259If the map will cover a large area (at least a few hundred km on a side),
260but less than
261a hemisphere, then you have several choices.  Azimuthal projections
262are usually good (choose stereographic, azimuthal equidistant, or
263Lambert azimuthal equal-area according to whether shapes, distances from
264a central point, or areas are important).  Azimuthal projections (and possibly
265the Cassini projection) are the only
266really good choices for mapping the polar regions.
267[para]
268If the large area is in one of the temperate zones and is round or has
269a primarily east-west extent, then the conic projections are good choices.
270Choose the Lambert conformal conic, the conic equidistant, or the Albers
271equal-area conic according to whether shape, distance, or area are the
272most important parameters.  For any of these, the reference parallels
273should be chosen at approximately 1/6 and 5/6 of the range of latitudes
274to be displayed.  For instance, maps of the 48 coterminous United States
275are attractive with reference parallels of 28.5 and 45.5 degrees.
276[para]
277If the large area is equatorial and is round or has a primarily east-west
278extent, then the Mercator projection is a good choice for a conformal
279projection; Lambert cylindrical equal-area and sinusoidal projections are
280good equal-area projections; and the [emph "plate carr\u00e9e"] is a
281good equidistant projection.
282[para]
283Large areas having a primarily North-South aspect, particularly those
284spanning the Equator, need some other choices.  The Cassini projection
285is a good choice for an equidistant projection (for instance, a Cassini
286projection with a central meridian of 80 degrees West produces an
287attractive map of the Americas). The cylindrical equal-area, Albers
288equal-area conic, sinusoidal, Mollweide and Hammer
289projections are possible choices for equal-area projections.
290A good conformal projection in this situation is the Transverse
291Mercator, which alas, is not yet implemented.
292[para]
293Small areas begin to get into a realm where the ellipticity of the
294Earth affects the map scale.  This package does not attempt to
295handle accurate mapping for large-scale topographic maps.  If
296slight scale errors are acceptable in your application, then any
297of the projections appropriate to large areas should work for
298small ones as well.
299[para]
300There are a few projections that are included for their special
301properties.  The orthographic projection produces views of the
302Earth as seen from space.  The gnomonic projection produces a
303map on which all great circles (the shortest distance between
304two points on the Earth's surface) are rendered as straight lines.
305While this projection is useful for navigational planning, it
306has extreme distortions of shape and area, and can display
307only a limited area of the Earth (substantially less than a hemisphere).
308[manpage_end]
309