mapproj(3tcl)

📦
version 2.0 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 mapproj — Tcl Library 💖

ok bestie, come closer, because this is mapproj(3tcl) from the Tcl Library and it is genuinely about to be your whole personality 🫶. it's the map projection page. it turns world co-ordinates into map co-ordinates and back again. that's the vibe. no cap. let's get into it 💅✨

🌍 NAME 🌍

mapproj — map projection routines 🗺️

🌸 SYNOPSIS 🌸

package require Tcl ?8.5 9?

package require math::interpolate ?1.1?

package require math::special ?0.2.2?

package require mapproj ?1.1?

::mapproj::toPlateCarree lambda_0 phi_0 lambda phi
::mapproj::fromPlateCarree lambda_0 phi_0 x y
::mapproj::toCylindricalEqualArea lambda_0 phi_0 lambda phi
::mapproj::fromCylindricalEqualArea lambda_0 phi_0 x y
::mapproj::toMercator lambda_0 phi_0 lambda phi
::mapproj::fromMercator lambda_0 phi_0 x y
::mapproj::toMillerCylindrical lambda_0 lambda phi
::mapproj::fromMillerCylindrical lambda_0 x y
::mapproj::toSinusoidal lambda_0 phi_0 lambda phi
::mapproj::fromSinusoidal lambda_0 phi_0 x y
::mapproj::toMollweide lambda_0 lambda phi
::mapproj::fromMollweide lambda_0 x y
::mapproj::toEckertIV lambda_0 lambda phi
::mapproj::fromEckertIV lambda_0 x y
::mapproj::toEckertVI lambda_0 lambda phi
::mapproj::fromEckertVI lambda_0 x y
::mapproj::toRobinson lambda_0 lambda phi
::mapproj::fromRobinson lambda_0 x y
::mapproj::toCassini lambda_0 phi_0 lambda phi
::mapproj::fromCassini lambda_0 phi_0 x y
::mapproj::toPeirceQuincuncial lambda_0 lambda phi
::mapproj::fromPeirceQuincuncial lambda_0 x y
::mapproj::toOrthographic lambda_0 phi_0 lambda phi
::mapproj::fromOrthographic lambda_0 phi_0 x y
::mapproj::toStereographic lambda_0 phi_0 lambda phi
::mapproj::fromStereographic lambda_0 phi_0 x y
::mapproj::toGnomonic lambda_0 phi_0 lambda phi
::mapproj::fromGnomonic lambda_0 phi_0 x y
::mapproj::toAzimuthalEquidistant lambda_0 phi_0 lambda phi
::mapproj::fromAzimuthalEquidistant lambda_0 phi_0 x y
::mapproj::toLambertAzimuthalEqualArea lambda_0 phi_0 lambda phi
::mapproj::fromLambertAzimuthalEqualArea lambda_0 phi_0 x y
::mapproj::toHammer lambda_0 lambda phi
::mapproj::fromHammer lambda_0 x y
::mapproj::toConicEquidistant lambda_0 phi_0 phi_1 phi_2 lambda phi
::mapproj::fromConicEquidistant lambda_0 phi_0 phi_1 phi_2 x y
::mapproj::toAlbersEqualAreaConic lambda_0 phi_0 phi_1 phi_2 lambda phi
::mapproj::fromAlbersEqualAreaConic lambda_0 phi_0 phi_1 phi_2 x y
::mapproj::toLambertConformalConic lambda_0 phi_0 phi_1 phi_2 lambda phi
::mapproj::fromLambertConformalConic lambda_0 phi_0 phi_1 phi_2 x y
::mapproj::toLambertCylindricalEqualArea lambda_0 phi_0 lambda phi
::mapproj::fromLambertCylindricalEqualArea lambda_0 phi_0 x y
::mapproj::toBehrmann lambda_0 phi_0 lambda phi
::mapproj::fromBehrmann lambda_0 phi_0 x y
::mapproj::toTrystanEdwards lambda_0 phi_0 lambda phi
::mapproj::fromTrystanEdwards lambda_0 phi_0 x y
::mapproj::toHoboDyer lambda_0 phi_0 lambda phi
::mapproj::fromHoboDyer lambda_0 phi_0 x y
::mapproj::toGallPeters lambda_0 phi_0 lambda phi
::mapproj::fromGallPeters lambda_0 phi_0 x y
::mapproj::toBalthasart lambda_0 phi_0 lambda phi
::mapproj::fromBalthasart lambda_0 phi_0 x y

🦋 DESCRIPTION 🦋

