GEOD(1)

📦
version 9.8.1 · 6 versions
, in ubuntu stonking

💖 GEOD(1) — the PROJ manual page, bestie edition 💖

okay so this is geod from the PROJ manual, and I'm gonna walk you through it like we're texting at 2am, except every single flag is still here, no cap. 🫶

✨ NAME ✨

geod — geodesic computations, aka the math that makes the planet go brrr 🌍

🌸 SYNOPSIS 🌸

geod +ellps=<ellispoid> [-afFIlptwW [args]] [+opt[=arg] ...] file ...

invgeod +ellps=<ellispoid> [-afFIlptwW [args]] [+opt[=arg] ...] file
...

(that <ellispoid> typo is literally in the original, I'm not touching it, we respect the ancestors 💅)

🦋 DESCRIPTION 🦋

so geod (the direct one) and invgeod (the inverse one) do geodesic — Great Circle — computations. 🧚

  • direct mode: you give it a starting point's latitude, longitude, azimuth and distance, and it gives you back the latitude, longitude and back azimuth of the terminus point.
  • inverse mode: you give it the initial and terminus latitudes and longitudes, and it gives you back the forward and back azimuths plus the distance between them.

the results are accurate to round off for |f| < 1/50, where f is flattening. periodt.

ngl, invgeod may not be available on all platforms 😭 — in that case just use geod -I instead. it's giving the same energy, fr fr.

the following command-line options can show up in any order:

  • -I — says "we're doing the inverse geodesic computation." you can use this with geod as an alternative to running invgeod. iconic.
  • -a — outputs the latitudes and longitudes of the initial and terminal points, the forward and back azimuths, and the distance. the whole girl dinner of output 🍓
  • -t<a> — where a is a character you pick to be the first character denoting a control line that gets passed through without processing. a little VIP pass ✨
  • -le — gives you a listing of all the ellipsoids that can be selected with the +ellps= option. window shopping 🛍️
  • -lu — gives you a listing of all the units that can be selected with the +units= option. (default units are meters.) 📏
  • -f <format> — where format is a printf format string controlling the output form of the geographic coordinate and azimuth values. the default mode is DMS.
  • -F <format> — where format is a printf format string controlling the output form of the distance value. the default mode is "%.3f".
  • -w<n> — where n is the number of significant fractional digits to use for seconds output. (if you don't specify the option, -w3 is assumed.) lowkey a default, highkey a lifestyle.
  • -W<n> — where n is the number of significant fractional digits to use for seconds output. when -W is used, the fields will be constant width with leading zeroes. so satisfying, honestly 😌
  • -p — makes the azimuthal values output as unsigned DMS numbers between 0 and 360 degrees. also note -f while you're at it.

💜 the +opt situation 💜

the +opt command-line options are associated with geodetic parameters for specifying the ellipsoidal or sphere to use. controls. the options are processed in left to right order from the command line. if you re-enter an option, it's ignored — the first occurrence is assumed to be the desired value. first come, first served, no take-backs 💅

see the PROJ documentation for a full list of these parameters and controls.

🌈 files & input 🌈

one or more files (processed in left to right order) specify the source of the data to be transformed. a - specifies the location of processing standard input. if no files are specified, the input is assumed to come from stdin. she's flexible like that.

  • for direct determinations, input data must be in latitude, longitude, azimuth and distance order, and the output will be latitude, longitude and back azimuth of the terminus point.
  • for inverse mode, you input the latitude and longitude of the initial and terminus points, and out come the respective forward and back azimuth from the initial and terminus points, along with the distance between the points.

input geographic coordinates (latitude and longitude) and azimuthal data must be in decimal degrees or DMS format, and input distance data must be in units consistent with the ellipsoid major axis or sphere radius units. the latitude must lie in the range [-90d,90d]. 🚨

output geographic coordinates and azimuths will be in DMS (if the -f switch isn't used) to 0.001", with trailing, zero-valued minute-second fields deleted. output distance data will be in the same units as the ellipsoid or sphere radius. consistency queen 👑

the Earth's ellipsoidal figure may be selected in the same manner as program proj by using +ellps=, +a=, +es=, etc.

🎀 intermediate points 🎀

geod may also be used to determine intermediate points along either a geodesic line between two points, or along an arc of specified distance from a geographic point. in both cases an initial point must be specified with +lat_1=lat and +lon_1=long parameters, and either:

  • a terminus point with +lat_2=lat and +lon_2=long, or
  • a distance and azimuth from the initial point with +S=distance and +A=azimuth.

if points along a geodesic are to be determined, then either +n_S=integer — specifying the number of intermediate points — and/or +del_S=distance — specifying the incremental distance between points — must be specified.

to determine points along an arc equidistant from the initial point, both +del_A=angle and +n_A=integer must be specified, which determine the respective angular increments and number of points to be determined. both, bestie. not one. both. ✋

🔥 EXAMPLES 🔥

the Boston → Portland girlie 🦞

this script determines the geodesic azimuths and distance in U.S. statute miles from Boston, MA, to Portland, OR:

geod +ellps=clrk66 -I +units=us-mi <<EOF
42d15'N 71d07'W 45d31'N 123d41'W
EOF

which gives the results:

-66d31'50.141" 75d39'13.083" 2587.504

where the first two values are the azimuth from Boston to Portland, the back azimuth from Portland to Boston, followed by the distance. three little numbers, so much lore ✨

now the direct way 💫

an example of forward geodesic use is to use the Boston location and determine Portland's location by azimuth and distance:

geod +ellps=clrk66 +units=us-mi <<EOF
42d15'N 71d07'W -66d31'50.141" 2587.504
EOF

which gives:

45d31'0.003"N 123d40'59.985"W 75d39'13.094"

i.e., the latitude and longitude of Portland, and the back azimuth from Portland to Boston. we love a round trip 🫶

Note: lack of precision in the distance value compromises the precision of the Portland location. she's sensitive like that, be careful 😭

📚 FURTHER READING 📚

  1. GeographicLib — https://geographiclib.sourceforge.io.
  2. C. F. F. Karney, Algorithms for Geodesics — https://doi.org/10.1007/s00190-012-0578-z, J. Geodesy 87(1), 43–55 (2013); addenda — https://geographiclib.sourceforge.io/geod-addenda.html.
  3. A geodesic bibliography — https://geographiclib.sourceforge.io/geodesic-papers/biblio.html.

go read, bestie, it's giving academic 😌📖

👀 SEE ALSO 👀

proj(1), cs2cs(1), cct(1), gie(1), projinfo(1), projsync(1)

the whole friend group, love that for them 💖

💀 BUGS 💀

a list of known bugs can be found at https://github.com/OSGeo/PROJ/issues, where new bug reports can be submitted to. not me encouraging you to file a bug... okay yes me, I am 💅

🏠 HOME PAGE 🏠

https://proj.org/

👑 Author 👑

Charles Karney

1983-2026, PROJ contributors

and that's the whole page!! this one's from PROJ version 9.8, dated 10 avril 2026 — so if you're reading this way after that, go check if the girlies shipped a newer one. slay, bye, go compute a geodesic 💜✨🦋

📦 where this page comes from