1Cartography(3)        User Contributed Perl Documentation       Cartography(3)
2
3
4

NAME

6       PDL::Transform::Cartography - Useful cartographic projections
7

SYNOPSIS

9        # make a Mercator map of Earth
10        use PDL::Transform::Cartography;
11        $x = earth_coast();
12        $x = graticule(10,2)->glue(1,$x);
13        $t = t_mercator;
14        $w = pgwin(xs);
15        $w->lines($t->apply($x)->clean_lines());
16

DESCRIPTION

18       PDL::Transform::Cartography includes a variety of useful cartographic
19       and observing projections (mappings of the surface of a sphere),
20       including reprojected observer coordinates.  See PDL::Transform for
21       more information about image transforms in general.
22
23       Cartographic transformations are used for projecting not just
24       terrestrial maps, but also any nearly spherical surface including the
25       Sun, the Celestial sphere, various moons and planets, distant stars,
26       etc.  They also are useful for interpreting scientific images, which
27       are themselves generally projections of a sphere onto a flat focal
28       plane (e.g. the "t_gnomonic" projection).
29
30       Unless otherwise noted, all the transformations in this file convert
31       from (theta,phi) coordinates on the unit sphere (e.g. (lon,lat) on a
32       planet or (RA,dec) on the celestial sphere) into some sort of projected
33       coordinates, and have inverse transformations that convert back to
34       (theta,phi).  This is equivalent to working from the equidistant
35       cylindrical (or "plate caree") projection, if you are a cartography
36       wonk.
37
38       The projected coordinates are generally in units of body radii
39       (radians), so that multiplying the output by the scale of the map
40       yields physical units that are correct wherever the scale is correct
41       for that projection.  For example, areas should be correct everywhere
42       in the authalic projections; and linear scales are correct along
43       meridians in the equidistant projections and along the standard
44       parallels in all the projections.
45
46       The transformations that are authalic (equal-area), conformal (equal-
47       angle), azimuthal (circularly symmetric), or perspective (true
48       perspective on a focal plane from some viewpoint) are marked.  The
49       first two categories are mutually exclusive for all but the "unit
50       sphere" 3-D projection.
51
52       Extra dimensions tacked on to each point to be transformed are, in
53       general, ignored.  That is so that you can add on an extra index to
54       keep track of pen color.  For example, "earth_coast" returns a 3x<n>
55       ndarray containing (lon, lat, pen) at each list location.  Transforming
56       the vector list retains the pen value as the first index after the
57       dimensional directions.
58

GENERAL NOTES ON CARTOGRAPHY