so like — the mapproj package hands you a whole lil friend group of procedures 🫶. their entire job is converting back and forth between world co-ordinates (that's latitude and longitude, bestie 🌐) and map co-ordinates on a bunch of different map projections. that's it. that's the whole deal. iconic. 👑

🎀 COMMANDS 🎀

these next ones are the besties that convert between world co-ordinates and map co-ordinates 🗺️✨:

  • ::mapproj::toPlateCarree lambda_0 phi_0 lambda phi — converts to the plate carrée (cylindrical equidistant) projection 🥞
  • ::mapproj::fromPlateCarree lambda_0 phi_0 x y — converts from the plate carrée (cylindrical equidistant) projection 🥞
  • ::mapproj::toCylindricalEqualArea lambda_0 phi_0 lambda phi — converts to the cylindrical equal-area projection 🌈
  • ::mapproj::fromCylindricalEqualArea lambda_0 phi_0 x y — converts from the cylindrical equal-area projection 🌈
  • ::mapproj::toMercator lambda_0 phi_0 lambda phi — converts to the Mercator (cylindrical conformal) projection 🧭
  • ::mapproj::fromMercator lambda_0 phi_0 x y — converts from the Mercator (cylindrical conformal) projection 🧭
  • ::mapproj::toMillerCylindrical lambda_0 lambda phi — converts to the Miller Cylindrical projection 🌀
  • ::mapproj::fromMillerCylindrical lambda_0 x y — converts from the Miller Cylindrical projection 🌀
  • ::mapproj::toSinusoidal lambda_0 phi_0 lambda phi — converts to the sinusoidal (Sanson-Flamsteed) projection. projection. 💀 (yes bestie, it says it twice, we don't make the rules)
  • ::mapproj::fromSinusoidal lambda_0 phi_0 x y — converts from the sinusoidal (Sanson-Flamsteed) projection. projection. 💀 (twice again, it's the brand now)
  • ::mapproj::toMollweide lambda_0 lambda phi — converts to the Mollweide projection 🥚
  • ::mapproj::fromMollweide lambda_0 x y — converts from the Mollweide projection 🥚
  • ::mapproj::toEckertIV lambda_0 lambda phi — converts to the Eckert IV projection 4️⃣
  • ::mapproj::fromEckertIV lambda_0 x y — converts from the Eckert IV projection 4️⃣
  • ::mapproj::toEckertVI lambda_0 lambda phi — converts to the Eckert VI projection 6️⃣
  • ::mapproj::fromEckertVI lambda_0 x y — converts from the Eckert VI projection 6️⃣
  • ::mapproj::toRobinson lambda_0 lambda phi — converts to the Robinson projection 🌎
  • ::mapproj::fromRobinson lambda_0 x y — converts from the Robinson projection 🌎
  • ::mapproj::toCassini lambda_0 phi_0 lambda phi — converts to the Cassini (transverse cylindrical equidistant) projection 🛰️
  • ::mapproj::fromCassini lambda_0 phi_0 x y — converts from the Cassini (transverse cylindrical equidistant) projection 🛰️
  • ::mapproj::toPeirceQuincuncial lambda_0 lambda phi — converts to the Peirce Quincuncial Projection 🎲
  • ::mapproj::fromPeirceQuincuncial lambda_0 x y — converts from the Peirce Quincuncial Projection 🎲
  • ::mapproj::toOrthographic lambda_0 phi_0 lambda phi — converts to the orthographic projection 🌕
  • ::mapproj::fromOrthographic lambda_0 phi_0 x y — converts from the orthographic projection 🌕
  • ::mapproj::toStereographic lambda_0 phi_0 lambda phi — converts to the stereographic (azimuthal conformal) projection 🪩
  • ::mapproj::fromStereographic lambda_0 phi_0 x y — converts from the stereographic (azimuthal conformal) projection 🪩
  • ::mapproj::toGnomonic lambda_0 phi_0 lambda phi — converts to the gnomonic projection 🧚
  • ::mapproj::fromGnomonic lambda_0 phi_0 x y — converts from the gnomonic projection 🧚
  • ::mapproj::toAzimuthalEquidistant lambda_0 phi_0 lambda phi — converts to the azimuthal equidistant projection 📍
  • ::mapproj::fromAzimuthalEquidistant lambda_0 phi_0 x y — converts from the azimuthal equidistant projection 📍
  • ::mapproj::toLambertAzimuthalEqualArea lambda_0 phi_0 lambda phi — converts to the Lambert azimuthal equal-area projection 🟣
  • ::mapproj::fromLambertAzimuthalEqualArea lambda_0 phi_0 x y — converts from the Lambert azimuthal equal-area projection 🟣
  • ::mapproj::toHammer lambda_0 lambda phi — converts to the Hammer projection 🔨
  • ::mapproj::fromHammer lambda_0 x y — converts from the Hammer projection 🔨
  • ::mapproj::toConicEquidistant lambda_0 phi_0 phi_1 phi_2 lambda phi — converts to the conic equidistant projection 🍦
  • ::mapproj::fromConicEquidistant lambda_0 phi_0 phi_1 phi_2 x y — converts from the conic equidistant projection 🍦
  • ::mapproj::toAlbersEqualAreaConic lambda_0 phi_0 phi_1 phi_2 lambda phi — converts to the Albers equal-area conic projection 🎂
  • ::mapproj::fromAlbersEqualAreaConic lambda_0 phi_0 phi_1 phi_2 x y — converts from the Albers equal-area conic projection 🎂
  • ::mapproj::toLambertConformalConic lambda_0 phi_0 phi_1 phi_2 lambda phi — converts to the Lambert conformal conic projection 💜
  • ::mapproj::fromLambertConformalConic lambda_0 phi_0 phi_1 phi_2 x y — converts from the Lambert conformal conic projection 💜

and now, bestie, get ready, because among the cylindrical equal-area projections there are a whole bunch of standard parallels that have names 👑 — and each one gets its own little duo:

  • ::mapproj::toLambertCylindricalEqualArea lambda_0 phi_0 lambda phi — converts to the Lambert cylindrical equal area projection 🌴 (standard parallel is the Equator.)
  • ::mapproj::fromLambertCylindricalEqualArea lambda_0 phi_0 x y — converts from the Lambert cylindrical equal area projection 🌴 (standard parallel is the Equator.)
  • ::mapproj::toBehrmann lambda_0 phi_0 lambda phi — converts to the Behrmann cylindrical equal area projection 🌸 (standard parallels are 30 degrees North and South)
  • ::mapproj::fromBehrmann lambda_0 phi_0 x y — converts from the Behrmann cylindrical equal area projection 🌸 (standard parallels are 30 degrees North and South.)
  • ::mapproj::toTrystanEdwards lambda_0 phi_0 lambda phi — converts to the Trystan Edwards cylindrical equal area projection 🦋 (standard parallels are 37.4 degrees North and South)
  • ::mapproj::fromTrystanEdwards lambda_0 phi_0 x y — converts from the Trystan Edwards cylindrical equal area projection 🦋 (standard parallels are 37.4 degrees North and South.)
  • ::mapproj::toHoboDyer lambda_0 phi_0 lambda phi — converts to the Hobo-Dyer cylindrical equal area projection 🎒 (standard parallels are 37.5 degrees North and South)
  • ::mapproj::fromHoboDyer lambda_0 phi_0 x y — converts from the Hobo-Dyer cylindrical equal area projection 🎒 (standard parallels are 37.5 degrees North and South.)
  • ::mapproj::toGallPeters lambda_0 phi_0 lambda phi — converts to the Gall-Peters cylindrical equal area projection 🐧 (standard parallels are 45 degrees North and South)
  • ::mapproj::fromGallPeters lambda_0 phi_0 x y — converts from the Gall-Peters cylindrical equal area projection 🐧 (standard parallels are 45 degrees North and South.)
  • ::mapproj::toBalthasart lambda_0 phi_0 lambda phi — converts to the Balthasart cylindrical equal area projection 🍓 (standard parallels are 50 degrees North and South)
  • ::mapproj::fromBalthasart lambda_0 phi_0 x y — converts from the Balthasart cylindrical equal area projection 🍓 (standard parallels are 50 degrees North and South.)

🗺️ ARGUMENTS 🗺️

Okay bestie, here are the args that the projection commands are gonna accept. They're all just numbers, but they mean very specific things, so don't mix them up 💅

  • lambda — Longitude of the point you're projecting, in degrees. 🌍
  • phi — Latitude of the point you're projecting, in degrees. 📍
  • lambda_0 — Longitude of the center of the sheet, in degrees. For lots of projections, this is also the reference meridian of the projection. 🎯
  • phi_0 — Latitude of the center of the sheet, in degrees. For the azimuthal projections, this is also the latitude of the center of the projection. 🧭
  • phi_1 — Latitude of the first reference parallel, for projections that use reference parallels. 1️⃣
  • phi_2 — Latitude of the second reference parallel, for projections that use reference parallels. 2️⃣
  • x — X co-ordinate of a point on the map, in units of Earth radii. 📏
  • y — Y co-ordinate of a point on the map, in units of Earth radii. 📐

📐 RESULTS 📐

So like, for every procedure whose name starts with to, you get back a list with an x co-ordinate and a y co-ordinate. These co-ordinates are relative to the center of the map sheet you're gonna draw, and they're measured in Earth radii at the reference location on the map. 🌍✨

And for every function whose name starts with from, the return value is a list with the longitude and latitude, in degrees. Easy peasy. 🫶

🧭 CHOOSING A PROJECTION 🧭

This package has so many projections because no single projection is the moment for every map. So here's the bestie guide on how to pick one. 💖

First, think about the kind of data you're showing. If your data is directional — like winds, ocean currents, or magnetic fields — you need a projection that preserves angles. Those are called conformal projections. The conformal squad includes Mercator, Albers azimuthal equal-area, stereographic, and Peirce Quincuncial. 🌬️

If your data is thematic — describing properties of land or water, like temperature, population density, land use, or demographics — then you need a projection that shows areas on the map proportional to areas in real life. These are the equal area projections, and they include the various cylindrical equal area projections, the sinusoidal projection, the Lambert azimuthal equal-area projection, the Albers equal-area conic projection, and several of the world-map projections (Miller Cylindrical, Mollweide, Eckert IV, Eckert VI, Robinson, and Hammer). 🌎

If the big factor in your data is distance from a central point or line — think air routes — then you'll do best with an equidistant projection, like plate carrée, Cassini, azimuthal equidistant, or conic equidistant. ✈️

And if direction from a central point is critical — air routes again, or radio antenna pointing — then you almost surely want one of the azimuthal projections. Good picks are azimuthal equidistant, azimuthal equal-area, stereographic, and maybe orthographic. 📡

Next, think about how much of the Earth your map covers and the general shape of the area you care about. For maps of the entire Earth, the cylindrical equal area, Eckert IV and VI, Mollweide, Robinson, and Hammer projections are good overall choices. The Mercator projection is traditional, but the extreme distortions of area at high latitudes make it a poor choice unless you actually need a conformal projection. The Peirce projection is a better conformal choice because it distorts landforms less. The Miller Cylindrical is a compromise — it gives shapes similar to the traditional Mercator but with less polar stretching. The Peirce Quincuncial projection shows all the continents with acceptable distortion if you choose a reference meridian close to +20 degrees. The Robinson projection gives attractive maps for things like political divisions, but avoid it for scientific data, since other projections have more useful geometric properties. 🗺️

If your map covers a hemisphere, choose stereographic, azimuthal-equidistant, Hammer, or Mollweide projections — all of these project the hemisphere into a circle. ⭕

If your map covers a large area (at least a few hundred km on a side) but less than a hemisphere, you've got options. Azimuthal projections are usually good — pick stereographic, azimuthal equidistant, or Lambert azimuthal equal-area depending on whether shapes, distances from a central point, or areas matter most. Azimuthal projections (and possibly the Cassini projection) are the only really good choices for mapping the polar regions. ❄️

If that large area is in one of the temperate zones and is round or mostly east-west, then conic projections are great. Choose the Lambert conformal conic, the conic equidistant, or the Albers equal-area conic depending on whether shape, distance, or area is the most important. For any of these, pick reference parallels at approximately 1/6 and 5/6 of the range of latitudes you're displaying. For example, maps of the 48 coterminous United States look attractive with reference parallels of 28.5 and 45.5 degrees. 🇺🇸

If the large area is equatorial and is round or mostly east-west, then the Mercator projection is a good conformal choice; Lambert cylindrical equal-area and sinusoidal are good equal-area choices; and plate carrée is a good equidistant choice. 🌴

Large areas with a mostly North-South aspect — especially ones spanning the Equator — need different picks. The Cassini projection is a good equidistant choice (for instance, a Cassini projection with a central meridian of 80 degrees West produces an attractive map of the Americas). The cylindrical equal-area, Albers equal-area conic, sinusoidal, Mollweide, and Hammer projections are possible equal-area choices. A good conformal projection here is the Transverse Mercator, which alas is not yet implemented. 😭

Small areas start getting into territory where the ellipticity of the Earth affects the map scale. This package does not try to handle accurate mapping for large-scale topographic maps. If slight scale errors are acceptable in your application, then any of the projections that work for large areas should work for small ones too. 🔬

There are also a few projections included for their special properties. The orthographic projection produces views of the Earth as seen from space. The gnomonic projection produces a map where all great circles — the shortest distance between two points on the Earth's surface — are rendered as straight lines. While this is useful for navigational planning, it has extreme distortions of shape and area and can display only a limited area of the Earth (substantially less than a hemisphere). 🛰️

🏷️ KEYWORDS 🏷️

geodesy, map, projection — that's the whole vibe. ✨

Copyright (c) 2007 Kevin B. Kenny <kennykb@acm.org>

Okay bestie, that's the whole page! This is from tcllib 1.1, the mapproj(3tcl) manual — date? not in the footer, but it's giving timeless icon behavior. Go make some gorgeous maps. 💅🗺️💖

📦 where this page comes from