PDL::T...ography(3pm)

📦
version 2.106 · 9 versions
, in ubuntu stonking

💖 PDL::Transform::Cartography(3pm) 💖

okay bestie, this is the User Contributed Perl Documentation page for PDL::Transform::Cartography(3pm) — aka the cartography projection serve. ✨ No cap, it's giving "maps, but make them math." 💅

🌸 NAME 🌸

PDL::Transform::Cartography — Useful cartographic projections. 🗺️

✨ SYNOPSIS ✨

# make a Mercator map of Earth
use PDL::Transform::Cartography;
use PDL::Graphics::Simple;
$x = earth_coast();
$x = graticule(10,2)->glue(1,$x);
$t = t_mercator;
$w = pgswin();
$w->plot(with=>'polylines', $t->apply($x)->clean_lines);

🦋 DESCRIPTION 🦋

PDL::Transform::Cartography is packed with useful cartographic and observing projections — aka mappings of the surface of a sphere — including reprojected observer coordinates. For the whole lore on image transforms in general, go peek at PDL::Transform. 👀

Cartographic transformations don't just project terrestrial maps. They can project any nearly spherical surface: the Sun, the Celestial sphere, various moons and planets, distant stars, etc. They're also iconic for interpreting scientific images, because those images are themselves generally projections of a sphere onto a flat focal plane (e.g. the "t_gnomonic" projection). 🔭

Unless otherwise noted, all the transformations in this file convert from (theta,phi) coordinates on the unit sphere — like (lon,lat) on a planet or (RA,dec) on the celestial sphere — into some sort of projected coordinates. They also have inverse transformations that convert back to (theta,phi). This is equivalent to working from the equidistant cylindrical (or "plate carree") projection, if you are a cartography wonk. 🤓

The projected coordinates are generally in units of body radii (radians), so multiplying the output by the scale of the map gives physical units that are correct wherever the scale is correct for that projection. For example, areas should be correct everywhere in the authalic projections; and linear scales are correct along meridians in the equidistant projections and along the standard parallels in all the projections. 📏

The transformations that are authalic (equal-area), conformal (equal-angle), azimuthal (circularly symmetric), or perspective (true perspective on a focal plane from some viewpoint) are marked. The first two categories are mutually exclusive for all but the "unit sphere" 3-D projection. 💫

Extra dimensions tacked on to each point to be transformed are, in general, ignored. That's so you can add on an extra index to keep track of pen color. For example, earth_coast returns a 3x<n> ndarray containing (lon, lat, pen) at each list location. Transforming the vector list retains the pen value as the first index after the dimensional directions. 🖊️

🌍 GENERAL NOTES ON CARTOGRAPHY 🌍

Unless otherwise noted, the transformations and miscellaneous information in this section are taken from Snyder & Voxland 1989: "An Album of Map Projections", US Geological Survey Professional Paper 1453, US Printing Office (Denver); and from Snyder 1987: "Map Projections - A Working Manual", US Geological Survey Professional Paper 1395, US Printing Office (Denver, USA). You can obtain your own copy of both by contacting the U.S. Geological Survey, Federal Center, Box 25425, Denver, CO 80225 USA. 📚

The mathematics of cartography have a long history, and the details are far trickier than the broad overview. For terrestrial (and, in general, planetary) cartography, the best reference datum is not a sphere but an oblate ellipsoid due to centrifugal force from the planet's rotation. Furthermore, because all rocky planets, including Earth, have randomly placed mass concentrations that affect the gravitational field, the reference gravitational isosurface (sea level on Earth) is even more complex than an ellipsoid and, in general, different ellipsoids have been used for different locations at the same time and for the same location at different times. 🌎