60       Unless otherwise noted, the transformations and miscellaneous
61       information in this section are taken from Snyder & Voxland 1989: "An
62       Album of Map Projections", US Geological Survey Professional Paper
63       1453, US Printing Office (Denver); and from Snyder 1987: "Map
64       Projections - A Working Manual", US Geological Survey Professional
65       Paper 1395, US Printing Office (Denver, USA).  You can obtain your own
66       copy of both by contacting the U.S. Geological Survey, Federal Center,
67       Box 25425, Denver, CO 80225 USA.
68
69       The mathematics of cartography have a long history, and the details are
70       far trickier than the broad overview.  For terrestrial (and, in
71       general, planetary) cartography, the best reference datum is not a
72       sphere but an oblate ellipsoid due to centrifugal force from the
73       planet's rotation.  Furthermore, because all rocky planets, including
74       Earth, have randomly placed mass concentrations that affect the
75       gravitational field, the reference gravitational isosurface (sea level
76       on Earth) is even more complex than an ellipsoid and, in general,
77       different ellipsoids have been used for different locations at the same
78       time and for the same location at different times.
79
80       The transformations in this package use a spherical datum and hence
81       include global distortion at about the 0.5% level for terrestrial maps
82       (Earth's oblateness is ~1/300).  This is roughly equal to the
83       dimensional precision of physical maps printed on paper (due to
84       stretching and warping of the paper) but is significant at larger
85       scales (e.g. for regional maps).  If you need more precision than that,
86       you will want to implement and use the ellipsoidal transformations from
87       Snyder 1987 or another reference work on geodesy.  A good name for that
88       package would be "...::Cartography::Geodetic".
89

GENERAL NOTES ON PERSPECTIVE AND SCIENTIFIC IMAGES

91       Cartographic transformations are useful for interpretation of
92       scientific images, as all cameras produce projections of the celestial
93       sphere onto the focal plane of the camera.  A simple (single-element)
94       optical system with a planar focal plane generates gnomonic images --
95       that is to say, gnomonic projections of a portion of the celestial
96       sphere near the paraxial direction.  This is the projection that most
97       consumer grade cameras produce.
98
99       Magnification in an optical system changes the angle of incidence of
100       the rays on the focal plane for a given angle of incidence at the
101       aperture.  For example, a 10x telescope with a 2 degree field of view
102       exhibits the same gnomonic distortion as a simple optical system with a
103       20 degree field of view.  Wide-angle optics typically have
104       magnification less than 1 ('fisheye lenses'), reducing the gnomonic
105       distortion considerably but introducing "equidistant azimuthal"
106       distortion -- there's no such thing as a free lunch!
107
108       Because many solar-system objects are spherical,
109       PDL::Transform::Cartography includes perspective projections for
110       producing maps of spherical bodies from perspective views.  Those
111       projections are "t_vertical" and "t_perspective".  They map between
112       (lat,lon) on the spherical body and planar projected coordinates at the
113       viewpoint.  "t_vertical" is the vertical perspective projection given
114       by Snyder, but "t_perspective" is a fully general perspective
115       projection that also handles magnification correction.
116

TRANSVERSE & OBLIQUE PROJECTIONS; STANDARD OPTIONS

118       Oblique projections rotate the sphere (and graticule) to an arbitrary
119       angle before generating the projection; transverse projections rotate
120       the sphere exactly 90 degrees before generating the projection.
121
122       Most of the projections accept the following standard options, useful
123       for making transverse and oblique projection maps.
124
125       o, origin, Origin [default (0,0,0)]
126          The origin of the oblique map coordinate system, in (old-theta, old-
127          phi) coordinates.
128
129       r, roll, Roll [default 0.0]
130          The roll angle of the sphere about the origin, measured CW from (N =
131          up) for reasonable values of phi and CW from (S = up) for
132          unreasonable values of phi.  This is equivalent to observer roll
133          angle CCW from the same direction.
134
135       u, unit, Unit [default 'degree']
136          This is the name of the angular unit to use in the lon/lat
137          coordinate system.
138
139       b, B
140          The "B" angle of the body -- used for extraterrestrial maps.
141          Setting this parameter is exactly equivalent to setting the phi
142          component of the origin, and in fact overrides it.
143
144       l,L
145          The longitude of the central meridian as observed -- used for
146          extraterrestrial maps.  Setting this parameter is exactly equivalent
147          to setting the theta component of the origin, and in fact overrides
148          it.
149
150       p,P
151          The "P" (or position) angle of the body -- used for extraterrestrial
152          maps.  This parameter is a synonym for the roll angle, above.
153
154       bad, Bad, missing, Missing [default nan]
155          This is the value that missing points get.  Mainly useful for the
156          inverse transforms.  (This should work fine if set to BAD, if you
157          have bad-value support compiled in).  The default nan is asin(1.2),
158          calculated at load time.
159

EXAMPLES

161       Draw a Mercator map of the world on-screen:
162
163          $w = pgwin(xs);
164          $w->lines(earth_coast->apply(t_mercator)->clean_lines);
165
166       Here, "earth_coast()" returns a 3xn ndarray containing (lon, lat, pen)
167       values for the included world coastal outline; "t_mercator" converts
168       the values to projected Mercator coordinates, and "clean_lines" breaks
169       lines that cross the 180th meridian.
170
171       Draw a Mercator map of the world, with lon/lat at 10 degree intervals:
172
173          $w = pgwin(xs)
174          $x = earth_coast()->glue(1,graticule(10,1));
175          $w->lines($x->apply(t_mercator)->clean_lines);
176
177       This works just the same as the first example, except that a map
178       graticule has been applied with interline spacing of 10 degrees lon/lat
179       and inter-vertex spacing of 1 degree (so that each meridian contains
180       181 points, and each parallel contains 361 points).
181

NOTES

183       Currently angular conversions are rather simpleminded.  A list of
184       common conversions is present in the main constructor, which inserts a
185       conversion constant to radians into the {params} field of the new
186       transform.  Something like Math::Convert::Units should be used instead
187       to generate the conversion constant.
188
189       A cleaner higher-level interface is probably needed (see the examples);
190       for example, earth_coast could return a graticule if asked, instead of
191       needing one to be glued on.
192
193       The class structure is somewhat messy because of the varying needs of
194       the different transformations.  PDL::Transform::Cartography is a base
195       class that interprets the origin options and sets up the basic
196       machinery of the Transform.  The conic projections have their own
197       subclass, PDL::Transform::Conic, that interprets the standard
198       parallels.  Since the cylindrical and azimuthal projections are pretty
199       simple, they are not subclassed.
200
201       The perl 5.6.1 compiler is quite slow at adding new classes to the
202       structure, so it does not makes sense to subclass new transformations
203       merely for the sake of pedantry.
204

AUTHOR

206       Copyright 2002, Craig DeForest (deforest@boulder.swri.edu).  This
207       module may be modified and distributed under the same terms as PDL
208       itself.  The module comes with NO WARRANTY.
209
210       The included digital world map is derived from the 1987 CIA World Map,
211       translated to ASCII in 1988 by Joe Dellinger (geojoe@freeusp.org) and
212       simplified in 1995 by Kirk Johnson (tuna@indra.com) for the program
213       XEarth.  The map comes with NO WARRANTY.  An ASCII version of the map,
214       and a sample PDL function to read it, may be found in the Demos
215       subdirectory of the PDL source distribution.
216

FUNCTIONS

218       The module exports both transform constructors ('t_<foo>') and some
219       auxiliary functions (no leading 't_').
220
221   graticule
222          $lonlatp     = graticule(<grid-spacing>,<line-segment-size>);
223          $lonlatp     = graticule(<grid-spacing>,<line-segment-size>,1);
224
225       (Cartography) PDL constructor - generate a lat/lon grid.
226
227       Returns a grid of meridians and parallels as a list of vectors suitable
228       for sending to PDL::Graphics::PGPLOT::Window::lines for plotting.  The
229       grid is in degrees in (theta, phi) coordinates -- this is (E lon, N
230       lat) for terrestrial grids or (RA, dec) for celestial ones.  You must
231       then transform the graticule in the same way that you transform the
232       map.
233
234       You can attach the graticule to a vector map using the syntax:
235
236           $out = graticule(10,2)->glue(1,$map);
237
238       In array context you get back a 2-element list containing an ndarray of
239       the (theta,phi) pairs and an ndarray of the pen values (1 or 0)
240       suitable for calling PDL::Graphics::PGPLOT::Window::lines.  In scalar
241       context the two elements are combined into a single ndarray.
242
243       The pen values associated with the graticule are negative, which will
244       cause PDL::Graphics::PGPLOT::Window::lines to plot them as hairlines.
245
246       If a third argument is given, it is a hash of options, which can be:
247
248       nan - if true, use two columns instead of three, and separate lines
249       with a 'nan' break
250       lonpos - if true, all reported longitudes are positive (0 to 360)
251       instead of (-180 to 180).
252       dup - if true, the meridian at the far boundary is duplicated.
253
254   earth_coast
255         $x = earth_coast()
256
257       (Cartography) PDL constructor - coastline map of Earth
258
259       Returns a vector coastline map based on the 1987 CIA World Coastline
260       database (see author information).  The vector coastline data are in
261       plate caree format so they can be converted to other projections via
262       the apply method and cartographic transforms, and are suitable for
263       plotting with the lines method in the PGPLOT output library:  the first
264       dimension is (X,Y,pen) with breaks having a pen value of 0 and
265       hairlines having negative pen values.  The second dimension broadcasts
266       over all the points in the data set.
267
268       The vector map includes lines that pass through the antipodean
269       meridian, so if you want to plot it without reprojecting, you should
270       run it through "clean_lines" first:
271
272           $w = pgwin();
273           $w->lines(earth_coast->clean_lines);     # plot plate caree map of world
274           $w->lines(earth_coast->apply(t_gnomonic))# plot gnomonic map of world
275
276       "earth_coast" is just a quick-and-dirty way of loading the file
277       "earth_coast.vec.fits" that is part of the normal installation tree.
278
279   earth_image
280        $rgb = earth_image()
281
282       (Cartography) PDL constructor - RGB pixel map of Earth
283
284       Returns an RGB image of Earth based on data from the MODIS instrument
285       on the NASA EOS/Terra satellite.  (You can get a full-resolution image
286       from <http://earthobservatory.nasa.gov/Newsroom/BlueMarble/>).  The
287       image is a plate caree map, so you can convert it to other projections
288       via the map method and cartographic transforms.
289
290       This is just a quick-and-dirty way of loading the earth-image files
291       that are distributed along with PDL.
292
293   clean_lines
294        $x = clean_lines(t_mercator->apply(scalar(earth_coast())));
295        $x = clean_lines($line_pen, [threshold]);
296        $x = $lines->clean_lines;
297
298       (Cartography) PDL method - remove projection irregularities
299
300       "clean_lines" massages vector data to remove jumps due to singularities
301       in the transform.
302
303       In the first (scalar) form, $line_pen contains both (X,Y) points and
304       pen values suitable to be fed to lines: in the second (list) form,
305       $lines contains the (X,Y) points and $pen contains the pen values.
306
307       "clean_lines" assumes that all the outline polylines are local -- that
308       is to say, there are no large jumps.  Any jumps larger than a threshold
309       size are broken by setting the appropriate pen values to 0.
310
311       The "threshold" parameter sets the relative size of the largest jump,
312       relative to the map range (as determined by a min/max operation).  The
313       default size is 0.1.
314
315       NOTES
316
317       This almost never catches stuff near the apex of cylindrical maps,
318       because the anomalous vectors get arbitrarily small.  This could be
319       improved somewhat by looking at individual runs of the pen and using a
320       relative length scale that is calibrated to the rest of each run.  it
321       is probably not worth the computational overhead.
322
323   t_unit_sphere
324         $t = t_unit_sphere(<options>);
325
326       (Cartography) 3-D globe projection (conformal; authalic)
327
328       This is similar to the inverse of t_spherical, but the inverse
329       transform projects 3-D coordinates onto the unit sphere, yielding only
330       a 2-D (lon/lat) output.  Similarly, the forward transform deprojects
331       2-D (lon/lat) coordinates onto the surface of a unit sphere.
332
333       The cartesian system has its Z axis pointing through the pole of the
334       (lon,lat) system, and its X axis pointing through the equator at the
335       prime meridian.
336
337       Unit sphere mapping is unusual in that it is both conformal and
338       authalic.  That is possible because it properly embeds the sphere in
339       3-space, as a notional globe.
340
341       This is handy as an intermediate step in lots of transforms, as
342       Cartesian 3-space is cleaner to work with than spherical 2-space.
343
344       Higher dimensional indices are preserved, so that "rider" indices (such
345       as pen value) are propagated.
346
347       There is no oblique transform for t_unit_sphere, largely because it's
348       so easy to rotate the output using t_linear once it's out into
349       Cartesian space.  In fact, the other projections implement oblique
350       transforms by wrapping t_linear with "t_unit_sphere".
351
352       OPTIONS:
353
354       radius, Radius (default 1.0)
355          The radius of the sphere, for the inverse transform.  (Radius is
356          ignored in the forward transform).  Defaults to 1.0 so that the
357          resulting Cartesian coordinates are in units of "body radii".
358
359   t_rot_sphere
360           $t = t_rot_sphere({origin=>[<theta>,<phi>],roll=>[<roll>]});
361
362       (Cartography) Generate oblique projections
363
364       You feed in the origin in (theta,phi) and a roll angle, and you get
365       back out (theta', phi') coordinates.  This is useful for making oblique
366       or transverse projections:  just compose t_rot_sphere with your
367       favorite projection and you get an oblique one.
368
369       Most of the projections automagically compose themselves with
370       t_rot_sphere if you feed in an origin or roll angle.
371
372       t_rot_sphere converts the base plate caree projection (straight lon,
373       straight lat) to a Cassini projection.
374
375       OPTIONS
376
377       STANDARD POSITIONAL OPTIONS
378
379   t_orthographic
380           $t = t_orthographic(<options>);
381
382       (Cartography) Ortho. projection (azimuthal; perspective)
383
384       This is a perspective view as seen from infinite distance.  You can
385       specify the sub-viewer point in (lon,lat) coordinates, and a rotation
386       angle of the map CW from (north=up).  This is equivalent to specify
387       viewer roll angle CCW from (north=up).
388
389       t_orthographic is a convenience interface to t_unit_sphere -- it is
390       implemented as a composition of a t_unit_sphere call, a rotation, and a
391       slice.
392
393       [*] In the default case where the near hemisphere is mapped, the
394       inverse exists.  There is no single inverse for the whole-sphere case,
395       so the inverse transform superimposes everything on a single
396       hemisphere.  If you want an invertible 3-D transform, you want
397       "t_unit_sphere".
398
399       OPTIONS
400
401       STANDARD POSITIONAL OPTIONS
402       m, mask, Mask, h, hemisphere, Hemisphere [default 'near']
403          The hemisphere to keep in the projection (see
404          PDL::Transform::Cartography).
405
406       NOTES
407
408       Alone of the various projections, this one does not use "t_rot_sphere"
409       to handle the standard options, because the cartesian coordinates of
410       the rotated sphere are already correctly projected -- t_rot_sphere
411       would put them back into (theta', phi') coordinates.
412
413   t_caree
414           $t = t_caree(<options>);
415
416       (Cartography) Plate Caree projection (cylindrical; equidistant)
417
418       This is the simple Plate Caree projection -- also called a "lat/lon
419       plot".  The horizontal axis is theta; the vertical axis is phi.  This
420       is a no-op if the angular unit is radians; it is a simple scale
421       otherwise.
422
423       OPTIONS
424
425       STANDARD POSITIONAL OPTIONS
426       s, std, standard, Standard (default 0)
427          The standard parallel where the transformation is conformal.
428          Conformality is achieved by shrinking of the horizontal scale to
429          match the vertical scale (which is correct everywhere).
430
431   t_mercator
432           $t = t_mercator(<options>);
433
434       (Cartography) Mercator projection (cylindrical; conformal)
435
436       This is perhaps the most famous of all map projections: meridians are
437       mapped to parallel vertical lines and parallels are unevenly spaced
438       horizontal lines.  The poles are shifted to +/- infinity.  The output
439       values are in units of globe-radii for easy conversion to kilometers;
440       hence the horizontal extent is -pi to pi.
441
442       You can get oblique Mercator projections by specifying the "origin" or
443       "roll" options; this is implemented via "t_rot_sphere".
444
445       OPTIONS
446
447       STANDARD POSITIONAL OPTIONS
448       c, clip, Clip (default 75 [degrees])
449          The north/south clipping boundary of the transformation.  Because
450          the poles are displaced to infinity, many applications require a
451          clipping boundary.  The value is in whatever angular unit you set
452          with the standard 'units' option.  The default roughly matches
453          interesting landforms on Earth.  For no clipping at all, set b=>0.
454          For asymmetric clipping, use a 2-element list ref or ndarray.
455
456       s, std, Standard (default 0)
457          This is the parallel at which the map has correct scale.  The scale
458          is also correct at the parallel of opposite sign.
459
460   t_utm
461         $t = t_utm(<zone>,<options>);
462
463       (Cartography) Universal Transverse Mercator projection (cylindrical)
464
465       This is the internationally used UTM projection, with 2 subzones
466       (North/South).  The UTM zones are parametrized individually, so if you
467       want a Zone 30 map you should use "t_utm(30)".  By default you get the
468       northern subzone, so that locations in the southern hemisphere get
469       negative Y coordinates.  If you select the southern subzone (with the
470       "subzone=>-1" option), you get offset southern UTM coordinates.
471
472       The 20-subzone military system is not yet supported.  If/when it is
473       implemented, you will be able to enter "subzone=>[a-t]" to select a N/S
474       subzone.
475
476       Note that UTM is really a family of transverse Mercator projections
477       with different central meridia.  Each zone properly extends for six
478       degrees of longitude on either side of its appropriate central
479       meridian, with Zone 1 being centered at -177 degrees longitude (177
480       west).  Properly speaking, the zones only extend from 80 degrees south
481       to 84 degrees north; but this implementation lets you go all the way to
482       90 degrees.  The default UTM coordinates are meters.  The origin for
483       each zone is on the equator, at an easting of -500,000 meters.
484
485       The default output units are meters, assuming that you are wanting a
486       map of the Earth.  This will break for bodies other than Earth (which
487       have different radii and hence different conversions between lat/lon
488       angle and meters).
489
490       The standard UTM projection has a slight reduction in scale at the
491       prime meridian of each zone: the transverse Mercator projection's
492       standard "parallels" are 180km e/w of the central meridian.  However,
493       many Europeans prefer the "Gauss-Kruger" system, which is virtually
494       identical to UTM but with a normal tangent Mercator (standard parallel
495       on the prime meridian).  To get this behavior, set "gk=>1".
496
497       Like the rest of the PDL::Transform::Cartography package, t_utm uses a
498       spherical datum rather than the "official" ellipsoidal datums for the
499       UTM system.
500
501       This implementation was derived from the rather nice description by
502       Denis J. Dean, located on the web at:
503       http://www.cnr.colostate.edu/class_info/nr502/lg3/datums_coordinates/utm.html
504
505       OPTIONS
506
507       STANDARD OPTIONS
508          (No positional options -- Origin and Roll are ignored)
509
510       ou, ounit, OutputUnit (default 'meters')
511          (This is likely to become a standard option in a future release) The
512          unit of the output map.  By default, this is 'meters' for UTM, but
513          you may specify 'deg' or 'km' or even (heaven help us) 'miles' if
514          you prefer.
515
516       sz, subzone, SubZone (default 1)
517          Set this to -1 for the southern hemisphere subzone.  Ultimately you
518          should be able to set it to a letter to get the corresponding
519          military subzone, but that's too much effort for now.
520
521       gk, gausskruger (default 0)
522          Set this to 1 to get the (European-style) tangent-plane Mercator
523          with standard parallel on the prime meridian.  The default of 0
524          places the standard parallels 180km east/west of the prime meridian,
525          yielding better average scale across the zone.  Setting gk=>1 makes
526          the scale exactly 1.0 at the central meridian, and >1.0 everywhere
527          else on the projection.  The difference in scale is about 0.3%.
528
529   t_sin_lat
530           $t = t_sin_lat(<options>);
531
532       (Cartography) Cyl. equal-area projection (cyl.; authalic)
533
534       This projection is commonly used in solar Carrington plots; but not
535       much for terrestrial mapping.
536
537       OPTIONS
538
539       STANDARD POSITIONAL OPTIONS
540       s,std, Standard (default 0)
541          This is the parallel at which the map is conformal.  It is also
542          conformal at the parallel of opposite sign.  The conformality is
543          achieved by matched vertical stretching and horizontal squishing (to
544          achieve constant area).
545
546   t_sinusoidal
547           $t = t_sinusoidal(<options>);
548
549       (Cartography) Sinusoidal projection (authalic)
550
551       Sinusoidal projection preserves the latitude scale but scales longitude
552       according to sin(lat); in this respect it is the companion to
553       "t_sin_lat", which is also authalic but preserves the longitude scale
554       instead.
555
556       OPTIONS
557
558       STANDARD POSITIONAL OPTIONS
559
560   t_conic
561           $t = t_conic(<options>)
562
563       (Cartography) Simple conic projection (conic; equidistant)
564
565       This is the simplest conic projection, with parallels mapped to
566       equidistant concentric circles.  It is neither authalic nor conformal.
567       This transformation is also referred to as the "Modified Transverse
568       Mercator" projection in several maps of Alaska published by the USGS;
569       and the American State of New Mexico re-invented the projection in 1936
570       for an official map of that State.
571
572       OPTIONS
573
574       STANDARD POSITIONAL OPTIONS
575       s, std, Standard (default 29.5, 45.5)
576          The locations of the standard parallel(s) (where the cone intersects
577          the surface of the sphere).  If you specify only one then the other
578          is taken to be the nearest pole.  If you specify both of them to be
579          one pole then you get an equidistant azimuthal map.  If you specify
580          both of them to be opposite and equidistant from the equator you get
581          a Plate Caree projection.
582
583   t_albers
584           $t = t_albers(<options>)
585
586       (Cartography) Albers conic projection (conic; authalic)
587
588       This is the standard projection used by the US Geological Survey for
589       sectionals of the 50 contiguous United States of America.
590
591       The projection reduces to the Lambert equal-area conic (infrequently
592       used and not to be confused with the Lambert conformal conic,
593       "t_lambert"!)  if the pole is used as one of the two standard
594       parallels.
595
596       Notionally, this is a conic projection onto a cone that intersects the
597       sphere at the two standard parallels; it works best when the two
598       parallels straddle the region of interest.
599
600       OPTIONS
601
602       STANDARD POSITIONAL OPTIONS
603       s, std, standard, Standard (default (29.5,45.5))
604          The locations of the standard parallel(s).  If you specify only one
605          then the other is taken to be the nearest pole and a Lambert Equal-
606          Area Conic map results.  If you specify both standard parallels to
607          be the same pole, then the projection reduces to the Lambert
608          Azimuthal Equal-Area map as aq special case.  (Note that "t_lambert"
609          is Lambert's Conformal Conic, the most commonly used of Lambert's
610          projections.)
611
612          The default values for the standard parallels are those chosen by
613          Adams for maps of the lower 48 US states: (29.5,45.5).  The USGS
614          recommends (55,65) for maps of Alaska and (8,18) for maps of Hawaii
615          -- these latter are chosen to also include the Canal Zone and
616          Philippine Islands farther south, which is why both of those
617          parallels are south of the Hawaiian islands.
618
619          The transformation reduces to the cylindrical equal-area (sin-lat)
620          transformation in the case where the standard parallels are opposite
621          and equidistant from the equator, and in fact this is implemented by
622          a call to t_sin_lat.
623
624   t_lambert
625           $t = t_lambert(<options>);
626
627       (Cartography) Lambert conic projection (conic; conformal)
628
629       Lambert conformal conic projection is widely used in aeronautical
630       charts and state base maps published by the USA's FAA and USGS.  It's
631       especially useful for mid-latitude charts.  In particular, straight
632       lines approximate (but are not exactly) great circle routes of up to ~2
633       radians.
634
635       The default standard parallels are 33 and 45 to match the USGS state
636       1:500,000 base maps of the United States.  At scales of 1:500,000 and
637       larger, discrepancies between the spherical and ellipsoidal projections
638       become important; use care with this projection on spheres.
639
640       OPTIONS
641
642       STANDARD POSITIONAL OPTIONS
643       s, std, standard, Standard (default (33,45))
644          The locations of the standard parallel(s) for the conic projection.
645          The transform reduces to the Mercator projection in the case where
646          the standard parallels are opposite and equidistant from the
647          equator, and in fact this is implemented by a call to t_mercator.
648
649       c, clip, Clip (default [-75,75])
650          Because the transform is conformal, the distant pole is displaced to
651          infinity.  Many applications require a clipping boundary.  The value
652          is in whatever angular unit you set with the standard 'unit' option.
653          For consistency with "t_mercator", clipping works the same way even
654          though in most cases only one pole needs it.  Set this to 0 for no
655          clipping at all.
656
657   t_stereographic
658           $t = t_stereographic(<options>);
659
660       (Cartography) Stereographic projection (az.; conf.; persp.)
661
662       The stereographic projection is a true perspective (planar) projection
663       from a point on the spherical surface opposite the origin of the map.
664
665       OPTIONS
666
667       STANDARD POSITIONAL OPTIONS
668       c, clip, Clip (default 120)
669          This is the angular distance from the center to the edge of the
670          projected map.  The default 120 degrees gives you most of the
671          opposite hemisphere but avoids the hugely distorted part near the
672          antipodes.
673
674   t_gnomonic
675           $t = t_gnomonic(<options>);
676
677       (Cartography) Gnomonic (focal-plane) projection (az.; persp.)
678
679       The gnomonic projection projects a hemisphere onto a tangent plane.  It
680       is useful in cartography for the property that straight lines are great
681       circles; and it is useful in scientific imaging because it is the
682       projection generated by a simple optical system with a flat focal
683       plane.
684
685       OPTIONS
686
687       STANDARD POSITIONAL OPTIONS
688       c, clip, Clip (default 75)
689          This is the angular distance from the center to the edge of the
690          projected map.  The default 75 degrees gives you most of the
691          hemisphere but avoids the hugely distorted part near the horizon.
692
693   t_az_eqd
694         $t = t_az_eqd(<options>);
695
696       (Cartography) Azimuthal equidistant projection (az.; equi.)
697
698       Basic azimuthal projection preserving length along radial lines from
699       the origin (meridians, in the original polar aspect).  Hence, both
700       azimuth and distance are correct for journeys beginning at the origin.
701
702       Applied to the celestial sphere, this is the projection made by fisheye
703       lenses; it is also the projection into which "t_vertical" puts
704       perspective views.
705
706       The projected plane scale is normally taken to be planetary radii; this
707       is useful for cartographers but not so useful for scientific observers.
708       Setting the 't=>1' option causes the output scale to shift to camera
709       angular coordinates (the angular unit is determined by the standard
710       'Units' option; default is degrees).
711
712       OPTIONS
713
714       STANDARD POSITIONAL OPTIONS
715       c, clip, Clip (default 180 degrees)
716          The largest angle relative to the origin.  Default is the whole
717          sphere.
718
719   t_az_eqa
720         $t = t_az_eqa(<options>);
721
722       (Cartography) Azimuthal equal-area projection (az.; auth.)
723
724       OPTIONS
725
726       STANDARD POSITIONAL OPTIONS
727       c, clip, Clip (default 180 degrees)
728          The largest angle relative to the origin.  Default is the whole
729          sphere.
730
731   t_aitoff
732       "t_aitoff" in an alias for "t_hammer"
733
734   t_hammer
735       (Cartography) Hammer/Aitoff elliptical projection (az.; auth.)
736
737       The Hammer/Aitoff projection is often used to display the Celestial
738       sphere.  It is mathematically related to the Lambert Azimuthal Equal-
739       Area projection ("t_az_eqa"), and maps the sphere to an ellipse of unit
740       eccentricity, with vertical radius sqrt(2) and horizontal radius of 2
741       sqrt(2).
742
743       OPTIONS
744
745       STANDARD POSITIONAL OPTIONS
746
747   t_zenithal
748       Vertical projections are also called "zenithal", and "t_zenithal" is an
749       alias for "t_vertical".
750
751   t_vertical
752           $t = t_vertical(<options>);
753
754       (Cartography) Vertical perspective projection (az.; persp.)
755
756       Vertical perspective projection is a generalization of gnomonic and
757       stereographic projection, and a special case of perspective projection.
758       It is a projection from the sphere onto a tangent plane from a point at
759       the camera location.
760
761       OPTIONS
762
763       STANDARD POSITIONAL OPTIONS
764       m, mask, Mask, h, hemisphere, Hemisphere [default 'near']
765          The hemisphere to keep in the projection (see
766          PDL::Transform::Cartography).
767
768       r0, R0, radius, d, dist, distance [default 2.0]
769          The altitude of the focal plane above the center of the sphere.  The
770          default places the point of view one radius above the surface.
771
772       t, telescope, Telescope, cam, Camera (default '')
773          If this is set, then the central scale is in telescope or camera
774          angular units rather than in planetary radii.  The angular units are
775          parsed as with the normal 'u' option for the lon/lat specification.
776          If you specify a non-string value (such as 1) then you get
777          telescope-frame radians, suitable for working on with other
778          transformations.
779
780       f, fish, fisheye (default '')
781          If this is set then the output is in azimuthal equidistant
782          coordinates instead of in tangent-plane coordinates.  This is a
783          convenience function for '(t_az_eqd) x !(t_gnomonic) x
784          (t_vertical)'.
785
786   t_perspective
787           $t = t_perspective(<options>);
788
789       (Cartography) Arbitrary perspective projection
790
791       Perspective projection onto a focal plane from an arbitrary location
792       within or without the sphere, with an arbitrary central look direction,
793       and with correction for magnification within the optical system.
794
795       In the forward direction, t_perspective generates perspective views of
796       a sphere given (lon/lat) mapping or vector information.  In the reverse
797       direction, t_perspective produces (lon/lat) maps from aerial or distant
798       photographs of spherical objects.
799
800       Viewpoints outside the sphere treat the sphere as opaque by default,
801       though you can use the 'm' option to specify either the near or far
802       surface (relative to the origin).  Viewpoints below the surface treat
803       the sphere as transparent and undergo a mirror reversal for consistency
804       with projections that are special cases of the perspective projection
805       (e.g. t_gnomonic for r0=0 or t_stereographic for r0=-1).
806
807       Magnification correction handles the extra edge distortion due to
808       higher angles between the focal plane and focused rays within the
809       optical system of your camera.  If you do not happen to know the
810       magnification of your camera, a simple rule of thumb is that the
811       magnification of a reflective telescope is roughly its focal length
812       (plate scale) divided by its physical length; and the magnification of
813       a compound refractive telescope is roughly twice its physical length
814       divided by its focal length.  Simple optical systems with a single
815       optic have magnification = 1.  Fisheye lenses have magnification < 1.
816
817       This transformation was derived by direct geometrical calculation
818       rather than being translated from Voxland & Snyder.
819
820       OPTIONS
821
822       STANDARD POSITIONAL OPTIONS
823          As always, the 'origin' field specifies the sub-camera point on the
824          sphere.
825
826          The 'roll' option is the roll angle about the sub-camera point, for
827          consistency with the other projectons.
828
829       p, ptg, pointing, Pointing (default (0,0,0))
830          The pointing direction, in (horiz. offset, vert. offset, roll) of
831          the camera relative to the center of the sphere.  This is a
832          spherical coordinate system with the origin pointing directly at the
833          sphere and the pole pointing north in the pre-rolled coordinate
834          system set by the standard origin.  It's most useful for space-based
835          images taken some distance from the body in question (e.g. images of
836          other planets or the Sun).
837
838          Be careful not to confuse 'p' (pointing) with 'P' (P angle, a
839          standard synonym for roll).
840
841       c, cam, camera, Camera (default undef)
842          Alternate way of specifying the camera pointing, using a spherical
843          coordinate system with poles at the zenith (positive) and nadir
844          (negative) -- this is useful for aerial photographs and such, where
845          the point of view is near the surface of the sphere.  You specify
846          (azimuth from N, altitude from horizontal, roll from vertical=up).
847          If you specify pointing by this method, it overrides the 'pointing'
848          option, above.  This coordinate system is most useful for aerial
849          photography or low-orbit work, where the nadir is not necessarily
850          the most interesting part of the scene.
851
852       r0, R0, radius, d, dist, distance [default 2.0]
853          The altitude of the point of view above the center of the sphere.
854          The default places the point of view 1 radius aboove the surface.
855          Do not confuse this with 'r', the standard origin roll angle!
856          Setting r0 < 1 gives a viewpoint inside the sphere.  In that case,
857          the images are mirror-reversed to preserve the chiralty of the
858          perspective.  Setting r0=0 gives gnomonic projections; setting r0=-1
859          gives stereographic projections.  Setting r0 < -1 gives strange
860          results.
861
862       iu, im_unit, image_unit, Image_Unit (default 'degrees')
863          This is the angular units in which the viewing camera is calibrated
864          at the center of the image.
865
866       mag, magnification, Magnification (default 1.0)
867          This is the magnification factor applied to the optics -- it affects
868          the amount of tangent-plane distortion within the telescope.  1.0
869          yields the view from a simple optical system; higher values are
870          telescopic, while lower values are wide-angle (fisheye).  Higher
871          magnification leads to higher angles within the optical system, and
872          more tangent-plane distortion at the edges of the image.  The
873          magnification is applied to the incident angles themselves, rather
874          than to their tangents (simple two-element telescopes magnify
875          tan(theta) rather than theta itself); this is appropriate because
876          wide-field optics more often conform to the equidistant azimuthal
877          approximation than to the tangent plane approximation.  If you need
878          more detailed control of the relationship between incident angle and
879          focal-plane position, use mag=1.0 and compose the transform with
880          something else to tweak the angles.
881
882       m, mask, Mask, h, hemisphere, Hemisphere [default 'near']
883          'hemisphere' is by analogy to other cartography methods although the
884          two regions to be selected are not really hemispheres.
885
886       f, fov, field_of_view, Field_Of_View [default 60 degrees]
887          The field of view of the telescope -- sets the crop radius on the
888          focal plane.  If you pass in a scalar, you get a circular crop.  If
889          you pass in a 2-element list ref, you get a rectilinear crop, with
890          the horizontal 'radius' and vertical 'radius' set separately.
891
892       EXAMPLES
893
894       Model a camera looking at the Sun through a 10x telescope from Earth
895       (~230 solar radii from the Sun), with an 0.5 degree field of view and a
896       solar P (roll) angle of 30 degrees, in February (sub-Earth solar
897       latitude is 7 degrees south).  Convert a solar FITS image taken with
898       that camera to a FITS lon/lat map of the Sun with 20 pixels/degree
899       latitude:
900
901         # Define map output header (no need if you don't want a FITS output map)
902         $maphdr = {NAXIS1=>7200,NAXIS2=>3600,            # Size of image
903                    CTYPE1=>longitude,CTYPE2=>latitude,   # Type of axes
904                    CUNIT1=>deg,CUNIT2=>deg,              # Unit of axes
905                    CDELT1=>0.05,CDELT2=>0.05,            # Scale of axes
906                    CRPIX1=>3601,CRPIX2=>1801,            # Center of map
907                    CRVAL1=>0,CRVAL2=>0                   # (lon,lat) of center
908                    };
909
910         # Set up the perspective transformation, and apply it.
911         $t = t_perspective(r0=>229,fov=>0.5,mag=>10,P=>30,B=>-7);
912         $map = $im->map( $t , $maphdr );
913
914       Draw an aerial-view map of the Chesapeake Bay, as seen from a sounding
915       rocket at an altitude of 100km, looking NNE from ~200km south of
916       Washington (the radius of Earth is 6378 km; Washington D.C. is at
917       roughly 77W,38N).  Superimpose a linear coastline map on a photographic
918       map.
919
920         $x = graticule(1,0.1)->glue(1,earth_coast());
921         $t = t_perspective(r0=>6478/6378.0,fov=>60,cam=>[22.5,-20],o=>[-77,36])
922         $w = pgwin(size=>[10,6],J=>1);
923         $w->fits_imag(earth_image()->map($t,[800,500],{m=>linear}));
924         $w->hold;
925         $w->lines($x->apply($t),{xt=>'Degrees',yt=>'Degrees'});
926         $w->release;
927
928       Model a 5x telescope looking at Betelgeuse with a 10 degree field of
929       view (since the telescope is looking at the Celestial sphere, r is 0
930       and this is just an expensive modified-gnomonic projection).
931
932         $t = t_perspective(r0=>0,fov=>10,mag=>5,o=>[88.79,7.41])
933
934
935
936perl v5.34.0                      2022-02-28                    Cartography(3)
Impressum