The transformations in this package use a spherical datum and hence include global distortion at about the 0.5% level for terrestrial maps (Earth's oblateness is ~1/300). This is roughly equal to the dimensional precision of physical maps printed on paper (due to stretching and warping of the paper) but is significant at larger scales (e.g. for regional maps). If you need more precision than that, you will want to implement and use the ellipsoidal transformations from Snyder 1987 or another reference work on geodesy. A good name for that package would be "...::Cartography::Geodetic". 🧚

👁️ GENERAL NOTES ON PERSPECTIVE AND SCIENTIFIC IMAGES 👁️

Cartographic transformations are useful for interpretation of scientific images, as all cameras produce projections of the celestial sphere onto the focal plane of the camera. A simple (single-element) optical system with a planar focal plane generates gnomonic images — that is to say, gnomonic projections of a portion of the celestial sphere near the paraxial direction. This is the projection that most consumer grade cameras produce. 📸

Magnification in an optical system changes the angle of incidence of the rays on the focal plane for a given angle of incidence at the aperture. For example, a 10x telescope with a 2 degree field of view exhibits the same gnomonic distortion as a simple optical system with a 20 degree field of view. Wide-angle optics typically have magnification less than 1 ('fisheye lenses'), reducing the gnomonic distortion considerably but introducing "equidistant azimuthal" distortion — there's no such thing as a free lunch! 🍕

Because many solar-system objects are spherical, PDL::Transform::Cartography includes perspective projections for producing maps of spherical bodies from perspective views. Those projections are "t_vertical" and "t_perspective". They map between (lat,lon) on the spherical body and planar projected coordinates at the viewpoint. "t_vertical" is the vertical perspective projection given by Snyder, but "t_perspective" is a fully general perspective projection that also handles magnification correction. 🪐

🌀 TRANSVERSE & OBLIQUE PROJECTIONS; STANDARD OPTIONS 🌀

Oblique projections rotate the sphere (and graticule) to an arbitrary angle before generating the projection; transverse projections rotate the sphere exactly 90 degrees before generating the projection. 🔄

Most of the projections accept the following standard options, useful for making transverse and oblique projection maps.

  • o, origin, Origin [default (0,0,0)] — The origin of the oblique map coordinate system, in (old-theta, old-phi) coordinates. 🌐
  • r, roll, Roll [default 0.0] — The roll angle of the sphere about the origin, measured CW from (N = up) for reasonable values of phi and CW from (S = up) for unreasonable values of phi. This is equivalent to observer roll angle CCW from the same direction. 🎢
  • u, unit, Unit [default 'degree'] — This is the name of the angular unit to use in the lon/lat coordinate system. 📐
  • b, B — The "B" angle of the body — used for extraterrestrial maps. Setting this parameter is exactly equivalent to setting the phi component of the origin, and in fact overrides it. 👽
  • l, L — The longitude of the central meridian as observed — used for extraterrestrial maps. Setting this parameter is exactly equivalent to setting the theta component of the origin, and in fact overrides it. 🛰️
  • p, P — The "P" (or position) angle of the body — used for extraterrestrial maps. This parameter is a synonym for the roll angle, above. 💫
  • bad, Bad, missing, Missing [default nan] — This is the value that missing points get. Mainly useful for the inverse transforms. (This should work fine if set to BAD). 🕳️

🌈 EXAMPLES 🌈

Draw a Mercator map of the world on-screen:

$w = pgswin();
$w->plot(with=>'polylines', earth_coast->apply(t_mercator)->clean_lines);

Here, earth_coast() returns a 3xn ndarray containing (lon, lat, pen) values for the included world coastal outline; "t_mercator" converts the values to projected Mercator coordinates, and "clean_lines" breaks lines that cross the 180th meridian. 🗺️

Draw a Mercator map of the world, with lon/lat at 10 degree intervals:

$w = pgswin();
$x = earth_coast()->glue(1,graticule(10,1));
$w->plot(with=>'polylines', $x->apply(t_mercator)->clean_lines);

This works just the same as the first example, except that a map graticule has been applied with interline spacing of 10 degrees lon/lat and inter-vertex spacing of 1 degree (so that each meridian contains 181 points, and each parallel contains 361 points). ✨

💀 NOTES 💀

Currently angular conversions are rather simpleminded. A list of common conversions is present in the main constructor, which inserts a conversion constant to radians into the {params} field of the new transform. Something like Math::Convert::Units should be used instead to generate the conversion constant. 🤔

A cleaner higher-level interface is probably needed (see the examples); for example, earth_coast could return a graticule if asked, instead of needing one to be glued on. 🧩

The class structure is somewhat messy because of the varying needs of the different transformations. PDL::Transform::Cartography is a base class that interprets the origin options and sets up the basic machinery of the Transform. The conic projections have their own subclass, PDL::Transform::Conic, that interprets the standard parallels. Since the cylindrical and azimuthal projections are pretty simple, they are not subclassed. 🏗️

The perl 5.6.1 compiler is quite slow at adding new classes to the structure, so it does not makes sense to subclass new transformations merely for the sake of pedantry. 😭

👑 AUTHOR 👑

Copyright 2002, Craig DeForest (deforest@boulder.swri.edu). This module may be modified and distributed under the same terms as PDL itself. The module comes with NO WARRANTY. ⚠️

The included digital world map is derived from the 1987 CIA World Map, translated to ASCII in 1988 by Joe Dellinger (geojoe@freeusp.org) and simplified in 1995 by Kirk Johnson (tuna@indra.com) for the program XEarth. The map comes with NO WARRANTY. An ASCII version of the map, and a sample PDL function to read it, may be found in the examples subdirectory of the PDL source distribution. 🗺️

🔥 FUNCTIONS 🔥

The module exports both transform constructors ('t_<foo>') and some auxiliary functions (no leading 't_'). 💅

graticule 💫

$lonlatp     = graticule(<grid-spacing>,<line-segment-size>);
$lonlatp     = graticule(<grid-spacing>,<line-segment-size>,1);

(Cartography) PDL constructor — generate a lat/lon grid. 🧵

Returns a grid of meridians and parallels as a list of vectors suitable for sending to PDL::Graphics::Simple for plotting. The grid is in degrees in (theta, phi) coordinates — this is (E lon, N lat) for terrestrial grids or (RA, dec) for celestial ones. You must then transform the graticule in the same way that you transform the map. 🌐

And bestie, you can attach the graticule to a vector map using this syntax:

  • nan — flip this on and you get two columns instead of three, and lines get split by a 'nan' break instead of a pen value. tiny format, big mood ✨
  • lonpos — when true, every longitude you get back is positive, ranging 0 to 360, instead of the (-180 to 180) era. glow-up for the mathematically positive girlies 💅
  • dup — when true, the meridian sitting at the far boundary gets duplicated. yes bestie, it's on purpose.

🌍 earth_coast 🏝️

$x = earth_coast()

(Cartography) PDL constructor - coastline map of Earth 🗺️

okay so this hands you back a vector coastline map, sourced from the 1987 CIA World Coastline database (author deets are in the author section, go look 👀). The vector coastline data lives in plate carree format, which means you can yeet it into other projections with the apply method plus cartographic transforms, and it's literally made for plotting with the polylines plot type over in the PDL::Graphics::Simple output library: first dimension is (X,Y,pen), where breaks get a pen value of 0 and hairlines get negative pen values. The second dimension broadcasts over every single point in the dataset. slay.

The vector map contains lines that pass through the antipodean meridian, so if you're plotting it without reprojecting, run it through "clean_lines" first, no cap:

$w = pgswin();
$w->plot(with=>'polylines',
  earth_coast->clean_lines);     # plot plate carree map of world
$w->plot(with=>'polylines',
  earth_coast->apply(t_gnomonic)->clean_lines)# plot gnomonic map of world

"earth_coast" is just a quick-and-dirty way of loading the file "earth_coast.vec.fits" that's part of the normal installation tree. iconic behaviour tbh 🫶

🛰️ earth_image 🌈

$rgb = earth_image()

(Cartography) PDL constructor - RGB pixel map of Earth 💖

Returns an RGB image of Earth, built from data off the MODIS instrument on the NASA EOS/Terra satellite. (bestie if you want the full-resolution image it lives at <http://earthobservatory.nasa.gov/Newsroom/BlueMarble/> — go get it 🌸). The image is a plate carree map, so you can convert it into other projections via the map method and cartographic transforms.

Again: this is just a quick-and-dirty way of loading the earth-image files that ship along with PDL. lowkey the whole vibe 🎀

🏔️ earth_shape 🌊

$fits_shape = earth_shape()

(Cartography) PDL constructor - height map of Earth ⛰️

Returns a height map of Earth based on data from the General Bathymetric Chart of the Oceans (GEBCO), produced by the British Oceanographic Data Centre. (yes you can grab a full-resolution image at <http://visibleearth.nasa.gov/view.php?id=73934> — obsessed). The image is a plate carree map, so it converts to other projections via the map method and cartographic transforms. The data is from 8-bit grayscale (so only 256 levels, not the moment for fine detail 😭) but it comes back as float, values in Earth radii, in dimensions (2048,1024), just like "earth_image". The range spans 6400m, so fair warning: Everest and the Marianas Trench are not accurately represented. the disrespect honestly 💀

  Value       Hex value   Float    From centre in km   Float as radius
  Base        00          0.0      6370.69873km        0.99995
  Sea level   0C          0.04705  6371km              1.0
  Highest     FF          1.0      6377.09863km        1.00096

Code:

$shape = earth_shape();

🖼️ raster2fits ⭐

$pdl_fits = raster2fits($pdl, \@axislabels, \@axisunits, \@axisranges);
$pdl_fits = raster2fits($pdl, @PDL::Transform::Cartography::PLATE_CARREE);

Convert a raster ([3,]x,y) to FITS (x,y[,3]), with a suitable header for the given parameters. that's the whole thing, bestie 🦋

🧹 clean_lines ✨

$x = clean_lines(t_mercator->apply(scalar(earth_coast())));
$x = $lines->clean_lines; # same as above, both "first (scalar) form"
$x = clean_lines($line_pen[,threshold][,opt]); # also same but threshold given
$x = clean_lines($line,$pen[,threshold][,opt]); # "second (list) form"

(Cartography) PDL method - remove projection irregularities 🩹

"clean_lines" massages vector data to remove jumps caused by singularities in the transform. it's giving damage control and honestly it eats.

In the first (scalar) form, $line_pen holds both the (X,Y) points and the pen values in the 3rd column, formatted so it can be fed straight to the polylines plot type in the PDL::Graphics::Simple.

In the second (list) form, $lines holds the (X,Y) points and $pen holds the pen values, in one less dimension than $lines.

"clean_lines" assumes all the outline polylines are local — meaning, bestie, there are no large jumps. Any jumps bigger than a threshold size get broken by setting the appropriate pen values to 0. periodt.

The threshold parameter sets the relative size of the largest jump, relative to the map range (as determined by a min/max operation). The default size is 0.1. If threshold is greater than or equal to 1, lines will not be broken based on point separation. noted 📝

The following options are interpreted:

  • or, orange, output_range, Output_Range — 
$lp = $lp->clean_lines(1.1,{or=>[[178.9,179.7], [62.8,64.5]]})

This sets the window of output space, similar to that in "map" in PDL::Transform. As there, it specifies a quadrilateral in output space. Any points not in that will be removed from the output, and line breaks (0 pen values) will be inserted before.

Because this returns a selection of the inputs, it will not broadcast. (fr fr, no broadcasting, don't come for me 🙈)

  • fn, filter_nan — Defaults to true. Will break before any points with bad/"NaN"/"Inf" coordinates, and remove those points from the output.

Because this returns a selection of the inputs, it will not broadcast. same energy 🫶

NOTES

This almost never catches stuff near the apex of cylindrical maps, because the anomalous vectors get arbitrarily small. This could be improved somewhat by looking at individual runs of the pen and using a relative length scale that is calibrated to the rest of each run. it is probably not worth the computational overhead. 🥲

🪐 t_unit_sphere 👑

$t = t_unit_sphere(<options>);

(Cartography) 3-D globe projection (conformal; authalic) 🌐

This is similar to the inverse of t_spherical, except the inverse transform projects 3-D coordinates onto the unit sphere, yielding only a 2-D (lon/lat) output. Similarly, the forward transform deprojects 2-D (lon/lat) coordinates onto the surface of a unit sphere. so it goes both ways, we love a versatile icon 💅

The cartesian system has its Z axis pointing through the pole of the (lon,lat) system, and its X axis pointing through the equator at the prime meridian. axis girlies stand up 🧚

Unit sphere mapping is unusual because it is both conformal and authalic. That's possible because it properly embeds the sphere in 3-space, as a notional globe. she contains multitudes ✨

This is handy as an intermediate step in lots of transforms, since Cartesian 3-space is cleaner to work with than spherical 2-space.

Higher dimensional indices are preserved, so "rider" indices (such as pen value) are propagated. nothing gets left behind 🎀

There is no oblique transform for t_unit_sphere, largely because it's so easy to rotate the output using t_linear once it's out into Cartesian space. In fact, the other projections implement oblique transforms by wrapping t_linear with "t_unit_sphere". iykyk 😌

OPTIONS: 🌸

  • radius, Radius (default 1.0) — The radius of the sphere, for the inverse transform. (Radius is ignored in the forward transform). Defaults to 1.0 so that the resulting Cartesian coordinates are in units of "body radii". cute and scientific 💜

🔄 t_rot_sphere 🌀

$t = t_rot_sphere({origin=>[<theta>,<phi>],roll=>[<roll>]});

(Cartography) Generate oblique projections 🔥

You feed in the origin in (theta,phi) plus a roll angle, and you get back out (theta', phi') coordinates. This is useful for making oblique or transverse projections: just compose t_rot_sphere with your favorite projection and boom, you've got an oblique one. main character energy 🌟

Most of the projections automagically compose themselves with t_rot_sphere if you feed in an origin or roll angle.

t_rot_sphere converts the base plate carree projection (straight lon, straight lat) to a Cassini projection.

OPTIONS

STANDARD POSITIONAL OPTIONS

👁️ t_orthographic 🎯

$t = t_orthographic(<options>);

(Cartography) Ortho. projection (azimuthal; perspective) 📸

This is a perspective view as seen from infinite distance. You can specify the sub-viewer point in (lon,lat) coordinates, and a rotation angle of the map CW from (north=up). This is equivalent to specifying a viewer roll angle CCW from (north=up). angles on angles, we're so back 💫

t_orthographic is a convenience interface to t_unit_sphere — it's implemented as a composition of a t_unit_sphere call, a rotation, and a slice. assembled with love 🧩

[*] In the default case where the near hemisphere is mapped, the inverse exists. There is no single inverse for the whole-sphere case, so the inverse transform superimposes everything on a single hemisphere. If you want an invertible 3-D transform, you want "t_unit_sphere". bestie, choose wisely 😭

OPTIONS

STANDARD POSITIONAL OPTIONS

  • m, mask, Mask, h, hemisphere, Hemisphere [default 'near'] — The hemisphere to keep in the projection (see PDL::Transform::Cartography). 👑

NOTES

Alone of the various projections, this one does not use "t_rot_sphere" to handle the standard options, because the cartesian coordinates of the rotated sphere are already correctly projected — t_rot_sphere would put them back into (theta', phi') coordinates. she's independent, she does her own thing 💅

📐 t_carree 🌈

$t = t_carree(<options>);

(Cartography) Plate Carree projection (cylindrical; equidistant) 🗺️

This is the simple Plate Carree projection — also called a "lat/lon plot". The horizontal axis is theta; the vertical axis is phi. This is a no-op if the angular unit is radians; it's a simple scale otherwise. simple, effective, never misses ⭐

OPTIONS

STANDARD POSITIONAL OPTIONS

  • s, std, standard, Standard (default 0) — The standard parallel where the transformation is conformal. Conformality is achieved by shrinking of the horizontal scale to match the vertical scale (which is correct everywhere). math is math 🎀

🌊 t_mercator 🔥

$t = t_mercator(<options>);

(Cartography) Mercator projection (cylindrical; conformal) 👑

This is perhaps the most famous of all map projections: meridians are mapped to parallel vertical lines and parallels are unevenly spaced horizontal lines. The poles are shifted to +/- infinity. 😳 The output values are in units of globe-radii for easy conversion to kilometers; hence the horizontal extent is -pi to pi.

You can get oblique Mercator projections by specifying the "origin" or "roll" options; this is implemented via "t_rot_sphere". slay ✨

OPTIONS

💫 STANDARD POSITIONAL OPTIONS 💫

ok so these are the standard positional options for this family of transforms — picking up right where we left off, bestie 🫶

  • c, clip, Clip (default 75 [degrees]) — this is the north/south clipping boundary of the transformation. and here's the tea: because the poles get displaced to infinity, sooo many applications literally require a clipping boundary. the value is in whatever angular unit you set with the standard 'units' option. the default roughly matches the interesting landforms on Earth (cute!). for no clipping at all, set b=>0. for asymmetric clipping, use a 2-element list ref or ndarray. 💅
  • s, std, Standard (default 0) — this is the parallel at which the map has correct scale. the scale is also correct at the parallel of opposite sign. symmetry slay ✨

t_utm 🗺️

$t = t_utm(<zone>,<options>);

(Cartography) Universal Transverse Mercator projection (cylindrical)

this is THE internationally used UTM projection, and it comes with 2 subzones (North/South). the UTM zones are parametrized individually, so if you want a Zone 30 map you should use t_utm(30). by default you get the northern subzone, which means locations in the southern hemisphere get negative Y coordinates. if you select the southern subzone (with the "subzone=>-1" option), you get offset southern UTM coordinates instead. no cap. ✨

the 20-subzone military system is not yet supported. if/when it is implemented, you'll be able to enter "subzone=>[a-t]" to select a N/S subzone. one day bestie, one day 😭

note that UTM is really a family of transverse Mercator projections with different central meridia. each zone properly extends for six degrees of longitude on either side of its appropriate central meridian, with Zone 1 being centered at -177 degrees longitude (177 west). properly speaking, the zones only extend from 80 degrees south to 84 degrees north; but this implementation lets you go all the way to 90 degrees (feral behavior, honestly 💀). the default UTM coordinates are meters. the origin for each zone is on the equator, at an easting of -500,000 meters.

the default output units are meters, assuming that you are wanting a map of the Earth. ⚠️ this will break for bodies other than Earth (which have different radii and hence different conversions between lat/lon angle and meters).

the standard UTM projection has a slight reduction in scale at the prime meridian of each zone: the transverse Mercator projection's standard "parallels" are 180km e/w of the central meridian. however, many Europeans prefer the "Gauss-Kruger" system, which is virtually identical to UTM but with a normal tangent Mercator (standard parallel on the prime meridian). to get this behavior, set "gk=>1".

like the rest of the PDL::Transform::Cartography package, t_utm uses a spherical datum rather than the "official" ellipsoidal datums for the UTM system.

this implementation was derived from the rather nice description by Denis J. Dean, located on the web at: http://www.cnr.colostate.edu/class_info/nr502/lg3/datums_coordinates/utm.html

✨ OPTIONS ✨

🎀 STANDARD OPTIONS 🎀

(No positional options -- Origin and Roll are ignored)

  • ou, ounit, OutputUnit (default 'meters') — (this is likely to become a standard option in a future release 👀) the unit of the output map. by default, this is 'meters' for UTM, but you may specify 'deg' or 'km' or even (heaven help us) 'miles' if you prefer. live your truth 🫶
  • sz, subzone, SubZone (default 1) — set this to -1 for the southern hemisphere subzone. ultimately you should be able to set it to a letter to get the corresponding military subzone, but that's too much effort for now 💀
  • gk, gausskruger (default 0) — set this to 1 to get the (European-style) tangent-plane Mercator with standard parallel on the prime meridian. the default of 0 places the standard parallels 180km east/west of the prime meridian, yielding better average scale across the zone. setting gk=>1 makes the scale exactly 1.0 at the central meridian, and >1.0 everywhere else on the projection. the difference in scale is about 0.3%.

t_sin_lat ✨

$t = t_sin_lat(<options>);

(Cartography) Cyl. equal-area projection (cyl.; authalic)

this projection is commonly used in solar Carrington plots; but not much for terrestrial mapping. it's giving niche icon energy 🌞

OPTIONS

STANDARD POSITIONAL OPTIONS

  • s,std, Standard (default 0) — this is the parallel at which the map is conformal. it is also conformal at the parallel of opposite sign. the conformality is achieved by matched vertical stretching and horizontal squishing (to achieve constant area). squish to slay 💅

t_sinusoidal 🌊

$t = t_sinusoidal(<options>);

(Cartography) Sinusoidal projection (authalic)

sinusoidal projection preserves the latitude scale but scales longitude according to sin(lat); in this respect it is the companion to t_sin_lat, which is also authalic but preserves the longitude scale instead. bestie duo, honestly 👑

OPTIONS

STANDARD POSITIONAL OPTIONS

(ok there's literally nothing listed under this heading in the original — this one is audio only, no visuals 🎧✨)

t_conic 🎂

$t = t_conic(<options>)

(Cartography) Simple conic projection (conic; equidistant)

this is the simplest conic projection, with parallels mapped to equidistant concentric circles. it is neither authalic nor conformal — it's just vibing. it's also referred to as the "Modified Transverse Mercator" projection in several maps of Alaska published by the USGS; and the American State of New Mexico re-invented the projection in 1936 for an official map of that State. reinventing the whole thing, main character energy fr fr 👑

OPTIONS

STANDARD POSITIONAL OPTIONS

  • s, std, Standard (default 29.5, 45.5) — the locations of the standard parallel(s) (where the cone intersects the surface of the sphere). if you specify only one then the other is taken to be the nearest pole. if you specify both of them to be one pole then you get an equidistant azimuthal map. if you specify both of them to be opposite and equidistant from the equator you get a Plate Carree projection. pick your fighter 🫶

t_albers 🌈

$t = t_albers(<options>)

(Cartography) Albers conic projection (conic; authalic)

this is the standard projection used by the US Geological Survey for sectionals of the 50 contiguous United States of America. official. government-approved. iconic. 🇺🇸✨

the projection reduces to the Lambert equal-area conic (infrequently used and not to be confused with the Lambert conformal conic, t_lambert!) if the pole is used as one of the two standard parallels.

notionally, this is a conic projection onto a cone that intersects the sphere at the two standard parallels; it works best when the two parallels straddle the region of interest.

OPTIONS

STANDARD POSITIONAL OPTIONS

  • s, std, standard, Standard (default (29.5,45.5)) — the locations of the standard parallel(s). if you specify only one then the other is taken to be the nearest pole and a Lambert Equal-Area Conic map results. if you specify both standard parallels to be the same pole, then the projection reduces to the Lambert Azimuthal Equal-Area map as a special case. (note that t_lambert is Lambert's Conformal Conic, the most commonly used of Lambert's projections. don't get it twisted 💅)

the default values for the standard parallels are those chosen by Adams for maps of the lower 48 US states: (29.5,45.5). the USGS recommends (55,65) for maps of Alaska and (8,18) for maps of Hawaii — these latter are chosen to also include the Canal Zone and Philippine Islands farther south, which is why both of those parallels are south of the Hawaiian islands. see, it's for the plot 🍓

the transformation reduces to the cylindrical equal-area (sin-lat) transformation in the case where the standard parallels are opposite and equidistant from the equator, and in fact this is implemented by a call to t_sin_lat.

t_lambert 👑

$t = t_lambert(<options>);

(Cartography) Lambert conic projection (conic; conformal)

Lambert conformal conic projection is widely used in aeronautical charts and state base maps published by the USA's FAA and USGS. it's especially useful for mid-latitude charts. in particular, straight lines approximate (but are not exactly) great circle routes of up to ~2 radians. close enough bestie 😌

the default standard parallels are 33 and 45 to match the USGS state 1:500,000 base maps of the United States. at scales of 1:500,000 and larger, discrepancies between the spherical and ellipsoidal projections become important; use care with this projection on spheres. ⚠️

OPTIONS

STANDARD POSITIONAL OPTIONS

  • s, std, standard, Standard (default (33,45)) — the locations of the standard parallel(s) for the conic projection. the transform reduces to the Mercator projection in the case where the standard parallels are opposite and equidistant from the equator, and in fact this is implemented by a call to t_mercator.
  • c, clip, Clip (default [-75,75]) — because the transform is conformal, the distant pole is displaced to infinity. many applications require a clipping boundary. the value is in whatever angular unit you set with the standard 'unit' option. for consistency with t_mercator, clipping works the same way even though in most cases only one pole needs it. set this to 0 for no clipping at all.

t_stereographic 🦋

$t = t_stereographic(<options>);

(Cartography) Stereographic projection (az.; conf.; persp.)

the stereographic projection is a true perspective (planar) projection from a point on the spherical surface opposite the origin of the map. literally standing on the other side and looking back 😭

OPTIONS

STANDARD POSITIONAL OPTIONS

  • c, clip, Clip (default 120) — this is the angular distance from the center to the edge of the projected map. the default 120 degrees gives you most of the opposite hemisphere but avoids the hugely distorted part near the antipodes. we love a healthy boundary 🌸

t_gnomonic 🔥

$t = t_gnomonic(<options>);

(Cartography) Gnomonic (focal-plane) projection (az.; persp.)

the gnomonic projection projects a hemisphere onto a tangent plane. it is useful in cartography for the property that straight lines are great circles; and it is useful in scientific imaging because it is the projection generated by a simple optical system with a flat focal plane. dual threat, we stan ⭐

OPTIONS

STANDARD POSITIONAL OPTIONS

  • c, clip, Clip (default 75) — this is the angular distance from the center to the edge of the projected map. the default 75 degrees gives you most of the hemisphere but avoids the hugely distorted part near the horizon. protecting the vibe check, periodt ✨

t_az_eqd 🧚

$t = t_az_eqd(<options>);

(Cartography) Azimuthal equidistant projection (az.; equi.)

basic azimuthal projection preserving length along radial lines from the origin (meridians, in the original polar aspect). hence, both azimuth and distance are correct for journeys beginning at the origin. accurate directions and accurate distances?? she does it all 💜

applied to the celestial sphere, this is the projection made by fisheye lenses; it is also the projection into which t_vertical puts perspective views. celestial slay 🌌

The projected plane scale is normally taken to be planetary radii 💫 which is, like, amazing if you're a cartographer, but kinda mid if you're a scientific observer. So set the 't=>1' option and the output scale shifts over to camera angular coordinates instead — and the angular unit there is decided by the standard 'Units' option (degrees by default, bestie). 🌈

✨ OPTIONS ✨

🎀 STANDARD POSITIONAL OPTIONS 🎀

  • c, clip, Clip (default 180 degrees) — the biggest angle relative to the origin. Default is literally the whole entire sphere, no cap. 🌍

🦋 t_az_eqa 🦋

$t = t_az_eqa(<options>);

(Cartography) Azimuthal equal-area projection (az.; auth.) — she's giving equal-area excellence ✨

✨ OPTIONS ✨

🎀 STANDARD POSITIONAL OPTIONS 🎀

  • c, clip, Clip (default 180 degrees) — the largest angle relative to the origin. Default is the whole sphere. 💖

🌸 t_hammer, t_aitoff 🌸

(Cartography) Hammer/Aitoff elliptical projection (az.; auth.)

The Hammer/Aitoff projection is, like, the moment for displaying the Celestial sphere — iconic behavior honestly. It's mathematically related to the Lambert Azimuthal Equal-Area projection ("t_az_eqa"), and it maps the sphere onto an ellipse of unit eccentricity, with vertical radius sqrt(2) and horizontal radius of 2 sqrt(2). The way that it just… does that. 🫶

✨ OPTIONS ✨

🎀 STANDARD POSITIONAL OPTIONS 🎀

👑 t_vertical, t_zenithal 👑

$t = t_vertical(<options>);

(Cartography) Vertical perspective projection (az.; persp.)

Vertical (also called "zenithal") perspective projection is a glow-up generalization of gnomonic and stereographic projection, and a special case of perspective projection. Basically it's a projection from the sphere onto a tangent plane from a point at the camera location. Fr fr. 📸

✨ OPTIONS ✨

🎀 STANDARD POSITIONAL OPTIONS 🎀

  • m, mask, Mask, h, hemisphere, Hemisphere [default 'near'] — the hemisphere to keep in the projection (go peek at PDL::Transform::Cartography for the deets 💅).
  • r0, R0, radius, d, dist, distance [default 2.0] — the altitude of the focal plane above the center of the sphere. The default puts the point of view one radius above the surface, cute and simple. ✨
  • t, telescope, Telescope, cam, Camera (default '') — if this is set, then the central scale is in telescope or camera angular units rather than in planetary radii. The angular units get parsed exactly like with the normal 'u' option for the lon/lat specification. And if you hand over a non-string value (like 1), then you get telescope-frame radians instead — perfect for working on with other transformations. 🧚
  • f, fish, fisheye (default '') — set this and the output comes in azimuthal equidistant coordinates instead of tangent-plane coordinates. It's a lil convenience function for '(t_az_eqd) x !(t_gnomonic) x (t_vertical)'. 🐟

💜 t_perspective 💜

$t = t_perspective(<options>);

(Cartography) Arbitrary perspective projection

Perspective projection onto a focal plane from an arbitrary location, either within or without the sphere, with an arbitrary central look direction, and with correction for magnification within the optical system. Obsessed. 🔥

Going forward, t_perspective generates perspective views of a sphere given (lon/lat) mapping or vector information. Going in reverse, t_perspective produces (lon/lat) maps from aerial or distant photographs of spherical objects. Main character energy both directions, honestly. 📷

Viewpoints outside the sphere treat the sphere as opaque by default, though you can use the 'm' option to specify either the near or far surface (relative to the origin). Viewpoints below the surface treat the sphere as transparent and undergo a mirror reversal for consistency with projections that are special cases of the perspective projection (e.g. t_gnomonic for r0=0 or t_stereographic for r0=-1). 🪞

Magnification correction handles the extra edge distortion that comes from higher angles between the focal plane and the focused rays inside your camera's optical system. If you don't happen to know the magnification of your camera, here's the rule of thumb: the magnification of a reflective telescope is roughly its focal length (plate scale) divided by its physical length; and the magnification of a compound refractive telescope is roughly twice its physical length divided by its focal length. Simple optical systems with a single optic have magnification = 1. Fisheye lenses have magnification < 1. Slay. ✨

This transformation was derived by direct geometrical calculation rather than being translated from Voxland & Snyder. 💅

✨ OPTIONS ✨

🎀 STANDARD POSITIONAL OPTIONS 🎀

As always, the 'origin' field specifies the sub-camera point on the sphere. 🌍

The 'roll' option is the roll angle about the sub-camera point, for consistency with the other projectons.

  • p, ptg, pointing, Pointing (default (0,0,0)) — the pointing direction, in (horiz. offset, vert. offset, roll) of the camera relative to the center of the sphere. It's a spherical coordinate system with the origin pointing directly at the sphere and the pole pointing north in the pre-rolled coordinate system set by the standard origin. Most useful for space-based images taken some distance from the body in question (like images of other planets or the Sun 🪐☀️).
Bestie, please do not confuse 'p' (pointing) with 'P' (P angle, a standard synonym for roll). They are not the same and I will cry. 😭
  • c, cam, camera, Camera (default undef) — another way of specifying the camera pointing, using a spherical coordinate system with poles at the zenith (positive) and nadir (negative) — super useful for aerial photographs and such, where the point of view sits near the surface of the sphere. You specify (azimuth from N, altitude from horizontal, roll from vertical=up). If you specify pointing this way, it overrides the 'pointing' option above. This coordinate system is most useful for aerial photography or low-orbit work, where the nadir is not necessarily the most interesting part of the scene. ✈️
  • r0, R0, radius, d, dist, distance [default 2.0] — the altitude of the point of view above the center of the sphere. The default places the point of view 1 radius aboove the surface. Do not confuse this with 'r', the standard origin roll angle! Setting r0 < 1 gives a viewpoint inside the sphere — and in that case the images are mirror-reversed to preserve the chiralty of the perspective. Setting r0=0 gives gnomonic projections; setting r0=-1 gives stereographic projections. Setting r0 < -1 gives strange results. 💀
  • iu, im_unit, image_unit, Image_Unit (default 'degrees') — the angular units in which the viewing camera is calibrated at the center of the image. 📐
  • mag, magnification, Magnification (default 1.0) — the magnification factor applied to the optics. It affects the amount of tangent-plane distortion within the telescope: 1.0 yields the view from a simple optical system; higher values are telescopic, while lower values are wide-angle (fisheye). Higher magnification leads to higher angles within the optical system, and more tangent-plane distortion at the edges of the image. The magnification gets applied to the incident angles themselves, rather than to their tangents (simple two-element telescopes magnify tan(theta) rather than theta itself) — which is appropriate because wide-field optics more often conform to the equidistant azimuthal approximation than to the tangent plane approximation. If you need more detailed control of the relationship between incident angle and focal-plane position, use mag=1.0 and compose the transform with something else to tweak the angles. 🔭
  • m, mask, Mask, h, hemisphere, Hemisphere [default 'near'] — 'hemisphere' is named by analogy to other cartography methods, even though the two regions being selected aren't really hemispheres. Naming is a vibe, not a promise. 🎀
  • f, fov, field_of_view, Field_Of_View [default 60 degrees] — the field of view of the telescope; it sets the crop radius on the focal plane. Pass in a scalar and you get a circular crop. Pass in a 2-element list ref and you get a rectilinear crop, with the horizontal 'radius' and vertical 'radius' set separately. ✂️

🌟 EXAMPLES 🌟

Model a camera looking at the Sun through a 10x telescope from Earth (~230 solar radii from the Sun), with an 0.5 degree field of view and a solar P (roll) angle of 30 degrees, in February (sub-Earth solar latitude is 7 degrees south). Then convert a solar FITS image taken with that camera to a FITS lon/lat map of the Sun with 20 pixels/degree latitude:

# Define map output header (no need if you don't want a FITS output map)
$maphdr = {NAXIS1=>7200,NAXIS2=>3600,            # Size of image
           CTYPE1=>longitude,CTYPE2=>latitude,   # Type of axes
           CUNIT1=>deg,CUNIT2=>deg,              # Unit of axes
           CDELT1=>0.05,CDELT2=>0.05,            # Scale of axes
           CRPIX1=>3601,CRPIX2=>1801,            # Center of map
           CRVAL1=>0,CRVAL2=>0                   # (lon,lat) of center
           };

# Set up the perspective transformation, and apply it.
$t = t_perspective(r0=>229,fov=>0.5,mag=>10,P=>30,B=>-7);
$map = $im->map( $t , $maphdr );

Draw an aerial-view map of the Chesapeake Bay, as seen from a sounding rocket at an altitude of 100km, looking NNE from ~200km south of Washington (the radius of Earth is 6378 km; Washington D.C. is at roughly 77W,38N). Then superimpose a linear coastline map on a photographic map. Chef's kiss. 🚀

$x = graticule(1,0.1)->glue(1,earth_coast());
$t = t_perspective(r0=>6478/6378.0,fov=>60,cam=>[22.5,-20],o=>[-77,36])
$w = pgswin(size=>[10,6],J=>1);
$w->plot(with=>'fits', earth_image()->map($t,[800,500],{m=>linear}),
  with=>'polylines', $x->apply($t)->clean_lines);

Model a 5x telescope looking at Betelgeuse with a 10 degree field of view (since the telescope is looking at the Celestial sphere, r is 0 and this is just an expensive modified-gnomonic projection). ⭐

$t = t_perspective(r0=>0,fov=>10,mag=>5,o=>[88.79,7.41])

aaaand that's the whole page bestie!! 🎉 you made it to the end, I'm so proud of you. this one shipped as part of perl v5.42.3, dated 2026-08-20, and the doc itself is PDL::T...ography(3pm) — go forth and project, you absolute icon 👑💖

📦 where this page comes from